@akira-tl/forgerelay 1.0.1 → 1.1.1

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

@@ -0,0 +1,382 @@
+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;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "ExternalMcpError";
+    }
+}
+export class ExternalMcpGateway {
+    mediaMaxBytes;
+    credentialStore;
+    negotiationCache = new Map();
+    constructor(mediaMaxBytes, credentialStore) {
+        this.mediaMaxBytes = mediaMaxBytes;
+        this.credentialStore = credentialStore;
+    }
+    async run(servers, input, signal, transforms, authContext) {
+        signal?.throwIfAborted();
+        switch (input.operation) {
+            case "servers":
+                return {
+                    value: {
+                        operation: "servers",
+                        servers: Object.entries(servers)
+                            .sort(([left], [right]) => left.localeCompare(right))
+                            .map(([name, server]) => ({ name, transport: server.transport })),
+                    },
+                };
+            case "tools":
+                return this.withClient(servers, input.server, signal, authContext, async (client) => {
+                    const discovery = await discoverTools(client, signal);
+                    return {
+                        value: {
+                            operation: "tools",
+                            server: input.server,
+                            tools: discovery.tools.map(summarizeTool),
+                            ...(discovery.truncated ? { truncated: true } : {}),
+                        },
+                    };
+                });
+            case "call":
+                return this.withClient(servers, input.server, signal, authContext, async (client) => {
+                    await assertRegisteredTool(client, input.server, input.tool, signal);
+                    const appliedTransforms = [];
+                    let callArguments = input.arguments ?? {};
+                    if (transforms?.request) {
+                        const transformed = await transforms.request(input.server, input.tool, callArguments);
+                        callArguments = transformed.value;
+                        appliedTransforms.push(...transformed.transforms);
+                    }
+                    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.`);
+                    }
+                    if (transforms?.result) {
+                        const transformed = await transforms.result(input.server, input.tool, result);
+                        result = transformed.value;
+                        appliedTransforms.push(...transformed.transforms);
+                        assertCallToolResult(input.server, input.tool, result);
+                        if (result.isError) {
+                            throw new ExternalMcpError("tool_failed", `External MCP ${input.server} tool ${input.tool} returned an error after result transformation.`);
+                        }
+                    }
+                    const projection = projectExternalMcpContent(input.server, input.tool, result, this.mediaMaxBytes);
+                    return {
+                        content: result.content,
+                        value: {
+                            operation: "call",
+                            server: input.server,
+                            tool: input.tool,
+                            content: projection.content,
+                            ...(!projection.hasMedia && isRecord(result.structuredContent)
+                                ? { structuredContent: result.structuredContent }
+                                : {}),
+                            ...(appliedTransforms.length > 0 ? { transforms: appliedTransforms } : {}),
+                        },
+                    };
+                });
+        }
+    }
+    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 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, 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();
+            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, authProvider) {
+    if (config.transport === "stdio") {
+        return new StdioClientTransport({
+            command: config.command,
+            ...(config.args ? { args: config.args } : {}),
+            ...(config.cwd ? { cwd: config.cwd } : {}),
+            ...(config.env
+                ? { env: { ...getDefaultEnvironment(), ...config.env } }
+                : {}),
+            stderr: "ignore",
+        });
+    }
+    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;
+    for (let pageIndex = 0; pageIndex < MAX_TOOL_DISCOVERY_PAGES; pageIndex += 1) {
+        signal?.throwIfAborted();
+        const page = await client.listTools(cursor ? { cursor } : undefined, { signal });
+        const remaining = MAX_DISCOVERED_TOOLS - tools.length;
+        tools.push(...page.tools.slice(0, remaining));
+        if (page.tools.length > remaining)
+            return { tools, truncated: true };
+        cursor = page.nextCursor;
+        if (!cursor)
+            return { tools, truncated: false };
+        if (tools.length >= MAX_DISCOVERED_TOOLS)
+            return { tools, truncated: true };
+    }
+    return { tools, truncated: cursor !== undefined };
+}
+async function assertRegisteredTool(client, server, tool, signal) {
+    let cursor;
+    for (let pageIndex = 0; pageIndex < MAX_TOOL_DISCOVERY_PAGES; pageIndex += 1) {
+        signal?.throwIfAborted();
+        const page = await client.listTools(cursor ? { cursor } : undefined, { signal });
+        if (page.tools.some((candidate) => candidate.name === tool))
+            return;
+        cursor = page.nextCursor;
+        if (!cursor)
+            break;
+    }
+    throw new ExternalMcpError("unknown_tool", `External MCP ${server} does not advertise tool ${tool}.`);
+}
+function summarizeTool(tool) {
+    const serialized = safeJson(tool.inputSchema);
+    const schemaTruncated = Buffer.byteLength(serialized, "utf8") > MAX_TOOL_SCHEMA_BYTES;
+    return {
+        name: tool.name,
+        ...(tool.description
+            ? { description: tool.description.slice(0, MAX_TOOL_DESCRIPTION_CHARS) }
+            : {}),
+        inputSchema: schemaTruncated ? { type: "object" } : tool.inputSchema,
+        ...(schemaTruncated ? { schemaTruncated: true } : {}),
+    };
+}
+function projectExternalMcpContent(server, tool, result, mediaMaxBytes) {
+    const budget = createMediaBudget(mediaMaxBytes);
+    const content = [];
+    let hasMedia = false;
+    for (const entry of result.content ?? []) {
+        if (entry.type === "image") {
+            hasMedia = true;
+            if (!isSupportedImageMimeType(entry.mimeType)) {
+                throw new ExternalMcpError("media_unsupported", `External MCP ${server} tool ${tool} returned unsupported image MIME type ${entry.mimeType}.`);
+            }
+            const bytes = strictBase64ByteLength(entry.data);
+            if (bytes === undefined) {
+                throw new ExternalMcpError("media_malformed", `External MCP ${server} tool ${tool} returned malformed base64 image content.`);
+            }
+            try {
+                claimMediaBytes(budget, bytes);
+            }
+            catch {
+                throw new ExternalMcpError("media_too_large", `External MCP ${server} tool ${tool} returned media exceeding the configured ${mediaMaxBytes}-byte aggregate limit.`);
+            }
+            content.push({ type: "image", mimeType: entry.mimeType, bytes });
+            continue;
+        }
+        if (entry.type === "audio") {
+            throw new ExternalMcpError("media_unsupported", `External MCP ${server} tool ${tool} returned unsupported audio media content.`);
+        }
+        if (entry.type === "resource" && "blob" in entry.resource && typeof entry.resource.blob === "string") {
+            throw new ExternalMcpError("media_unsupported", `External MCP ${server} tool ${tool} returned unsupported binary resource content.`);
+        }
+        content.push(entry);
+    }
+    return { content, hasMedia };
+}
+function assertCallToolResult(server, tool, value) {
+    if (!isRecord(value)
+        || !Array.isArray(value.content)
+        || !CallToolResultSchema.safeParse(value).success) {
+        throw new ExternalMcpError("unsupported_result", `External MCP ${server} tool ${tool} returned an unsupported result shape.`);
+    }
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/mcp/operations/media-content.js

@@ -0,0 +1,28 @@
+export const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+export const SUPPORTED_IMAGE_MIME_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+];
+export function createMediaBudget(maxBytes) {
+    return { maxBytes, remainingBytes: maxBytes };
+}
+export function isSupportedImageMimeType(value) {
+    return SUPPORTED_IMAGE_MIME_TYPES.includes(value);
+}
+export function strictBase64ByteLength(value) {
+    if (value.length === 0 || value.length % 4 !== 0)
+        return undefined;
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        return undefined;
+    }
+    return Buffer.byteLength(value, "base64");
+}
+export function claimMediaBytes(budget, bytes) {
+    if (bytes > budget.remainingBytes) {
+        throw new Error(`Media content exceeds the configured per-result limit of ${budget.maxBytes} bytes ` +
+            `(${bytes} bytes requested, ${budget.remainingBytes} bytes remaining).`);
+    }
+    budget.remainingBytes -= bytes;
+}

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/activity-support.js

@@ -65,6 +65,6 @@ export function runActivityTool(lifecycle, workspace, conversationScopeId, tool,
         ...relation,
     });
 }
-export function runActivityToolWithHooks(lifecycle, hooks, workspace, conversationScopeId, request, hookOptions, relation = {}) {
-    return runActivityTool(lifecycle, workspace, conversationScopeId, hookOptions.tool, request, () => runToolWithHooks(hooks, hookOptions), standardActivityOutcome, relation);
+export function runActivityToolWithHooks(lifecycle, hooks, workspace, conversationScopeId, request, hookOptions, relation = {}, auditResult) {
+    return runActivityTool(lifecycle, workspace, conversationScopeId, hookOptions.tool, request, () => runToolWithHooks(hooks, hookOptions), standardActivityOutcome, relation, auditResult);
 }

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

@@ -0,0 +1,31 @@
+import { z } from "zod";
+const externalMcpInputSchema = z.discriminatedUnion("operation", [
+    z.object({ operation: z.literal("servers") }).strict(),
+    z.object({
+        operation: z.literal("tools"),
+        server: z.string().min(1),
+    }).strict(),
+    z.object({
+        operation: z.literal("call"),
+        server: z.string().min(1),
+        tool: z.string().min(1),
+        arguments: z.record(z.string(), z.unknown()).optional(),
+    }).strict(),
+]);
+export function externalMcpCapabilityDefinitions(dependency) {
+    if (!dependency)
+        return [];
+    return [{
+            name: "mcp.external",
+            description: "Discover and call tools from user-configured external MCP servers through the ForgeRelay Capability gateway.",
+            guideName: "external-mcp",
+            readGuideBeforeFirstUse: true,
+            batchPolicy: "unsupported",
+            inputSchema: externalMcpInputSchema,
+            availability: () => ({
+                available: dependency.available,
+                reason: dependency.unavailableReason,
+            }),
+            run: async (input, context, options) => dependency.run(input, context, options),
+        }];
+}