@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.1

package/dist/code-mode/index.js

@@ -1,35 +1,111 @@
-import { getEligibleTools } from "./eligibility.js";
-import { executeInSandbox } from "./executor.js";
+import { McpPolicyError } from "../mcp/policy.js";
+import { getCodeModeDiagnostics, getCodeModeTools, } from "./eligibility.js";
+import { CodeModeDispatchError, executeInSandbox } from "./executor.js";
+import { loadIsolatedVm } from "./isolated-vm.js";
 import { createCodeExecuteTool, createCodeSearchTool } from "./tools.js";
 import { generateTypeHints } from "./type-hints.js";
-export { getEligibleTools, isEligibleForCodeMode } from "./eligibility.js";
-export { executeInSandbox, normalizeCode } from "./executor.js";
+export { SYNTHESIZED_OUTPUT_SCHEMA, getCodeModeDiagnostics, getCodeModeTools, getEligibleTools, isEligibleForCodeMode, toCodeModeTool, } from "./eligibility.js";
+export { SANDBOX_UNAVAILABLE_ERROR, executeInSandbox, normalizeCode } from "./executor.js";
+export { loadIsolatedVm, peekIsolatedVm, resetIsolatedVmCacheForTests, setIsolatedVmForTests, } from "./isolated-vm.js";
 export { createCodeExecuteTool, createCodeSearchTool } from "./tools.js";
 export { generateTypeHints, jsonSchemaToTypeString, sanitizeToolName } from "./type-hints.js";
