@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/docker-e2e.js

@@ -0,0 +1,234 @@
+import { spawn } from "node:child_process";
+import { Type } from "typebox";
+const DOCKER_IMAGE = "mcpi-ext-e2e";
+const DockerE2EParams = Type.Object({
+    task: Type.String({ description: "The task/prompt to run inside the sandbox" }),
+    token: Type.String({
+        description: "GitHub token for Copilot model access",
+    }),
+    model: Type.Optional(Type.String({
+        description: "Model to use (e.g. claude-sonnet-4-5). Defaults to the provider default.",
+    })),
+    timeout: Type.Optional(Type.Number({
+        description: "Timeout in seconds. Defaults to 300 (5 minutes).",
+    })),
+});
+export function parseJsonlLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return { type: parsed.type ?? "unknown", timestamp: Date.now(), raw: trimmed };
+    }
+    catch {
+        return { type: "raw", timestamp: Date.now(), raw: trimmed };
+    }
+}
+export function extractAssistantText(log) {
+    const parts = [];
+    for (const entry of log) {
+        if (entry.type !== "message_end")
+            continue;
+        try {
+            const event = JSON.parse(entry.raw);
+            const msg = event.message;
+            if (msg?.role !== "assistant")
+                continue;
+            for (const part of msg.content ?? []) {
+                if (part.type === "text")
+                    parts.push(part.text);
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return parts.join("\n");
+}
+export function extractUsage(log) {
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    for (const entry of log) {
+        if (entry.type !== "message_end")
+            continue;
+        try {
+            const event = JSON.parse(entry.raw);
+            const msg = event.message;
+            if (msg?.role !== "assistant")
+                continue;
+            usage.turns++;
+            const u = msg.usage;
+            if (u) {
+                usage.input += u.input ?? 0;
+                usage.output += u.output ?? 0;
+                usage.cacheRead += u.cacheRead ?? 0;
+                usage.cacheWrite += u.cacheWrite ?? 0;
+                usage.cost += u.cost?.total ?? 0;
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    return usage;
+}
+export function extractModel(log) {
+    for (const entry of log) {
+        if (entry.type !== "message_end")
+            continue;
+        try {
+            const event = JSON.parse(entry.raw);
+            if (event.message?.model)
+                return event.message.model;
+        }
+        catch {
+            // skip
+        }
+    }
+    return undefined;
+}
+export function buildDockerArgs(image, params) {
+    const args = ["run", "--rm", "-e", `GITHUB_TOKEN=${params.token}`];
+    if (params.model) {
+        args.push("-e", `PI_MODEL=${params.model}`);
+    }
+    args.push(image, params.task);
+    return args;
+}
+export const dockerE2ETool = {
+    name: "docker_e2e",
+    label: "Docker E2E",
+    description: "Run a task end-to-end inside an isolated Docker container with pi and this project's extensions. Returns the full run log for evaluation.",
+    promptSnippet: "Run an isolated e2e task in Docker. Requires a GitHub token and task prompt.",
+    parameters: DockerE2EParams,
+    async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+        const startTime = Date.now();
+        const timeoutMs = (params.timeout ?? 300) * 1000;
+        const log = [];
+        let lastAssistantText = "";
+        const dockerArgs = buildDockerArgs(DOCKER_IMAGE, params);
+        const exitCode = await new Promise((resolve) => {
+            const proc = spawn("docker", dockerArgs, {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let buffer = "";
+            let timedOut = false;
+            let timeoutHandle;
+            if (timeoutMs > 0) {
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    proc.kill("SIGTERM");
+                    setTimeout(() => {
+                        if (!proc.killed)
+                            proc.kill("SIGKILL");
+                    }, 5000);
+                }, timeoutMs);
+            }
+            const processLine = (line) => {
+                const entry = parseJsonlLine(line);
+                if (!entry)
+                    return;
+                log.push(entry);
+                if (entry.type === "message_end") {
+                    const text = extractAssistantText(log);
+                    if (text)
+                        lastAssistantText = text;
+                }
+                onUpdate?.({
+                    content: [
+                        {
+                            type: "text",
+                            text: lastAssistantText || `(running… ${log.length} events)`,
+                        },
+                    ],
+                    details: {
+                        exitCode: null,
+                        log,
+                        duration: Date.now() - startTime,
+                        model: extractModel(log),
+                        usage: extractUsage(log),
+                    },
+                });
+            };
+            proc.stdout.on("data", (data) => {
+                buffer += data.toString();
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines)
+                    processLine(line);
+            });
+            proc.stderr.on("data", (data) => {
+                const text = data.toString().trim();
+                if (text) {
+                    log.push({ type: "stderr", timestamp: Date.now(), raw: text });
+                }
+            });
+            proc.on("close", (code) => {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                if (buffer.trim())
+                    processLine(buffer);
+                if (timedOut) {
+                    log.push({
+                        type: "timeout",
+                        timestamp: Date.now(),
+                        raw: `Timed out after ${params.timeout ?? 300}s`,
+                    });
+                }
+                resolve(timedOut ? null : (code ?? 1));
+            });
+            proc.on("error", (err) => {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                log.push({
+                    type: "error",
+                    timestamp: Date.now(),
+                    raw: err.message,
+                });
+                resolve(null);
+            });
+            if (signal) {
+                const onAbort = () => {
+                    proc.kill("SIGTERM");
+                    setTimeout(() => {
+                        if (!proc.killed)
+                            proc.kill("SIGKILL");
+                    }, 5000);
+                };
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            }
+        });
+        const duration = Date.now() - startTime;
+        const assistantText = extractAssistantText(log);
+        const usage = extractUsage(log);
+        const model = extractModel(log);
+        const fullLog = log.map((e) => e.raw).join("\n");
+        const summary = [
+            `## Docker E2E Run Complete`,
+            ``,
+            `**Exit code:** ${exitCode ?? "killed"}`,
+            `**Duration:** ${(duration / 1000).toFixed(1)}s`,
+            model ? `**Model:** ${model}` : null,
+            usage.turns > 0
+                ? `**Usage:** ${usage.turns} turns, ↑${usage.input} ↓${usage.output} tokens, $${usage.cost.toFixed(4)}`
+                : null,
+            ``,
+            `### Output`,
+            assistantText || "(no assistant output)",
+            ``,
+            `### Full Log (${log.length} events)`,
+            "```",
+            fullLog,
+            "```",
+        ]
+            .filter((l) => l !== null)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: summary }],
+            details: { exitCode, log, duration, model, usage },
+        };
+    },
+};

package/dist/index.d.ts

@@ -0,0 +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;

package/dist/index.js

@@ -0,0 +1,227 @@
+import { CodeModeManager } from "./code-mode/index.js";
+import { dockerE2ETool } from "./docker-e2e.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",
+    });
+    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 { 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, 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");
+        }
+        const configPath = pi.getFlag("mcp-config");
+        const log = (msg) => {
+            if (ctx.hasUI) {
+                ctx.ui.notify(msg, "info");
+            }
+            else {
+                console.error(msg);
+            }
+        };
+        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();
+                log(`MCP: ${mcpManager.getConnectedServers().length} server(s), ${tools.length} tool(s) discovered`);
+                // 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, 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 viaExtension = skillsExtensionEnabled && skillsClient.supports(serverName);
+                    try {
+                        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}" via ${viaExtension ? "the draft skills extension" : "skill:// resources"}: ${err.message}`);
+                    }
+                }
+                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}")`);
+                }
+                // 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) {
+            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");
+            }
+            else {
+                console.error(msg);
+            }
+        }
+    });
+    // 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);
+        }
+        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. 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 || !policy.isGated(name))
+            return;
+        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 () => {
+        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();
+    });
+}

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;