@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.1

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

@@ -1,10 +1,35 @@
 import type { McpClientManager, McpTool } from "../mcp/index.js";
+export declare const SYNTHESIZED_OUTPUT_SCHEMA: NonNullable<McpTool["outputSchema"]>;
+export type OutputSchemaProvenance = "declared" | "synthesized" | "unavailable";
+export type CodeModeRefusalReason = "destructive_hint" | "read_only_hint_required";
 /**
- * A tool is eligible for code mode when:
- * 1. annotations.readOnlyHint === true — does not modify its environment
- * 2. outputSchema is defined — results are typed and parseable
+ * Client-internal Code Mode metadata. The source MCP tool is retained separately
+ * so provenance never becomes part of an MCP request or response.
+ */
+export interface CodeModeTool {
+    readonly tool: McpTool;
+    readonly callable: boolean;
+    readonly refusalReasons: readonly CodeModeRefusalReason[];
+    readonly outputSchema?: NonNullable<McpTool["outputSchema"]>;
+    readonly outputSchemaProvenance: OutputSchemaProvenance;
+}
+export interface CodeModeDiagnostics {
+    readonly totalTools: number;
+    readonly callableTools: number;
+    readonly refusedTools: number;
+    readonly declaredOutputSchemas: number;
+    readonly synthesizedOutputSchemas: number;
+    readonly unavailableOutputSchemas: number;
+}
+/**
+ * Code Mode dispatch is allowed only when a tool explicitly declares itself
+ * read-only and does not also declare destructive behavior.
  */
 export declare function isEligibleForCodeMode(tool: McpTool): boolean;
 /** Get all tools eligible for code mode across all connected MCP servers. */
 export declare function getEligibleTools(mcpManager: McpClientManager): McpTool[];
-//# sourceMappingURL=eligibility.d.ts.map
+/** Build the internal Code Mode catalog without mutating source MCP tool definitions. */
+export declare function toCodeModeTool(tool: McpTool): CodeModeTool;
+/** Get every discovered MCP tool with Code Mode permission and schema metadata. */
+export declare function getCodeModeTools(mcpManager: McpClientManager): CodeModeTool[];
+export declare function getCodeModeDiagnostics(tools: readonly CodeModeTool[]): CodeModeDiagnostics;

package/dist/code-mode/eligibility.js

@@ -1,14 +1,64 @@
+export const SYNTHESIZED_OUTPUT_SCHEMA = Object.freeze({});
 /**
- * A tool is eligible for code mode when:
- * 1. annotations.readOnlyHint === true — does not modify its environment
- * 2. outputSchema is defined — results are typed and parseable
+ * Code Mode dispatch is allowed only when a tool explicitly declares itself
+ * read-only and does not also declare destructive behavior.
  */
 export function isEligibleForCodeMode(tool) {
-    const annotations = tool.annotations;
-    return annotations?.readOnlyHint === true && tool.outputSchema != null;
+    return tool.annotations?.readOnlyHint === true && tool.annotations.destructiveHint !== true;
 }
 /** Get all tools eligible for code mode across all connected MCP servers. */
 export function getEligibleTools(mcpManager) {
     return mcpManager.getTools().filter(isEligibleForCodeMode);
 }
-//# sourceMappingURL=eligibility.js.map
+/** Build the internal Code Mode catalog without mutating source MCP tool definitions. */
+export function toCodeModeTool(tool) {
+    const refusalReasons = [];
+    if (tool.annotations?.readOnlyHint !== true) {
+        refusalReasons.push("read_only_hint_required");
+    }
+    if (tool.annotations?.destructiveHint === true) {
+        refusalReasons.push("destructive_hint");
+    }
+    const callable = refusalReasons.length === 0;
+    const declaredOutputSchema = tool.outputSchema !== undefined && tool.outputSchema !== null ? tool.outputSchema : undefined;
+    if (declaredOutputSchema) {
+        return {
+            tool,
+            callable,
+            refusalReasons,
+            outputSchema: declaredOutputSchema,
+            outputSchemaProvenance: "declared",
+        };
+    }
+    if (callable) {
+        return {
+            tool,
+            callable,
+            refusalReasons,
+            outputSchema: SYNTHESIZED_OUTPUT_SCHEMA,
+            outputSchemaProvenance: "synthesized",
+        };
+    }
+    return {
+        tool,
+        callable,
+        refusalReasons,
+        outputSchemaProvenance: "unavailable",
+    };
+}
+/** Get every discovered MCP tool with Code Mode permission and schema metadata. */
+export function getCodeModeTools(mcpManager) {
+    return mcpManager.getTools().map(toCodeModeTool);
+}
+export function getCodeModeDiagnostics(tools) {
+    const callableTools = tools.filter((tool) => tool.callable).length;
+    const countProvenance = (provenance) => tools.filter((tool) => tool.outputSchemaProvenance === provenance).length;
+    return {
+        totalTools: tools.length,
+        callableTools,
+        refusedTools: tools.length - callableTools,
+        declaredOutputSchemas: countProvenance("declared"),
+        synthesizedOutputSchemas: countProvenance("synthesized"),
+        unavailableOutputSchemas: countProvenance("unavailable"),
+    };
+}

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

