@jini-ai/mcp 0.4.3 → 0.6.10

package/dist/federation/approvals/call-confirmation.js

@@ -1,5 +1,4 @@
-import { nowIso } from "@jini-ai/core/primitives";
-import { federatedToolApprovalFingerprint } from "../tool-approvals.js";
+import { approvalContext, cardOffers, isRemembered, rememberApproval } from "./remembered-approval.js";
 const INLINE_ARGUMENT_MAX_LENGTH = 60;
 function argumentDetail(name, value) {
     if (typeof value === "string") {
@@ -17,7 +16,7 @@ export function buildFederatedCallConfirmSpec({ request, messages, errorCode },
     if (!request.destructive && request.writeShapedInputs.length === 0) {
         if (offers.offerChat)
             alternatives.push({ id: "allow-chat", label: messages.allowChatLabel, choice: "chat" });
-        if (offers.offerAlways && !request.destructive)
+        if (offers.offerAlways)
             alternatives.push({ id: "allow-always", label: messages.allowAlwaysLabel, choice: "always" });
     }
     return {
@@ -29,66 +28,6 @@ export function buildFederatedCallConfirmSpec({ request, messages, errorCode },
         danger: request.destructive, confirmLabel: messages.confirmLabel, ...(alternatives.length ? { alternatives } : {}),
     };
 }
-function approvalContext(context, request, approvals, fingerprintDomain) {
-    const fingerprint = federatedToolApprovalFingerprint({ identity: request, fingerprintDomain });
-    const conversationId = approvals?.conversationIdForRun?.({ runId: context.run.id });
-    return {
-        fingerprint,
-        chatKey: approvals?.chat && conversationId ? { conversationId, principalId: context.principal.id, connectionId: request.connectionId, toolName: request.remoteName, fingerprint } : undefined,
-        alwaysKey: approvals?.always && request.origin?.kind === "roster" ? { serverId: request.connectionId, toolName: request.remoteName } : undefined,
-    };
-}
-async function isRemembered(approvals, request, keys, options) {
-    if (request.writeShapedInputs.length > 0)
-        return false;
-    if (keys.alwaysKey && approvals.always) {
-        const saved = await approvals.always.find(keys.alwaysKey, options.scope === undefined ? {} : { scope: options.scope });
-        if (saved && saved.fingerprint === keys.fingerprint && !request.destructive)
-            return true;
-        if (saved)
-            await approvals.always.delete(keys.alwaysKey, options.scope === undefined ? {} : { scope: options.scope });
-    }
-    // Neither a matching chat grant nor an always grant can authorize permanent deletion.
-    if (request.destructive)
-        return false;
-    return keys.chatKey !== undefined && approvals.chat !== undefined && await approvals.chat.has(keys.chatKey);
-}
-function report(options, diagnostic) {
-    // Observability must never turn an explicit approval into a failed mutation.
-    try {
-        options.onPersistenceError?.(diagnostic);
-    }
-    catch { /* Host diagnostic failures are isolated. */ }
-}
-async function remember(input) {
-    const { context, request, keys, approvals, choice, options } = input;
-    // Defense in depth: a forged remember choice must not persist a destructive call's approval.
-    if (request.destructive || request.writeShapedInputs.length > 0)
-        return;
-    let grantedAt;
-    try {
-        grantedAt = nowIso({ clock: approvals.clock });
-        if (choice === "chat" && keys.chatKey && approvals.chat)
-            await approvals.chat.grant({ key: keys.chatKey, grantedAt });
-        else if (choice === "always" && keys.alwaysKey && approvals.always)
-            await approvals.always.upsert({
-                ...keys.alwaysKey, fingerprint: keys.fingerprint, grantedByPrincipalId: context.principal.id, grantedAt,
-            }, options.scope === undefined ? {} : { scope: options.scope });
-        else
-            return;
-    }
-    catch (error) {
-        report(options, { toolId: request.toolId, choice, stage: "store", error });
-        return;
-    }
-    try {
-        await options.webhooks?.approvalRemembered({ principalId: context.principal.id,
-            connectionId: request.connectionId, toolName: request.remoteName, fingerprint: keys.fingerprint, scope: choice, grantedAt }, options.scope === undefined ? {} : { scope: options.scope });
-    }
-    catch (error) {
-        report(options, { toolId: request.toolId, choice, stage: "webhook", error });
-    }
-}
 /** Remembered-approval orchestration over host-owned storage, presentation and permission ports.
  * The host adapts the returned object-argument function to its federation runtime callback.
  * Lookup failures fail closed. Save failures allow the approved call and are reported via a port.
@@ -105,19 +44,15 @@ export function createFederatedCallConfirmer(required, options = {}) {
         const keys = approvalContext(context, request, approvals, required.fingerprintDomain);
         if (approvals && await isRemembered(approvals, request, keys, options))
             return { confirmed: true };
-        const rememberable = !request.destructive && request.writeShapedInputs.length === 0;
-        const offerAlways = rememberable && !request.destructive && keys.alwaysKey !== undefined && approvals !== undefined
-            && await approvals.mayAlwaysAllow({ principalId: context.principal.id }, options.scope === undefined ? {} : { scope: options.scope });
-        const spec = buildFederatedCallConfirmSpec({ request, messages: required.messages, errorCode: required.errorCode }, {
-            offers: { offerChat: rememberable && keys.chatKey !== undefined, offerAlways },
-        });
+        const offers = await cardOffers({ request, principalId: context.principal.id, keys, approvals, options });
+        const spec = buildFederatedCallConfirmSpec({ request, messages: required.messages, errorCode: required.errorCode }, { offers });
         const outcome = await required.humanConfirm.ask({ context, surfaceExchanges: required.surfaceExchanges, spec });
         if (!outcome.confirmed)
             return outcome;
         // Never trust a remember scope the host did not offer, even with a valid one-call answer.
         const choice = spec.alternatives?.find(alternative => alternative.choice === outcome.choice)?.choice;
         if (approvals && choice)
-            await remember({ context, request, keys, approvals, choice, options });
+            await rememberApproval({ context, request, keys, approvals, choice, options });
         return { confirmed: true };
     };
 }

package/dist/federation/approvals/remembered-approval.d.ts

@@ -0,0 +1,39 @@
+import type { FederatedCallConfirmationRequest } from "../ports.js";
+import type { ConversationToolApprovalKey } from "../tool-approvals.js";
+import type { FederatedApprovalDeps, FederatedCallConfirmerOptions, FederatedCardOffers, FederatedConfirmationContext } from "./ports.js";
+/** The lookup keys one call's remembered approvals are stored under. A key is absent when the
+ *  host cannot persist that scope: no store, no conversation, or (always) not a roster origin. */
+export interface ApprovalContext {
+    readonly fingerprint: string;
+    readonly chatKey: ConversationToolApprovalKey | undefined;
+    readonly alwaysKey: {
+        serverId: string;
+        toolName: string;
+    } | undefined;
+}
+/** @complexity O(1) beyond the fingerprint hash. */
+export declare function approvalContext(context: FederatedConfirmationContext, request: FederatedCallConfirmationRequest, approvals: FederatedApprovalDeps | undefined, fingerprintDomain: string): ApprovalContext;
+/** Whether a remembered grant lets this call skip its card. A write-shaped call never does. */
+export declare function isRemembered(approvals: FederatedApprovalDeps, request: FederatedCallConfirmationRequest, keys: ApprovalContext, options: FederatedCallConfirmerOptions): Promise<boolean>;
+/** The remember buttons this call's card may offer. A destructive or write-shaped call offers
+ *  none, and the host's always permission is then not even consulted. */
+export declare function cardOffers({ request, principalId, keys, approvals, options }: {
+    request: FederatedCallConfirmationRequest;
+    principalId: string;
+    keys: ApprovalContext;
+    approvals: FederatedApprovalDeps | undefined;
+    options: FederatedCallConfirmerOptions;
+}): Promise<FederatedCardOffers>;
+interface RememberInput {
+    context: FederatedConfirmationContext;
+    request: FederatedCallConfirmationRequest;
+    keys: ApprovalContext;
+    approvals: FederatedApprovalDeps;
+    choice: "chat" | "always";
+    options: FederatedCallConfirmerOptions;
+}
+/** Saves one explicitly chosen grant, then notifies. Save and notification failures are reported
+ *  via `onPersistenceError` and never fail the already approved call. */
+export declare function rememberApproval(input: RememberInput): Promise<void>;
+export {};
+//# sourceMappingURL=remembered-approval.d.ts.map

package/dist/federation/approvals/remembered-approval.js

@@ -0,0 +1,98 @@
+import { nowIso } from "@jini-ai/core/primitives";
+import { federatedToolApprovalFingerprint } from "../tool-approvals.js";
+import { scopeOption } from "./scope-option.js";
+/** @complexity O(1) beyond the fingerprint hash. */
+export function approvalContext(context, request, approvals, fingerprintDomain) {
+    const fingerprint = federatedToolApprovalFingerprint({ identity: request, fingerprintDomain });
+    const conversationId = approvals?.conversationIdForRun?.({ runId: context.run.id });
+    return {
+        fingerprint,
+        chatKey: approvals?.chat && conversationId ? { conversationId, principalId: context.principal.id, connectionId: request.connectionId, toolName: request.remoteName, fingerprint } : undefined,
+        alwaysKey: approvals?.always && request.origin?.kind === "roster" ? { serverId: request.connectionId, toolName: request.remoteName } : undefined,
+    };
+}
+/** Whether a saved always grant authorizes this call. A saved grant that does not (stale
+ *  fingerprint, or a destructive call) is removed so the operator's list stops claiming it is
+ *  still valid. Lookup and delete failures propagate: remembered lookups fail closed. */
+async function alwaysGrantAuthorizes(approvals, request, keys, options) {
+    if (!keys.alwaysKey || !approvals.always)
+        return false;
+    const saved = await approvals.always.find(keys.alwaysKey, scopeOption(options.scope));
+    if (saved && saved.fingerprint === keys.fingerprint && !request.destructive)
+        return true;
+    if (saved)
+        await approvals.always.delete(keys.alwaysKey, scopeOption(options.scope));
+    return false;
+}
+/** Whether a remembered grant lets this call skip its card. A write-shaped call never does. */
+export async function isRemembered(approvals, request, keys, options) {
+    if (request.writeShapedInputs.length > 0)
+        return false;
+    if (await alwaysGrantAuthorizes(approvals, request, keys, options))
+        return true;
+    // Neither a matching chat grant nor an always grant can authorize permanent deletion.
+    if (request.destructive)
+        return false;
+    return keys.chatKey !== undefined && approvals.chat !== undefined && await approvals.chat.has(keys.chatKey);
+}
+/** Whether the card may offer "always": only with an always key, approval deps, and the host's
+ *  per-principal permission. {@link cardOffers} has already excluded destructive and write-shaped calls. */
+async function mayOfferAlways({ principalId, keys, approvals, options }) {
+    if (keys.alwaysKey === undefined || approvals === undefined)
+        return false;
+    return approvals.mayAlwaysAllow({ principalId }, scopeOption(options.scope));
+}
+/** The remember buttons this call's card may offer. A destructive or write-shaped call offers
+ *  none, and the host's always permission is then not even consulted. */
+export async function cardOffers({ request, principalId, keys, approvals, options }) {
+    if (request.destructive || request.writeShapedInputs.length > 0)
+        return { offerChat: false, offerAlways: false };
+    return { offerChat: keys.chatKey !== undefined, offerAlways: await mayOfferAlways({ principalId, keys, approvals, options }) };
+}
+function report(options, diagnostic) {
+    // Observability must never turn an explicit approval into a failed mutation.
+    try {
+        options.onPersistenceError?.(diagnostic);
+    }
+    catch { /* Host diagnostic failures are isolated. */ }
+}
+/** Writes the chosen grant; `false` when that scope has no key or store, so nothing was saved. */
+async function persistGrant({ context, keys, approvals, choice, options }, grantedAt) {
+    if (choice === "chat" && keys.chatKey && approvals.chat) {
+        await approvals.chat.grant({ key: keys.chatKey, grantedAt });
+        return true;
+    }
+    if (choice === "always" && keys.alwaysKey && approvals.always) {
+        await approvals.always.upsert({
+            ...keys.alwaysKey, fingerprint: keys.fingerprint, grantedByPrincipalId: context.principal.id, grantedAt,
+        }, scopeOption(options.scope));
+        return true;
+    }
+    return false;
+}
+/** Saves one explicitly chosen grant, then notifies. Save and notification failures are reported
+ *  via `onPersistenceError` and never fail the already approved call. */
+export async function rememberApproval(input) {
+    const { context, request, keys, choice, options } = input;
+    // Defense in depth: a forged remember choice must not persist a destructive call's approval.
+    if (request.destructive || request.writeShapedInputs.length > 0)
+        return;
+    let grantedAt;
+    try {
+        grantedAt = nowIso({ clock: input.approvals.clock });
+        if (!await persistGrant(input, grantedAt))
+            return;
+    }
+    catch (error) {
+        report(options, { toolId: request.toolId, choice, stage: "store", error });
+        return;
+    }
+    try {
+        await options.webhooks?.approvalRemembered({ principalId: context.principal.id,
+            connectionId: request.connectionId, toolName: request.remoteName, fingerprint: keys.fingerprint, scope: choice, grantedAt }, scopeOption(options.scope));
+    }
+    catch (error) {
+        report(options, { toolId: request.toolId, choice, stage: "webhook", error });
+    }
+}
+//# sourceMappingURL=remembered-approval.js.map

package/dist/federation/approvals/revocation-reason.d.ts

@@ -0,0 +1,9 @@
+import type { ToolRefusalReason } from "../trust.js";
+import type { ExternalMcpRevocationReason } from "./revocation.js";
+/** Maps an admitted tool's refusal under the row's current grants to the revocation reason the
+ *  gate reports. `refusalForAdmittedToolUnderCurrentGrants` no longer produces
+ *  `"remote-declares-not-read-only"` (hints never refuse since G3), but the union still carries it,
+ *  so the mapping keeps it rather than collapsing a write refusal into "tool-not-allowed".
+ *  @complexity O(1). */
+export declare function revocationReasonForToolRefusal(refusal: ToolRefusalReason | null): ExternalMcpRevocationReason | null;
+//# sourceMappingURL=revocation-reason.d.ts.map

package/dist/federation/approvals/revocation-reason.js

@@ -0,0 +1,11 @@
+/** Maps an admitted tool's refusal under the row's current grants to the revocation reason the
+ *  gate reports. `refusalForAdmittedToolUnderCurrentGrants` no longer produces
+ *  `"remote-declares-not-read-only"` (hints never refuse since G3), but the union still carries it,
+ *  so the mapping keeps it rather than collapsing a write refusal into "tool-not-allowed".
+ *  @complexity O(1). */
+export function revocationReasonForToolRefusal(refusal) {
+    if (refusal === null)
+        return null;
+    return refusal === "remote-declares-not-read-only" ? "write-not-allowed" : "tool-not-allowed";
+}
+//# sourceMappingURL=revocation-reason.js.map

package/dist/federation/approvals/revocation.js

@@ -1,4 +1,6 @@
 import { refusalForAdmittedToolUnderCurrentGrants } from "../trust.js";
+import { revocationReasonForToolRefusal } from "./revocation-reason.js";
+import { scopeOption } from "./scope-option.js";
 /** Pure current-row check. Ordering matches admission semantics: identity before mutable grants. */
 export function rosterRefusalFor({ record, call }) {
     if (call.origin === undefined || call.origin.kind === "preset")
@@ -11,8 +13,21 @@ export function rosterRefusalFor({ record, call }) {
         return "turned-off";
     if (record.disconnected)
         return "disconnected";
-    const refusal = refusalForAdmittedToolUnderCurrentGrants({ tool: call, grants: record.grants });
-    return refusal === null ? null : refusal === "remote-declares-not-read-only" ? "write-not-allowed" : "tool-not-allowed";
+    return revocationReasonForToolRefusal(refusalForAdmittedToolUnderCurrentGrants({ tool: call, grants: record.grants }));
+}
+/** One roster read plus its refusal. A failed read or check is reported and fails closed as
+ *  `"unverifiable"`, so the driver error never reaches the refusal. @complexity O(1). */
+async function readRosterRefusal({ roster, connectionId, call }, { scope, report }) {
+    // A row that was read but cannot be judged keeps its label on the refusal.
+    let record = null;
+    try {
+        record = await roster.findByServerId({ serverId: connectionId }, scopeOption(scope));
+        return { record, reason: rosterRefusalFor({ record, call }) };
+    }
+    catch (error) {
+        report({ connectionId, stage: "store", error });
+        return { record, reason: "unverifiable" };
+    }
 }
 /** Revocation half of a connection gate; credential refresh/reauth checks are composed by the host.
  * Presets have no roster row. Reads and notification failures never disclose driver errors.
@@ -27,21 +42,12 @@ export function createFederatedConnectionRevocationGate(required, optional = {})
     return async ({ connectionId, call }) => {
         if (call.origin?.kind === "preset")
             return;
-        let record = null;
-        let reason;
-        try {
-            record = await required.roster.findByServerId({ serverId: connectionId }, optional.scope === undefined ? {} : { scope: optional.scope });
-            reason = rosterRefusalFor({ record, call });
-        }
-        catch (error) {
-            report({ connectionId, stage: "store", error });
-            reason = "unverifiable";
-        }
+        const { record, reason } = await readRosterRefusal({ roster: required.roster, connectionId, call }, { scope: optional.scope, report });
         if (reason === null)
             return;
         const refusal = { serverId: connectionId, label: record?.label ?? null, remoteName: call.remoteName, reason };
         try {
-            await optional.webhooks?.connectionRefused(refusal, optional.scope === undefined ? {} : { scope: optional.scope });
+            await optional.webhooks?.connectionRefused(refusal, scopeOption(optional.scope));
         }
         catch (error) {
             report({ connectionId, stage: "webhook", error });

package/dist/federation/approvals/scope-option.d.ts

@@ -0,0 +1,6 @@
+/** The opaque host storage partition as a port's options object: `{}` when absent, so a port
+ *  never receives `{ scope: undefined }`. @complexity O(1). */
+export declare function scopeOption(scope: string | undefined): {
+    scope?: string;
+};
+//# sourceMappingURL=scope-option.d.ts.map

package/dist/federation/approvals/scope-option.js

@@ -0,0 +1,6 @@
+/** The opaque host storage partition as a port's options object: `{}` when absent, so a port
+ *  never receives `{ scope: undefined }`. @complexity O(1). */
+export function scopeOption(scope) {
+    return scope === undefined ? {} : { scope };
+}
+//# sourceMappingURL=scope-option.js.map

package/dist/federation/stdio/adapter.stdio.js

@@ -493,19 +493,27 @@ const ELECTRON_RUN_AS_NODE = "ELECTRON_RUN_AS_NODE";
  * @complexity O(k) in the number of inherited names.
  */
 export function buildMcpChildEnv({ command, specEnv, }, { launchEnv = {}, platform = process.platform, parentEnv = process.env, execPath = process.execPath, } = {}) {
-    const isWin32 = platform === "win32";
-    const names = isWin32 ? [...INHERITED_ENV_VARS, ...WIN32_INHERITED_ENV_VARS] : INHERITED_ENV_VARS;
+    return { ...inheritedParentEnv(parentEnv, platform), ...carriedRunMode({ command, platform, parentEnv, execPath }), ...launchEnv, ...specEnv };
+}
+/** The allowlisted parent variables ({@link INHERITED_ENV_VARS}, plus
+ *  {@link WIN32_INHERITED_ENV_VARS} on win32). Empty parent values are skipped. @complexity O(k). */
+function inheritedParentEnv(parentEnv, platform) {
+    const names = platform === "win32" ? [...INHERITED_ENV_VARS, ...WIN32_INHERITED_ENV_VARS] : INHERITED_ENV_VARS;
     const inherited = {};
     for (const name of names) {
         const value = parentEnv[name];
         if (typeof value === "string" && value.length > 0)
             inherited[name] = value;
     }
+    return inherited;
+}
+/** `ELECTRON_RUN_AS_NODE` for a win32 child that is this very executable while this process runs
+ *  with it set (see {@link buildMcpChildEnv}); `{}` for every other child. @complexity O(n) in the path length. */
+function carriedRunMode({ command, platform, parentEnv, execPath }) {
     const runMode = parentEnv[ELECTRON_RUN_AS_NODE];
-    if (isWin32 && typeof runMode === "string" && runMode.length > 0 && isSameWin32Path(command, execPath)) {
-        inherited[ELECTRON_RUN_AS_NODE] = runMode;
-    }
-    return { ...inherited, ...launchEnv, ...specEnv };
+    if (platform !== "win32" || typeof runMode !== "string" || runMode.length === 0)
+        return {};
+    return isSameWin32Path(command, execPath) ? { [ELECTRON_RUN_AS_NODE]: runMode } : {};
 }
 /** Whether two win32 paths name the same file: resolved, then compared case-insensitively, as
  *  Windows' own file system does. @complexity O(n) in the path length. */

package/dist/federation/stdio/default-connect.js

@@ -58,35 +58,32 @@ async function connectMcpStdioSessionWithSpawnTimeout(connection, launch, resolv
     const timeoutError = () => new Error(`connect timed out after ${timeoutMs}ms`);
     let channel;
     let timer;
-    try {
-        return await Promise.race([
-            Promise.resolve().then(() => {
-                // Synchronous ports cannot be interrupted by a JS timer. Check elapsed time after each
-                // returns so a slow resolver cannot spawn, and a late spawn cannot begin the handshake.
-                const resolved = resolver.resolve({ spec: launch });
-                if (Date.now() >= deadline)
-                    throw timeoutError();
-                channel = spawnChannel({ resolved });
-                if (Date.now() >= deadline)
-                    throw timeoutError();
-                return connectMcpStdioSession({ channel, requestTimeoutMs: connection.config.callTimeoutMs, clientInfo, messages });
-            }),
-            // Not `unref()`ed, for the same reason as `adapter.stdio.ts`'s per-request timer: an unref'd
-            // timer would let the loop drain and abandon this race unsettled instead of rejecting. The
-            // `finally` below clears it either way, so it never outlives the connect attempt.
-            new Promise((_resolve, reject) => {
-                timer = setTimeout(() => reject(timeoutError()), timeoutMs);
-            }),
-        ]);
-    }
-    catch (error) {
+    // Promise `.catch`/`.finally` rather than try/catch/finally: same settle semantics, and no
+    // statement follows the rethrow, so the coverage report has no phantom post-throw range.
+    return Promise.race([
+        Promise.resolve().then(() => {
+            // Synchronous ports cannot be interrupted by a JS timer. Check elapsed time after each
+            // returns so a slow resolver cannot spawn, and a late spawn cannot begin the handshake.
+            const resolved = resolver.resolve({ spec: launch });
+            if (Date.now() >= deadline)
+                throw timeoutError();
+            channel = spawnChannel({ resolved });
+            if (Date.now() >= deadline)
+                throw timeoutError();
+            return connectMcpStdioSession({ channel, requestTimeoutMs: connection.config.callTimeoutMs, clientInfo, messages });
+        }),
+        // Not `unref()`ed, for the same reason as `adapter.stdio.ts`'s per-request timer: an unref'd
+        // timer would let the loop drain and abandon this race unsettled instead of rejecting. The
+        // `finally` below clears it either way, so it never outlives the connect attempt.
+        new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+        }),
+    ])
+        .catch((error) => {
         // Whichever branch lost, the child process must not survive it.
         channel?.close({});
         throw error;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
+    })
+        .finally(() => clearTimeout(timer));
 }
 //# sourceMappingURL=default-connect.js.map

package/dist/federation/stdio/stdio-launch-resolver.d.ts

@@ -74,8 +74,8 @@ export declare const IDENTITY_STDIO_LAUNCH_RESOLVER: McpStdioLaunchResolver;
 /** {@link createBundledNodeLaunchResolver}'s config. Only `toolchainDir` and `npmRoot` are ever
  * passed in production; the rest are test seams that default to the real process. */
 export interface BundledNodeLaunchResolverConfig {
-    /** `toolchain env option`: holds `bin/` (shims), `npm-cache/`, `npm-prefix/`. */
     readonly messages: FederationMessages;
+    /** `toolchain env option`: holds `bin/` (shims), `npm-cache/`, `npm-prefix/`. */
     readonly toolchainDir: string;
     /** `npm root env option`: the npm package root; `<npmRoot>/bin/npx-cli.js` must exist (checked
      * by {@link stdioLaunchResolverFromEnv} before this is constructed, not here). */

package/dist/federation/stdio/stdio-launch-resolver.js

@@ -44,6 +44,8 @@ export const IDENTITY_STDIO_LAUNCH_RESOLVER = {
         return { command: spec.command, args: spec.args, cwd: spec.cwd, env: spec.env, launchEnv: {} };
     },
 };
+/** The npm CLI script each toolchain command runs on Electron's Node; `node` runs its args as-is. */
+const NODE_TOOLCHAIN_CLI = { npx: "npx-cli.js", npm: "npm-cli.js", node: null };
 /** @complexity O(1). */
 function matchNodeToolchainCommand(command, platform) {
     const isWin32 = platform === "win32";
@@ -133,6 +135,15 @@ function findOnSearchDirs(command, searchDirs, pathModule, isExecutable) {
 function isPathCommand(command, pathModule) {
     return pathModule.isAbsolute(command) || command.includes("/") || (pathModule === path.win32 && command.includes("\\"));
 }
+/** The executable a non-toolchain `command` names, or `null` when nothing executable is there. A
+ *  path command is checked only where the child will exec it (never searched); a bare name is
+ *  searched on `searchDirs`. @complexity O(n) in `searchDirs.length`. */
+function findExecutable({ command, cwd }, { pathModule, searchDirs, isExecutable }) {
+    if (!isPathCommand(command, pathModule))
+        return findOnSearchDirs(command, searchDirs, pathModule, isExecutable);
+    // A relative path runs against the child's own cwd, so that is where it has to exist.
+    return isExecutable({ candidatePath: pathModule.resolve(cwd ?? process.cwd(), command) }) ? command : null;
+}
 /**
  * The desktop resolver: rewrites `npx`/`npm`/`node` to run on Electron's own Node via the bundled
  * npm package, resolves any other bare command (`uvx`, `docker`, …) against a PATH widened with
@@ -158,18 +169,11 @@ export function createBundledNodeLaunchResolver({ messages, toolchainDir, npmRoo
         resolve({ spec }) {
             const nodeToolchainCommand = matchNodeToolchainCommand(spec.command, platform);
             if (nodeToolchainCommand !== null) {
-                const cli = nodeToolchainCommand === "npx" ? "npx-cli.js" : nodeToolchainCommand === "npm" ? "npm-cli.js" : null;
+                const cli = NODE_TOOLCHAIN_CLI[nodeToolchainCommand];
                 const args = cli === null ? [...spec.args] : [pathModule.join(npmRoot, "bin", cli), ...spec.args];
                 return { command: execPath, args, cwd: spec.cwd, env: spec.env, launchEnv: nodeToolchainLaunchEnv, requestedCommand: spec.command };
             }
-            if (isPathCommand(spec.command, pathModule)) {
-                // A relative path runs against the child's own cwd, so that is where it has to exist.
-                if (!isExecutable({ candidatePath: pathModule.resolve(spec.cwd ?? process.cwd(), spec.command) })) {
-                    throw new McpLaunchUnavailableError({ message: messages.launchUnavailable({ command: spec.command, searchedDirs: searchDirs }) });
-                }
-                return { command: spec.command, args: [...spec.args], cwd: spec.cwd, env: spec.env, launchEnv: otherLaunchEnv };
-            }
-            const found = findOnSearchDirs(spec.command, searchDirs, pathModule, isExecutable);
+            const found = findExecutable({ command: spec.command, cwd: spec.cwd }, { pathModule, searchDirs, isExecutable });
             if (found === null) {
                 throw new McpLaunchUnavailableError({ message: messages.launchUnavailable({ command: spec.command, searchedDirs: searchDirs }) });
             }

package/dist/federation/tool-approvals.js

@@ -6,7 +6,9 @@ function canonicalJson(value) {
     if (value !== null && typeof value === "object") {
         const entries = Object.entries(value)
             .filter(([, child]) => child !== undefined)
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+            // Object.entries never yields the same key twice, so two keys are never equal and a
+            // two-way comparison is a total order here.
+            .sort(([a], [b]) => (a < b ? -1 : 1));
         return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
     }
     return JSON.stringify(value) ?? "null";

package/dist/federation/trust.d.ts

@@ -297,6 +297,10 @@ export declare function writeShapedSchemaInputNames({ schema }: {
  * SQL tools are classified by the statement, so SELECT/CREATE are not blocked by destructive hints.
  * Unknown destructive tools keep their card until their irreversible behavior can be classified.
  * This decision never grants admission, permissions or descriptor readOnly.
+ * The rule ORDER is the policy: delivery and system-prompt changes always card, even when named
+ * like a read; a read verb (after an assistant/agent prefix) skips the card unless the remote
+ * declares it destructive; assistant-access changes card; SQL is decided by its statements;
+ * only then do removal names and the destructive hint decide.
  * @complexity O(n) in the serialized input size.
  */
 export declare function federatedCallConfirmationForAction({ remoteName, annotations, args }: {
@@ -326,6 +330,23 @@ export declare function refusalForAdmittedToolUnderCurrentGrants({ tool, grants
         readonly writeAllowedToolNames: readonly string[];
     };
 }): ToolRefusalReason | null;
+/**
+ * R2 + R3 + R4 + R6, applied to one remote server's advertised surface. The gate.
+ *
+ * Order matters and is deliberate: name validity, then the operator allowlist, then the remote's
+ * own hints (including the write-list override), then the schema. The allowlist is consulted
+ * BEFORE the hints so that the common refusal ("we never asked for this tool") is the one reported,
+ * rather than a confusing complaint about the annotations of a tool nobody wanted anyway — and so a
+ * tool named in `writeAllowedToolNames` but not in `allowedToolNames` can NEVER be admitted by the
+ * write list alone : the allowlist check runs and refuses it before the write list is ever
+ * read.
+ *
+ * @param params.tools - The remote's `tools/list`, verbatim and untrusted.
+ * @param params.config - The site owner's connection config, the trusted side.
+ * @returns Every admitted tool plus a full accounting of what was refused and why.
+ * @complexity O(t) in the advertised tool count.
+ * See docs/decisions/DR-001-federation-admission.md.
+ */
 export declare function admitRemoteTools(params: {
     tools: readonly RemoteToolDescriptor[];
     config: FederatedMcpConnectionConfig;
@@ -390,10 +411,10 @@ export declare function describeRemoteToolSurface(params: {
  *
  * @complexity O(n) in the description length, capped.
  */
-export declare function describeFederatedTool(requiredArgs: {
+export declare function describeFederatedTool({ label, remoteName }: {
     label: string;
     remoteName: string;
-}, optionalArgs?: {
+}, { remoteDescription }?: {
     remoteDescription?: string | undefined;
 }): string;
 /**