@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/code-mode/executor.js

@@ -0,0 +1,185 @@
+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.
+ *
+ * The code runs in a fresh `isolated-vm` isolate with:
+ * - Enforced memory limit (default 128MB)
+ * - Execution timeout (default 30s)
+ * - No access to Node.js APIs, filesystem, or network
+ * - Only access to provided tool dispatch functions via `codemode.*` proxy
+ *
+ * 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(ivm, isolate, code, toolNames, dispatch, timeoutMs);
+    }
+    finally {
+        isolate.dispose();
+    }
+}
+async function runInIsolate(ivm, isolate, code, toolNames, dispatch, timeoutMs) {
+    const ctx = await isolate.createContext();
+    const jail = ctx.global;
+    const logs = [];
+    // Inject console.log that captures to logs array
+    const logCallback = new ivm.Callback((...args) => {
+        logs.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
+    });
+    await jail.set("__log", logCallback);
+    // Inject tool dispatcher Reference (async callback)
+    const dispatchRef = new ivm.Reference(async (toolName, argsJson) => {
+        const args = JSON.parse(argsJson);
+        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
+    const toolProxyEntries = toolNames
+        .map((name) => {
+        const safe = sanitizeToolName(name);
+        return `    ${safe}: async (args) => __callTool(${JSON.stringify(name)}, args)`;
+    })
+        .join(",\n");
+    const normalized = normalizeCode(code);
+    // Use ctx.eval with { promise: true } instead of compileModule,
+    // because module.evaluate() can resolve prematurely with multiple
+    // sequential async Reference.apply calls.
+    const wrappedCode = `
+    (async () => {
+      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 } });
+        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)},
+        describeTools: async (names) => "Use the typed codemode.toolName(args) methods instead.",
+${toolProxyEntries}
+      };
+
+      const __userFn = async () => {
+        ${normalized}
+      };
+
+      return JSON.stringify({ value: await __userFn() });
+    })()
+  `;
+    try {
+        const rawResult = (await ctx.eval(wrappedCode, {
+            promise: true,
+            copy: true,
+            timeout: timeoutMs,
+        }));
+        const parsed = JSON.parse(rawResult);
+        return { result: parsed.value, logs };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const errorDetails = parseStructuredError(message);
+        return {
+            result: undefined,
+            error: errorDetails?.message ?? message,
+            errorDetails,
+            logs,
+        };
+    }
+}
+/**
+ * Normalize model-generated code:
+ * - Strip markdown code fences
+ * - Handle arrow functions, function declarations, export default
+ * - Otherwise leave code as a statement block; callers must explicitly `return` a value
+ */
+export function normalizeCode(code) {
+    let normalized = code.trim();
+    // Strip markdown code fences
+    normalized = normalized.replace(/^```(?:js|javascript|typescript|ts)?\s*\n?/i, "");
+    normalized = normalized.replace(/\n?```\s*$/i, "");
+    normalized = normalized.trim();
+    // If it's an arrow function or function expression, invoke it
+    if (/^(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/.test(normalized)) {
+        return `return (${normalized})();`;
+    }
+    // If it's a function declaration, invoke it
+    if (/^(?:async\s+)?function\s+/.test(normalized)) {
+        const match = normalized.match(/^(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/);
+        if (match) {
+            return `${normalized}\nreturn ${match[1]}();`;
+        }
+    }
+    // If it starts with export default, strip the export default
+    if (/^export\s+default\s+/.test(normalized)) {
+        normalized = normalized.replace(/^export\s+default\s+/, "");
+        return `return (${normalized})();`;
+    }
+    // Otherwise, treat as a code block — return the last expression
+    return normalized;
+}
+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

@@ -0,0 +1,107 @@
+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";
+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;
+}
+/**
+ * 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 policy;
+    private codeModeTools;
+    private diagnostics;
+    private typeHints;
+    private readonly options;
+    private readonly sandboxExecutor;
+    private log;
+    private lastDiagnosticSummary;
+    private sandbox;
+    private sandboxProbe;
+    constructor(options?: CodeModeManagerOptions);
+    /**
+     * 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[];
+    /** 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. */
+    executeCode(code: string): Promise<ExecuteResult>;
+    /** Create the Pi tool definitions for code_search and code_execute. */
+    createTools(): {
+        codeSearch: {
+            name: string;
+            label: string;
+            description: string;
+            parameters: import("typebox").TObject<{
+                code: import("typebox").TString;
+            }>;
+            execute(_toolCallId: string, params: {
+                code: string;
+            }, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: import("@sammorrowdrums/mcpi").ExtensionContext): Promise<import("@sammorrowdrums/mcpi-agent").AgentToolResult<import("./tools.js").CodeModeToolDetails>>;
+        };
+        codeExecute: {
+            name: string;
+            label: string;
+            description: string;
+            parameters: import("typebox").TObject<{
+                code: import("typebox").TString;
+            }>;
+            execute(_toolCallId: string, params: {
+                code: string;
+            }, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: import("@sammorrowdrums/mcpi").ExtensionContext): Promise<import("@sammorrowdrums/mcpi-agent").AgentToolResult<import("./tools.js").CodeModeToolDetails>>;
+        };
+    };
+    /** Format a system prompt section for code mode. */
+    formatSystemPromptSection(): string;
+    private execute;
+}

package/dist/code-mode/index.js

@@ -0,0 +1,267 @@
+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 { 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: catalogs tools, generates type hints,
+ * and executes model-generated code in a sandbox with tool dispatch.
+ */
+export class CodeModeManager {
+    mcpManager = null;
+    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;
+    }
+    /**
+     * 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 the complete tool catalog and type hints (call on tools/list_changed). */
+    refresh() {
+        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() {
+        return this.typeHints;
+    }
+    /** Get eligible tools. */
+    getEligibleTools() {
+        return this.codeModeTools.filter((entry) => entry.callable).map((entry) => entry.tool);
+    }
+    /** 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. */
+    createTools() {
+        return {
+            codeSearch: createCodeSearchTool(this),
+            codeExecute: createCodeExecuteTool(this),
+        };
+    }
+    /** Format a system prompt section for code mode. */
+    formatSystemPromptSection() {
+        return [
+            "",
+            "<code_mode>",
+            "## Code mode",
+            "",
+            "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.",
+            "2. **Multi-tool aggregation** — counting, filtering, trending, or transforming results across",
+            "   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 which MCP tools are reachable from inside the sandbox.",
+            "",
+            "`code_search` and `code_execute` are always registered and never gated.",
+            "",
+            "After producing a result, verify it makes sense — run a quick sanity check or spot-check values.",
+            "",
+            "### How to write code",
+            "",
+            "Write vanilla JavaScript (not TypeScript, not Node.js). No `require`, `import`, `fetch`,",
+            "`fs`, `process`, or any Node.js/browser APIs. The only external API is the `codemode` namespace",
+            "for MCP tool calls (optional — pure computation works without it). Always `return` the final result.",
+            "",
+            "**Write ONE `code_execute` call that does the whole job.** Loops, comparisons, pagination,",
+            "and aggregation all happen inside a single execution.",
+            "",
+            "```javascript",
+            "// Pure computation — no tools needed",
+            "const factorial = (n) => n <= 1 ? 1 : n * factorial(n - 1);",
+            "return { result: factorial(20), formatted: factorial(20).toLocaleString() };",
+            "```",
+            "",
+            "```javascript",
+            "// Aggregate across paginated MCP tool results",
+            "const counts = {};",
+            "let page = 1;",
+            "while (true) {",
+            "  const result = await codemode.list_items({ page, perPage: 100 });",
+            "  for (const item of result.items) {",
+            "    counts[item.category] = (counts[item.category] || 0) + 1;",
+            "  }",
+            "  if (result.items.length < 100) break;",
+            "  page++;",
+            "}",
+            "return counts;",
+            "```",
+            "",
+            "### Available tools",
+            "",
+            "```typescript",
+            this.typeHints,
+            "```",
+            "</code_mode>",
+        ].join("\n");
+    }
+    async execute(code) {
+        const policy = this.policy;
+        const toolNames = this.codeModeTools.map((entry) => entry.tool.name);
+        const dispatch = async (toolName, args) => {
+            const codeModeTool = this.codeModeTools.find((entry) => entry.tool.name === toolName);
+            if (!codeModeTool) {
+                throw new Error(`Tool "${toolName}" not found in code mode eligible tools`);
+            }
+            if (!policy) {
+                throw new Error("Code mode MCP policy is not initialized");
+            }
+            try {
+                const terminal = await policy.callTool({
+                    source: "code-mode",
+                    serverName: codeModeTool.tool.serverName,
+                    toolName: codeModeTool.tool.name,
+                    args,
+                });
+                return terminal.result;
+            }
+            catch (error) {
+                throw toCodeModeDispatchError(error, codeModeTool);
+            }
+        };
+        return this.sandboxExecutor(code, toolNames, dispatch, {
+            memoryLimit: this.options.memoryLimit,
+            timeoutMs: this.options.timeoutMs,
+        });
+    }
+}
+/**
+ * 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;