@@ -2,8 +2,20 @@
 export interface ExecuteResult {
     result: unknown;
     error?: string;
+    errorDetails?: CodeModeErrorDetails;
     logs: string[];
 }
+export interface CodeModeErrorDetails {
+    error: string;
+    message: string;
+    alternatives?: string[];
+    toolName?: string;
+    reason?: string;
+}
+export declare class CodeModeDispatchError extends Error {
+    readonly details: CodeModeErrorDetails;
+    constructor(details: CodeModeErrorDetails);
+}
 /** A function the sandbox can call to invoke an MCP tool. */
 export type ToolDispatchFn = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
 export interface ExecutorOptions {
@@ -12,6 +24,8 @@ export interface ExecutorOptions {
     /** Execution timeout in milliseconds. Default: 30000. */
     timeoutMs?: number;
 }
+/** Error code surfaced when the V8 isolate backend is not installed. */
+export declare const SANDBOX_UNAVAILABLE_ERROR = "sandbox_unavailable";
 /**
  * Execute model-generated JavaScript code in an isolated V8 sandbox.
  *
@@ -23,6 +37,11 @@ export interface ExecutorOptions {
  *
  * Tool calls are dispatched to the host via `Reference` callbacks —
  * actual MCP tool execution happens outside the sandbox.
+ *
+ * The `isolated-vm` addon is optional and loaded lazily. If it is unavailable
+ * this returns a structured `sandbox_unavailable` error rather than falling
+ * back to Node's `vm` module: `node:vm` shares the host realm and heap, so
+ * using it here would silently void the isolation guarantee this API makes.
  */
 export declare function executeInSandbox(code: string, toolNames: string[], dispatch: ToolDispatchFn, options?: ExecutorOptions): Promise<ExecuteResult>;
 /**
@@ -32,4 +51,3 @@ export declare function executeInSandbox(code: string, toolNames: string[], disp
  * - Otherwise leave code as a statement block; callers must explicitly `return` a value
  */
 export declare function normalizeCode(code: string): string;
-//# sourceMappingURL=executor.d.ts.map

package/dist/code-mode/executor.js

@@ -1,7 +1,18 @@
-import ivm from "isolated-vm";
+import { loadIsolatedVm } from "./isolated-vm.js";
 import { sanitizeToolName } from "./type-hints.js";
+export class CodeModeDispatchError extends Error {
+    details;
+    constructor(details) {
+        super(details.message);
+        this.details = details;
+        this.name = "CodeModeDispatchError";
+    }
+}
 const DEFAULT_MEMORY_LIMIT = 128;
 const DEFAULT_TIMEOUT_MS = 30_000;
+const STRUCTURED_ERROR_PREFIX = "__CODE_MODE_ERROR__";
+/** Error code surfaced when the V8 isolate backend is not installed. */
+export const SANDBOX_UNAVAILABLE_ERROR = "sandbox_unavailable";
 /**
  * Execute model-generated JavaScript code in an isolated V8 sandbox.
  *
@@ -13,19 +24,40 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  *
  * Tool calls are dispatched to the host via `Reference` callbacks —
  * actual MCP tool execution happens outside the sandbox.
+ *
+ * The `isolated-vm` addon is optional and loaded lazily. If it is unavailable
+ * this returns a structured `sandbox_unavailable` error rather than falling
+ * back to Node's `vm` module: `node:vm` shares the host realm and heap, so
+ * using it here would silently void the isolation guarantee this API makes.
  */
 export async function executeInSandbox(code, toolNames, dispatch, options = {}) {
     const memoryLimit = options.memoryLimit ?? DEFAULT_MEMORY_LIMIT;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const load = await loadIsolatedVm();
+    if (!load.available) {
+        const message = `Code Mode is unavailable: ${load.reason}. Use tool-cli or the MCP tool proxies instead.`;
+        return {
+            result: undefined,
+            error: message,
+            errorDetails: {
+                error: SANDBOX_UNAVAILABLE_ERROR,
+                message,
+                reason: load.reason,
+                alternatives: ["tool-cli", "MCP tool proxies"],
+            },
+            logs: [],
+        };
+    }
+    const ivm = load.module;
     const isolate = new ivm.Isolate({ memoryLimit });
     try {
-        return await runInIsolate(isolate, code, toolNames, dispatch, timeoutMs);
+        return await runInIsolate(ivm, isolate, code, toolNames, dispatch, timeoutMs);
     }
     finally {
         isolate.dispose();
     }
 }
-async function runInIsolate(isolate, code, toolNames, dispatch, timeoutMs) {
+async function runInIsolate(ivm, isolate, code, toolNames, dispatch, timeoutMs) {
     const ctx = await isolate.createContext();
     const jail = ctx.global;
     const logs = [];
@@ -37,8 +69,16 @@ async function runInIsolate(isolate, code, toolNames, dispatch, timeoutMs) {
     // Inject tool dispatcher Reference (async callback)
     const dispatchRef = new ivm.Reference(async (toolName, argsJson) => {
         const args = JSON.parse(argsJson);
-        const result = await dispatch(toolName, args);
-        return JSON.stringify(result === undefined ? null : result);
+        try {
+            const result = await dispatch(toolName, args);
+            return JSON.stringify({ ok: true, value: result === undefined ? null : result });
+        }
+        catch (error) {
+            if (error instanceof CodeModeDispatchError) {
+                return JSON.stringify({ ok: false, error: error.details });
+            }
+            throw error;
+        }
     });
     await jail.set("__dispatch", dispatchRef);
     // Build the tool call helper and codemode proxy as setup code
@@ -57,7 +97,11 @@ async function runInIsolate(isolate, code, toolNames, dispatch, timeoutMs) {
       const console = { log: (...args) => __log(args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')) };
       const __callTool = async (name, args) => {
         const r = await __dispatch.apply(undefined, [name, JSON.stringify(args ?? {})], { arguments: { copy: true }, result: { promise: true, copy: true } });
-        return JSON.parse(r);
+        const response = JSON.parse(r);
+        if (!response.ok) {
+          throw new Error(${JSON.stringify(STRUCTURED_ERROR_PREFIX)} + JSON.stringify(response.error));
+        }
+        return response.value;
       };
       const codemode = {
         listTools: async () => ${JSON.stringify(toolNames)},
@@ -83,7 +127,13 @@ ${toolProxyEntries}
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return { result: undefined, error: message, logs };
+        const errorDetails = parseStructuredError(message);
+        return {
+            result: undefined,
+            error: errorDetails?.message ?? message,
+            errorDetails,
+            logs,
+        };
     }
 }
 /**
@@ -117,4 +167,19 @@ export function normalizeCode(code) {
     // Otherwise, treat as a code block — return the last expression
     return normalized;
 }
-//# sourceMappingURL=executor.js.map
+function parseStructuredError(message) {
+    const markerIndex = message.indexOf(STRUCTURED_ERROR_PREFIX);
+    if (markerIndex === -1)
+        return undefined;
+    const serialized = message.slice(markerIndex + STRUCTURED_ERROR_PREFIX.length);
+    try {
+        const details = JSON.parse(serialized);
+        if (typeof details.error !== "string" || typeof details.message !== "string") {
+            return undefined;
+        }
+        return details;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,34 +1,77 @@
 import type { McpClientManager, McpTool } from "../mcp/index.js";
+import { type McpPolicy } from "../mcp/policy.js";
+import { type CodeModeDiagnostics, type CodeModeTool } from "./eligibility.js";
 import type { ExecuteResult, ExecutorOptions } from "./executor.js";
-export { getEligibleTools, isEligibleForCodeMode } from "./eligibility.js";
-export type { ExecuteResult, ExecutorOptions } from "./executor.js";
-export { executeInSandbox, normalizeCode } from "./executor.js";
+import { executeInSandbox } from "./executor.js";
+export { SYNTHESIZED_OUTPUT_SCHEMA, getCodeModeDiagnostics, getCodeModeTools, getEligibleTools, isEligibleForCodeMode, toCodeModeTool, } from "./eligibility.js";
+export type { CodeModeDiagnostics, CodeModeRefusalReason, CodeModeTool, OutputSchemaProvenance, } from "./eligibility.js";
+export type { CodeModeErrorDetails, ExecuteResult, ExecutorOptions } from "./executor.js";
+export { SANDBOX_UNAVAILABLE_ERROR, executeInSandbox, normalizeCode } from "./executor.js";
+export { loadIsolatedVm, peekIsolatedVm, resetIsolatedVmCacheForTests, setIsolatedVmForTests, type IsolatedVmLoad, type IsolatedVmModule, } from "./isolated-vm.js";
 export { createCodeExecuteTool, createCodeSearchTool } from "./tools.js";
 export { generateTypeHints, jsonSchemaToTypeString, sanitizeToolName } from "./type-hints.js";
 export interface CodeModeManagerOptions extends ExecutorOptions {
     /** Log function for status messages. */
     log?: (msg: string) => void;
+    /** Test seam for proving pre-isolate refusals. */
+    sandboxExecutor?: typeof executeInSandbox;
 }
 /**
- * Orchestrates code mode: discovers eligible tools, generates type hints,
+ * Whether the sandbox backend can run code.
+ *
+ * `unknown` is a real state, not a synonym for unavailable: before the optional
+ * native addon has been probed we have not established anything, and reporting
+ * that honestly is better than guessing in either direction.
+ */
+export interface SandboxAvailability {
+    readonly state: "available" | "unavailable" | "unknown";
+    readonly reason: string;
+}
+/**
+ * Orchestrates code mode: catalogs tools, generates type hints,
  * and executes model-generated code in a sandbox with tool dispatch.
  */
 export declare class CodeModeManager {
     private mcpManager;
-    private eligibleTools;
+    private policy;
+    private codeModeTools;
+    private diagnostics;
     private typeHints;
-    private options;
+    private readonly options;
+    private readonly sandboxExecutor;
+    private log;
+    private lastDiagnosticSummary;
+    private sandbox;
+    private sandboxProbe;
     constructor(options?: CodeModeManagerOptions);
-    /** Initialize with MCP manager, discover eligible tools, generate type hints. */
-    initialize(mcpManager: McpClientManager): void;
-    /** Refresh eligible tools and type hints (call on tools/list_changed). */
+    /**
+     * 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(): boolean;
+    /** Current sandbox backend availability, without triggering a probe. */
+    getSandboxAvailability(): SandboxAvailability;
+    /**
+     * Load the optional native addon once and cache the verdict.
+     *
+     * Safe to call from any lifecycle hook; concurrent callers share one probe.
+     */
+    probeSandbox(): Promise<SandboxAvailability>;
+    /** Initialize with MCP manager and policy, catalog tools, and generate type hints. */
+    initialize(mcpManager: McpClientManager, policy: McpPolicy, log?: (msg: string) => void): void;
+    /** Refresh the complete tool catalog and type hints (call on tools/list_changed). */
     refresh(): void;
     /** Get the type hints string for injection into system prompt. */
     getTypeHints(): string;
     /** Get eligible tools. */
     getEligibleTools(): McpTool[];
-    /** Whether code mode has any eligible tools. */
-    get isActive(): boolean;
+    /** Get the complete client-internal catalog, including permission and schema provenance. */
+    getCatalogTools(): readonly CodeModeTool[];
+    getDiagnostics(): CodeModeDiagnostics;
     /** Execute code in search mode (tool catalog queries). */
     searchTools(code: string): Promise<ExecuteResult>;
     /** Execute code that chains MCP tool calls. */
@@ -62,4 +105,3 @@ export declare class CodeModeManager {
     formatSystemPromptSection(): string;
     private execute;
 }
-//# sourceMappingURL=index.d.ts.map