@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

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

@@ -0,0 +1,48 @@
+import type { AgentToolResult, ExtensionContext } from "@sammorrowdrums/mcpi";
+import { Type, type Static } from "typebox";
+import type { CodeModeManager } from "./index.js";
+declare const CodeInput: Type.TObject<{
+    code: Type.TString;
+}>;
+type CodeInputType = Static<typeof CodeInput>;
+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.
+ *
+ * The model writes JavaScript to discover and filter available tools.
+ * The sandbox provides `codemode.listTools()` and `codemode.describeTools(names)`.
+ */
+export declare function createCodeSearchTool(manager: CodeModeManager): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        code: Type.TString;
+    }>;
+    execute(_toolCallId: string, params: CodeInputType, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<CodeModeToolDetails>>;
+};
+/**
+ * Create the `code_execute` tool for chaining tool calls.
+ *
+ * The model writes JavaScript that calls read-only MCP tools via
+ * the `codemode` namespace (e.g. `codemode.search_docs({ query: 'test' })`).
+ * Code runs in a sandbox with no access to filesystem, network, or Node.js APIs.
+ */
+export declare function createCodeExecuteTool(manager: CodeModeManager): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        code: Type.TString;
+    }>;
+    execute(_toolCallId: string, params: CodeInputType, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<CodeModeToolDetails>>;
+};
+export {};

package/dist/code-mode/tools.js

@@ -0,0 +1,73 @@
+import { Type } from "typebox";
+const CodeInput = Type.Object({
+    code: Type.String({
+        description: "JavaScript code to execute. Use the `codemode` namespace to call tools (e.g. `codemode.search_docs({ query: 'test' })`). Always `return` your final result. Code runs in a sandbox with no access to filesystem, network, or Node.js APIs.",
+    }),
+});
+/** 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, ...errorDetails },
+        };
+    }
+    // If code didn't return a value, fall back to captured console output
+    const output = result.result !== undefined
+        ? typeof result.result === "string"
+            ? result.result
+            : JSON.stringify(result.result, null, 2)
+        : result.logs.length > 0
+            ? result.logs.join("\n")
+            : "(no return value)";
+    const logsSection = result.result !== undefined && result.logs.length > 0
+        ? `\n\nLogs:\n${result.logs.join("\n")}`
+        : "";
+    return {
+        content: [{ type: "text", text: output + logsSection }],
+        details: { executionMs, logs: result.logs },
+    };
+}
+/**
+ * Create the `code_search` tool for querying the tool catalog.
+ *
+ * The model writes JavaScript to discover and filter available tools.
+ * The sandbox provides `codemode.listTools()` and `codemode.describeTools(names)`.
+ */
+export function createCodeSearchTool(manager) {
+    return {
+        name: "code_search",
+        label: "Code Search",
+        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();
+            const result = await manager.searchTools(params.code);
+            return formatResult(result, Math.round(performance.now() - start), "Code search error");
+        },
+    };
+}
+/**
+ * Create the `code_execute` tool for chaining tool calls.
+ *
+ * The model writes JavaScript that calls read-only MCP tools via
+ * the `codemode` namespace (e.g. `codemode.search_docs({ query: 'test' })`).
+ * Code runs in a sandbox with no access to filesystem, network, or Node.js APIs.
+ */
+export function createCodeExecuteTool(manager) {
+    return {
+        name: "code_execute",
+        label: "Code Execute",
+        description: "Execute JavaScript that chains read-only MCP tool calls for computation over data. Use when you need to aggregate, filter, loop, or transform results across multiple tool calls. Access tools via `codemode.toolName(args)`. Runs in a sandbox — no filesystem, network, or Node.js API access.",
+        parameters: CodeInput,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const start = performance.now();
+            const result = await manager.executeCode(params.code);
+            return formatResult(result, Math.round(performance.now() - start), "Code execution error");
+        },
+    };
+}

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

