@tanstack/ai-isolate-quickjs 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @tanstack/ai-isolate-quickjs
+
+QuickJS WASM driver for TanStack AI Code Mode. Runs everywhere — Node.js, browsers, and edge runtimes — with zero native dependencies.
+
+## Installation
+
+```bash
+pnpm add @tanstack/ai-isolate-quickjs
+```
+
+## Usage
+
+```typescript
+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+import { createCodeModeTool } from '@tanstack/ai-code-mode'
+
+const driver = createQuickJSIsolateDriver({
+  timeout: 30000, // execution timeout in ms (default: 30000)
+  memoryLimit: 128, // memory limit in MB (default: 128)
+  maxStackSize: 512 * 1024, // max stack size in bytes (default: 512 KiB)
+})
+
+const executeTypescript = createCodeModeTool({
+  driver,
+  tools: [myTool],
+})
+```
+
+## Config Options
+
+- `timeout` — Default execution timeout in milliseconds (default: 30000)
+- `memoryLimit` — Default QuickJS runtime memory limit in MB (default: 128)
+- `maxStackSize` — Default QuickJS runtime max stack size in bytes (default: 524288)
+
+## Tradeoffs vs Node Driver
+
+|                 | QuickJS (WASM)             | Node (`isolated-vm`)    |
+| --------------- | -------------------------- | ----------------------- |
+| Native deps     | None                       | Yes (C++ addon)         |
+| Browser support | Yes                        | No                      |
+| Performance     | Slower (interpreted)       | Faster (V8 JIT)         |
+| Memory limit    | Configurable               | Configurable            |
+| Best for        | Browser, edge, portability | Server-side performance |
+
+## How It Works
+
+Uses [QuickJS](https://bellard.org/quickjs/) compiled to WebAssembly via [`quickjs-emscripten`](https://github.com/nicolo-ribaudo/quickjs-emscripten). Each execution creates a fresh async QuickJS context with tool bindings injected as global async functions.
+
+## Runtime Limits and Errors
+
+- QuickJS enforces runtime memory and stack limits for each context.
+- Exceeding limits can produce normalized errors such as `MemoryLimitError` or `StackOverflowError`.
+- Certain fatal limit conditions may dispose the underlying VM; create a fresh context before running more code after disposal.
+
+## License
+
+MIT

package/dist/esm/error-normalizer.d.ts

@@ -0,0 +1,10 @@
+import { NormalizedError } from '@tanstack/ai-code-mode';
+/**
+ * Whether this normalized error indicates the QuickJS VM should not be reused
+ * (memory or stack limit exceeded).
+ */
+export declare function isFatalQuickJSLimitError(error: NormalizedError): boolean;
+/**
+ * Normalize various error types into a consistent format
+ */
+export declare function normalizeError(error: unknown): NormalizedError;

package/dist/esm/error-normalizer.js

@@ -0,0 +1,60 @@
+const MEMORY_LIMIT_ERROR = "MemoryLimitError";
+const STACK_OVERFLOW_ERROR = "StackOverflowError";
+function isFatalQuickJSLimitError(error) {
+  return error.name === MEMORY_LIMIT_ERROR || error.name === STACK_OVERFLOW_ERROR;
+}
+function normalizeError(error) {
+  if (error instanceof Error) {
+    const msg = error.message;
+    const lower = msg.toLowerCase();
+    if (lower.includes("out of memory") || lower.includes("memory alloc") || error.name === "InternalError" && lower.includes("memory")) {
+      return {
+        name: MEMORY_LIMIT_ERROR,
+        message: "Code execution exceeded memory limit",
+        stack: error.stack
+      };
+    }
+    if (lower.includes("stack overflow")) {
+      return {
+        name: STACK_OVERFLOW_ERROR,
+        message: "Code execution exceeded stack size limit",
+        stack: error.stack
+      };
+    }
+    if (error.name === "RuntimeError" && lower.includes("unreachable")) {
+      return {
+        name: "WasmRuntimeError",
+        message: msg || "WebAssembly runtime error",
+        stack: error.stack
+      };
+    }
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+  if (typeof error === "string") {
+    return {
+      name: "Error",
+      message: error
+    };
+  }
+  if (typeof error === "object" && error !== null) {
+    const errObj = error;
+    return {
+      name: String(errObj.name || "Error"),
+      message: String(errObj.message || "Unknown error"),
+      stack: errObj.stack ? String(errObj.stack) : void 0
+    };
+  }
+  return {
+    name: "UnknownError",
+    message: String(error)
+  };
+}
+export {
+  isFatalQuickJSLimitError,
+  normalizeError
+};
+//# sourceMappingURL=error-normalizer.js.map

package/dist/esm/error-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-normalizer.js","sources":["../../src/error-normalizer.ts"],"sourcesContent":["import type { NormalizedError } from '@tanstack/ai-code-mode'\n\nconst MEMORY_LIMIT_ERROR = 'MemoryLimitError'\nconst STACK_OVERFLOW_ERROR = 'StackOverflowError'\n\n/**\n * Whether this normalized error indicates the QuickJS VM should not be reused\n * (memory or stack limit exceeded).\n */\nexport function isFatalQuickJSLimitError(error: NormalizedError): boolean {\n  return (\n    error.name === MEMORY_LIMIT_ERROR || error.name === STACK_OVERFLOW_ERROR\n  )\n}\n\n/**\n * Normalize various error types into a consistent format\n */\nexport function normalizeError(error: unknown): NormalizedError {\n  if (error instanceof Error) {\n    const msg = error.message\n    const lower = msg.toLowerCase()\n\n    if (\n      lower.includes('out of memory') ||\n      lower.includes('memory alloc') ||\n      (error.name === 'InternalError' && lower.includes('memory'))\n    ) {\n      return {\n        name: MEMORY_LIMIT_ERROR,\n        message: 'Code execution exceeded memory limit',\n        stack: error.stack,\n      }\n    }\n\n    if (lower.includes('stack overflow')) {\n      return {\n        name: STACK_OVERFLOW_ERROR,\n        message: 'Code execution exceeded stack size limit',\n        stack: error.stack,\n      }\n    }\n\n    if (error.name === 'RuntimeError' && lower.includes('unreachable')) {\n      return {\n        name: 'WasmRuntimeError',\n        message: msg || 'WebAssembly runtime error',\n        stack: error.stack,\n      }\n    }\n\n    return {\n      name: error.name,\n      message: error.message,\n      stack: error.stack,\n    }\n  }\n\n  if (typeof error === 'string') {\n    return {\n      name: 'Error',\n      message: error,\n    }\n  }\n\n  if (typeof error === 'object' && error !== null) {\n    const errObj = error as Record<string, unknown>\n    return {\n      name: String(errObj.name || 'Error'),\n      message: String(errObj.message || 'Unknown error'),\n      stack: errObj.stack ? String(errObj.stack) : undefined,\n    }\n  }\n\n  return {\n    name: 'UnknownError',\n    message: String(error),\n  }\n}\n"],"names":[],"mappings":"AAEA,MAAM,qBAAqB;AAC3B,MAAM,uBAAuB;AAMtB,SAAS,yBAAyB,OAAiC;AACxE,SACE,MAAM,SAAS,sBAAsB,MAAM,SAAS;AAExD;AAKO,SAAS,eAAe,OAAiC;AAC9D,MAAI,iBAAiB,OAAO;AAC1B,UAAM,MAAM,MAAM;AAClB,UAAM,QAAQ,IAAI,YAAA;AAElB,QACE,MAAM,SAAS,eAAe,KAC9B,MAAM,SAAS,cAAc,KAC5B,MAAM,SAAS,mBAAmB,MAAM,SAAS,QAAQ,GAC1D;AACA,aAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,QACT,OAAO,MAAM;AAAA,MAAA;AAAA,IAEjB;AAEA,QAAI,MAAM,SAAS,gBAAgB,GAAG;AACpC,aAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,QACT,OAAO,MAAM;AAAA,MAAA;AAAA,IAEjB;AAEA,QAAI,MAAM,SAAS,kBAAkB,MAAM,SAAS,aAAa,GAAG;AAClE,aAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,OAAO;AAAA,QAChB,OAAO,MAAM;AAAA,MAAA;AAAA,IAEjB;AAEA,WAAO;AAAA,MACL,MAAM,MAAM;AAAA,MACZ,SAAS,MAAM;AAAA,MACf,OAAO,MAAM;AAAA,IAAA;AAAA,EAEjB;AAEA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO;AAAA,MACL,MAAM;AAAA,MACN,SAAS;AAAA,IAAA;AAAA,EAEb;AAEA,MAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,UAAM,SAAS;AACf,WAAO;AAAA,MACL,MAAM,OAAO,OAAO,QAAQ,OAAO;AAAA,MACnC,SAAS,OAAO,OAAO,WAAW,eAAe;AAAA,MACjD,OAAO,OAAO,QAAQ,OAAO,OAAO,KAAK,IAAI;AAAA,IAAA;AAAA,EAEjD;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,OAAO,KAAK;AAAA,EAAA;AAEzB;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { createQuickJSIsolateDriver, type QuickJSIsolateDriverConfig, } from './isolate-driver.js';
+export type { IsolateDriver, IsolateConfig, IsolateContext, ExecutionResult, NormalizedError, } from '@tanstack/ai-code-mode';

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+import { createQuickJSIsolateDriver } from "./isolate-driver.js";
+export {
+  createQuickJSIsolateDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/esm/isolate-context.d.ts

@@ -0,0 +1,15 @@
+import { QuickJSAsyncContext } from 'quickjs-emscripten';
+import { ExecutionResult, IsolateContext } from '@tanstack/ai-code-mode';
+/**
+ * IsolateContext implementation using QuickJS WASM
+ */
+export declare class QuickJSIsolateContext implements IsolateContext {
+    private vm;
+    private logs;
+    private timeout;
+    private disposed;
+    private executing;
+    constructor(vm: QuickJSAsyncContext, logs: Array<string>, timeout: number);
+    execute<T = unknown>(code: string): Promise<ExecutionResult<T>>;
+    dispose(): Promise<void>;
+}

package/dist/esm/isolate-context.js

@@ -0,0 +1,122 @@
+import { wrapCode } from "@tanstack/ai-code-mode";
+import { normalizeError, isFatalQuickJSLimitError } from "./error-normalizer.js";
+let globalExecQueue = Promise.resolve();
+class QuickJSIsolateContext {
+  constructor(vm, logs, timeout) {
+    this.disposed = false;
+    this.executing = false;
+    this.vm = vm;
+    this.logs = logs;
+    this.timeout = timeout;
+  }
+  async execute(code) {
+    if (this.disposed) {
+      return {
+        success: false,
+        error: {
+          name: "DisposedError",
+          message: "Context has been disposed"
+        },
+        logs: []
+      };
+    }
+    let resolve;
+    const myTurn = new Promise((r) => {
+      resolve = r;
+    });
+    const waitForPrev = globalExecQueue;
+    globalExecQueue = myTurn;
+    await waitForPrev;
+    if (this.disposed) {
+      resolve();
+      return {
+        success: false,
+        error: {
+          name: "DisposedError",
+          message: "Context has been disposed"
+        },
+        logs: []
+      };
+    }
+    this.executing = true;
+    this.logs.length = 0;
+    const releaseVmAfterFatalLimit = () => {
+      if (this.disposed) return;
+      try {
+        this.vm.runtime.setInterruptHandler(() => false);
+      } catch {
+      }
+      this.disposed = true;
+      this.vm.dispose();
+    };
+    const fail = (error) => {
+      const normalized = normalizeError(error);
+      if (isFatalQuickJSLimitError(normalized)) {
+        releaseVmAfterFatalLimit();
+      }
+      return {
+        success: false,
+        error: normalized,
+        logs: [...this.logs]
+      };
+    };
+    try {
+      const wrappedCode = wrapCode(code);
+      const deadline = Date.now() + this.timeout;
+      this.vm.runtime.setInterruptHandler(() => {
+        return Date.now() > deadline;
+      });
+      try {
+        const result = await this.vm.evalCodeAsync(wrappedCode);
+        let parsedResult;
+        try {
+          const promiseHandle = this.vm.unwrapResult(result);
+          const nativePromise = this.vm.resolvePromise(promiseHandle);
+          promiseHandle.dispose();
+          this.vm.runtime.executePendingJobs();
+          const resolvedResult = await nativePromise;
+          const valueHandle = this.vm.unwrapResult(resolvedResult);
+          const dumpedResult = this.vm.dump(valueHandle);
+          valueHandle.dispose();
+          if (typeof dumpedResult === "string") {
+            try {
+              parsedResult = JSON.parse(dumpedResult);
+            } catch {
+              parsedResult = dumpedResult;
+            }
+          } else {
+            parsedResult = dumpedResult;
+          }
+          return {
+            success: true,
+            value: parsedResult,
+            logs: [...this.logs]
+          };
+        } catch (unwrapError) {
+          return fail(unwrapError);
+        }
+      } finally {
+        if (!this.disposed) {
+          this.vm.runtime.setInterruptHandler(() => false);
+        }
+      }
+    } catch (error) {
+      return fail(error);
+    } finally {
+      this.executing = false;
+      resolve();
+    }
+  }
+  async dispose() {
+    if (this.disposed) return;
+    if (this.executing) {
+      await globalExecQueue;
+    }
+    this.disposed = true;
+    this.vm.dispose();
+  }
+}
+export {
+  QuickJSIsolateContext
+};
+//# sourceMappingURL=isolate-context.js.map

package/dist/esm/isolate-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolate-context.js","sources":["../../src/isolate-context.ts"],"sourcesContent":["import { wrapCode } from '@tanstack/ai-code-mode'\nimport { isFatalQuickJSLimitError, normalizeError } from './error-normalizer'\nimport type { QuickJSAsyncContext } from 'quickjs-emscripten'\nimport type { ExecutionResult, IsolateContext } from '@tanstack/ai-code-mode'\n\n/**\n * Serializes all QuickJS evalCodeAsync calls across contexts.\n * Required because newAsyncContext() reuses a singleton WASM module\n * whose asyncify stack can only handle one suspension at a time.\n */\nlet globalExecQueue: Promise<void> = Promise.resolve()\n\n/**\n * IsolateContext implementation using QuickJS WASM\n */\nexport class QuickJSIsolateContext implements IsolateContext {\n  private vm: QuickJSAsyncContext\n  private logs: Array<string>\n  private timeout: number\n  private disposed = false\n  private executing = false\n\n  constructor(vm: QuickJSAsyncContext, logs: Array<string>, timeout: number) {\n    this.vm = vm\n    this.logs = logs\n    this.timeout = timeout\n  }\n\n  async execute<T = unknown>(code: string): Promise<ExecutionResult<T>> {\n    if (this.disposed) {\n      return {\n        success: false,\n        error: {\n          name: 'DisposedError',\n          message: 'Context has been disposed',\n        },\n        logs: [],\n      }\n    }\n\n    // Serialize through the global queue to prevent concurrent\n    // WASM asyncify suspensions across contexts.\n    let resolve!: () => void\n    const myTurn = new Promise<void>((r) => {\n      resolve = r\n    })\n    const waitForPrev = globalExecQueue\n    globalExecQueue = myTurn\n\n    await waitForPrev\n\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose() may be called concurrently while awaiting the queue\n    if (this.disposed) {\n      resolve()\n      return {\n        success: false,\n        error: {\n          name: 'DisposedError',\n          message: 'Context has been disposed',\n        },\n        logs: [],\n      }\n    }\n\n    this.executing = true\n    this.logs.length = 0\n\n    const releaseVmAfterFatalLimit = () => {\n      if (this.disposed) return\n      try {\n        this.vm.runtime.setInterruptHandler(() => false)\n      } catch {\n        // ignore if runtime is already torn down\n      }\n      this.disposed = true\n      this.vm.dispose()\n    }\n\n    const fail = (error: unknown) => {\n      const normalized = normalizeError(error)\n      if (isFatalQuickJSLimitError(normalized)) {\n        releaseVmAfterFatalLimit()\n      }\n      return {\n        success: false as const,\n        error: normalized,\n        logs: [...this.logs],\n      }\n    }\n\n    try {\n      const wrappedCode = wrapCode(code)\n\n      const deadline = Date.now() + this.timeout\n      this.vm.runtime.setInterruptHandler(() => {\n        return Date.now() > deadline\n      })\n\n      try {\n        const result = await this.vm.evalCodeAsync(wrappedCode)\n\n        let parsedResult: T\n        try {\n          const promiseHandle = this.vm.unwrapResult(result)\n\n          // evalCodeAsync returns a Promise handle (our wrapper is an async IIFE).\n          // Use resolvePromise + executePendingJobs to properly await the\n          // QuickJS promise without re-entering the WASM asyncify state.\n          const nativePromise = this.vm.resolvePromise(promiseHandle)\n          promiseHandle.dispose()\n          this.vm.runtime.executePendingJobs()\n          const resolvedResult = await nativePromise\n\n          const valueHandle = this.vm.unwrapResult(resolvedResult)\n          const dumpedResult = this.vm.dump(valueHandle)\n          valueHandle.dispose()\n\n          if (typeof dumpedResult === 'string') {\n            try {\n              parsedResult = JSON.parse(dumpedResult) as T\n            } catch {\n              parsedResult = dumpedResult as T\n            }\n          } else {\n            parsedResult = dumpedResult as T\n          }\n\n          return {\n            success: true,\n            value: parsedResult,\n            logs: [...this.logs],\n          }\n        } catch (unwrapError) {\n          return fail(unwrapError)\n        }\n      } finally {\n        // fail() may set disposed when releasing the VM after memory/stack limit errors\n        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- disposed set in fail()\n        if (!this.disposed) {\n          this.vm.runtime.setInterruptHandler(() => false)\n        }\n      }\n    } catch (error) {\n      return fail(error)\n    } finally {\n      this.executing = false\n      resolve()\n    }\n  }\n\n  async dispose(): Promise<void> {\n    if (this.disposed) return\n\n    // If an execution is in flight, wait for the global queue to drain\n    // before disposing the VM. Otherwise the asyncified callback would\n    // try to access a freed context.\n    if (this.executing) {\n      await globalExecQueue\n    }\n\n    this.disposed = true\n    this.vm.dispose()\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/isolate-driver.d.ts

@@ -0,0 +1,55 @@
+import { IsolateDriver } from '@tanstack/ai-code-mode';
+/**
+ * Configuration for the QuickJS WASM isolate driver
+ */
+export interface QuickJSIsolateDriverConfig {
+    /**
+     * Default execution timeout in ms (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Default memory limit in MB (default: 128).
+     * Applied via QuickJS `runtime.setMemoryLimit`.
+     */
+    memoryLimit?: number;
+    /**
+     * Default max stack size in bytes (default: 512 KiB).
+     * Applied via QuickJS `runtime.setMaxStackSize`.
+     */
+    maxStackSize?: number;
+}
+/**
+ * Create a QuickJS WASM isolate driver
+ *
+ * This driver uses QuickJS compiled to WebAssembly via Emscripten.
+ * It provides a sandboxed JavaScript environment that runs anywhere
+ * (Node.js, browser, edge) without native dependencies.
+ *
+ * Tools are injected as async functions that bridge back to the host.
+ *
+ * @example
+ * ```typescript
+ * import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+ *
+ * const driver = createQuickJSIsolateDriver({
+ *   timeout: 30000,
+ * })
+ *
+ * const context = await driver.createContext({
+ *   bindings: {
+ *     readFile: {
+ *       name: 'readFile',
+ *       description: 'Read a file',
+ *       inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+ *       execute: async ({ path }) => fs.readFile(path, 'utf-8'),
+ *     },
+ *   },
+ * })
+ *
+ * const result = await context.execute(`
+ *   const content = await readFile({ path: './data.json' })
+ *   return JSON.parse(content)
+ * `)
+ * ```
+ */
+export declare function createQuickJSIsolateDriver(config?: QuickJSIsolateDriverConfig): IsolateDriver;

package/dist/esm/isolate-driver.js

@@ -0,0 +1,88 @@
+import { newAsyncContext } from "quickjs-emscripten";
+import { QuickJSIsolateContext } from "./isolate-context.js";
+const DEFAULT_MEMORY_LIMIT_MB = 128;
+const DEFAULT_MAX_STACK_SIZE_BYTES = 512 * 1024;
+function createQuickJSIsolateDriver(config = {}) {
+  const defaultTimeout = config.timeout ?? 3e4;
+  const defaultMemoryLimit = config.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB;
+  const defaultMaxStackSize = config.maxStackSize ?? DEFAULT_MAX_STACK_SIZE_BYTES;
+  return {
+    async createContext(isolateConfig) {
+      const timeout = isolateConfig.timeout ?? defaultTimeout;
+      const memoryLimitMb = isolateConfig.memoryLimit ?? defaultMemoryLimit;
+      const maxStackSizeBytes = defaultMaxStackSize;
+      const vm = await newAsyncContext();
+      vm.runtime.setMemoryLimit(memoryLimitMb * 1024 * 1024);
+      vm.runtime.setMaxStackSize(maxStackSizeBytes);
+      const logs = [];
+      const consoleObj = vm.newObject();
+      const createConsoleMethod = (prefix) => {
+        return vm.newFunction(`console.${prefix}`, (...args) => {
+          const parts = args.map((arg) => {
+            const str = vm.getString(arg);
+            return str;
+          });
+          const msg = prefix ? `${prefix}: ${parts.join(" ")}` : parts.join(" ");
+          logs.push(msg);
+        });
+      };
+      const logFn = createConsoleMethod("");
+      const errorFn = createConsoleMethod("ERROR");
+      const warnFn = createConsoleMethod("WARN");
+      const infoFn = createConsoleMethod("INFO");
+      vm.setProp(consoleObj, "log", logFn);
+      vm.setProp(consoleObj, "error", errorFn);
+      vm.setProp(consoleObj, "warn", warnFn);
+      vm.setProp(consoleObj, "info", infoFn);
+      vm.setProp(vm.global, "console", consoleObj);
+      logFn.dispose();
+      errorFn.dispose();
+      warnFn.dispose();
+      infoFn.dispose();
+      consoleObj.dispose();
+      for (const [name, binding] of Object.entries(isolateConfig.bindings)) {
+        const toolFn = vm.newAsyncifiedFunction(name, async (argsHandle) => {
+          try {
+            const argsJson = vm.getString(argsHandle);
+            const args = JSON.parse(argsJson);
+            const result = await binding.execute(args);
+            const returnHandle = vm.newString(
+              JSON.stringify({ success: true, value: result })
+            );
+            return returnHandle;
+          } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const returnHandle = vm.newString(
+              JSON.stringify({ success: false, error: errorMessage })
+            );
+            return returnHandle;
+          }
+        });
+        vm.setProp(vm.global, `__${name}_impl`, toolFn);
+        toolFn.dispose();
+        const wrapperCode = `
+          async function ${name}(input) {
+            const resultJson = await __${name}_impl(JSON.stringify(input));
+            const result = JSON.parse(resultJson);
+            if (!result.success) {
+              throw new Error(result.error);
+            }
+            return result.value;
+          }
+        `;
+        const wrapperResult = vm.evalCode(wrapperCode);
+        if (wrapperResult.error) {
+          const errorStr = vm.dump(wrapperResult.error);
+          wrapperResult.error.dispose();
+          throw new Error(`Failed to create wrapper for ${name}: ${errorStr}`);
+        }
+        wrapperResult.value.dispose();
+      }
+      return new QuickJSIsolateContext(vm, logs, timeout);
+    }
+  };
+}
+export {
+  createQuickJSIsolateDriver
+};
+//# sourceMappingURL=isolate-driver.js.map

package/dist/esm/isolate-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolate-driver.js","sources":["../../src/isolate-driver.ts"],"sourcesContent":["import { newAsyncContext } from 'quickjs-emscripten'\nimport { QuickJSIsolateContext } from './isolate-context'\nimport type {\n  IsolateConfig,\n  IsolateContext,\n  IsolateDriver,\n} from '@tanstack/ai-code-mode'\n\n/** Default memory limit in MB (matches Node isolate driver default). */\nconst DEFAULT_MEMORY_LIMIT_MB = 128\n\n/** Default max stack size in bytes for QuickJS runtime. */\nconst DEFAULT_MAX_STACK_SIZE_BYTES = 512 * 1024\n\n/**\n * Configuration for the QuickJS WASM isolate driver\n */\nexport interface QuickJSIsolateDriverConfig {\n  /**\n   * Default execution timeout in ms (default: 30000)\n   */\n  timeout?: number\n\n  /**\n   * Default memory limit in MB (default: 128).\n   * Applied via QuickJS `runtime.setMemoryLimit`.\n   */\n  memoryLimit?: number\n\n  /**\n   * Default max stack size in bytes (default: 512 KiB).\n   * Applied via QuickJS `runtime.setMaxStackSize`.\n   */\n  maxStackSize?: number\n}\n\n/**\n * Create a QuickJS WASM isolate driver\n *\n * This driver uses QuickJS compiled to WebAssembly via Emscripten.\n * It provides a sandboxed JavaScript environment that runs anywhere\n * (Node.js, browser, edge) without native dependencies.\n *\n * Tools are injected as async functions that bridge back to the host.\n *\n * @example\n * ```typescript\n * import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'\n *\n * const driver = createQuickJSIsolateDriver({\n *   timeout: 30000,\n * })\n *\n * const context = await driver.createContext({\n *   bindings: {\n *     readFile: {\n *       name: 'readFile',\n *       description: 'Read a file',\n *       inputSchema: { type: 'object', properties: { path: { type: 'string' } } },\n *       execute: async ({ path }) => fs.readFile(path, 'utf-8'),\n *     },\n *   },\n * })\n *\n * const result = await context.execute(`\n *   const content = await readFile({ path: './data.json' })\n *   return JSON.parse(content)\n * `)\n * ```\n */\nexport function createQuickJSIsolateDriver(\n  config: QuickJSIsolateDriverConfig = {},\n): IsolateDriver {\n  const defaultTimeout = config.timeout ?? 30000\n  const defaultMemoryLimit = config.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB\n  const defaultMaxStackSize =\n    config.maxStackSize ?? DEFAULT_MAX_STACK_SIZE_BYTES\n\n  return {\n    async createContext(isolateConfig: IsolateConfig): Promise<IsolateContext> {\n      const timeout = isolateConfig.timeout ?? defaultTimeout\n      const memoryLimitMb = isolateConfig.memoryLimit ?? defaultMemoryLimit\n      const maxStackSizeBytes = defaultMaxStackSize\n\n      // Create async QuickJS context (supports async host functions)\n      const vm = await newAsyncContext()\n\n      // Enforce heap and stack limits so OOM/stack overflow surface as JS errors\n      // instead of growing WASM memory until the host process OOMs.\n      vm.runtime.setMemoryLimit(memoryLimitMb * 1024 * 1024)\n      vm.runtime.setMaxStackSize(maxStackSizeBytes)\n\n      // Set up console.log capture\n      const logs: Array<string> = []\n\n      // Create console object\n      const consoleObj = vm.newObject()\n\n      // Helper to create console methods\n      const createConsoleMethod = (prefix: string) => {\n        return vm.newFunction(`console.${prefix}`, (...args) => {\n          const parts = args.map((arg) => {\n            const str = vm.getString(arg)\n            return str\n          })\n          const msg = prefix ? `${prefix}: ${parts.join(' ')}` : parts.join(' ')\n          logs.push(msg)\n        })\n      }\n\n      const logFn = createConsoleMethod('')\n      const errorFn = createConsoleMethod('ERROR')\n      const warnFn = createConsoleMethod('WARN')\n      const infoFn = createConsoleMethod('INFO')\n\n      vm.setProp(consoleObj, 'log', logFn)\n      vm.setProp(consoleObj, 'error', errorFn)\n      vm.setProp(consoleObj, 'warn', warnFn)\n      vm.setProp(consoleObj, 'info', infoFn)\n      vm.setProp(vm.global, 'console', consoleObj)\n\n      // Dispose console handles\n      logFn.dispose()\n      errorFn.dispose()\n      warnFn.dispose()\n      infoFn.dispose()\n      consoleObj.dispose()\n\n      // Inject each tool binding as an async function\n      for (const [name, binding] of Object.entries(isolateConfig.bindings)) {\n        // Create async function that calls back to host\n        // newAsyncifiedFunction receives QuickJS handles as arguments\n        const toolFn = vm.newAsyncifiedFunction(name, async (argsHandle) => {\n          try {\n            // Get the input argument - argsHandle is a QuickJS handle\n            const argsJson = vm.getString(argsHandle)\n            const args = JSON.parse(argsJson)\n\n            // Execute the tool on the host\n            const result = await binding.execute(args)\n\n            // Return result as JSON string handle\n            const returnHandle = vm.newString(\n              JSON.stringify({ success: true, value: result }),\n            )\n            return returnHandle\n          } catch (error) {\n            const errorMessage =\n              error instanceof Error ? error.message : String(error)\n            const returnHandle = vm.newString(\n              JSON.stringify({ success: false, error: errorMessage }),\n            )\n            return returnHandle\n          }\n        })\n\n        // Set on global - the VM keeps its own reference\n        vm.setProp(vm.global, `__${name}_impl`, toolFn)\n        toolFn.dispose()\n\n        // Create wrapper that parses input and output\n        // Function names match the binding keys (e.g., external_fetchWeather)\n        const wrapperCode = `\n          async function ${name}(input) {\n            const resultJson = await __${name}_impl(JSON.stringify(input));\n            const result = JSON.parse(resultJson);\n            if (!result.success) {\n              throw new Error(result.error);\n            }\n            return result.value;\n          }\n        `\n        const wrapperResult = vm.evalCode(wrapperCode)\n        if (wrapperResult.error) {\n          const errorStr = vm.dump(wrapperResult.error)\n          wrapperResult.error.dispose()\n          throw new Error(`Failed to create wrapper for ${name}: ${errorStr}`)\n        }\n        wrapperResult.value.dispose()\n      }\n\n      return new QuickJSIsolateContext(vm, logs, timeout)\n    },\n  }\n}\n"],"names":[],"mappings":";;AASA,MAAM,0BAA0B;AAGhC,MAAM,+BAA+B,MAAM;AA0DpC,SAAS,2BACd,SAAqC,IACtB;AACf,QAAM,iBAAiB,OAAO,WAAW;AACzC,QAAM,qBAAqB,OAAO,eAAe;AACjD,QAAM,sBACJ,OAAO,gBAAgB;AAEzB,SAAO;AAAA,IACL,MAAM,cAAc,eAAuD;AACzE,YAAM,UAAU,cAAc,WAAW;AACzC,YAAM,gBAAgB,cAAc,eAAe;AACnD,YAAM,oBAAoB;AAG1B,YAAM,KAAK,MAAM,gBAAA;AAIjB,SAAG,QAAQ,eAAe,gBAAgB,OAAO,IAAI;AACrD,SAAG,QAAQ,gBAAgB,iBAAiB;AAG5C,YAAM,OAAsB,CAAA;AAG5B,YAAM,aAAa,GAAG,UAAA;AAGtB,YAAM,sBAAsB,CAAC,WAAmB;AAC9C,eAAO,GAAG,YAAY,WAAW,MAAM,IAAI,IAAI,SAAS;AACtD,gBAAM,QAAQ,KAAK,IAAI,CAAC,QAAQ;AAC9B,kBAAM,MAAM,GAAG,UAAU,GAAG;AAC5B,mBAAO;AAAA,UACT,CAAC;AACD,gBAAM,MAAM,SAAS,GAAG,MAAM,KAAK,MAAM,KAAK,GAAG,CAAC,KAAK,MAAM,KAAK,GAAG;AACrE,eAAK,KAAK,GAAG;AAAA,QACf,CAAC;AAAA,MACH;AAEA,YAAM,QAAQ,oBAAoB,EAAE;AACpC,YAAM,UAAU,oBAAoB,OAAO;AAC3C,YAAM,SAAS,oBAAoB,MAAM;AACzC,YAAM,SAAS,oBAAoB,MAAM;AAEzC,SAAG,QAAQ,YAAY,OAAO,KAAK;AACnC,SAAG,QAAQ,YAAY,SAAS,OAAO;AACvC,SAAG,QAAQ,YAAY,QAAQ,MAAM;AACrC,SAAG,QAAQ,YAAY,QAAQ,MAAM;AACrC,SAAG,QAAQ,GAAG,QAAQ,WAAW,UAAU;AAG3C,YAAM,QAAA;AACN,cAAQ,QAAA;AACR,aAAO,QAAA;AACP,aAAO,QAAA;AACP,iBAAW,QAAA;AAGX,iBAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,cAAc,QAAQ,GAAG;AAGpE,cAAM,SAAS,GAAG,sBAAsB,MAAM,OAAO,eAAe;AAClE,cAAI;AAEF,kBAAM,WAAW,GAAG,UAAU,UAAU;AACxC,kBAAM,OAAO,KAAK,MAAM,QAAQ;AAGhC,kBAAM,SAAS,MAAM,QAAQ,QAAQ,IAAI;AAGzC,kBAAM,eAAe,GAAG;AAAA,cACtB,KAAK,UAAU,EAAE,SAAS,MAAM,OAAO,QAAQ;AAAA,YAAA;AAEjD,mBAAO;AAAA,UACT,SAAS,OAAO;AACd,kBAAM,eACJ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACvD,kBAAM,eAAe,GAAG;AAAA,cACtB,KAAK,UAAU,EAAE,SAAS,OAAO,OAAO,cAAc;AAAA,YAAA;AAExD,mBAAO;AAAA,UACT;AAAA,QACF,CAAC;AAGD,WAAG,QAAQ,GAAG,QAAQ,KAAK,IAAI,SAAS,MAAM;AAC9C,eAAO,QAAA;AAIP,cAAM,cAAc;AAAA,2BACD,IAAI;AAAA,yCACU,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQrC,cAAM,gBAAgB,GAAG,SAAS,WAAW;AAC7C,YAAI,cAAc,OAAO;AACvB,gBAAM,WAAW,GAAG,KAAK,cAAc,KAAK;AAC5C,wBAAc,MAAM,QAAA;AACpB,gBAAM,IAAI,MAAM,gCAAgC,IAAI,KAAK,QAAQ,EAAE;AAAA,QACrE;AACA,sBAAc,MAAM,QAAA;AAAA,MACtB;AAEA,aAAO,IAAI,sBAAsB,IAAI,MAAM,OAAO;AAAA,IACpD;AAAA,EAAA;AAEJ;"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tanstack/ai-isolate-quickjs",
+  "version": "0.1.0",
+  "description": "QuickJS WASM driver for TanStack AI Code Mode - runs everywhere",
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-isolate-quickjs"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "code-mode",
+    "isolate",
+    "sandbox",
+    "quickjs",
+    "wasm"
+  ],
+  "dependencies": {
+    "quickjs-emscripten": "^0.31.0"
+  },
+  "peerDependencies": {
+    "@tanstack/ai-code-mode": "workspace:*"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14"
+  }
+}

package/src/error-normalizer.ts

@@ -0,0 +1,79 @@
+import type { NormalizedError } from '@tanstack/ai-code-mode'
+
+const MEMORY_LIMIT_ERROR = 'MemoryLimitError'
+const STACK_OVERFLOW_ERROR = 'StackOverflowError'
+
+/**
+ * Whether this normalized error indicates the QuickJS VM should not be reused
+ * (memory or stack limit exceeded).
+ */
+export function isFatalQuickJSLimitError(error: NormalizedError): boolean {
+  return (
+    error.name === MEMORY_LIMIT_ERROR || error.name === STACK_OVERFLOW_ERROR
+  )
+}
+
+/**
+ * Normalize various error types into a consistent format
+ */
+export function normalizeError(error: unknown): NormalizedError {
+  if (error instanceof Error) {
+    const msg = error.message
+    const lower = msg.toLowerCase()
+
+    if (
+      lower.includes('out of memory') ||
+      lower.includes('memory alloc') ||
+      (error.name === 'InternalError' && lower.includes('memory'))
+    ) {
+      return {
+        name: MEMORY_LIMIT_ERROR,
+        message: 'Code execution exceeded memory limit',
+        stack: error.stack,
+      }
+    }
+
+    if (lower.includes('stack overflow')) {
+      return {
+        name: STACK_OVERFLOW_ERROR,
+        message: 'Code execution exceeded stack size limit',
+        stack: error.stack,
+      }
+    }
+
+    if (error.name === 'RuntimeError' && lower.includes('unreachable')) {
+      return {
+        name: 'WasmRuntimeError',
+        message: msg || 'WebAssembly runtime error',
+        stack: error.stack,
+      }
+    }
+
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    }
+  }
+
+  if (typeof error === 'string') {
+    return {
+      name: 'Error',
+      message: error,
+    }
+  }
+
+  if (typeof error === 'object' && error !== null) {
+    const errObj = error as Record<string, unknown>
+    return {
+      name: String(errObj.name || 'Error'),
+      message: String(errObj.message || 'Unknown error'),
+      stack: errObj.stack ? String(errObj.stack) : undefined,
+    }
+  }
+
+  return {
+    name: 'UnknownError',
+    message: String(error),
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export {
+  createQuickJSIsolateDriver,
+  type QuickJSIsolateDriverConfig,
+} from './isolate-driver'
+
+// Re-export types from ai-code-mode for convenience
+export type {
+  IsolateDriver,
+  IsolateConfig,
+  IsolateContext,
+  ExecutionResult,
+  NormalizedError,
+} from '@tanstack/ai-code-mode'

package/src/isolate-context.ts

@@ -0,0 +1,164 @@
+import { wrapCode } from '@tanstack/ai-code-mode'
+import { isFatalQuickJSLimitError, normalizeError } from './error-normalizer'
+import type { QuickJSAsyncContext } from 'quickjs-emscripten'
+import type { ExecutionResult, IsolateContext } from '@tanstack/ai-code-mode'
+
+/**
+ * Serializes all QuickJS evalCodeAsync calls across contexts.
+ * Required because newAsyncContext() reuses a singleton WASM module
+ * whose asyncify stack can only handle one suspension at a time.
+ */
+let globalExecQueue: Promise<void> = Promise.resolve()
+
+/**
+ * IsolateContext implementation using QuickJS WASM
+ */
+export class QuickJSIsolateContext implements IsolateContext {
+  private vm: QuickJSAsyncContext
+  private logs: Array<string>
+  private timeout: number
+  private disposed = false
+  private executing = false
+
+  constructor(vm: QuickJSAsyncContext, logs: Array<string>, timeout: number) {
+    this.vm = vm
+    this.logs = logs
+    this.timeout = timeout
+  }
+
+  async execute<T = unknown>(code: string): Promise<ExecutionResult<T>> {
+    if (this.disposed) {
+      return {
+        success: false,
+        error: {
+          name: 'DisposedError',
+          message: 'Context has been disposed',
+        },
+        logs: [],
+      }
+    }
+
+    // Serialize through the global queue to prevent concurrent
+    // WASM asyncify suspensions across contexts.
+    let resolve!: () => void
+    const myTurn = new Promise<void>((r) => {
+      resolve = r
+    })
+    const waitForPrev = globalExecQueue
+    globalExecQueue = myTurn
+
+    await waitForPrev
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose() may be called concurrently while awaiting the queue
+    if (this.disposed) {
+      resolve()
+      return {
+        success: false,
+        error: {
+          name: 'DisposedError',
+          message: 'Context has been disposed',
+        },
+        logs: [],
+      }
+    }
+
+    this.executing = true
+    this.logs.length = 0
+
+    const releaseVmAfterFatalLimit = () => {
+      if (this.disposed) return
+      try {
+        this.vm.runtime.setInterruptHandler(() => false)
+      } catch {
+        // ignore if runtime is already torn down
+      }
+      this.disposed = true
+      this.vm.dispose()
+    }
+
+    const fail = (error: unknown) => {
+      const normalized = normalizeError(error)
+      if (isFatalQuickJSLimitError(normalized)) {
+        releaseVmAfterFatalLimit()
+      }
+      return {
+        success: false as const,
+        error: normalized,
+        logs: [...this.logs],
+      }
+    }
+
+    try {
+      const wrappedCode = wrapCode(code)
+
+      const deadline = Date.now() + this.timeout
+      this.vm.runtime.setInterruptHandler(() => {
+        return Date.now() > deadline
+      })
+
+      try {
+        const result = await this.vm.evalCodeAsync(wrappedCode)
+
+        let parsedResult: T
+        try {
+          const promiseHandle = this.vm.unwrapResult(result)
+
+          // evalCodeAsync returns a Promise handle (our wrapper is an async IIFE).
+          // Use resolvePromise + executePendingJobs to properly await the
+          // QuickJS promise without re-entering the WASM asyncify state.
+          const nativePromise = this.vm.resolvePromise(promiseHandle)
+          promiseHandle.dispose()
+          this.vm.runtime.executePendingJobs()
+          const resolvedResult = await nativePromise
+
+          const valueHandle = this.vm.unwrapResult(resolvedResult)
+          const dumpedResult = this.vm.dump(valueHandle)
+          valueHandle.dispose()
+
+          if (typeof dumpedResult === 'string') {
+            try {
+              parsedResult = JSON.parse(dumpedResult) as T
+            } catch {
+              parsedResult = dumpedResult as T
+            }
+          } else {
+            parsedResult = dumpedResult as T
+          }
+
+          return {
+            success: true,
+            value: parsedResult,
+            logs: [...this.logs],
+          }
+        } catch (unwrapError) {
+          return fail(unwrapError)
+        }
+      } finally {
+        // fail() may set disposed when releasing the VM after memory/stack limit errors
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- disposed set in fail()
+        if (!this.disposed) {
+          this.vm.runtime.setInterruptHandler(() => false)
+        }
+      }
+    } catch (error) {
+      return fail(error)
+    } finally {
+      this.executing = false
+      resolve()
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+
+    // If an execution is in flight, wait for the global queue to drain
+    // before disposing the VM. Otherwise the asyncified callback would
+    // try to access a freed context.
+    if (this.executing) {
+      await globalExecQueue
+    }
+
+    this.disposed = true
+    this.vm.dispose()
+  }
+}

package/src/isolate-driver.ts

@@ -0,0 +1,185 @@
+import { newAsyncContext } from 'quickjs-emscripten'
+import { QuickJSIsolateContext } from './isolate-context'
+import type {
+  IsolateConfig,
+  IsolateContext,
+  IsolateDriver,
+} from '@tanstack/ai-code-mode'
+
+/** Default memory limit in MB (matches Node isolate driver default). */
+const DEFAULT_MEMORY_LIMIT_MB = 128
+
+/** Default max stack size in bytes for QuickJS runtime. */
+const DEFAULT_MAX_STACK_SIZE_BYTES = 512 * 1024
+
+/**
+ * Configuration for the QuickJS WASM isolate driver
+ */
+export interface QuickJSIsolateDriverConfig {
+  /**
+   * Default execution timeout in ms (default: 30000)
+   */
+  timeout?: number
+
+  /**
+   * Default memory limit in MB (default: 128).
+   * Applied via QuickJS `runtime.setMemoryLimit`.
+   */
+  memoryLimit?: number
+
+  /**
+   * Default max stack size in bytes (default: 512 KiB).
+   * Applied via QuickJS `runtime.setMaxStackSize`.
+   */
+  maxStackSize?: number
+}
+
+/**
+ * Create a QuickJS WASM isolate driver
+ *
+ * This driver uses QuickJS compiled to WebAssembly via Emscripten.
+ * It provides a sandboxed JavaScript environment that runs anywhere
+ * (Node.js, browser, edge) without native dependencies.
+ *
+ * Tools are injected as async functions that bridge back to the host.
+ *
+ * @example
+ * ```typescript
+ * import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+ *
+ * const driver = createQuickJSIsolateDriver({
+ *   timeout: 30000,
+ * })
+ *
+ * const context = await driver.createContext({
+ *   bindings: {
+ *     readFile: {
+ *       name: 'readFile',
+ *       description: 'Read a file',
+ *       inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+ *       execute: async ({ path }) => fs.readFile(path, 'utf-8'),
+ *     },
+ *   },
+ * })
+ *
+ * const result = await context.execute(`
+ *   const content = await readFile({ path: './data.json' })
+ *   return JSON.parse(content)
+ * `)
+ * ```
+ */
+export function createQuickJSIsolateDriver(
+  config: QuickJSIsolateDriverConfig = {},
+): IsolateDriver {
+  const defaultTimeout = config.timeout ?? 30000
+  const defaultMemoryLimit = config.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB
+  const defaultMaxStackSize =
+    config.maxStackSize ?? DEFAULT_MAX_STACK_SIZE_BYTES
+
+  return {
+    async createContext(isolateConfig: IsolateConfig): Promise<IsolateContext> {
+      const timeout = isolateConfig.timeout ?? defaultTimeout
+      const memoryLimitMb = isolateConfig.memoryLimit ?? defaultMemoryLimit
+      const maxStackSizeBytes = defaultMaxStackSize
+
+      // Create async QuickJS context (supports async host functions)
+      const vm = await newAsyncContext()
+
+      // Enforce heap and stack limits so OOM/stack overflow surface as JS errors
+      // instead of growing WASM memory until the host process OOMs.
+      vm.runtime.setMemoryLimit(memoryLimitMb * 1024 * 1024)
+      vm.runtime.setMaxStackSize(maxStackSizeBytes)
+
+      // Set up console.log capture
+      const logs: Array<string> = []
+
+      // Create console object
+      const consoleObj = vm.newObject()
+
+      // Helper to create console methods
+      const createConsoleMethod = (prefix: string) => {
+        return vm.newFunction(`console.${prefix}`, (...args) => {
+          const parts = args.map((arg) => {
+            const str = vm.getString(arg)
+            return str
+          })
+          const msg = prefix ? `${prefix}: ${parts.join(' ')}` : parts.join(' ')
+          logs.push(msg)
+        })
+      }
+
+      const logFn = createConsoleMethod('')
+      const errorFn = createConsoleMethod('ERROR')
+      const warnFn = createConsoleMethod('WARN')
+      const infoFn = createConsoleMethod('INFO')
+
+      vm.setProp(consoleObj, 'log', logFn)
+      vm.setProp(consoleObj, 'error', errorFn)
+      vm.setProp(consoleObj, 'warn', warnFn)
+      vm.setProp(consoleObj, 'info', infoFn)
+      vm.setProp(vm.global, 'console', consoleObj)
+
+      // Dispose console handles
+      logFn.dispose()
+      errorFn.dispose()
+      warnFn.dispose()
+      infoFn.dispose()
+      consoleObj.dispose()
+
+      // Inject each tool binding as an async function
+      for (const [name, binding] of Object.entries(isolateConfig.bindings)) {
+        // Create async function that calls back to host
+        // newAsyncifiedFunction receives QuickJS handles as arguments
+        const toolFn = vm.newAsyncifiedFunction(name, async (argsHandle) => {
+          try {
+            // Get the input argument - argsHandle is a QuickJS handle
+            const argsJson = vm.getString(argsHandle)
+            const args = JSON.parse(argsJson)
+
+            // Execute the tool on the host
+            const result = await binding.execute(args)
+
+            // Return result as JSON string handle
+            const returnHandle = vm.newString(
+              JSON.stringify({ success: true, value: result }),
+            )
+            return returnHandle
+          } catch (error) {
+            const errorMessage =
+              error instanceof Error ? error.message : String(error)
+            const returnHandle = vm.newString(
+              JSON.stringify({ success: false, error: errorMessage }),
+            )
+            return returnHandle
+          }
+        })
+
+        // Set on global - the VM keeps its own reference
+        vm.setProp(vm.global, `__${name}_impl`, toolFn)
+        toolFn.dispose()
+
+        // Create wrapper that parses input and output
+        // Function names match the binding keys (e.g., external_fetchWeather)
+        const wrapperCode = `
+          async function ${name}(input) {
+            const resultJson = await __${name}_impl(JSON.stringify(input));
+            const result = JSON.parse(resultJson);
+            if (!result.success) {
+              throw new Error(result.error);
+            }
+            return result.value;
+          }
+        `
+        const wrapperResult = vm.evalCode(wrapperCode)
+        if (wrapperResult.error) {
+          const errorStr = vm.dump(wrapperResult.error)
+          wrapperResult.error.dispose()
+          throw new Error(`Failed to create wrapper for ${name}: ${errorStr}`)
+        }
+        wrapperResult.value.dispose()
+      }
+
+      return new QuickJSIsolateContext(vm, logs, timeout)
+    },
+  }
+}