@sigrun/ext-mcp 0.0.0-stage → 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The MCP config store: reads `mcp.json` — the MCP server registry.
+ *
+ * Resolution order (ruling 2):
+ *   1. `SIGRUN_MCP_CONFIG` env override — an explicit path to an mcp.json
+ *   2. `~/.config/sigrun/mcp.json` (the sigrun config dir)
+ *
+ * Shape:
+ *   { "servers": { "<name>": {
+ *       "command": string, "args": string[], "env"?: {...}, "disabled"?: boolean
+ *   } } }
+ *
+ * Fail-loud on malformed config: unparseable JSON or a wrong-shaped body
+ * throws a clear error naming the path (the loader turns a throwing factory
+ * into quarantine semantics — this package never silently degrades).
+ */
+/** How one tool's registration reaches callers (pi-durable 1.2.0):
+ * `codemode` → `callers: ["tools"]` (scripts only, never model-offered),
+ * `deferred` → `deferred: true` (model-callable once tool_search loads it),
+ * `direct` → normal registration (model-offered),
+ * `hidden` → not registered at all. */
+export type McpExposure = "codemode" | "deferred" | "direct" | "hidden";
+/** The server-default exposure (spec slice 3: the default flip — a server
+ * with no `exposure` registers its tools script-only, NOT model-offered;
+ * `"exposure": "direct"` restores the pre-1.2.0 behavior). */
+export declare const DEFAULT_EXPOSURE: McpExposure;
+/** Default per-request wire timeout in seconds (config `timeout` overrides). */
+export declare const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Resolve one discovered tool's exposure: an exact `toolExposure` name wins
+ * over patterns; among patterns the FIRST matching one in config order wins
+ * (pi's precedence); otherwise the server default (default "codemode"). */
+export declare function resolveToolExposure(server: McpServerConfig, toolName: string): McpExposure;
+/** Whether a configured server participates at all: `enabled: false` and
+ * `disabled: true` both skip it (parse-time validation rejects
+ * contradictions, so either false simply means off). */
+export declare function serverEnabled(server: McpServerConfig): boolean;
+/** Fields every server variant carries regardless of transport. */
+interface McpServerCommon {
+    /** Skip this server entirely (default false). */
+    readonly disabled?: boolean;
+    /** Skip this server entirely (default true; contradicts `disabled`). */
+    readonly enabled?: boolean;
+    /** Server-default registration exposure (default "codemode"). */
+    readonly exposure?: McpExposure;
+    /** Per-tool exposure overrides: exact tool names beat patterns; the
+     * first matching `*`-pattern in config order wins. */
+    readonly toolExposure?: Readonly<Record<string, McpExposure>>;
+    /** Per-request wire timeout in seconds (default 60). */
+    readonly timeout?: number;
+}
+/** One configured MCP server (stdio transport). */
+export interface McpStdioServerConfig extends McpServerCommon {
+    /** The executable to spawn. */
+    readonly command: string;
+    /** Arguments to the executable. */
+    readonly args: readonly string[];
+    /** Extra environment variables for the child process. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** OAuth (T3c): when present, `sigrun-ext-mcp oauth <name>` can mint a
+     * token and spawn injects it as `MCP_ACCESS_TOKEN` (see tokens.ts). */
+    readonly oauth?: McpOAuthConfig;
+}
+/** One configured MCP server (remote transport: streamable HTTP, with a
+ * legacy-SSE fallback negotiated on first contact). */
+export interface McpUrlServerConfig extends McpServerCommon {
+    /** The server endpoint (http/https). */
+    readonly url: string;
+    /** Extra request headers (auth etc.), sent on every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** One configured MCP server: stdio OR remote. */
+export type McpServerConfig = McpStdioServerConfig | McpUrlServerConfig;
+/** Narrow to the stdio variant (the spawn path). */
+export declare function isStdioServer(server: McpServerConfig): server is McpStdioServerConfig;
+/** OAuth block for one server: how to run the authorization-code flow. */
+export interface McpOAuthConfig {
+    /** The AS's authorize endpoint (GET; the user opens this in a browser). */
+    readonly authorizeUrl: string;
+    /** The AS's token endpoint (POST; the CLI exchanges the code here). */
+    readonly tokenUrl: string;
+    /** The registered client id. */
+    readonly clientId: string;
+    /** Requested scopes (optional). */
+    readonly scopes?: readonly string[];
+    /** PKCE method (optional; only "S256" is implemented — and always used). */
+    readonly codeChallengeMethod?: string;
+}
+/** The parsed `mcp.json` body. */
+export interface McpConfig {
+    readonly servers: Readonly<Record<string, McpServerConfig>>;
+}
+/** The env override the config store reads. */
+export declare const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
+/** Resolve the config path without reading it (for diagnostics).
+ *
+ * Resolution order: the `SIGRUN_MCP_CONFIG` override → the sigrun config
+ * dir (`SIGRUN_CONFIG_DIR`, the SAME root every sigrun store resolves
+ * through — a deployment setting one sets them all) → `~/.config/sigrun`
+ * (the pre-deployment fallback, kept so a bare user install keeps
+ * working). */
+export declare function resolveMcpConfigPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Parse and validate an `mcp.json` body. Throws a clear error naming the
+ * source when the JSON is unparseable or the shape is wrong.
+ */
+export declare function parseMcpConfig(text: string, source: string): McpConfig;
+/**
+ * Read and parse the config from the resolved path. A missing file is an
+ * empty config (zero servers — the extension installs and contributes
+ * nothing); an existing-but-malformed file throws.
+ */
+export declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,286 @@
+/**
+ * The MCP config store: reads `mcp.json` — the MCP server registry.
+ *
+ * Resolution order (ruling 2):
+ *   1. `SIGRUN_MCP_CONFIG` env override — an explicit path to an mcp.json
+ *   2. `~/.config/sigrun/mcp.json` (the sigrun config dir)
+ *
+ * Shape:
+ *   { "servers": { "<name>": {
+ *       "command": string, "args": string[], "env"?: {...}, "disabled"?: boolean
+ *   } } }
+ *
+ * Fail-loud on malformed config: unparseable JSON or a wrong-shaped body
+ * throws a clear error naming the path (the loader turns a throwing factory
+ * into quarantine semantics — this package never silently degrades).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/** Config-level exposure words: the four real ones plus pi's `codemode-deferred`
+ * alias (normalized to "codemode" at parse time — pi compat). */
+const EXPOSURE_WORDS = [
+    "codemode",
+    "deferred",
+    "direct",
+    "hidden",
+    "codemode-deferred",
+];
+/** The server-default exposure (spec slice 3: the default flip — a server
+ * with no `exposure` registers its tools script-only, NOT model-offered;
+ * `"exposure": "direct"` restores the pre-1.2.0 behavior). */
+export const DEFAULT_EXPOSURE = "codemode";
+/** Default per-request wire timeout in seconds (config `timeout` overrides). */
+export const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Parse one exposure word; the alias normalizes to "codemode". */
+function parseExposure(value, source, where) {
+    if (typeof value !== "string" || !EXPOSURE_WORDS.includes(value)) {
+        throw new Error(`mcp config ${source}: ${where} exposure must be one of ${EXPOSURE_WORDS.map((word) => JSON.stringify(word)).join(", ")}`);
+    }
+    const word = value;
+    return word === "codemode-deferred" ? "codemode" : word;
+}
+/** Glob match for `toolExposure` patterns: `*` matches any run of
+ * characters (including `/`); a pattern without `*` is exact-only. */
+function globMatch(pattern, name) {
+    const parts = pattern.split("*");
+    if (parts.length === 1)
+        return pattern === name;
+    if (!name.startsWith(parts[0]))
+        return false;
+    let index = parts[0].length;
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        const last = i === parts.length - 1;
+        const found = last ? name.lastIndexOf(part) : name.indexOf(part, index);
+        if (found < 0 || found < index)
+            return false;
+        index = found + part.length;
+        if (last && index !== name.length)
+            return false;
+    }
+    return true;
+}
+/** Resolve one discovered tool's exposure: an exact `toolExposure` name wins
+ * over patterns; among patterns the FIRST matching one in config order wins
+ * (pi's precedence); otherwise the server default (default "codemode"). */
+export function resolveToolExposure(server, toolName) {
+    const overrides = server.toolExposure;
+    if (overrides !== undefined) {
+        const exact = overrides[toolName];
+        if (exact !== undefined)
+            return exact;
+        for (const [pattern, exposure] of Object.entries(overrides)) {
+            if (!pattern.includes("*"))
+                continue;
+            if (globMatch(pattern, toolName))
+                return exposure;
+        }
+    }
+    return server.exposure ?? DEFAULT_EXPOSURE;
+}
+/** Whether a configured server participates at all: `enabled: false` and
+ * `disabled: true` both skip it (parse-time validation rejects
+ * contradictions, so either false simply means off). */
+export function serverEnabled(server) {
+    return server.enabled !== false && server.disabled !== true;
+}
+/** Narrow to the stdio variant (the spawn path). */
+export function isStdioServer(server) {
+    return "command" in server;
+}
+/** The env override the config store reads. */
+export const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
+/** Resolve the config path without reading it (for diagnostics).
+ *
+ * Resolution order: the `SIGRUN_MCP_CONFIG` override → the sigrun config
+ * dir (`SIGRUN_CONFIG_DIR`, the SAME root every sigrun store resolves
+ * through — a deployment setting one sets them all) → `~/.config/sigrun`
+ * (the pre-deployment fallback, kept so a bare user install keeps
+ * working). */
+export function resolveMcpConfigPath(env = process.env) {
+    const override = env[MCP_CONFIG_ENV];
+    if (override !== undefined && override !== "") {
+        // A relative override resolves against cwd, like sigrun's other paths.
+        return isAbsolute(override) ? override : resolve(override);
+    }
+    const configDir = env.SIGRUN_CONFIG_DIR;
+    if (configDir !== undefined && configDir !== "") {
+        return join(configDir, "mcp.json");
+    }
+    return resolve(homedir(), ".config", "sigrun", "mcp.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse and validate an `mcp.json` body. Throws a clear error naming the
+ * source when the JSON is unparseable or the shape is wrong.
+ */
+export function parseMcpConfig(text, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`mcp config ${source} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`mcp config ${source} must be a JSON object`);
+    }
+    const servers = {};
+    const rawServers = parsed.servers;
+    if (!isRecord(rawServers)) {
+        throw new Error(`mcp config ${source} must have a "servers" object mapping names to server entries`);
+    }
+    for (const [name, entry] of Object.entries(rawServers)) {
+        if (!isRecord(entry)) {
+            throw new Error(`mcp config ${source}: server "${name}" must be an object`);
+        }
+        // Transport dispatch: a server is EITHER a stdio child or a remote
+        // endpoint. Both arms share the optional fields below; each arm then
+        // validates its own required fields.
+        const hasCommand = entry.command !== undefined || entry.args !== undefined;
+        const hasUrl = entry.url !== undefined;
+        if (hasCommand && hasUrl) {
+            throw new Error(`mcp config ${source}: server "${name}" cannot carry both "command" (stdio) and "url" (remote) — pick one transport`);
+        }
+        if (!hasCommand && !hasUrl) {
+            throw new Error(`mcp config ${source}: server "${name}" needs either "command"+"args" (stdio) or "url" (remote)`);
+        }
+        if (hasUrl) {
+            if (typeof entry.url !== "string" || !/^https?:\/\//.test(entry.url)) {
+                throw new Error(`mcp config ${source}: server "${name}" url must be an http(s) URL`);
+            }
+            if (entry.headers !== undefined &&
+                (!isRecord(entry.headers) ||
+                    Object.values(entry.headers).some((v) => typeof v !== "string"))) {
+                throw new Error(`mcp config ${source}: server "${name}" headers must map strings to strings`);
+            }
+        }
+        else if (typeof entry.command !== "string" ||
+            !Array.isArray(entry.args) ||
+            entry.args.some((arg) => typeof arg !== "string")) {
+            throw new Error(`mcp config ${source}: server "${name}" needs a string "command" and a string[] "args"`);
+        }
+        if (entry.env !== undefined &&
+            (!isRecord(entry.env) ||
+                Object.values(entry.env).some((v) => typeof v !== "string"))) {
+            throw new Error(`mcp config ${source}: server "${name}" env must map strings to strings`);
+        }
+        if (entry.disabled !== undefined && typeof entry.disabled !== "boolean") {
+            throw new Error(`mcp config ${source}: server "${name}" disabled must be a boolean`);
+        }
+        if (entry.enabled !== undefined && typeof entry.enabled !== "boolean") {
+            throw new Error(`mcp config ${source}: server "${name}" enabled must be a boolean`);
+        }
+        // enabled/disabled must agree when both present: a server that is
+        // simultaneously on and off is a config lie, not a default to guess.
+        if (entry.enabled !== undefined &&
+            entry.disabled !== undefined &&
+            entry.enabled === entry.disabled) {
+            throw new Error(`mcp config ${source}: server "${name}" enabled and disabled contradict each other`);
+        }
+        if (entry.timeout !== undefined) {
+            if (typeof entry.timeout !== "number" ||
+                !Number.isFinite(entry.timeout) ||
+                entry.timeout <= 0) {
+                throw new Error(`mcp config ${source}: server "${name}" timeout must be a positive number of seconds`);
+            }
+        }
+        const exposure = entry.exposure === undefined
+            ? undefined
+            : parseExposure(entry.exposure, source, `server "${name}"`);
+        let toolExposure;
+        if (entry.toolExposure !== undefined) {
+            if (!isRecord(entry.toolExposure)) {
+                throw new Error(`mcp config ${source}: server "${name}" toolExposure must be an object mapping tool names or patterns to exposure words`);
+            }
+            toolExposure = {};
+            for (const [key, value] of Object.entries(entry.toolExposure)) {
+                toolExposure[key] = parseExposure(value, source, `server "${name}" toolExposure "${key}"`);
+            }
+        }
+        const oauth = entry.oauth === undefined
+            ? undefined
+            : parseOauthEntry(entry.oauth, source, name);
+        // The common optionals first, then the transport arm's own fields —
+        // the union stays discriminable by "command" vs "url" presence.
+        servers[name] = hasUrl
+            ? {
+                url: entry.url,
+                ...(entry.headers === undefined
+                    ? {}
+                    : { headers: entry.headers }),
+                ...(entry.disabled === undefined ? {} : { disabled: entry.disabled }),
+                ...(entry.enabled === undefined ? {} : { enabled: entry.enabled }),
+                ...(exposure === undefined ? {} : { exposure }),
+                ...(toolExposure === undefined ? {} : { toolExposure }),
+                ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
+            }
+            : {
+                command: entry.command,
+                args: entry.args,
+                ...(entry.env === undefined
+                    ? {}
+                    : { env: entry.env }),
+                ...(entry.disabled === undefined ? {} : { disabled: entry.disabled }),
+                ...(entry.enabled === undefined ? {} : { enabled: entry.enabled }),
+                ...(exposure === undefined ? {} : { exposure }),
+                ...(toolExposure === undefined ? {} : { toolExposure }),
+                ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
+                ...(oauth === undefined ? {} : { oauth }),
+            };
+    }
+    return { servers };
+}
+/** Parse one server's oauth block. Fail-loud on a wrong shape: a
+ * half-configured block is a config error, not a silently-ignored field. */
+function parseOauthEntry(value, source, name) {
+    if (!isRecord(value)) {
+        throw new Error(`mcp config ${source}: server "${name}" oauth must be an object`);
+    }
+    if (typeof value.authorizeUrl !== "string" ||
+        typeof value.tokenUrl !== "string" ||
+        typeof value.clientId !== "string") {
+        throw new Error(`mcp config ${source}: server "${name}" oauth needs string "authorizeUrl", "tokenUrl" and "clientId"`);
+    }
+    if (value.scopes !== undefined &&
+        (!Array.isArray(value.scopes) ||
+            value.scopes.some((scope) => typeof scope !== "string"))) {
+        throw new Error(`mcp config ${source}: server "${name}" oauth scopes must be a string[]`);
+    }
+    if (value.codeChallengeMethod !== undefined &&
+        typeof value.codeChallengeMethod !== "string") {
+        throw new Error(`mcp config ${source}: server "${name}" oauth codeChallengeMethod must be a string`);
+    }
+    // Only S256 is implemented; a config naming anything else would silently
+    // send S256 anyway — fail loudly instead (config lies must not pass).
+    if (value.codeChallengeMethod !== undefined &&
+        value.codeChallengeMethod !== "S256") {
+        throw new Error(`mcp config ${source}: server "${name}" oauth codeChallengeMethod must be "S256" (the only implemented method)`);
+    }
+    return {
+        authorizeUrl: value.authorizeUrl,
+        tokenUrl: value.tokenUrl,
+        clientId: value.clientId,
+        ...(value.scopes === undefined
+            ? {}
+            : { scopes: value.scopes }),
+        ...(value.codeChallengeMethod === undefined
+            ? {}
+            : { codeChallengeMethod: value.codeChallengeMethod }),
+    };
+}
+/**
+ * Read and parse the config from the resolved path. A missing file is an
+ * empty config (zero servers — the extension installs and contributes
+ * nothing); an existing-but-malformed file throws.
+ */
+export function loadMcpConfig(env = process.env) {
+    const path = resolveMcpConfigPath(env);
+    if (!existsSync(path))
+        return { servers: {} };
+    const text = readFileSync(path, "utf8");
+    return parseMcpConfig(text, path);
+}

package/dist/extension.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The MCP extension (sigrun-ext-mcp): registers every tool discovered on
+ * the configured MCP servers as a pi-durable tool named
+ * `<server>/<toolname>` (ruling 4).
+ *
+ * Contract (sigrun's src/harness/loader.ts): the package default-exports a
+ * FACTORY TAKING NO ARGUMENTS, returning `{ extension }`. The loader calls
+ * it synchronously at boot, before `Harness.open` reads the registry — so
+ * the factory returns immediately and the async connect/discover work lands
+ * through a LIVE tools array (the registry re-reads `extension.tools` on
+ * every snapshot, so tools discovered after install appear in the harness
+ * without a reinstall).
+ *
+ * Lifecycle (ruling 5): servers spawn eagerly at factory time (a server is
+ * a long-lived stdio process; lazy-at-first-use buys nothing and complicates
+ * discovery visibility). Each server is ISOLATED: a spawn or handshake or
+ * discovery failure quarantines just that server (warned, contributing no
+ * tools) and never affects the others. Children are killed on process exit
+ * and on `wiring.close()`; there is no loader-side uninstall callback to
+ * hook.
+ *
+ * Config (ruling 2): `mcp.json` resolved as `SIGRUN_MCP_CONFIG` env
+ * override → `~/.config/sigrun/mcp.json`. Malformed config THROWS from the
+ * factory (the loader's quarantine semantics take over); a missing config
+ * is an empty registry (the extension installs with zero tools).
+ */
+import { type Extension } from "@earendil-works/pi-durable";
+/** The extension's pi-durable registry name. */
+export declare const MCP_EXTENSION_NAME = "sigrun.mcp";
+/** What {@link createMcpExtension} returns (the loader contract: `.extension`). */
+export interface McpWiring {
+    /** The extension to install into the harness registry. */
+    readonly extension: Extension;
+    /**
+     * Kill every connected MCP server child process (idempotent). Called on
+     * process exit automatically; hosts may call it on harness shutdown.
+     */
+    close(): void;
+    /**
+     * Resolves when every enabled server has connected (and discovered its
+     * tools) or failed (isolated). Hosts that want tools present before
+     * `Harness.open` reads the registry await this; the loader does not.
+     */
+    readonly ready: Promise<void>;
+}
+/**
+ * The extension factory (the loader contract: no arguments; config resolves
+ * from the package context — the `SIGRUN_MCP_CONFIG` override or the sigrun
+ * config dir).
+ */
+export declare function createMcpExtension(): McpWiring;

package/dist/extension.js

@@ -0,0 +1,212 @@
+/**
+ * The MCP extension (sigrun-ext-mcp): registers every tool discovered on
+ * the configured MCP servers as a pi-durable tool named
+ * `<server>/<toolname>` (ruling 4).
+ *
+ * Contract (sigrun's src/harness/loader.ts): the package default-exports a
+ * FACTORY TAKING NO ARGUMENTS, returning `{ extension }`. The loader calls
+ * it synchronously at boot, before `Harness.open` reads the registry — so
+ * the factory returns immediately and the async connect/discover work lands
+ * through a LIVE tools array (the registry re-reads `extension.tools` on
+ * every snapshot, so tools discovered after install appear in the harness
+ * without a reinstall).
+ *
+ * Lifecycle (ruling 5): servers spawn eagerly at factory time (a server is
+ * a long-lived stdio process; lazy-at-first-use buys nothing and complicates
+ * discovery visibility). Each server is ISOLATED: a spawn or handshake or
+ * discovery failure quarantines just that server (warned, contributing no
+ * tools) and never affects the others. Children are killed on process exit
+ * and on `wiring.close()`; there is no loader-side uninstall callback to
+ * hook.
+ *
+ * Config (ruling 2): `mcp.json` resolved as `SIGRUN_MCP_CONFIG` env
+ * override → `~/.config/sigrun/mcp.json`. Malformed config THROWS from the
+ * factory (the loader's quarantine semantics take over); a missing config
+ * is an empty registry (the extension installs with zero tools).
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension, defineTool, } from "@earendil-works/pi-durable";
+import { connectMcpServer } from "./client.js";
+import { isStdioServer, loadMcpConfig, resolveToolExposure, serverEnabled, } from "./config.js";
+import { MCP_SERVERS_SECTION_KEY, partitionForSection, renderMcpServersSection, } from "./section.js";
+/** The extension's pi-durable registry name. */
+export const MCP_EXTENSION_NAME = "sigrun.mcp";
+/** Render one MCP content block as pi-ai tool-result content. */
+function toContent(block) {
+    if (block.type === "text" && typeof block.text === "string") {
+        return { type: "text", text: block.text };
+    }
+    return { type: "text", text: JSON.stringify(block) };
+}
+/** Build the pi-durable tool for one discovered MCP tool. */
+function mcpTool(serverName, tool, client, exposure, timeoutSeconds) {
+    // MCP advertises a plain JSON Schema for arguments. pi-durable validates
+    // with TypeBox's Compile, which accepts plain JSON Schema objects; pass it
+    // through as an unsafe schema (fallback: the empty object schema when the
+    // server omitted inputSchema).
+    const parameters = (tool.inputSchema !== undefined &&
+        typeof tool.inputSchema === "object" &&
+        tool.inputSchema !== null
+        ? tool.inputSchema
+        : { type: "object" });
+    const toolName = `${serverName}/${tool.name}`;
+    // The exposure mapping onto pi-durable 1.2.0 (spec slice 3):
+    //   codemode → callers: ["tools"] (scripts only, never model-offered);
+    //   deferred → deferred: true (invisible until tool_search loads it);
+    //   direct   → normal registration (model-offered when in the tool set);
+    //   hidden   → never registered (the caller checks and skips).
+    const exposureFlags = exposure === "codemode"
+        ? { callers: ["tools"] }
+        : exposure === "deferred"
+            ? { deferred: true }
+            : {};
+    return defineTool({
+        name: toolName,
+        description: tool.description !== undefined && tool.description !== ""
+            ? tool.description
+            : `MCP tool ${tool.name} on server ${serverName}.`,
+        parameters: Type.Unsafe(parameters),
+        // A tools/call round-trip is external I/O; never rerun on recovery.
+        replay: "unsafe",
+        ...exposureFlags,
+        async execute(args) {
+            const result = await client.callTool(tool.name, { ...args }, timeoutSeconds);
+            const blocks = result.content ?? [];
+            const content = blocks.length > 0 ? blocks.map(toContent) : [];
+            return {
+                output: content.length > 0 ? content : [
+                    { type: "text", text: JSON.stringify(result) },
+                ],
+                isError: result.isError === true,
+                details: result,
+            };
+        },
+    });
+}
+/**
+ * The extension factory (the loader contract: no arguments; config resolves
+ * from the package context — the `SIGRUN_MCP_CONFIG` override or the sigrun
+ * config dir).
+ */
+export function createMcpExtension() {
+    const config = loadMcpConfig();
+    const tools = []; // live: discovered tools land here
+    const clients = new Map();
+    /** Live per-server exposure mix: which registered tools use codemode /
+     * deferred (the section renders from this snapshot). */
+    const serverExposures = new Map();
+    let closed = false;
+    // Per-server isolation: each server connects independently; any failure
+    // quarantines that server alone (warned, zero tools) and the others
+    // proceed. A disabled server is skipped before it ever spawns.
+    const pending = [];
+    for (const [name, server] of Object.entries(config.servers)) {
+        if (!serverEnabled(server))
+            continue;
+        pending.push((async () => {
+            let client;
+            try {
+                client = await connectMcpServer(name, server);
+            }
+            catch (cause) {
+                console.warn(`mcp server "${name}" quarantined: ${cause instanceof Error ? cause.message : String(cause)}`);
+                return;
+            }
+            if (closed) {
+                client.close();
+                return;
+            }
+            clients.set(name, client);
+            try {
+                const discovered = await client.listTools();
+                const mix = { codemode: false, deferred: false, count: 0 };
+                for (const tool of discovered) {
+                    const exposure = resolveToolExposure(server, tool.name);
+                    if (exposure === "hidden")
+                        continue; // not registered
+                    if (exposure === "codemode")
+                        mix.codemode = true;
+                    if (exposure === "deferred")
+                        mix.deferred = true;
+                    mix.count += 1;
+                    tools.push(mcpTool(name, tool, client, exposure, server.timeout));
+                }
+                if (mix.count > 0 && (mix.codemode || mix.deferred)) {
+                    const origin = isStdioServer(server)
+                        ? `${server.command} ${server.args.join(" ")}`.trim()
+                        : server.url;
+                    serverExposures.set(name, {
+                        ...mix,
+                        description: `${mix.count} tool${mix.count === 1 ? "" : "s"} from ${origin}`.trim(),
+                    });
+                }
+            }
+            catch (cause) {
+                clients.delete(name);
+                client.close();
+                console.warn(`mcp server "${name}" quarantined during discovery: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        })());
+    }
+    const killAll = () => {
+        if (closed)
+            return;
+        closed = true;
+        for (const client of clients.values())
+            client.close();
+        clients.clear();
+        tools.length = 0;
+        serverExposures.clear();
+    };
+    // Children must not outlive this process. The exit handler must be
+    // synchronous (exit listeners cannot await), so it only SIGTERMs.
+    process.on("exit", killAll);
+    // NOTE: no factory-time boot log for codemode/deferred servers —
+    // exposure is only known AFTER discovery (per-tool resolution), so a
+    // warn here could only fire on config guesses; the per-request
+    // `mcp_servers` section (below) is the real, accurate warning channel.
+    // The `mcp_servers` section (rev 3's corrected warning channel): renders
+    // per request from the live agent. A codemode/deferred server appears ONLY
+    // when its discovery tool (codemode / tool_search) is model-offered in
+    // THIS request; unreachable servers collapse into one notice line.
+    const mcpServersSection = (input) => {
+        const reaches = new Map();
+        for (const [name, mix] of serverExposures) {
+            reaches.set(name, mix.codemode && mix.deferred
+                ? "either"
+                : mix.codemode
+                    ? "codemode"
+                    : "tool_search");
+        }
+        const offers = new Set(input.agent.tools.map((tool) => tool.name));
+        const { listed, unreachable } = partitionForSection(reaches, offers);
+        const entries = listed.map((name) => {
+            const mix = serverExposures.get(name);
+            return {
+                name,
+                description: mix.description,
+                how: mix.codemode && mix.deferred
+                    ? "codemode scripts and the tool_search tool"
+                    : mix.codemode
+                        ? "codemode scripts"
+                        : "the tool_search tool",
+            };
+        });
+        return renderMcpServersSection(entries, unreachable.length);
+    };
+    const extension = defineExtension({
+        name: MCP_EXTENSION_NAME,
+        tools, // live array: the registry re-reads it on every snapshot
+        sections: [
+            {
+                key: MCP_SERVERS_SECTION_KEY,
+                render: mcpServersSection,
+            },
+        ],
+    });
+    return {
+        extension,
+        close: killAll,
+        ready: Promise.all(pending).then(() => undefined),
+    };
+}