+const NO_ELIGIBLE_TOOLS_ERROR = {
+    error: "no_eligible_tools",
+    message: "code_search has no callable read-only MCP tools to search.",
+    alternatives: ["code_execute", "tool-cli"],
+};
+const SANDBOX_UNPROBED = {
+    state: "unknown",
+    reason: "the isolated-vm native addon has not been probed yet",
+};
+const SANDBOX_INJECTED = {
+    state: "available",
+    reason: "a sandbox executor was supplied directly, bypassing the isolated-vm addon",
+};
+const SANDBOX_NATIVE = {
+    state: "available",
+    reason: "the isolated-vm native addon loaded",
+};
 /**
- * Orchestrates code mode: discovers eligible tools, generates type hints,
+ * Orchestrates code mode: catalogs tools, generates type hints,
  * and executes model-generated code in a sandbox with tool dispatch.
  */
 export class CodeModeManager {
     mcpManager = null;
-    eligibleTools = [];
-    typeHints = "";
+    policy = null;
+    codeModeTools = [];
+    diagnostics = getCodeModeDiagnostics([]);
+    typeHints = generateTypeHints([]);
     options;
+    sandboxExecutor;
+    log;
+    lastDiagnosticSummary = "";
+    sandbox;
+    sandboxProbe;
     constructor(options = {}) {
         this.options = options;
+        this.sandboxExecutor = options.sandboxExecutor ?? executeInSandbox;
+        this.log = options.log;
+        // An injected executor is the sandbox. Probing the native addon in that
+        // case would report on a backend this manager will never call.
+        this.sandbox = options.sandboxExecutor ? SANDBOX_INJECTED : SANDBOX_UNPROBED;
     }
-    /** Initialize with MCP manager, discover eligible tools, generate type hints. */
-    initialize(mcpManager) {
+    /**
+     * Whether code mode should be advertised to the model.
+     *
+     * Only a *proven* unavailable sandbox switches this off. An unprobed backend
+     * stays active because `code_execute` is registered synchronously at load and
+     * returns a structured `sandbox_unavailable` error if it turns out it cannot
+     * run — a truthful refusal at call time beats hiding a facility that works.
+     */
+    get isActive() {
+        return this.sandbox.state !== "unavailable";
+    }
+    /** Current sandbox backend availability, without triggering a probe. */
+    getSandboxAvailability() {
+        return this.sandbox;
+    }
+    /**
+     * Load the optional native addon once and cache the verdict.
+     *
+     * Safe to call from any lifecycle hook; concurrent callers share one probe.
+     */
+    async probeSandbox() {
+        if (this.sandbox.state !== "unknown")
+            return this.sandbox;
+        this.sandboxProbe ??= loadIsolatedVm().then((load) => {
+            this.sandbox = load.available
+                ? SANDBOX_NATIVE
+                : { state: "unavailable", reason: load.reason };
+            if (!load.available) {
+                this.log?.(`[code-mode] disabled: ${load.reason}. Skills, tool-cli, and routing are unaffected.`);
+            }
+            return this.sandbox;
+        });
+        return this.sandboxProbe;
+    }
+    /** Initialize with MCP manager and policy, catalog tools, and generate type hints. */
+    initialize(mcpManager, policy, log) {
         this.mcpManager = mcpManager;
+        this.policy = policy;
+        this.log = log ?? this.log;
         this.refresh();
     }
-    /** Refresh eligible tools and type hints (call on tools/list_changed). */
+    /** Refresh the complete tool catalog and type hints (call on tools/list_changed). */
     refresh() {
-        if (!this.mcpManager)
-            return;
-        this.eligibleTools = getEligibleTools(this.mcpManager);
-        this.typeHints = generateTypeHints(this.eligibleTools);
-        this.options.log?.(`[code-mode] ${this.eligibleTools.length} eligible tool(s), ${this.typeHints.length} chars of type hints`);
+        this.codeModeTools = this.mcpManager ? getCodeModeTools(this.mcpManager) : [];
+        this.diagnostics = getCodeModeDiagnostics(this.codeModeTools);
+        this.typeHints = generateTypeHints(this.codeModeTools);
+        const summary = `[code-mode] ${this.diagnostics.totalTools} tool(s): ` +
+            `${this.diagnostics.callableTools} callable, ${this.diagnostics.refusedTools} dispatch-refused; ` +
+            `output schemas: ${this.diagnostics.declaredOutputSchemas} declared, ` +
+            `${this.diagnostics.synthesizedOutputSchemas} synthesized, ` +
+            `${this.diagnostics.unavailableOutputSchemas} unavailable; ` +
+            `${this.typeHints.length} chars of type hints`;
+        if (summary !== this.lastDiagnosticSummary) {
+            this.log?.(summary);
+            this.lastDiagnosticSummary = summary;
+        }
     }
     /** Get the type hints string for injection into system prompt. */
     getTypeHints() {
@@ -37,18 +113,34 @@ export class CodeModeManager {
     }
     /** Get eligible tools. */
     getEligibleTools() {
-        return this.eligibleTools;
+        return this.codeModeTools.filter((entry) => entry.callable).map((entry) => entry.tool);
     }
-    /** Whether code mode has any eligible tools. */
-    get isActive() {
-        return this.eligibleTools.length > 0;
+    /** Get the complete client-internal catalog, including permission and schema provenance. */
+    getCatalogTools() {
+        return this.codeModeTools;
+    }
+    getDiagnostics() {
+        return this.diagnostics;
     }
     /** Execute code in search mode (tool catalog queries). */
     async searchTools(code) {
+        this.refresh();
+        if (this.diagnostics.callableTools === 0) {
+            return {
+                result: undefined,
+                error: NO_ELIGIBLE_TOOLS_ERROR.message,
+                errorDetails: {
+                    ...NO_ELIGIBLE_TOOLS_ERROR,
+                    alternatives: [...(NO_ELIGIBLE_TOOLS_ERROR.alternatives ?? [])],
+                },
+                logs: [],
+            };
+        }
         return this.execute(code);
     }
     /** Execute code that chains MCP tool calls. */
     async executeCode(code) {
+        this.refresh();
         return this.execute(code);
     }
     /** Create the Pi tool definitions for code_search and code_execute. */
@@ -60,14 +152,15 @@ export class CodeModeManager {
     }
     /** Format a system prompt section for code mode. */
     formatSystemPromptSection() {
-        if (!this.isActive)
-            return "";
         return [
             "",
             "<code_mode>",
             "## Code mode",
             "",
-            "`code_execute` runs vanilla JavaScript in a sandboxed V8 isolate. Use it for:",
+            "Use when a task needs exact computation or control flow: math, aggregation, looping over",
+            "results, data transformation, or chaining several MCP tool calls with logic in between.",
+            "",
+            "`code_execute` runs vanilla JavaScript in a sandboxed V8 isolate. Concretely, that covers:",
             "",
             "1. **Arbitrary computation** — math, string manipulation, date arithmetic, data transformation,",
             "   or any calculation the user asks for. No MCP tools needed; plain JS works.",
@@ -75,21 +168,10 @@ export class CodeModeManager {
             "   many tool calls. Write a loop inside one `code_execute` instead of making many separate tool calls.",
             "3. **Pagination** — fetch batches in a loop until exhausted, then compute over the full dataset.",
             "",
-            "Use `code_search` first to discover what tools are available before writing execution code.",
-            "",
-            "**Code mode tools are always available — you do not need to call `load_skill` first.**",
+            "Use `code_search` first to discover which MCP tools are reachable from inside the sandbox.",
             "",
-            "### Choosing the right approach",
+            "`code_search` and `code_execute` are always registered and never gated.",
             "",
-            "- **Skill** (`load_skill`) — a curated workflow exists for this domain task (e.g., a GitHub skill for PR management).",
-            "- **tool-cli** — you need to discover what tools exist, or make a quick ad-hoc tool call.",
-            "- **Code mode** (`code_execute`) — you need computation: math, aggregation, looping over results,",
-            "  data transformation, or chaining multiple tool calls with logic in between.",
-            "",
-            "Pick based on what the task needs, not a fixed order. A calculation goes straight to code mode;",
-            "a single lookup goes to a skill or tool-cli; exploration starts with tool-cli or `code_search`.",
-            "",
-            "**If unsure what's available**, start with `code_search` or `tool-cli --help` to see what you have.",
             "After producing a result, verify it makes sense — run a quick sanity check or spot-check values.",
             "",
             "### How to write code",
@@ -131,45 +213,55 @@ export class CodeModeManager {
         ].join("\n");
     }
     async execute(code) {
-        if (!this.mcpManager) {
-            return { result: undefined, error: "Code mode not initialized", logs: [] };
-        }
-        // Refresh eligible tools in case MCP servers changed since initialization
-        this.refresh();
-        const toolNames = this.eligibleTools.map((t) => t.name);
+        const policy = this.policy;
+        const toolNames = this.codeModeTools.map((entry) => entry.tool.name);
         const dispatch = async (toolName, args) => {
-            const tool = this.eligibleTools.find((t) => t.name === toolName);
-            if (!tool) {
+            const codeModeTool = this.codeModeTools.find((entry) => entry.tool.name === toolName);
+            if (!codeModeTool) {
                 throw new Error(`Tool "${toolName}" not found in code mode eligible tools`);
             }
-            const client = this.mcpManager?.getClient(tool.serverName);
-            if (!client) {
-                throw new Error(`MCP server "${tool.serverName}" is not connected`);
+            if (!policy) {
+                throw new Error("Code mode MCP policy is not initialized");
             }
-            const result = await client.callTool({ name: toolName, arguments: args });
-            // Prefer structuredContent (typed output) over raw content
-            if (result.structuredContent) {
-                return result.structuredContent;
+            try {
+                const terminal = await policy.callTool({
+                    source: "code-mode",
+                    serverName: codeModeTool.tool.serverName,
+                    toolName: codeModeTool.tool.name,
+                    args,
+                });
+                return terminal.result;
             }
-            // Fall back to parsing text content
-            if (Array.isArray(result.content)) {
-                const textParts = result.content
-                    .filter((c) => typeof c === "object" && c !== null && "text" in c)
-                    .map((c) => c.text);
-                const combined = textParts.join("\n");
-                try {
-                    return JSON.parse(combined);
-                }
-                catch {
-                    return combined;
-                }
+            catch (error) {
+                throw toCodeModeDispatchError(error, codeModeTool);
             }
-            return result;
         };
-        return executeInSandbox(code, toolNames, dispatch, {
+        return this.sandboxExecutor(code, toolNames, dispatch, {
             memoryLimit: this.options.memoryLimit,
             timeoutMs: this.options.timeoutMs,
         });
     }
 }
-//# sourceMappingURL=index.js.map
+/**
+ * Translate a policy denial into Code Mode's structured dispatch error, keeping
+ * the catalog's refusal detail so the model learns why a tool was refused.
+ */
+function toCodeModeDispatchError(error, codeModeTool) {
+    if (!(error instanceof McpPolicyError))
+        return error;
+    const isPermission = error.reason === "permission_denied";
+    return new CodeModeDispatchError({
+        error: isPermission ? "permission_denied" : error.reason,
+        message: error.message,
+        alternatives: [...error.alternatives],
+        toolName: codeModeTool.tool.name,
+        ...(isPermission ? { reason: formatRefusalReasons(codeModeTool) } : {}),
+    });
+}
+function formatRefusalReasons(codeModeTool) {
+    return codeModeTool.refusalReasons
+        .map((reason) => reason === "destructive_hint"
+        ? "annotations.destructiveHint is true"
+        : "annotations.readOnlyHint is not true")
+        .join("; ");
+}

package/dist/code-mode/isolated-vm.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Lazy adapter for the optional `isolated-vm` native addon.
+ *
+ * Code Mode is the only feature that needs a real V8 isolate. `isolated-vm` is a
+ * native addon, so it can legitimately be absent: an unsupported platform, a
+ * missing prebuild with no toolchain to compile one, or a deliberate
+ * `--omit=optional` install. When that happens Code Mode must report itself
+ * unavailable and the rest of the extension — skills, tool-cli, routing — must
+ * keep working.
+ *
+ * Two rules govern this module:
+ *
+ * 1. **No top-level import.** The specifier is resolved through a dynamic
+ *    `import()` behind a variable so neither Node nor TypeScript binds to the
+ *    addon at module-evaluation time. Loading the extension never throws
+ *    because a native addon is missing.
+ * 2. **Never fall back to Node's `vm`.** `node:vm` shares the host heap and
+ *    realm; it is a code-organisation tool, not a security boundary. Silently
+ *    downgrading to it would turn "sandboxed execution" into a false claim.
+ *    If the addon is absent, Code Mode is unavailable — full stop.
+ */
+/** The subset of the `isolated-vm` surface Code Mode actually uses. */
+export interface IsolatedVmContext {
+    readonly global: {
+        set(name: string, value: unknown): Promise<void>;
+    };
+    eval(code: string, options: {
+        promise: true;
+        copy: true;
+        timeout: number;
+    }): Promise<unknown>;
+}
+export interface IsolatedVmIsolate {
+    createContext(): Promise<IsolatedVmContext>;
+    dispose(): void;
+}
+export interface IsolatedVmModule {
+    Isolate: new (options: {
+        memoryLimit: number;
+    }) => IsolatedVmIsolate;
+    Callback: new (fn: (...args: never[]) => unknown) => unknown;
+    Reference: new (fn: (...args: never[]) => unknown) => unknown;
+}
+/** Outcome of attempting to load the native addon. */
+export type IsolatedVmLoad = {
+    readonly available: true;
+    readonly module: IsolatedVmModule;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+/**
+ * Load the native addon at most once per process.
+ *
+ * The result — success *or* failure — is cached. A failed load is not retried:
+ * a missing or broken native addon does not become present later in the same
+ * process, and retrying would repeat the cost on every Code Mode call.
+ */
+export declare function loadIsolatedVm(): Promise<IsolatedVmLoad>;
+/** Synchronously report a previously resolved load, if one has happened. */
+export declare function peekIsolatedVm(): IsolatedVmLoad | undefined;
+/** Reset the memoised state. Test-only. */
+export declare function resetIsolatedVmCacheForTests(): void;
+/** Seed the memoised state. Test-only — lets tests simulate an absent addon. */
+export declare function setIsolatedVmForTests(load: IsolatedVmLoad): void;

package/dist/code-mode/isolated-vm.js

@@ -0,0 +1,116 @@
+/**
+ * Lazy adapter for the optional `isolated-vm` native addon.
+ *
+ * Code Mode is the only feature that needs a real V8 isolate. `isolated-vm` is a
+ * native addon, so it can legitimately be absent: an unsupported platform, a
+ * missing prebuild with no toolchain to compile one, or a deliberate
+ * `--omit=optional` install. When that happens Code Mode must report itself
+ * unavailable and the rest of the extension — skills, tool-cli, routing — must
+ * keep working.
+ *
+ * Two rules govern this module:
+ *
+ * 1. **No top-level import.** The specifier is resolved through a dynamic
+ *    `import()` behind a variable so neither Node nor TypeScript binds to the
+ *    addon at module-evaluation time. Loading the extension never throws
+ *    because a native addon is missing.
+ * 2. **Never fall back to Node's `vm`.** `node:vm` shares the host heap and
+ *    realm; it is a code-organisation tool, not a security boundary. Silently
+ *    downgrading to it would turn "sandboxed execution" into a false claim.
+ *    If the addon is absent, Code Mode is unavailable — full stop.
+ */
+/**
+ * Resolved through a variable rather than a string literal so that TypeScript
+ * does not require `isolated-vm` types to be present to build, and so no
+ * bundler or loader statically links the addon into the module graph.
+ */
+const ISOLATED_VM_SPECIFIER = "isolated-vm";
+const MISSING_MODULE_CODES = new Set([
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND",
+    "ERR_DLOPEN_FAILED",
+]);
+let cached;
+let inFlight;
+/**
+ * Load the native addon at most once per process.
+ *
+ * The result — success *or* failure — is cached. A failed load is not retried:
+ * a missing or broken native addon does not become present later in the same
+ * process, and retrying would repeat the cost on every Code Mode call.
+ */
+export async function loadIsolatedVm() {
+    if (cached)
+        return cached;
+    inFlight ??= attemptLoad().then((result) => {
+        cached = result;
+        inFlight = undefined;
+        return result;
+    });
+    return inFlight;
+}
+/** Synchronously report a previously resolved load, if one has happened. */
+export function peekIsolatedVm() {
+    return cached;
+}
+/** Reset the memoised state. Test-only. */
+export function resetIsolatedVmCacheForTests() {
+    cached = undefined;
+    inFlight = undefined;
+}
+/** Seed the memoised state. Test-only — lets tests simulate an absent addon. */
+export function setIsolatedVmForTests(load) {
+    cached = load;
+    inFlight = undefined;
+}
+async function attemptLoad() {
+    try {
+        const imported = await import(ISOLATED_VM_SPECIFIER);
+        const candidate = unwrapDefault(imported);
+        if (!isIsolatedVmModule(candidate)) {
+            return {
+                available: false,
+                reason: "the optional isolated-vm addon loaded but did not expose the expected Isolate/Callback/Reference API",
+            };
+        }
+        return { available: true, module: candidate };
+    }
+    catch (error) {
+        return { available: false, reason: describeLoadFailure(error) };
+    }
+}
+function unwrapDefault(imported) {
+    if (typeof imported !== "object" || imported === null)
+        return imported;
+    const namespace = imported;
+    return namespace.default ?? imported;
+}
+function isIsolatedVmModule(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.Isolate === "function" &&
+        typeof candidate.Callback === "function" &&
+        typeof candidate.Reference === "function");
+}
+/**
+ * Turn a load failure into a reason a human can act on.
+ *
+ * The two failure shapes are meaningfully different: "not installed" is fixed
+ * by installing it, while "installed but failed to load" points at an ABI or
+ * platform mismatch and needs a rebuild.
+ */
+function describeLoadFailure(error) {
+    const code = getErrorCode(error);
+    const detail = error instanceof Error ? error.message : String(error);
+    if (code && MISSING_MODULE_CODES.has(code)) {
+        return `the optional isolated-vm native addon is not installed or failed to load (${code}: ${detail})`;
+    }
+    return `the optional isolated-vm native addon could not be loaded (${detail})`;
+}
+function getErrorCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}

package/dist/code-mode/tools.d.ts

@@ -9,6 +9,10 @@ export interface CodeModeToolDetails {
     executionMs: number;
     logs: string[];
     error?: string;
+    message?: string;
+    alternatives?: string[];
+    toolName?: string;
+    reason?: string;
 }
 /**
  * Create the `code_search` tool for querying the tool catalog.
@@ -42,4 +46,3 @@ export declare function createCodeExecuteTool(manager: CodeModeManager): {
     execute(_toolCallId: string, params: CodeInputType, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<CodeModeToolDetails>>;
 };
 export {};
-//# sourceMappingURL=tools.d.ts.map

package/dist/code-mode/tools.js

@@ -7,13 +7,17 @@ const CodeInput = Type.Object({
 /** Format an ExecuteResult into a tool response. Falls back to logs if result is undefined. */
 function formatResult(result, executionMs, errorPrefix) {
     if (result.error) {
+        const errorDetails = result.errorDetails ?? {
+            error: "execution_failed",
+            message: result.error,
+        };
         return {
             content: [{ type: "text", text: `${errorPrefix}: ${result.error}` }],
-            details: { executionMs, logs: result.logs, error: result.error },
+            details: { executionMs, logs: result.logs, ...errorDetails },
         };
     }
     // If code didn't return a value, fall back to captured console output
-    const output = result.result !== undefined && result.result !== null
+    const output = result.result !== undefined
         ? typeof result.result === "string"
             ? result.result
             : JSON.stringify(result.result, null, 2)
@@ -38,7 +42,7 @@ export function createCodeSearchTool(manager) {
     return {
         name: "code_search",
         label: "Code Search",
-        description: "Discover available read-only MCP tools by writing JavaScript. Use `codemode.listTools()` to list tools and `codemode.describeTools(names)` for type info. Use this before code_execute to understand what data sources are available.",
+        description: "Discover all available MCP tools by writing JavaScript. Use `codemode.listTools()` to list tools and `codemode.describeTools(names)` for type info. Type hints identify which tools Code Mode can call; non-read-only tools remain discovery-only.",
         parameters: CodeInput,
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const start = performance.now();
@@ -67,4 +71,3 @@ export function createCodeExecuteTool(manager) {
         },
     };
 }
-//# sourceMappingURL=tools.js.map

package/dist/code-mode/type-hints.d.ts

@@ -1,4 +1,5 @@
 import type { McpTool } from "../mcp/index.js";
+import { type CodeModeTool } from "./eligibility.js";
 type JsonSchema = Record<string, unknown>;
 /**
  * Convert a JSON Schema to a TypeScript type string.
@@ -15,6 +16,5 @@ export declare function sanitizeToolName(name: string): string;
  * Produces a `declare const codemode: { ... }` block with type-safe
  * method signatures the model can use when writing code.
  */
-export declare function generateTypeHints(tools: McpTool[]): string;
+export declare function generateTypeHints(tools: readonly (McpTool | CodeModeTool)[]): string;
 export {};
-//# sourceMappingURL=type-hints.d.ts.map

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