@akira-tl/forgerelay 1.1.0 → 1.1.1

package/dist/mcp/operations/external-mcp/external-mcp.js

@@ -1,45 +1,48 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createHash } from "node:crypto";
+import { AuthorizationServerMismatchError, Client, InsufficientScopeError, SdkHttpError, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/client/stdio";
+import { CallToolResultSchema } from "@modelcontextprotocol/core";
+import { externalMcpCredentialIdentity, } from "../../../runtime/config/external-mcp-auth-store.js";
 import { claimMediaBytes, createMediaBudget, isSupportedImageMimeType, strictBase64ByteLength, } from "../media-content.js";
 import { ExternalMcpTransformError, } from "../../hooks/external-mcp-transform.js";
+import { ExternalMcpOAuthError, createExternalMcpRuntimeAuth, externalMcpAuthError, markExternalMcpAuthorizationRequired, markExternalMcpReauthorization, } from "./external-mcp-oauth.js";
 const MAX_DISCOVERED_TOOLS = 100;
 const MAX_TOOL_DESCRIPTION_CHARS = 2_000;
 const MAX_TOOL_SCHEMA_BYTES = 64 * 1024;
 const MAX_TOOL_DISCOVERY_PAGES = 16;
+const LEGACY_NEGOTIATION_TTL_MS = 5 * 60 * 1_000;
 export class ExternalMcpError extends Error {
     code;
-    constructor(code, message) {
+    detail;
+    constructor(code, message, detail) {
         super(message);
         this.code = code;
+        this.detail = detail;
         this.name = "ExternalMcpError";
     }
 }
 export class ExternalMcpGateway {
-    servers;
     mediaMaxBytes;
-    constructor(servers, mediaMaxBytes) {
-        this.servers = servers;
+    credentialStore;
+    negotiationCache = new Map();
+    constructor(mediaMaxBytes, credentialStore) {
         this.mediaMaxBytes = mediaMaxBytes;
+        this.credentialStore = credentialStore;
     }
-    get available() {
-        return Object.keys(this.servers).length > 0;
-    }
-    async run(input, signal, transforms) {
+    async run(servers, input, signal, transforms, authContext) {
         signal?.throwIfAborted();
         switch (input.operation) {
             case "servers":
                 return {
                     value: {
                         operation: "servers",
-                        servers: Object.entries(this.servers)
+                        servers: Object.entries(servers)
                             .sort(([left], [right]) => left.localeCompare(right))
                             .map(([name, server]) => ({ name, transport: server.transport })),
                     },
                 };
             case "tools":
-                return this.withClient(input.server, signal, async (client) => {
+                return this.withClient(servers, input.server, signal, authContext, async (client) => {
                     const discovery = await discoverTools(client, signal);
                     return {
                         value: {
@@ -51,7 +54,7 @@ export class ExternalMcpGateway {
                     };
                 });
             case "call":
-                return this.withClient(input.server, signal, async (client) => {
+                return this.withClient(servers, input.server, signal, authContext, async (client) => {
                     await assertRegisteredTool(client, input.server, input.tool, signal);
                     const appliedTransforms = [];
                     let callArguments = input.arguments ?? {};
@@ -60,7 +63,7 @@ export class ExternalMcpGateway {
                         callArguments = transformed.value;
                         appliedTransforms.push(...transformed.transforms);
                     }
-                    let result = await client.callTool({ name: input.tool, arguments: callArguments }, undefined, { signal });
+                    let result = await client.callTool({ name: input.tool, arguments: callArguments }, { signal });
                     assertCallToolResult(input.server, input.tool, result);
                     if (result.isError) {
                         throw new ExternalMcpError("tool_failed", `External MCP ${input.server} tool ${input.tool} returned an upstream tool error.`);
@@ -91,31 +94,146 @@ export class ExternalMcpGateway {
                 });
         }
     }
-    async withClient(name, signal, operation) {
-        const config = this.servers[name];
+    async probe(servers, name, signal, authContext) {
+        return this.withClient(servers, name, signal, authContext, async (client) => {
+            let discovery;
+            try {
+                discovery = await discoverTools(client, signal);
+            }
+            catch (error) {
+                if (isExternalMcpAuthTransportError(error))
+                    throw error;
+                throw new ExternalMcpError("tool_discovery_failed", `External MCP ${name} tool discovery failed.`, externalMcpFailureDetail(error));
+            }
+            return {
+                protocolEra: client.getProtocolEra() ?? "unknown",
+                ...(client.getNegotiatedProtocolVersion()
+                    ? { protocolVersion: client.getNegotiatedProtocolVersion() }
+                    : {}),
+                toolCount: discovery.tools.length,
+                truncated: discovery.truncated,
+            };
+        });
+    }
+    async withClient(servers, name, signal, authContext, operation) {
+        const config = servers[name];
         if (!config)
             throw new ExternalMcpError("unknown_server", `Unknown configured external MCP server: ${name}.`);
-        const client = new Client({ name: "forgerelay-external-mcp", version: "1.0.0" });
-        const transport = createTransport(config);
+        const fingerprint = externalMcpServerFingerprint(config);
+        const runtimeAuth = this.resolveRuntimeAuth(name, config, authContext);
+        const client = new Client({ name: "forgerelay-external-mcp", version: "1.0.0" }, { versionNegotiation: { mode: "auto" } });
+        const transport = createTransport(config, runtimeAuth?.authProvider);
+        const prior = this.cachedPrior(name, fingerprint);
         try {
             signal?.throwIfAborted();
-            await client.connect(transport);
+            await client.connect(transport, prior ? { prior } : undefined);
+            this.rememberNegotiation(name, fingerprint, client);
             signal?.throwIfAborted();
             return await operation(client);
         }
         catch (error) {
             if (error instanceof ExternalMcpError || error instanceof ExternalMcpTransformError)
                 throw error;
+            this.invalidateNegotiation(name, fingerprint);
             if (signal?.aborted)
                 signal.throwIfAborted();
-            throw new ExternalMcpError("transport_failed", `External MCP ${name} request failed.`);
+            if (error instanceof ExternalMcpOAuthError) {
+                throw new ExternalMcpError(error.code, error.message);
+            }
+            const authError = externalMcpAuthError(name, error, runtimeAuth);
+            if (authError) {
+                if (this.credentialStore) {
+                    if (authError.code === "auth_required") {
+                        await markExternalMcpAuthorizationRequired(this.credentialStore, runtimeAuth).catch(() => undefined);
+                    }
+                    else if (error instanceof InsufficientScopeError) {
+                        await markExternalMcpReauthorization(this.credentialStore, runtimeAuth, "insufficient_scope", { ...(error.requiredScope ? { scope: error.requiredScope } : {}) }).catch(() => undefined);
+                    }
+                    else if (runtimeAuth?.bindingMismatch || error instanceof AuthorizationServerMismatchError) {
+                        await markExternalMcpReauthorization(this.credentialStore, runtimeAuth, "binding_changed").catch(() => undefined);
+                    }
+                }
+                throw new ExternalMcpError(authError.code, authError.message);
+            }
+            throw new ExternalMcpError("transport_failed", `External MCP ${name} request failed.`, externalMcpFailureDetail(error));
         }
         finally {
             await client.close().catch(() => undefined);
         }
     }
+    resolveRuntimeAuth(name, config, context) {
+        if (!this.credentialStore || !context || config.transport !== "streamable-http")
+            return undefined;
+        if (hasStaticAuthorizationHeader(config.headers))
+            return undefined;
+        const source = context.origins[name];
+        if (!source)
+            return undefined;
+        const identity = externalMcpCredentialIdentity(source, name, context.workspaceRoot);
+        return createExternalMcpRuntimeAuth(this.credentialStore, identity, config.url);
+    }
+    cachedPrior(name, fingerprint) {
+        const cached = this.negotiationCache.get(name);
+        if (!cached || cached.fingerprint !== fingerprint) {
+            if (cached)
+                this.negotiationCache.delete(name);
+            return undefined;
+        }
+        if (cached.prior.kind === "legacy" &&
+            Date.now() - cached.cachedAt >= LEGACY_NEGOTIATION_TTL_MS) {
+            this.negotiationCache.delete(name);
+            return undefined;
+        }
+        return cached.prior;
+    }
+    rememberNegotiation(name, fingerprint, client) {
+        const era = client.getProtocolEra();
+        if (era === "legacy") {
+            this.negotiationCache.set(name, {
+                fingerprint,
+                prior: { kind: "legacy" },
+                cachedAt: Date.now(),
+            });
+            return;
+        }
+        if (era !== "modern")
+            return;
+        const discover = client.getDiscoverResult();
+        if (!discover)
+            return;
+        this.negotiationCache.set(name, {
+            fingerprint,
+            prior: { kind: "modern", discover },
+            cachedAt: Date.now(),
+        });
+    }
+    invalidateNegotiation(name, fingerprint) {
+        const cached = this.negotiationCache.get(name);
+        if (cached?.fingerprint === fingerprint)
+            this.negotiationCache.delete(name);
+    }
+}
+function externalMcpServerFingerprint(config) {
+    const normalized = config.transport === "stdio"
+        ? {
+            transport: config.transport,
+            command: config.command,
+            args: config.args ?? [],
+            cwd: config.cwd ?? null,
+            env: sortedStringRecord(config.env),
+        }
+        : {
+            transport: config.transport,
+            url: config.url,
+            headers: sortedStringRecord(config.headers),
+            oauth: config.oauth ?? null,
+        };
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+function sortedStringRecord(value) {
+    return Object.fromEntries(Object.entries(value ?? {}).sort(([left], [right]) => left.localeCompare(right)));
 }
-function createTransport(config) {
+function createTransport(config, authProvider) {
     if (config.transport === "stdio") {
         return new StdioClientTransport({
             command: config.command,
@@ -129,8 +247,45 @@ function createTransport(config) {
     }
     return new StreamableHTTPClientTransport(new URL(config.url), {
         ...(config.headers ? { requestInit: { headers: config.headers } } : {}),
+        ...(authProvider ? { authProvider } : {}),
+        onInsufficientScope: "throw",
     });
 }
+function hasStaticAuthorizationHeader(headers) {
+    return Object.keys(headers ?? {}).some((name) => name.toLowerCase() === "authorization");
+}
+function isExternalMcpAuthTransportError(error) {
+    return error instanceof ExternalMcpOAuthError
+        || error instanceof InsufficientScopeError
+        || error instanceof AuthorizationServerMismatchError
+        || error instanceof UnauthorizedError
+        || (error instanceof SdkHttpError && error.status === 401);
+}
+function externalMcpFailureDetail(error) {
+    if (error instanceof SdkHttpError)
+        return `HTTP ${error.status}`;
+    const code = nestedErrorCode(error);
+    if (code && code !== "ERA_NEGOTIATION_FAILED")
+        return code;
+    if (error instanceof Error && /tim(?:e|ed)\s*out|timeout/i.test(error.message))
+        return "timeout";
+    return undefined;
+}
+function nestedErrorCode(error, depth = 0) {
+    if (depth > 4 || typeof error !== "object" || error === null)
+        return undefined;
+    if ("cause" in error) {
+        const nested = nestedErrorCode(error.cause, depth + 1);
+        if (nested)
+            return nested;
+    }
+    if ("code" in error) {
+        const code = error.code;
+        if (typeof code === "string" && /^[A-Z][A-Z0-9_]{1,39}$/.test(code))
+            return code;
+    }
+    return undefined;
+}
 async function discoverTools(client, signal) {
     const tools = [];
     let cursor;

package/dist/mcp/operations/native-bulk-mutations.js

@@ -60,7 +60,7 @@ export class NativeBulkMutationExecutor {
         return this.dependencies.lifecycle.run({
             tool,
             workspace: workspaceSnapshot(workspace),
-            conversationScopeId: openAiConversationScopeId(context.requestMeta),
+            conversationScopeId: context.conversationScopeId ?? openAiConversationScopeId(context.requestMeta),
             request,
             operation,
             outcome,

package/dist/mcp/process/tools.js

@@ -1,5 +1,6 @@
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import * as z from "zod/v4";
+import { mcpHandlerRequestContext } from "../request-context.js";
 import { runToolWithHooks } from "../hooks/hooks.js";
 import { commandPreview, logEvent, workspaceLogLabel } from "../../runtime/logging/logger.js";
 import { resolveProcessId } from "./process-sessions.js";
@@ -50,9 +51,10 @@ function registerBashTool(options) {
         _meta: {},
         annotations: SHELL_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, member, action = "run", command, processId, outputId, input, interrupt, tty, columns, rows, workingDirectory, yieldTimeMs, timeoutMs, maxOutputTokens, }, extra) => {
+        const requestContext = mcpHandlerRequestContext(extra);
         const target = routing.resolve(workspaceId, member);
         const executionWorkspaceId = target.executionWorkspaceId;
-        const executionContext = await routing.prepare(target, extra._meta, extra.signal, extra.sessionId);
+        const executionContext = await routing.prepare(target, requestContext);
         if (routing.isRemote(executionWorkspaceId)) {
             const response = await routing.bashRemote(executionWorkspaceId, {
                 action,
@@ -68,9 +70,9 @@ function registerBashTool(options) {
                 ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
-            }, routing.hostScopeIdFor(extra._meta, extra.sessionId));
+            }, routing.hostScopeIdFor(requestContext));
             return action === "run"
-                ? routing.presentSemantic(response, target, routing.hostScopeIdFor(extra._meta, extra.sessionId))
+                ? routing.presentSemantic(response, target, routing.hostScopeIdFor(requestContext))
                 : routing.present(response, target);
         }
         const workspace = workspaces.getWorkspace(executionWorkspaceId);
@@ -91,7 +93,7 @@ function registerBashTool(options) {
                 yieldTimeMs,
                 timeoutMs,
                 maxOutputTokens,
-            }, executionContext), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
+            }, executionContext), target, routing.hostScopeIdFor(requestContext));
         }
         if (action === "output") {
             if (!outputId)
@@ -102,7 +104,7 @@ function registerBashTool(options) {
                 throw new Error("bash action=output accepts only workspaceId and outputId.");
             }
             return runToolWithHooks(hooks, {
-                signal: extra.signal,
+                signal: requestContext.signal,
                 tool: toolNames.shell,
                 invocation: workspaceHookInvocation(workspace),
                 payload: { action, outputId },
@@ -120,7 +122,7 @@ function registerBashTool(options) {
             throw new Error("bash action=process cannot combine interrupt with input.");
         }
         return runToolWithHooks(hooks, {
-            signal: extra.signal,
+            signal: requestContext.signal,
             tool: toolNames.shell,
             invocation: workspaceHookInvocation(workspace),
             payload: {
@@ -142,7 +144,7 @@ function registerBashTool(options) {
                     rows,
                     yieldTimeMs,
                     maxOutputTokens,
-                    signal: extra.signal,
+                    signal: requestContext.signal,
                 });
                 logProcessToolCall(config, workspace, {
                     tool: toolNames.shell,
@@ -190,8 +192,9 @@ function registerCodexProcessTools(options) {
         _meta: {},
         annotations: SHELL_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, member, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, timeoutMs, maxOutputTokens }, extra) => {
+        const requestContext = mcpHandlerRequestContext(extra);
         const target = routing.resolve(workspaceId, member);
-        const context = await routing.prepare(target, extra._meta, extra.signal, extra.sessionId);
+        const context = await routing.prepare(target, requestContext);
         if (routing.isRemote(target.executionWorkspaceId)) {
             return routing.presentSemantic(await routing.execCommandRemote(target.executionWorkspaceId, {
                 cmd,
@@ -202,7 +205,7 @@ function registerCodexProcessTools(options) {
                 ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
-            }, routing.hostScopeIdFor(extra._meta, extra.sessionId)), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
+            }, routing.hostScopeIdFor(requestContext)), target, routing.hostScopeIdFor(requestContext));
         }
         return routing.presentSemantic(await shellRun({
             workspaceId: target.executionWorkspaceId,
@@ -215,7 +218,7 @@ function registerCodexProcessTools(options) {
             yieldTimeMs,
             timeoutMs,
             maxOutputTokens,
-        }, context), target, routing.hostScopeIdFor(extra._meta, extra.sessionId));
+        }, context), target, routing.hostScopeIdFor(requestContext));
     });
     registerAppTool(server, "write_stdin", {
         title: "Write to process",
@@ -236,8 +239,9 @@ function registerCodexProcessTools(options) {
         _meta: {},
         annotations: SHELL_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, member, processId, sessionId, outputId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
+        const requestContext = mcpHandlerRequestContext(extra);
         const target = routing.resolve(workspaceId, member);
-        await routing.prepare(target, extra._meta, extra.signal, extra.sessionId);
+        await routing.prepare(target, requestContext);
         if (routing.isRemote(target.executionWorkspaceId)) {
             return routing.present(await routing.writeStdinRemote(target.executionWorkspaceId, {
                 ...(processId !== undefined ? { processId } : {}),
@@ -248,7 +252,7 @@ function registerCodexProcessTools(options) {
                 ...(rows !== undefined ? { rows } : {}),
                 ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
                 ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
-            }, routing.hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            }, routing.hostScopeIdFor(requestContext)), target);
         }
         const executionWorkspaceId = target.executionWorkspaceId;
         const workspace = workspaces.getWorkspace(executionWorkspaceId);
@@ -258,7 +262,7 @@ function registerCodexProcessTools(options) {
                 throw new Error("write_stdin outputId lookup cannot be combined with process control fields.");
             }
             return runToolWithHooks(hooks, {
-                signal: extra.signal,
+                signal: requestContext.signal,
                 tool: "write_stdin",
                 invocation: workspaceHookInvocation(workspace),
                 payload: { outputId },
@@ -267,7 +271,7 @@ function registerCodexProcessTools(options) {
         }
         const resolvedProcessId = resolveProcessId(processId, sessionId);
         return runToolWithHooks(hooks, {
-            signal: extra.signal,
+            signal: requestContext.signal,
             tool: "write_stdin",
             invocation: workspaceHookInvocation(workspace),
             payload: {
@@ -286,7 +290,7 @@ function registerCodexProcessTools(options) {
                     rows,
                     yieldTimeMs,
                     maxOutputTokens,
-                    signal: extra.signal,
+                    signal: requestContext.signal,
                 });
                 logProcessToolCall(config, workspace, {
                     tool: "write_stdin",

package/dist/mcp/request-context.js

@@ -0,0 +1,18 @@
+export function mcpHandlerRequestContext(extra) {
+    if ("mcpReq" in extra) {
+        return {
+            requestMeta: extra.mcpReq._meta,
+            signal: extra.mcpReq.signal,
+            transportSessionId: extra.sessionId,
+            requestId: extra.mcpReq.id,
+            protocolEra: extra.mcpReq.envelope === undefined ? "legacy" : "modern",
+        };
+    }
+    return {
+        requestMeta: extra._meta,
+        signal: extra.signal,
+        transportSessionId: extra.sessionId,
+        requestId: extra.requestId,
+        protocolEra: "legacy",
+    };
+}

package/dist/mcp/request-meta.js

@@ -1,3 +1,4 @@
+export const FORGERELAY_CONVERSATION_META_KEY = "dev.forgerelay/conversation";
 function metadataString(meta, key) {
     if (typeof meta !== "object" || meta === null)
         return undefined;
@@ -7,7 +8,31 @@ function metadataString(meta, key) {
 export function openAiConversationScopeId(meta) {
     return metadataString(meta, "openai/session");
 }
-export function hostConversationScopeId(meta, transportSessionId, connectionScopeId) {
-    return openAiConversationScopeId(meta)
-        ?? (transportSessionId ? `mcp-session:${transportSessionId}` : connectionScopeId);
+export function forgeRelayConversationScopeId(meta) {
+    const value = metadataString(meta, FORGERELAY_CONVERSATION_META_KEY);
+    return value ? `forgerelay-conversation:${value}` : undefined;
+}
+function stableHostConversationScopeId(context) {
+    return openAiConversationScopeId(context.requestMeta)
+        ?? forgeRelayConversationScopeId(context.requestMeta);
+}
+function modernRequestScopeId(context, connectionScopeId) {
+    return `mcp-request:${connectionScopeId}:${String(context.requestId ?? "unknown")}`;
+}
+export function hostConversationScopeId(context, connectionScopeId) {
+    const stableScope = stableHostConversationScopeId(context);
+    if (stableScope)
+        return stableScope;
+    if (context.protocolEra === "modern")
+        return modernRequestScopeId(context, connectionScopeId);
+    const transportSessionId = context.transportSessionId ?? context.sessionId;
+    return transportSessionId ? `mcp-session:${transportSessionId}` : connectionScopeId;
+}
+export function hostContextDeliveryScopeId(context, connectionScopeId) {
+    const stableScope = stableHostConversationScopeId(context);
+    if (stableScope)
+        return stableScope;
+    return context.protocolEra === "modern"
+        ? modernRequestScopeId(context, connectionScopeId)
+        : undefined;
 }

package/dist/mcp/server/core/capabilities.js

@@ -45,7 +45,6 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         directory: "host-integration/external-mcp",
         description: "User-configured external MCP tool discovery and explicit forwarding through capability.",
         whenToRead: "Read before discovering or calling a configured external MCP server.",
-        enabled: (config) => Object.keys(config.mcpServers).length > 0,
     },
     {
         name: "workspace-tasks",
@@ -117,9 +116,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
     if (config.subagents) {
         capabilities.push("subagent.session");
     }
-    if (Object.keys(config.mcpServers).length > 0) {
-        capabilities.push("mcp.external");
-    }
+    capabilities.push("mcp.external");
     if (config.artifactsEnabled && context.artifactDownloadSupported) {
         capabilities.push("artifact.native-download");
     }