@ruifung/codemode-bridge 1.0.3-1

package/dist/executor/isolated-vm-executor.js

@@ -0,0 +1,368 @@
+// @ts-ignore - isolated-vm is an optional dependency; this file is only loaded via dynamic import() when available
+import ivm from 'isolated-vm';
+import { wrapCode } from './wrap-code.js';
+const { Isolate, Context } = ivm;
+/**
+ * Helper: Convert any value to a string representation for logging
+ */
+function stringify(value) {
+    try {
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'object') {
+            if (value instanceof Error) {
+                return `Error: ${value.message}`;
+            }
+            if (Array.isArray(value)) {
+                return `[ ${value.map((v) => stringify(v)).join(', ')} ]`;
+            }
+            return JSON.stringify(value, (key, val) => {
+                if (typeof val === 'function')
+                    return '[Function]';
+                return val;
+            });
+        }
+        return String(value);
+    }
+    catch {
+        return '[Object]';
+    }
+}
+/**
+ * Executor implementation using isolated-vm
+ *
+ * Architecture: Uses Promise chain pattern
+ * - Async IIFE is executed in the isolate
+ * - Its returned Promise is chained with .then() inside the isolate
+ * - The .then handlers call sync Callbacks on the host side
+ * - Host Promise resolves when the callback is invoked
+ *
+ * Features:
+ * - True memory isolation (V8 Isolate level)
+ * - Hard memory limit enforcement
+ * - Accurate timeout handling
+ * - Promise-based result capturing
+ *
+ * Security:
+ * - Separate V8 memory heap
+ * - No shared memory access
+ * - Explicit serialization boundaries
+ */
+export class IsolatedVmExecutor {
+    constructor(options = {}) {
+        this.context = null;
+        this.metrics = null;
+        this.options = {
+            memoryLimit: options.memoryLimit ?? 128,
+            inspector: options.inspector ?? false,
+            timeout: options.timeout ?? 30000,
+        };
+        this.isolate = new Isolate({
+            memoryLimit: this.options.memoryLimit,
+            inspector: this.options.inspector,
+        });
+    }
+    /**
+     * Execute code within a sandboxed isolate using Promise chain pattern
+     *
+     * The function `fns` are made available as `codemode.*` within the sandbox.
+     * Uses Promise chain: async IIFE → .then() in isolate → sync callback → host Promise
+     *
+     * Returns ExecuteResult with:
+     * - result: The return value of the code
+     * - error: Error message if execution failed
+     * - logs: Array of console.log outputs
+     */
+    async execute(code, fns) {
+        // Create new context for this execution (fresh globals)
+        const context = await this.createContext();
+        const logs = [];
+        // Tool invocation: Track call IDs for notification pattern
+        let toolCallId = 0;
+        try {
+            // Set up console logging
+            try {
+                await context.eval('this.console = {}');
+                const consoleRef = await context.global.get('console');
+                const logCallback = new ivm.Callback((...args) => {
+                    logs.push(args.map(stringify).join(' '));
+                });
+                await consoleRef.set('log', logCallback);
+                const warnCallback = new ivm.Callback((...args) => {
+                    logs.push('[WARN] ' + args.map(stringify).join(' '));
+                });
+                await consoleRef.set('warn', warnCallback);
+                const errorCallback = new ivm.Callback((...args) => {
+                    logs.push('[ERROR] ' + args.map(stringify).join(' '));
+                });
+                await consoleRef.set('error', errorCallback);
+            }
+            catch (e) {
+                // Continue if console setup fails
+            }
+            // Block dangerous functions
+            try {
+                await context.eval(`
+          this.eval = function() {
+            throw new Error("eval is not allowed");
+          };
+        `);
+            }
+            catch (e) {
+                // Continue even if this fails
+            }
+            // Provide setTimeout for async code support (like vm2 does)
+            try {
+                await context.eval(`
+          globalThis.setTimeout = function(fn, delay) {
+            Promise.resolve().then(fn);
+          };
+        `);
+            }
+            catch (e) {
+                // Continue even if this fails
+            }
+            // Provide global alias for Node.js compatibility
+            try {
+                await context.eval(`
+          globalThis.global = globalThis;
+        `);
+            }
+            catch (e) {
+                // Continue even if this fails
+            }
+            // Precompile resolver script once — resolves all pending promises that
+            // have results/errors waiting in _toolResults/_toolErrors. The host copies
+            // data into those objects via ExternalCopy, then runs this script.
+            const resolverScript = await this.isolate.compileScript(`
+        (function() {
+          for (const id in globalThis._toolResults) {
+            if (globalThis._pendingResolvers[id]) {
+              globalThis._pendingResolvers[id].resolve(globalThis._toolResults[id]);
+              delete globalThis._pendingResolvers[id];
+            }
+            delete globalThis._toolResults[id];
+          }
+          for (const id in globalThis._toolErrors) {
+            if (globalThis._pendingResolvers[id]) {
+              globalThis._pendingResolvers[id].reject(new Error(globalThis._toolErrors[id]));
+              delete globalThis._pendingResolvers[id];
+            }
+            delete globalThis._toolErrors[id];
+          }
+        })();
+      `);
+            // Set up tool invocation: precompiled notification pattern
+            // 1. hostExecuteTool starts async execution and returns a call ID
+            // 2. When done, host copies result into _toolResults[callId] via ExternalCopy
+            // 3. Host runs the precompiled resolver script to resolve the Promise
+            const hostExecuteTool = new ivm.Callback((toolName, toolArgs) => {
+                const callId = toolCallId++;
+                const fn = fns[toolName];
+                const notifySuccess = async (value) => {
+                    try {
+                        const ref = await context.global.get('_toolResults');
+                        await ref.set(String(callId), new ivm.ExternalCopy(value).copyInto({ transferIn: true }));
+                        await resolverScript.run(context);
+                    }
+                    catch {
+                        // Ignore errors during cleanup
+                    }
+                };
+                const notifyError = async (error) => {
+                    try {
+                        const errorMsg = error instanceof Error ? error.message : String(error);
+                        const ref = await context.global.get('_toolErrors');
+                        await ref.set(String(callId), new ivm.ExternalCopy(errorMsg).copyInto({ transferIn: true }));
+                        await resolverScript.run(context);
+                    }
+                    catch {
+                        // Ignore errors during cleanup
+                    }
+                };
+                if (!fn) {
+                    notifyError(new Error(`Tool '${toolName}' not found`));
+                    return callId;
+                }
+                // Execute the tool async, spread array arguments
+                fn(...(Array.isArray(toolArgs) ? toolArgs : [toolArgs]))
+                    .then(notifySuccess)
+                    .catch(notifyError);
+                return callId;
+            });
+            await context.global.set('_hostExecuteTool', hostExecuteTool);
+            // Set up codemode object with tool wrappers
+            // Each tool: creates a promise, starts execution, host notifies when done
+            const codemodeSandbox = {};
+            for (const toolName of Object.keys(fns)) {
+                codemodeSandbox[toolName] = toolName; // Just pass the name as string
+            }
+            await context.global.set('codemode', new ivm.ExternalCopy(codemodeSandbox).copyInto({ transferIn: true }));
+            // Set up the tool wrapper in isolate - uses notification pattern
+            await context.eval(`
+        globalThis._pendingResolvers = {};
+        globalThis._toolResults = {};
+        globalThis._toolErrors = {};
+        
+        const _codemodeMethods = {};
+        for (const toolName of Object.keys(codemode)) {
+          _codemodeMethods[toolName] = (...args) => {
+            return new Promise((resolve, reject) => {
+              const callId = _hostExecuteTool(toolName, args);
+              globalThis._pendingResolvers[callId] = { resolve, reject };
+            });
+          };
+        }
+        codemode = _codemodeMethods;
+      `);
+            // Use Promise-based execution with async function
+            const resultPromise = new Promise(async (resolve) => {
+                // Create resolve/reject callbacks for the isolate
+                const resolveCallback = new ivm.Callback((result) => {
+                    resolve({
+                        result,
+                        logs: logs.length > 0 ? logs : undefined,
+                    });
+                });
+                const rejectCallback = new ivm.Callback((error) => {
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    resolve({
+                        result: undefined,
+                        error: errorMsg,
+                        logs: logs.length > 0 ? logs : undefined,
+                    });
+                });
+                try {
+                    // Set protocol callbacks in isolate
+                    await context.global.set('protocol', new ivm.ExternalCopy({
+                        resolve: resolveCallback,
+                        reject: rejectCallback,
+                    }).copyInto({ transferIn: true }));
+                    // Wrap code so it returns a Promise we can .then()
+                    const wrappedCode = wrapCode(code, { alwaysAsync: true });
+                    // Execute the async function and chain its Promise with .then()
+                    await context.eval(`(${wrappedCode}).then(protocol.resolve, protocol.reject);`);
+                }
+                catch (err) {
+                    const errorMsg = err instanceof Error ? err.message : String(err);
+                    resolve({
+                        result: undefined,
+                        error: errorMsg,
+                        logs: logs.length > 0 ? logs : undefined,
+                    });
+                }
+            });
+            // Wait for the Promise-based execution to complete
+            const result = await resultPromise;
+            // Capture metrics before cleanup
+            await this.captureMetrics();
+            return result;
+        }
+        catch (error) {
+            await this.captureMetrics();
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Distinguish timeout errors
+            if (errorMessage.includes('timeout') ||
+                errorMessage.includes('CPU time limit')) {
+                return {
+                    result: undefined,
+                    error: `Execution timeout (${this.options.timeout}ms exceeded)`,
+                    logs: logs.length > 0 ? logs : undefined,
+                };
+            }
+            // Distinguish memory limit errors
+            if (errorMessage.includes('memory') || errorMessage.includes('heap')) {
+                return {
+                    result: undefined,
+                    error: `Memory limit exceeded (${this.options.memoryLimit}MB)`,
+                    logs: logs.length > 0 ? logs : undefined,
+                };
+            }
+            return {
+                result: undefined,
+                error: errorMessage,
+                logs: logs.length > 0 ? logs : undefined,
+            };
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    dispose() {
+        if (this.context) {
+            try {
+                this.context.release();
+            }
+            catch (e) {
+                // Ignore
+            }
+            this.context = null;
+        }
+        if (this.isolate) {
+            try {
+                this.isolate.dispose();
+            }
+            catch (e) {
+                // Ignore errors during cleanup
+            }
+        }
+    }
+    /**
+     * Get heap statistics from the isolate
+     */
+    async getHeapStatistics() {
+        const stats = await this.isolate.getHeapStatistics();
+        return {
+            total: stats.total_heap_size,
+            used: stats.used_heap_size,
+            limit: this.options.memoryLimit * 1024 * 1024,
+        };
+    }
+    /**
+     * Create or recreate context (resets globals for isolation)
+     */
+    async createContext() {
+        // Release old context if it exists
+        if (this.context) {
+            try {
+                this.context.release();
+            }
+            catch (e) {
+                // Ignore
+            }
+        }
+        this.context = await this.isolate.createContext({
+            inspector: this.options.inspector,
+        });
+        return this.context;
+    }
+    /**
+     * Capture execution metrics
+     */
+    async captureMetrics() {
+        try {
+            const stats = await this.isolate.getHeapStatistics();
+            this.metrics = {
+                cpuTime: BigInt(0),
+                wallTime: BigInt(0),
+                heapUsed: stats.used_heap_size,
+                heapLimit: stats.heap_size_limit,
+            };
+        }
+        catch (e) {
+            // Ignore metrics capture errors
+        }
+    }
+}
+/**
+ * Factory function to create an isolated-vm executor instance
+ */
+export function createIsolatedVmExecutor(options) {
+    return new IsolatedVmExecutor(options);
+}

package/dist/executor/vm2-executor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Executor Implementation for Codemode SDK
+ * Implements the @cloudflare/codemode Executor interface using vm2 sandbox
+ */
+import type { Executor, ExecuteResult } from "@cloudflare/codemode";
+/**
+ * VM2-based Executor implementation
+ * Runs LLM-generated code in an isolated sandbox with access to tools via codemode.* namespace
+ */
+export declare class VM2Executor implements Executor {
+    private timeout;
+    constructor(timeout?: number);
+    execute(code: string, fns: Record<string, (...args: unknown[]) => Promise<unknown>>): Promise<ExecuteResult>;
+    private stringify;
+}
+/**
+ * Factory function to create a VM2 executor instance
+ */
+export declare function createVM2Executor(options?: {
+    timeout?: number;
+}): Executor;

package/dist/executor/vm2-executor.js

@@ -0,0 +1,109 @@
+/**
+ * Executor Implementation for Codemode SDK
+ * Implements the @cloudflare/codemode Executor interface using vm2 sandbox
+ */
+import { VM } from "vm2";
+import { wrapCode } from "./wrap-code.js";
+/**
+ * VM2-based Executor implementation
+ * Runs LLM-generated code in an isolated sandbox with access to tools via codemode.* namespace
+ */
+export class VM2Executor {
+    constructor(timeout = 30000) {
+        this.timeout = timeout;
+    }
+    async execute(code, fns) {
+        const logs = [];
+        const capturedConsole = {
+            log: (...args) => {
+                logs.push(args.map((arg) => this.stringify(arg)).join(" "));
+            },
+            warn: (...args) => {
+                logs.push("[WARN] " + args.map((arg) => this.stringify(arg)).join(" "));
+            },
+            error: (...args) => {
+                logs.push("[ERROR] " + args.map((arg) => this.stringify(arg)).join(" "));
+            },
+        };
+        try {
+            // Wrap code using shared wrapCode utility (handles arrow functions, statements, etc.)
+            const wrappedCode = wrapCode(code);
+            const vm = new VM({
+                timeout: this.timeout,
+                eval: false,
+                sandbox: {
+                    console: capturedConsole,
+                    codemode: fns,
+                    // Block eval for security
+                    eval: () => { throw new Error('eval is not allowed'); },
+                    setTimeout: (fn, delay) => {
+                        return new Promise((resolve) => {
+                            setTimeout(() => { fn(); resolve(); }, delay ?? 0);
+                        });
+                    },
+                    setInterval: (fn, delay) => {
+                        return setInterval(fn, delay ?? 0);
+                    },
+                    clearInterval: (id) => {
+                        clearInterval(id);
+                    },
+                    clearTimeout: (id) => {
+                        clearTimeout(id);
+                    },
+                },
+            });
+            // vm.run() returns a Promise if the code returns a Promise
+            const rawResult = vm.run(wrappedCode, "codemode-execution.js");
+            // Await the result if it's a promise
+            const result = rawResult instanceof Promise ? await rawResult : rawResult;
+            return {
+                result,
+                ...(logs.length > 0 && { logs }),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                result: undefined,
+                error: errorMessage,
+                ...(logs.length > 0 && { logs }),
+            };
+        }
+    }
+    stringify(value) {
+        try {
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "number" || typeof value === "boolean")
+                return String(value);
+            if (value === null)
+                return "null";
+            if (value === undefined)
+                return "undefined";
+            if (typeof value === "object") {
+                if (value instanceof Error) {
+                    return `Error: ${value.message}`;
+                }
+                if (Array.isArray(value)) {
+                    return `[ ${value.map((v) => this.stringify(v)).join(", ")} ]`;
+                }
+                // For objects, use JSON.stringify with a replacer to handle circular refs
+                return JSON.stringify(value, (key, val) => {
+                    if (typeof val === "function")
+                        return "[Function]";
+                    return val;
+                });
+            }
+            return String(value);
+        }
+        catch {
+            return "[Object]";
+        }
+    }
+}
+/**
+ * Factory function to create a VM2 executor instance
+ */
+export function createVM2Executor(options) {
+    return new VM2Executor(options?.timeout);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Shared code-wrapping utility for executor implementations.
+ *
+ * The SDK's normalizeCode() shapes LLM-generated code into a callable
+ * function expression (arrow function). The executor's job is to invoke
+ * it — `(code)()`. When the executor is called directly (without
+ * normalizeCode()), it must also handle raw statements.
+ *
+ * This module uses acorn AST parsing to reliably classify code shape,
+ * matching how the SDK's normalizeCode() detects arrow functions.
+ */
+/**
+ * The shape of the code as determined by AST parsing.
+ *
+ * - `async-function`    — `async function ...` or `async () => ...`
+ * - `sync-arrow`        — `(params) => ...` or `param => ...` (non-async)
+ * - `sync-function`     — `function ...` (non-async named/anonymous function)
+ * - `raw-statements`    — anything else (variable declarations, calls, etc.)
+ */
+export type CodeShape = 'async-function' | 'sync-arrow' | 'sync-function' | 'raw-statements';
+/**
+ * Classify the shape of a code string using acorn AST parsing.
+ *
+ * Falls back to `'raw-statements'` if the code cannot be parsed
+ * (which will cause it to be wrapped in an async IIFE).
+ */
+export declare function classifyCode(code: string): CodeShape;
+export interface WrapCodeOptions {
+    /**
+     * When true, sync arrow functions and sync function expressions are
+     * additionally wrapped to ensure the result is always a Promise.
+     *
+     * Use this when the executor chains the result with `.then()` and
+     * cannot handle non-Promise return values (e.g. isolated-vm).
+     *
+     * When false, sync functions are simply invoked as `(code)()`, and
+     * the caller is responsible for handling non-Promise returns
+     * (e.g. VM2 checks `'then' in result`).
+     *
+     * @default false
+     */
+    alwaysAsync?: boolean;
+}
+/**
+ * Wrap code so it can be executed by an executor.
+ *
+ * - Function expressions / arrow functions → invoked with `(code)()`
+ * - Raw statements → wrapped in `(async () => { code })()`
+ * - When `alwaysAsync` is true, sync functions are additionally wrapped
+ *   to ensure the result is a Promise.
+ */
+export declare function wrapCode(code: string, options?: WrapCodeOptions): string;

package/dist/executor/wrap-code.js

@@ -0,0 +1,80 @@
+/**
+ * Shared code-wrapping utility for executor implementations.
+ *
+ * The SDK's normalizeCode() shapes LLM-generated code into a callable
+ * function expression (arrow function). The executor's job is to invoke
+ * it — `(code)()`. When the executor is called directly (without
+ * normalizeCode()), it must also handle raw statements.
+ *
+ * This module uses acorn AST parsing to reliably classify code shape,
+ * matching how the SDK's normalizeCode() detects arrow functions.
+ */
+import * as acorn from 'acorn';
+/**
+ * Classify the shape of a code string using acorn AST parsing.
+ *
+ * Falls back to `'raw-statements'` if the code cannot be parsed
+ * (which will cause it to be wrapped in an async IIFE).
+ */
+export function classifyCode(code) {
+    const trimmed = code.trim();
+    if (!trimmed)
+        return 'raw-statements';
+    try {
+        const ast = acorn.parse(trimmed, {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+        });
+        // Single expression statement — check what kind of function it is
+        if (ast.body.length === 1 && ast.body[0].type === 'ExpressionStatement') {
+            const expr = ast.body[0].expression;
+            if (expr.type === 'ArrowFunctionExpression') {
+                return expr.async ? 'async-function' : 'sync-arrow';
+            }
+            if (expr.type === 'FunctionExpression') {
+                return expr.async ? 'async-function' : 'sync-function';
+            }
+        }
+        // Top-level function declaration (not an expression)
+        if (ast.body.length === 1 && ast.body[0].type === 'FunctionDeclaration') {
+            const decl = ast.body[0];
+            return decl.async ? 'async-function' : 'sync-function';
+        }
+        return 'raw-statements';
+    }
+    catch {
+        // Parse failed — treat as raw statements
+        return 'raw-statements';
+    }
+}
+/**
+ * Wrap code so it can be executed by an executor.
+ *
+ * - Function expressions / arrow functions → invoked with `(code)()`
+ * - Raw statements → wrapped in `(async () => { code })()`
+ * - When `alwaysAsync` is true, sync functions are additionally wrapped
+ *   to ensure the result is a Promise.
+ */
+export function wrapCode(code, options) {
+    const trimmed = code.trim();
+    if (!trimmed)
+        return '(async () => {})()';
+    const shape = classifyCode(trimmed);
+    const alwaysAsync = options?.alwaysAsync ?? false;
+    switch (shape) {
+        case 'async-function':
+            // Already async — invoke it, result is a Promise
+            return `(${trimmed})()`;
+        case 'sync-arrow':
+        case 'sync-function':
+            if (alwaysAsync) {
+                // Wrap in async IIFE to ensure result is a Promise
+                return `(async () => (${trimmed})())()`;
+            }
+            // Just invoke — caller handles sync return
+            return `(${trimmed})()`;
+        case 'raw-statements':
+            // Wrap in async IIFE
+            return `(async () => { ${trimmed} })()`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Main entry point for the Code Mode bridge
+ */
+export * from "./mcp/config.js";
+export * from "./mcp/server.js";
+export * from "./mcp/executor.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * Main entry point for the Code Mode bridge
+ */
+export * from "./mcp/config.js";
+export * from "./mcp/server.js";
+export * from "./mcp/executor.js";

package/dist/mcp/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Config Loader - Load MCP server configurations from files
+ * Supports VS Code's mcp.json format and other config files
+ */
+import type { MCPServerConfig } from "./server.js";
+export interface MCPJsonConfig {
+    servers: Record<string, MCPServerConfigEntry>;
+    [key: string]: unknown;
+}
+export interface MCPServerConfigEntry {
+    type: "stdio" | "http";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    oauth?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Load MCP server configurations from VS Code's mcp.json file
+ * Default location: ~/.config/Code/User/mcp.json (Linux/Mac) or
+ *                   %APPDATA%\Code\User\mcp.json (Windows)
+ */
+export declare function loadMCPConfigFile(configPath?: string): MCPJsonConfig;
+/**
+ * Get a list of all configured server names from the config file
+ */
+export declare function getServerNames(config: MCPJsonConfig): string[];
+/**
+ * Get a server configuration by name
+ */
+export declare function getServerConfig(config: MCPJsonConfig, serverName: string): MCPServerConfig;
+/**
+ * Get multiple server configs by name from the config file
+ */
+export declare function getServerConfigs(config: MCPJsonConfig, serverNames: string[]): MCPServerConfig[];
+/**
+ * Load and return all healthy servers from the config
+ * (filters out offline servers based on availability checks)
+ */
+export declare function loadAvailableServers(config: MCPJsonConfig, serverNames?: string[]): Promise<{
+    available: MCPServerConfig[];
+    unavailable: string[];
+}>;