@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.0

package/dist/code-mode/type-hints.js

@@ -1,3 +1,4 @@
+import { getCodeModeDiagnostics, toCodeModeTool } from "./eligibility.js";
 /**
  * Convert a JSON Schema to a TypeScript type string.
  *
@@ -124,13 +125,14 @@ export function sanitizeToolName(name) {
  * method signatures the model can use when writing code.
  */
 export function generateTypeHints(tools) {
-    if (tools.length === 0)
-        return "";
+    const codeModeTools = tools.map(normalizeCodeModeTool);
+    const diagnostics = getCodeModeDiagnostics(codeModeTools);
     const methods = [];
-    for (const tool of tools) {
+    for (const codeModeTool of codeModeTools) {
+        const tool = codeModeTool.tool;
         const safeName = sanitizeToolName(tool.name);
         const inputSchema = tool.inputSchema;
-        const outputSchema = tool.outputSchema;
+        const outputSchema = codeModeTool.outputSchema;
         const definitions = (inputSchema.$defs ??
             inputSchema.definitions ??
             outputSchema?.$defs ??
@@ -140,13 +142,17 @@ export function generateTypeHints(tools) {
         // Build output type
         const outputType = outputSchema ? jsonSchemaToTypeString(outputSchema, definitions) : "unknown";
         // Build JSDoc
-        const jsdoc = buildJsDoc(tool, inputSchema);
+        const jsdoc = buildJsDoc(codeModeTool, inputSchema);
         methods.push(`${jsdoc}  ${safeName}: (input: ${inputType}) => Promise<${outputType}>;`);
     }
-    const toolListType = tools.map((t) => `"${escapeStr(t.name)}"`).join(" | ");
+    const toolListType = codeModeTools.length > 0
+        ? codeModeTools.map((entry) => `"${escapeStr(entry.tool.name)}"`).join(" | ")
+        : "never";
     return [
         "// Code mode type hints — auto-generated from MCP tool schemas",
         "// Available tools are accessed via the `codemode` namespace",
+        `// MCP catalog: ${diagnostics.totalTools} tool(s); ${diagnostics.callableTools} callable, ${diagnostics.refusedTools} dispatch-refused`,
+        `// Output schemas: ${diagnostics.declaredOutputSchemas} declared, ${diagnostics.synthesizedOutputSchemas} synthesized, ${diagnostics.unavailableOutputSchemas} unavailable`,
         "",
         `declare const codemode: {`,
         `  /** List all available code mode tool names. */`,
@@ -166,11 +172,19 @@ function generateInputType(_toolSafeName, inputSchema, definitions) {
     const typeStr = jsonSchemaToTypeString(inputSchema, definitions);
     return typeStr;
 }
-function buildJsDoc(tool, inputSchema) {
+function buildJsDoc(codeModeTool, inputSchema) {
+    const tool = codeModeTool.tool;
     const lines = ["  /**"];
     if (tool.description) {
         lines.push(`   * ${tool.description}`);
     }
+    if (codeModeTool.callable) {
+        lines.push("   * Code Mode dispatch: callable (explicitly read-only and non-destructive).");
+    }
+    else {
+        lines.push("   * Code Mode dispatch: refused. Use a permission-aware non-Code-Mode path.");
+    }
+    lines.push(`   * Output schema provenance: ${codeModeTool.outputSchemaProvenance}.`);
     const properties = inputSchema.properties;
     if (properties) {
         for (const [key, propSchema] of Object.entries(properties)) {
@@ -186,4 +200,6 @@ function buildJsDoc(tool, inputSchema) {
 function escapeStr(s) {
     return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");
 }
-//# sourceMappingURL=type-hints.js.map
+function normalizeCodeModeTool(tool) {
+    return "tool" in tool && "outputSchemaProvenance" in tool ? tool : toCodeModeTool(tool);
+}

package/dist/docker-e2e.d.ts

@@ -52,4 +52,3 @@ export declare const dockerE2ETool: {
     execute(_toolCallId: string, params: DockerE2EInput, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<DockerE2EDetails> | undefined, _ctx: ExtensionContext): Promise<AgentToolResult<DockerE2EDetails>>;
 };
 export {};
-//# sourceMappingURL=docker-e2e.d.ts.map

package/dist/docker-e2e.js

@@ -232,4 +232,3 @@ export const dockerE2ETool = {
         };
     },
 };
-//# sourceMappingURL=docker-e2e.js.map

package/dist/index.d.ts

@@ -1,3 +1,11 @@
 import type { ExtensionAPI } from "@sammorrowdrums/mcpi";
+import type { BashState } from "./routing/index.js";
+/**
+ * Report whether the host currently exposes a shell tool to the agent.
+ *
+ * `getActiveTools` may be missing on an older host or throw if the runner context
+ * is not bound, and neither is evidence that bash is absent — so both collapse
+ * to `undiscoverable` rather than a false negative.
+ */
+export declare function detectBashState(pi: ExtensionAPI): BashState;
 export default function (pi: ExtensionAPI): void;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,39 +1,71 @@
 import { CodeModeManager } from "./code-mode/index.js";
 import { dockerE2ETool } from "./docker-e2e.js";
-import { McpClientManager, loadMcpConfig } from "./mcp/index.js";
-import { SkillRegistry, createLoadSkillTool, discoverSkillsFromServer, formatMcpSkillsForPrompt, registerMcpToolProxies, } from "./skills/index.js";
-import { ToolCliServer, formatToolCliForPrompt } from "./tool-cli/index.js";
+import { McpiHostApproval } from "./mcp/host-approval.js";
+import { McpiHostElicitation } from "./mcp/host-elicitation.js";
+import { McpClientManager, McpPolicy, isSkillsExtensionEnabled, loadMcpConfig, } from "./mcp/index.js";
+import { SkillRegistry, SkillsExtensionClient, createLoadSkillTool, discoverSkillsFromServer, discoverSkillsViaExtension, formatMcpSkillsForPrompt, registerMcpToolProxies, skillsExtensionDiagnostic, } from "./skills/index.js";
+import { ToolCliServer, createPolicyToolProvider, formatToolCliForPrompt, startToolCliBridge, withholdToolCliCredentials, } from "./tool-cli/index.js";
+import { buildExecutionFacilities, formatExecutionFacilities, publishExecutionFacilities, } from "./routing/index.js";
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Report whether the host currently exposes a shell tool to the agent.
+ *
+ * `getActiveTools` may be missing on an older host or throw if the runner context
+ * is not bound, and neither is evidence that bash is absent — so both collapse
+ * to `undiscoverable` rather than a false negative.
+ */
+export function detectBashState(pi) {
+    try {
+        return pi.getActiveTools().includes("bash")
+            ? { kind: "registered", toolName: "bash" }
+            : { kind: "absent" };
+    }
+    catch (err) {
+        return { kind: "undiscoverable", reason: errorMessage(err) };
+    }
+}
 export default function (pi) {
     pi.registerTool(dockerE2ETool);
     pi.registerFlag("mcp-config", {
         description: "Path to MCP server configuration JSON file",
         type: "string",
     });
-    const mcpManager = new McpClientManager();
+    pi.registerFlag("mcp-skills-extension", {
+        description: "Enable the DRAFT MCP skills extension (SEP-2640). Unratified; off by default.",
+        type: "boolean",
+    });
+    const hostElicitation = new McpiHostElicitation();
+    const hostApproval = new McpiHostApproval();
+    const mcpManager = new McpClientManager({ elicitation: hostElicitation });
+    const policy = new McpPolicy({ gateway: mcpManager, approvals: hostApproval });
     const skillRegistry = new SkillRegistry();
+    const skillsClient = new SkillsExtensionClient({ policy });
     const codeModeManager = new CodeModeManager();
-    const enabledTools = new Set();
-    const gatedToolNames = new Set();
-    // Bridge McpClientManager to the ToolProvider interface
-    const toolProvider = {
-        getServerNames: () => mcpManager.getConnectedServers(),
-        getTools: (server) => mcpManager.getToolsForServer(server),
-        async callTool(server, tool, args) {
-            const client = mcpManager.getClient(server);
-            if (!client)
-                throw new Error(`No client for server "${server}"`);
-            const result = await client.callTool({ name: tool, arguments: args });
-            return {
-                content: result.content,
-                isError: result.isError === true ? true : undefined,
-                structuredContent: result.structuredContent,
-            };
-        },
-    };
+    const { codeSearch, codeExecute } = codeModeManager.createTools();
+    // Bridge the shared policy boundary to the ToolProvider interface. tool-cli
+    // sees exactly the policy-visible discovered schema set, and every call it
+    // makes is re-authorized by the same dispatcher, so it cannot reach a hidden
+    // tool by naming it directly.
+    const toolProvider = createPolicyToolProvider(policy, { upstream: mcpManager });
     const rpcServer = new ToolCliServer(toolProvider);
+    // Routing state the prompt reports on. tool-cli is only ever advertised after
+    // a compatible authenticated v1 handshake and confirmed bash availability.
+    let toolCliState = {
+        kind: "not_started",
+        reason: "the session has not finished starting",
+    };
+    let skillsExtensionEnabled = false;
+    let facilitiesPublished = false;
     // Register the load_skill tool so the model can activate MCP skills
-    pi.registerTool(createLoadSkillTool({ registry: skillRegistry, mcpManager, enabledTools }));
+    pi.registerTool(createLoadSkillTool({ registry: skillRegistry, policy, skillsClient }));
+    pi.registerTool(codeSearch);
+    pi.registerTool(codeExecute);
     pi.on("session_start", async (_event, ctx) => {
+        hostElicitation.setContext(ctx);
+        hostApproval.setContext(ctx);
+        withholdToolCliCredentials(pi);
         if (ctx.hasUI) {
             ctx.ui.notify("mcpi-ext loaded", "info");
         }
@@ -49,6 +81,15 @@ export default function (pi) {
         try {
             const config = await loadMcpConfig(configPath);
             const serverCount = Object.keys(config.mcpServers).length;
+            // Draft extension support is opt-in from either the config file or the
+            // CLI flag, and must be decided before any connection is opened because
+            // capabilities are fixed at initialize.
+            const skillsExtensionEnabledNow = pi.getFlag("mcp-skills-extension") === true || isSkillsExtensionEnabled(config);
+            skillsExtensionEnabled = skillsExtensionEnabledNow;
+            mcpManager.enableSkillsExtension(skillsExtensionEnabledNow);
+            if (skillsExtensionEnabledNow) {
+                log(skillsExtensionDiagnostic());
+            }
             if (serverCount > 0) {
                 await mcpManager.connectAll(config, log);
                 const tools = mcpManager.getTools();
@@ -56,49 +97,61 @@ export default function (pi) {
                 // Pre-register all MCP tools as deferred Pi tool proxies
                 // (in tools array for dispatch but excluded from system prompt)
                 const allToolNames = tools.map((t) => t.name);
-                registerMcpToolProxies(allToolNames, mcpManager, pi);
-                // Discover skills from all connected servers
+                registerMcpToolProxies(allToolNames, mcpManager, policy, pi);
+                // Discover skills from all connected servers. A server that declares
+                // the draft extension is served entirely by it: the legacy skill://
+                // resource scan is a compatibility fallback for servers that do not,
+                // never a second opinion on one that does. An empty extension listing
+                // therefore means "no skills right now", not "try the old way".
                 for (const serverName of mcpManager.getConnectedServers()) {
-                    const client = mcpManager.getClient(serverName);
-                    if (!client)
-                        continue;
+                    const viaExtension = skillsExtensionEnabled && skillsClient.supports(serverName);
                     try {
-                        const skills = await discoverSkillsFromServer(client, serverName, log);
-                        skillRegistry.registerAll(skills);
+                        if (viaExtension) {
+                            const result = await discoverSkillsViaExtension(policy, skillsClient, serverName, log);
+                            skillRegistry.registerAll(result.skills);
+                        }
+                        else {
+                            const skills = await discoverSkillsFromServer(policy, serverName, log);
+                            skillRegistry.registerAll(skills);
+                        }
                     }
                     catch (err) {
-                        log(`[skills] Failed to discover skills from "${serverName}": ${err.message}`);
-                    }
-                }
-                if (skillRegistry.size > 0) {
-                    for (const skill of skillRegistry.getAll()) {
-                        for (const t of skill.allowedTools) {
-                            gatedToolNames.add(t);
-                        }
+                        log(`[skills] Failed to discover skills from "${serverName}" via ${viaExtension ? "the draft skills extension" : "skill:// resources"}: ${err.message}`);
                     }
-                    log(`MCP: ${skillRegistry.size} skill(s) discovered, ${gatedToolNames.size} tool(s) deferred`);
                 }
-                // Start the tool-cli RPC server for progressive tool discovery
-                try {
-                    const { port, token } = await rpcServer.start(log);
-                    pi.setEnv("TOOL_CLI_PORT", String(port));
-                    pi.setEnv("TOOL_CLI_TOKEN", token);
+                for (const collision of skillRegistry.getCollisions()) {
+                    log(`[skills] Name collision on "${collision.name}": "${collision.challenger.serverName}" exposed as "${collision.registeredAs}" (name held by "${collision.incumbent.serverName}")`);
                 }
-                catch (err) {
-                    log(`[tool-cli] Failed to start RPC server: ${err.message}`);
-                }
-                // Initialize code mode (Tier 3) for read-only tools with structured output
-                codeModeManager.initialize(mcpManager);
-                if (codeModeManager.isActive) {
-                    const { codeSearch, codeExecute } = codeModeManager.createTools();
-                    pi.registerTool(codeSearch);
-                    pi.registerTool(codeExecute);
-                    log(`MCP: Code mode active (${codeModeManager.getEligibleTools().length} eligible tool(s))`);
+                // Hand the discovered skills to the policy so their tools are gated
+                // everywhere, not just on the mcpi dispatch path.
+                policy.registerSkills(skillRegistry.getAll());
+                if (skillRegistry.size > 0) {
+                    log(`MCP: ${skillRegistry.size} skill(s) discovered, ${policy.getGatedToolNames().length} tool(s) deferred`);
                 }
+                toolCliState = await startToolCliBridge({
+                    bash: detectBashState(pi),
+                    server: rpcServer,
+                    environment: pi,
+                    log,
+                });
             }
+            else {
+                toolCliState = {
+                    kind: "not_started",
+                    reason: "no MCP servers are configured, so there is nothing for it to expose",
+                };
+            }
+            // Code execution remains available even when no MCP servers or callable tools exist.
+            codeModeManager.initialize(mcpManager, policy, log);
+            // Probe the optional native sandbox backend once, so routing can state
+            // plainly whether code mode can run rather than assuming it can.
+            await codeModeManager.probeSandbox();
         }
         catch (err) {
-            const msg = `MCP config error: ${err.message}`;
+            withholdToolCliCredentials(pi);
+            await rpcServer.stop();
+            const msg = `MCP config error: ${errorMessage(err)}`;
+            toolCliState = { kind: "not_started", reason: msg };
             if (ctx.hasUI) {
                 ctx.ui.notify(msg, "warning");
             }
@@ -107,42 +160,68 @@ export default function (pi) {
             }
         }
     });
-    // Inject MCP skills, tool-cli advice, and code mode type hints into the system prompt
+    // Inject execution routing, MCP skills, tool-cli usage docs, and code mode
+    // type hints into the system prompt.
     pi.on("before_agent_start", async (event) => {
         let extra = "";
         const skills = skillRegistry.getAll();
+        const bashState = detectBashState(pi);
+        // Idempotent after the first resolution; covers hosts that reach
+        // before_agent_start without a preceding successful session_start.
+        const sandbox = await codeModeManager.probeSandbox();
+        // The routing section is emitted on every load, including with zero MCP
+        // servers — an agent still needs to know that exact computation and the
+        // shell are on the table, and why the MCP-backed facilities are not.
+        const facilities = buildExecutionFacilities({
+            skills: {
+                count: skills.length,
+                draftExtensionEnabled: skillsExtensionEnabled,
+            },
+            codeMode: { active: codeModeManager.isActive, reason: sandbox.reason },
+            toolCli: toolCliState,
+            bash: bashState,
+        });
+        // Prefer the host's own facility registry when it grows one. The two paths
+        // are mutually exclusive, so the section can never be emitted twice.
+        if (!facilitiesPublished) {
+            facilitiesPublished = publishExecutionFacilities(pi, facilities);
+        }
+        if (!facilitiesPublished) {
+            extra += formatExecutionFacilities(facilities);
+        }
         if (skills.length > 0) {
             extra += formatMcpSkillsForPrompt(skills);
         }
-        const serverCount = mcpManager.getConnectedServers().length;
-        extra += formatToolCliForPrompt(serverCount);
+        extra += formatToolCliForPrompt({ toolCli: toolCliState, bash: bashState });
         if (codeModeManager.isActive) {
+            codeModeManager.refresh();
             extra += codeModeManager.formatSystemPromptSection();
         }
         if (extra.length === 0)
             return;
         return { systemPrompt: event.systemPrompt + extra };
     });
-    // Block deferred MCP tools until their skill is loaded
+    // Block deferred MCP tools until their skill is loaded. The policy owns the
+    // decision so mcpi dispatch and the RPC path cannot disagree.
     pi.on("tool_call", async (event) => {
         const name = "toolName" in event ? event.toolName : undefined;
-        if (!name || !gatedToolNames.has(name) || enabledTools.has(name))
+        if (!name || !policy.isGated(name))
             return;
-        const relevantSkills = skillRegistry
-            .getAll()
-            .filter((s) => s.allowedTools.includes(name))
-            .map((s) => s.name);
+        const relevantSkills = policy.getGatingSkills(name);
         return {
             block: true,
             reason: `Tool "${name}" requires loading a skill first. Call load_skill with one of: ${relevantSkills.join(", ")}`,
         };
     });
     pi.on("session_shutdown", async () => {
-        pi.unsetEnv("TOOL_CLI_PORT");
-        pi.unsetEnv("TOOL_CLI_TOKEN");
+        hostElicitation.setContext(undefined);
+        hostApproval.setContext(undefined);
+        withholdToolCliCredentials(pi);
+        toolCliState = { kind: "not_started", reason: "the session has shut down" };
+        facilitiesPublished = false;
         await rpcServer.stop();
         await mcpManager.disconnectAll();
         skillRegistry.clear();
+        policy.reset();
     });
 }
-//# sourceMappingURL=index.js.map

package/dist/mcp/call-tool-result.d.ts

@@ -0,0 +1,10 @@
+import type { AgentToolResult } from "@sammorrowdrums/mcpi";
+import type { CallToolResult } from "@modelcontextprotocol/client";
+import type { CallToolResult as ToolCliCallToolResult } from "@sammorrowdrums/tool-cli";
+export interface TerminalCallToolResult {
+    readonly kind: "terminal";
+    readonly result: CallToolResult;
+}
+export declare function adaptTerminalCallToolResult(result: CallToolResult): TerminalCallToolResult;
+export declare function renderTerminalCallToolResult(terminal: TerminalCallToolResult): AgentToolResult<CallToolResult>;
+export declare function toToolCliCallToolResult(terminal: TerminalCallToolResult): ToolCliCallToolResult;

package/dist/mcp/call-tool-result.js

@@ -0,0 +1,70 @@
+export function adaptTerminalCallToolResult(result) {
+    return { kind: "terminal", result };
+}
+export function renderTerminalCallToolResult(terminal) {
+    const content = [];
+    if (terminal.result.isError) {
+        content.push({ type: "text", text: "MCP tool reported an error." });
+    }
+    for (const block of terminal.result.content) {
+        switch (block.type) {
+            case "text":
+                content.push({ type: "text", text: block.text });
+                break;
+            case "image":
+                content.push({ type: "image", data: block.data, mimeType: block.mimeType });
+                break;
+            case "audio":
+                content.push({
+                    type: "text",
+                    text: `[MCP audio: ${block.mimeType}; base64 payload preserved in result details]`,
+                });
+                break;
+            case "resource_link":
+                content.push({
+                    type: "text",
+                    text: formatResourceLink(block),
+                });
+                break;
+            case "resource":
+                content.push({
+                    type: "text",
+                    text: formatEmbeddedResource(block),
+                });
+                break;
+            default:
+                content.push({ type: "text", text: JSON.stringify(block, null, 2) });
+        }
+    }
+    if (terminal.result.structuredContent !== undefined) {
+        content.push({
+            type: "text",
+            text: `Structured content:\n${JSON.stringify(terminal.result.structuredContent, null, 2)}`,
+        });
+    }
+    if (content.length === 0) {
+        content.push({ type: "text", text: terminal.result.isError ? "MCP tool failed." : "" });
+    }
+    return {
+        content,
+        details: terminal.result,
+    };
+}
+export function toToolCliCallToolResult(terminal) {
+    return {
+        ...terminal.result,
+        content: [...terminal.result.content],
+    };
+}
+function formatResourceLink(block) {
+    const label = block.title ?? block.name ?? block.uri;
+    const details = [block.mimeType, block.description].filter(Boolean).join("; ");
+    return `[MCP resource link: ${label}] ${block.uri}${details ? ` (${details})` : ""}`;
+}
+function formatEmbeddedResource(block) {
+    const resource = block.resource;
+    if ("text" in resource) {
+        return `[MCP embedded resource: ${resource.uri}]\n${resource.text}`;
+    }
+    return `[MCP embedded resource: ${resource.uri}; ${resource.mimeType ?? "binary"} blob preserved in result details]`;
+}

package/dist/mcp/client-factory.d.ts

@@ -0,0 +1,59 @@
+import { Client, type DiscoverResult, type ElicitRequestParams, type ElicitResult, type Implementation, type ListChangedHandlers, type ProtocolEra, type ServerCapabilities } from "@modelcontextprotocol/client";
+export declare const MCP_CLIENT_IDENTITY: {
+    readonly name: "@sammorrowdrums/mcpi-ext";
+    readonly version: "1.0.0";
+};
+export declare const MCP_CLIENT_POLICY: {
+    readonly listMaxPages: 64;
+    readonly maxInputRequiredRounds: 4;
+    readonly probeTimeoutMs: 5000;
+    readonly requestTimeoutMs: 60000;
+    readonly maxTotalTimeoutMs: number;
+};
+export declare const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly ["2026-07-28", ...string[]];
+export interface McpElicitationHandler {
+    elicit(params: ElicitRequestParams): Promise<ElicitResult>;
+}
+export interface McpClientDiagnostics {
+    protocolVersion: string | undefined;
+    protocolEra: ProtocolEra | undefined;
+    discoverResult: DiscoverResult | undefined;
+    serverImplementation: Implementation | undefined;
+    serverCapabilities: ServerCapabilities | undefined;
+    /**
+     * What this client requested and what the server declared for the draft
+     * skills extension, so a draft feature is never silently in play.
+     */
+    skillsExtension: {
+        /** Whether this client advertised the extension at initialize. */
+        requested: boolean;
+        /** Pinned draft revision this implementation targets. */
+        revision: string;
+        /** Always `"draft"` — this is an unratified proposal. */
+        status: string;
+        /** Whether the server declared the extension back. */
+        serverDeclared: boolean;
+        /** Settings the server declared, or `undefined` if it declared none. */
+        serverCapability: Record<string, unknown> | undefined;
+    };
+}
+export interface CreateMcpClientOptions {
+    elicitation: McpElicitationHandler;
+    listChanged?: ListChangedHandlers;
+    /**
+     * Advertise the draft skills extension at initialize.
+     *
+     * Off by default. When false this client never mentions SEP-2640 on the
+     * wire, which is what makes the fallback path a genuine absence of the
+     * extension rather than a suppressed one.
+     */
+    skillsExtension?: boolean;
+}
+/**
+ * Creates every MCP client with the same identity, negotiated protocol policy,
+ * capabilities, pagination limit, and SDK-managed input_required handling.
+ */
+export declare function createMcpClient(options: CreateMcpClientOptions): Client;
+export declare function getMcpClientDiagnostics(client: Client, options?: {
+    skillsExtensionRequested?: boolean;
+}): McpClientDiagnostics;

package/dist/mcp/client-factory.js

@@ -0,0 +1,76 @@
+import { Client, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/client";
+import { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, } from "../skills/sep2640/spec.js";
+export const MCP_CLIENT_IDENTITY = {
+    name: "@sammorrowdrums/mcpi-ext",
+    version: "1.0.0",
+};
+export const MCP_CLIENT_POLICY = {
+    listMaxPages: 64,
+    maxInputRequiredRounds: 4,
+    probeTimeoutMs: 5_000,
+    requestTimeoutMs: 60_000,
+    maxTotalTimeoutMs: 10 * 60_000,
+};
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS = [
+    "2026-07-28",
+    ...SUPPORTED_PROTOCOL_VERSIONS,
+];
+/**
+ * Creates every MCP client with the same identity, negotiated protocol policy,
+ * capabilities, pagination limit, and SDK-managed input_required handling.
+ */
+export function createMcpClient(options) {
+    const client = new Client(MCP_CLIENT_IDENTITY, {
+        supportedProtocolVersions: [...MCP_SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: {
+            elicitation: { form: {} },
+            // Per SEP-2133 the extension is offered here, at initialize, and the
+            // server answers with its own settings. Every later skills request
+            // re-reads that answer instead of trusting a cached yes.
+            extensions: options.skillsExtension ? { [SKILLS_EXTENSION_NAME]: {} } : {},
+        },
+        versionNegotiation: {
+            mode: "auto",
+            probe: {
+                timeoutMs: MCP_CLIENT_POLICY.probeTimeoutMs,
+                maxRetries: 0,
+            },
+        },
+        inputRequired: {
+            autoFulfill: true,
+            maxRounds: MCP_CLIENT_POLICY.maxInputRequiredRounds,
+        },
+        listChanged: options.listChanged,
+        listMaxPages: MCP_CLIENT_POLICY.listMaxPages,
+        defaultCacheTtlMs: 0,
+    });
+    client.setRequestHandler("elicitation/create", (request) => options.elicitation.elicit(request.params));
+    return client;
+}
+export function getMcpClientDiagnostics(client, options = {}) {
+    // Diagnostics run inside `connectOne`, so this must never be able to fail a
+    // connection. `getServerCapabilities` is absent on minimal client doubles and
+    // returns undefined before initialize completes; either way an unavailable
+    // capability is reported as "not declared", never thrown.
+    const serverCapabilities = typeof client.getServerCapabilities === "function" ? client.getServerCapabilities() : undefined;
+    const declared = serverCapabilities?.extensions?.[SKILLS_EXTENSION_NAME];
+    const capability = declared !== undefined && declared !== null && typeof declared === "object"
+        ? declared
+        : undefined;
+    return {
+        protocolVersion: typeof client.getNegotiatedProtocolVersion === "function"
+            ? client.getNegotiatedProtocolVersion()
+            : undefined,
+        protocolEra: client.getProtocolEra(),
+        discoverResult: client.getDiscoverResult(),
+        serverImplementation: typeof client.getServerVersion === "function" ? client.getServerVersion() : undefined,
+        serverCapabilities,
+        skillsExtension: {
+            requested: options.skillsExtensionRequested === true,
+            revision: SKILLS_EXTENSION_REVISION,
+            status: SKILLS_EXTENSION_STATUS,
+            serverDeclared: capability !== undefined,
+            serverCapability: capability,
+        },
+    };
+}