@@ -0,0 +1,20 @@
+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.
+ *
+ * Handles objects, arrays, primitives, enums, anyOf/oneOf/allOf, $ref,
+ * and circular references (depth guard at 20).
+ */
+export declare function jsonSchemaToTypeString(schema: JsonSchema, definitions?: Record<string, JsonSchema>, depth?: number, seen?: Set<JsonSchema>): string;
+/** Sanitize a tool name to be a valid JS identifier. */
+export declare function sanitizeToolName(name: string): string;
+/**
+ * Generate TypeScript type declarations for a set of MCP tools.
+ *
+ * Produces a `declare const codemode: { ... }` block with type-safe
+ * method signatures the model can use when writing code.
+ */
+export declare function generateTypeHints(tools: readonly (McpTool | CodeModeTool)[]): string;
+export {};

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

@@ -0,0 +1,205 @@
+import { getCodeModeDiagnostics, toCodeModeTool } from "./eligibility.js";
+/**
+ * Convert a JSON Schema to a TypeScript type string.
+ *
+ * Handles objects, arrays, primitives, enums, anyOf/oneOf/allOf, $ref,
+ * and circular references (depth guard at 20).
+ */
+export function jsonSchemaToTypeString(schema, definitions, depth = 0, seen = new Set()) {
+    if (depth > 20)
+        return "unknown";
+    if (seen.has(schema))
+        return "unknown";
+    seen.add(schema);
+    // Handle $ref
+    if (typeof schema.$ref === "string") {
+        const refPath = schema.$ref;
+        const refName = refPath.replace(/^#\/(definitions|components\/schemas|\\$defs)\//, "");
+        const resolved = definitions?.[refName];
+        if (resolved) {
+            return jsonSchemaToTypeString(resolved, definitions, depth + 1, seen);
+        }
+        return "unknown";
+    }
+    // Handle enum
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    // Handle const
+    if ("const" in schema) {
+        return JSON.stringify(schema.const);
+    }
+    // Handle anyOf / oneOf
+    const unionKey = schema.anyOf ? "anyOf" : schema.oneOf ? "oneOf" : null;
+    if (unionKey && Array.isArray(schema[unionKey])) {
+        const variants = schema[unionKey].map((s) => jsonSchemaToTypeString(s, definitions, depth + 1, seen));
+        return variants.join(" | ");
+    }
+    // Handle allOf
+    if (Array.isArray(schema.allOf)) {
+        const parts = schema.allOf.map((s) => jsonSchemaToTypeString(s, definitions, depth + 1, seen));
+        return parts.join(" & ");
+    }
+    const type = schema.type;
+    // Handle type arrays (e.g. ["string", "null"])
+    if (Array.isArray(type)) {
+        const types = type.map((t) => primitiveToTs(t));
+        return types.join(" | ");
+    }
+    switch (type) {
+        case "object":
+            return objectToTs(schema, definitions, depth, seen);
+        case "array":
+            return arrayToTs(schema, definitions, depth, seen);
+        case "string":
+        case "number":
+        case "integer":
+        case "boolean":
+        case "null":
+            return primitiveToTs(type);
+        default:
+            // No type specified — try to infer from properties
+            if (schema.properties) {
+                return objectToTs(schema, definitions, depth, seen);
+            }
+            return "unknown";
+    }
+}
+function primitiveToTs(type) {
+    switch (type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        default:
+            return "unknown";
+    }
+}
+function objectToTs(schema, definitions, depth, seen) {
+    const properties = schema.properties;
+    if (!properties || Object.keys(properties).length === 0) {
+        return "Record<string, unknown>";
+    }
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const lines = [];
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const desc = propSchema.description;
+        if (desc) {
+            lines.push(`  /** ${desc} */`);
+        }
+        const optional = required.has(key) ? "" : "?";
+        const typeStr = jsonSchemaToTypeString(propSchema, definitions, depth + 1, seen);
+        lines.push(`  ${safeName(key)}${optional}: ${typeStr};`);
+    }
+    return `{\n${lines.join("\n")}\n}`;
+}
+function arrayToTs(schema, definitions, depth, seen) {
+    const items = schema.items;
+    if (!items)
+        return "unknown[]";
+    // Tuple form
+    if (Array.isArray(items)) {
+        const tupleTypes = items.map((s) => jsonSchemaToTypeString(s, definitions, depth + 1, seen));
+        return `[${tupleTypes.join(", ")}]`;
+    }
+    const itemType = jsonSchemaToTypeString(items, definitions, depth + 1, seen);
+    return `${itemType}[]`;
+}
+/** Ensure property name is a valid JS identifier, quote otherwise. */
+function safeName(name) {
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/** Sanitize a tool name to be a valid JS identifier. */
+export function sanitizeToolName(name) {
+    return name.replace(/[^a-zA-Z0-9_$]/g, "_");
+}
+/**
+ * Generate TypeScript type declarations for a set of MCP tools.
+ *
+ * Produces a `declare const codemode: { ... }` block with type-safe
+ * method signatures the model can use when writing code.
+ */
+export function generateTypeHints(tools) {
+    const codeModeTools = tools.map(normalizeCodeModeTool);
+    const diagnostics = getCodeModeDiagnostics(codeModeTools);
+    const methods = [];
+    for (const codeModeTool of codeModeTools) {
+        const tool = codeModeTool.tool;
+        const safeName = sanitizeToolName(tool.name);
+        const inputSchema = tool.inputSchema;
+        const outputSchema = codeModeTool.outputSchema;
+        const definitions = (inputSchema.$defs ??
+            inputSchema.definitions ??
+            outputSchema?.$defs ??
+            outputSchema?.definitions);
+        // Build input type
+        const inputType = generateInputType(safeName, inputSchema, definitions);
+        // Build output type
+        const outputType = outputSchema ? jsonSchemaToTypeString(outputSchema, definitions) : "unknown";
+        // Build JSDoc
+        const jsdoc = buildJsDoc(codeModeTool, inputSchema);
+        methods.push(`${jsdoc}  ${safeName}: (input: ${inputType}) => Promise<${outputType}>;`);
+    }
+    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. */`,
+        `  listTools: () => Promise<(${toolListType})[]>;`,
+        `  /** Get full type information for specific tools. */`,
+        `  describeTools: (names: string[]) => Promise<string>;`,
+        ...methods.map((m) => m),
+        `};`,
+    ].join("\n");
+}
+function generateInputType(_toolSafeName, inputSchema, definitions) {
+    const properties = inputSchema.properties;
+    if (!properties || Object.keys(properties).length === 0) {
+        return "Record<string, never>";
+    }
+    // Always inline the type — avoids emitting unreferenced named type aliases
+    const typeStr = jsonSchemaToTypeString(inputSchema, definitions);
+    return typeStr;
+}
+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)) {
+            const desc = propSchema.description;
+            if (desc) {
+                lines.push(`   * @param input.${key} - ${desc}`);
+            }
+        }
+    }
+    lines.push("   */");
+    return lines.join("\n") + "\n";
+}
+function escapeStr(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");
+}
+function normalizeCodeModeTool(tool) {
+    return "tool" in tool && "outputSchemaProvenance" in tool ? tool : toCodeModeTool(tool);
+}

package/dist/docker-e2e.d.ts

@@ -0,0 +1,54 @@
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@sammorrowdrums/mcpi";
+import { Type, type Static } from "typebox";
+declare const DockerE2EParams: Type.TObject<{
+    task: Type.TString;
+    token: Type.TString;
+    model: Type.TOptional<Type.TString>;
+    timeout: Type.TOptional<Type.TNumber>;
+}>;
+type DockerE2EInput = Static<typeof DockerE2EParams>;
+interface RunLogEntry {
+    type: string;
+    timestamp: number;
+    raw: string;
+}
+export interface DockerE2EDetails {
+    exitCode: number | null;
+    log: RunLogEntry[];
+    duration: number;
+    model?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+        turns: number;
+    };
+}
+export declare function parseJsonlLine(line: string): RunLogEntry | null;
+export declare function extractAssistantText(log: RunLogEntry[]): string;
+export declare function extractUsage(log: RunLogEntry[]): {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+};
+export declare function extractModel(log: RunLogEntry[]): string | undefined;
+export declare function buildDockerArgs(image: string, params: DockerE2EInput): string[];
+export declare const dockerE2ETool: {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        task: Type.TString;
+        token: Type.TString;
+        model: Type.TOptional<Type.TString>;
+        timeout: Type.TOptional<Type.TNumber>;
+    }>;
+    execute(_toolCallId: string, params: DockerE2EInput, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<DockerE2EDetails> | undefined, _ctx: ExtensionContext): Promise<AgentToolResult<DockerE2EDetails>>;
+};
+export {};