@absolutejs/ai 0.0.11 → 0.0.12

package/dist/ai/tools/index.js

@@ -116,9 +116,194 @@ var codeExecutionTool = (options = {}) => {
     }
   };
 };
+// src/ai/tools/codeMode.ts
+var buildDescription = (tools, types) => {
+  const lines = [
+    "Execute JavaScript that calls one or more host tools, returning a",
+    "single value. Prefer this over calling individual tools when you'd",
+    "otherwise need multiple sequential tool calls \u2014 one Code Mode call",
+    "replaces N tool calls plus the intermediate context.",
+    "",
+    "Input: `{ code: string }`. The code is a function BODY (not a full",
+    "function). It can use `await`, `const`/`let`, control flow, etc.",
+    "Whatever you `return` becomes the tool output.",
+    "",
+    "Built-in: `log(...args)` captures messages for debugging. Logs are",
+    "returned alongside the result; they don't enter the model context.",
+    "",
+    "Available host functions (calling these from your code is what runs",
+    "the real work; everything else is plain JS):",
+    ""
+  ];
+  for (const [name, tool] of Object.entries(tools)) {
+    lines.push(`// ${tool.description}`);
+    lines.push(`declare const ${name}: ${tool.tsSignature};`);
+    lines.push("");
+  }
+  if (types !== undefined && types.trim().length > 0) {
+    lines.push("// Shared types referenced by the signatures above:");
+    lines.push(types.trim());
+    lines.push("");
+  }
+  lines.push("Example:");
+  lines.push("```js");
+  lines.push("// Get the cheapest matching product and its full record.");
+  const firstTool = Object.keys(tools)[0];
+  if (firstTool !== undefined) {
+    lines.push(`const items = await ${firstTool}('search query');`);
+    lines.push("const cheapest = items.sort((a, b) => a.price - b.price)[0];");
+    lines.push("return cheapest;");
+  } else {
+    lines.push("return 42;");
+  }
+  lines.push("```");
+  lines.push("");
+  lines.push("Output: JSON with `{ result, log, toolCalls, cpuMs, heapBytes }`.");
+  return lines.join(`
+`);
+};
+var codeModeTool = (options) => {
+  const memoryLimit = options.memoryLimit ?? 64;
+  const timeout = options.timeout ?? 5000;
+  const backend = options.backend ?? "auto";
+  const poolSize = options.poolSize ?? 8;
+  const recycleAfter = options.recycleAfter ?? 50;
+  const tools = options.tools;
+  const description = options.description ?? buildDescription(tools, options.types);
+  let cachedPool = null;
+  let cachedPoolPromise = null;
+  const loadPool = async () => {
+    if (cachedPool !== null)
+      return cachedPool;
+    if (cachedPoolPromise !== null)
+      return cachedPoolPromise;
+    cachedPoolPromise = (async () => {
+      const jsc = await import("@absolutejs/isolated-jsc");
+      const pool = jsc.createIsolatePool({
+        isolate: { backend, memoryLimit },
+        maxSize: poolSize,
+        recycleAfter
+      });
+      cachedPool = { pool, jsc };
+      return cachedPool;
+    })();
+    return cachedPoolPromise;
+  };
+  const runCode = async (code) => {
+    const log = [];
+    const toolCalls = [];
+    let cpuMs = 0;
+    let heapBytes = 0;
+    try {
+      const { pool, jsc } = await loadPool();
+      return await pool.run("default", async (isolate) => {
+        const context = await isolate.createContext();
+        try {
+          await context.setGlobal("log", new jsc.Reference((...args) => {
+            log.push(args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" "));
+          }));
+          for (const [name, tool] of Object.entries(tools)) {
+            await context.setGlobal(name, new jsc.Reference((...args) => {
+              const startedAt = performance.now();
+              const recordSuccess = () => {
+                toolCalls.push({
+                  args,
+                  durationMs: performance.now() - startedAt,
+                  name,
+                  ok: true
+                });
+              };
+              const recordError = (err) => {
+                toolCalls.push({
+                  args,
+                  durationMs: performance.now() - startedAt,
+                  error: err instanceof Error ? err.message : String(err),
+                  name,
+                  ok: false
+                });
+              };
+              let outcome;
+              try {
+                outcome = tool.handler(...args);
+              } catch (err) {
+                recordError(err);
+                throw err;
+              }
+              if (outcome !== null && typeof outcome === "object" && "then" in outcome && typeof outcome.then === "function") {
+                return outcome.then((v) => {
+                  recordSuccess();
+                  return v;
+                }, (err) => {
+                  recordError(err);
+                  throw err;
+                });
+              }
+              recordSuccess();
+              return outcome;
+            }));
+          }
+          const wrapped = `(async () => { ${code}
+})()`;
+          const script = await isolate.compileScript(wrapped);
+          const { result, metrics } = await script.runWithMetrics(context, {
+            timeout
+          });
+          cpuMs = metrics.cpuMs;
+          heapBytes = metrics.heapBytes;
+          return { cpuMs, heapBytes, log, ok: true, result, toolCalls };
+        } finally {
+          await context.dispose().catch(() => {});
+        }
+      });
+    } catch (error) {
+      const name = error instanceof Error ? error.name : "Error";
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        cpuMs,
+        error: { message, name },
+        heapBytes,
+        log,
+        ok: false,
+        toolCalls
+      };
+    }
+  };
+  return {
+    description,
+    handler: async (input) => {
+      const code = input !== null && typeof input === "object" && "code" in input ? input.code : undefined;
+      if (typeof code !== "string") {
+        return JSON.stringify({
+          cpuMs: 0,
+          error: {
+            message: "expected `{ code: string }`",
+            name: "InvalidInput"
+          },
+          heapBytes: 0,
+          log: [],
+          ok: false,
+          toolCalls: []
+        });
+      }
+      const run = await runCode(code);
+      return JSON.stringify(run);
+    },
+    input: {
+      properties: {
+        code: {
+          description: "JavaScript function-body source. Use `await` to call host tools; `return` the final value. Multiple tool calls in one " + "block are encouraged \u2014 that's the whole point of Code Mode.",
+          type: "string"
+        }
+      },
+      required: ["code"],
+      type: "object"
+    }
+  };
+};
 export {
+  codeModeTool,
   codeExecutionTool
 };
 
-//# debugId=3DCC3269A76159BC64756E2164756E21
+//# debugId=05A8D1541DB1A68E64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/ai/tools/index.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/ai/tools/codeExecution.ts"],
+  "sources": ["../src/ai/tools/codeExecution.ts", "../src/ai/tools/codeMode.ts"],
   "sourcesContent": [
-    "/**\n * `codeExecutionTool` — an `AIToolDefinition` that runs model-generated\n * JavaScript inside an `@absolutejs/isolated-jsc` sandbox.\n *\n * Drop into any `tools: {...}` map:\n *\n * ```ts\n * import { codeExecutionTool } from '@absolutejs/ai/tools';\n *\n * const tools = {\n *   run_code: codeExecutionTool({\n *     memoryLimit: 64,\n *     timeout: 1000,\n *     expose: {\n *       lookup_user: async (id) => db.users.findById(id as string),\n *       round: (n) => Math.round(n as number),\n *     },\n *   }),\n * };\n * ```\n *\n * The model emits `{ code: '<JS source>' }` as the tool input; the host\n * runs the code in a fresh context inside a pooled isolate and returns\n * a JSON-stringified result containing:\n *\n *   - `result` — the script's return value (JSON-clonable).\n *   - `log` — array of strings captured via the host-injected `log(...)`.\n *   - `error` — error message + name if the script threw or timed out.\n *   - `cpuMs`, `heapBytes` — per-call telemetry (Phase 3 docs / monitoring).\n *\n * Defaults to the FFI backend on macOS + Linux (with libJSC installed),\n * Worker fallback elsewhere. Per-isolate pool is created once per\n * `codeExecutionTool()` call; pool key is `'default'` (one isolate for\n * all calls). For per-tenant isolation, create one tool instance per\n * tenant.\n *\n * Constraint: when using the FFI backend, **exposed host fns must be\n * synchronous**. Async host fns (returning a Promise that doesn't settle\n * synchronously — `fetch`, `setTimeout`-resolved Promises, real I/O)\n * require `backend: 'worker'` per isolated-jsc 0.3 documented limit.\n * Set `backend: 'worker'` in the tool options if any of your `expose`d\n * fns are async-settling.\n */\n\nimport type { AIToolDefinition } from \"../../../types/ai\";\n\n/** Options for {@link codeExecutionTool}. */\nexport type CodeExecutionToolOptions = {\n  /**\n   * Per-isolate heap memory cap (MB). Default 64. Note that the\n   * sandbox's cold-start baseline differs by backend (FFI ~300 KB vs\n   * Worker ~46 MB), so the practical floor for Worker is ~64 MB.\n   */\n  memoryLimit?: number;\n  /** Wall-clock timeout per `run_code` call (ms). Default 1000. */\n  timeout?: number;\n  /**\n   * isolated-jsc backend. Default `\"auto\"` (FFI when reachable, Worker\n   * otherwise). Set to `\"worker\"` if your `expose`d fns are async-settling\n   * — the FFI backend only supports sync host fns (see Reference docs).\n   */\n  backend?: \"auto\" | \"ffi\" | \"worker\";\n  /**\n   * Host functions the model can call from inside the sandbox. Names\n   * become globals; the model invokes them with `await name(...)`.\n   * The function's description (`.toString()` first line, if a doc\n   * comment) is included in the tool's description so the model knows\n   * what's available.\n   */\n  expose?: Record<string, (...args: unknown[]) => unknown>;\n  /**\n   * Override the tool's description string. Default is auto-generated\n   * from the exposed function list.\n   */\n  description?: string;\n  /**\n   * Pool size cap — max concurrent isolates across all parallel tool\n   * calls. Default 8.\n   */\n  poolSize?: number;\n  /**\n   * Recycle the isolate after N successful runs to bound per-context\n   * heap creep. Default 50.\n   */\n  recycleAfter?: number;\n};\n\ntype Run = {\n  ok: boolean;\n  result?: unknown;\n  log: string[];\n  error?: { name: string; message: string };\n  cpuMs: number;\n  heapBytes: number;\n};\n\nconst defaultDescription = (\n  expose: Record<string, (...args: unknown[]) => unknown> | undefined,\n): string => {\n  const lines = [\n    \"Execute JavaScript code in a sandboxed environment.\",\n    \"\",\n    \"Input: `{ code: string }` — the JS source to evaluate. The script's last\",\n    \"expression is the return value (vm.Script semantics).\",\n    \"\",\n    \"Output: JSON with `{ result, log, error?, cpuMs, heapBytes }`.\",\n    \"\",\n    \"Built-in: `log(...args)` captures stdout-like output into the result.log\",\n    \"array.\",\n  ];\n  const exposed = expose ? Object.keys(expose) : [];\n  if (exposed.length > 0) {\n    lines.push(\"\");\n    lines.push(\"Host functions available in the sandbox:\");\n    for (const name of exposed) {\n      lines.push(`  - ${name}(...)`);\n    }\n  }\n  return lines.join(\"\\n\");\n};\n\nexport const codeExecutionTool = (\n  options: CodeExecutionToolOptions = {},\n): AIToolDefinition => {\n  const memoryLimit = options.memoryLimit ?? 64;\n  const timeout = options.timeout ?? 1000;\n  const backend = options.backend ?? \"auto\";\n  const expose = options.expose ?? {};\n  const poolSize = options.poolSize ?? 8;\n  const recycleAfter = options.recycleAfter ?? 50;\n  const description = options.description ?? defaultDescription(expose);\n\n  // Lazy import isolated-jsc so this module loads without it (consumers\n  // who never call the tool don't pay the dep). The first call resolves\n  // and caches the pool; later calls reuse it.\n  type IsolatedJsc = typeof import(\"@absolutejs/isolated-jsc\");\n  let cachedPool:\n    | { pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>; jsc: IsolatedJsc }\n    | null = null;\n  let cachedPoolPromise: Promise<{\n    pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>;\n    jsc: IsolatedJsc;\n  }> | null = null;\n\n  const loadPool = async () => {\n    if (cachedPool !== null) return cachedPool;\n    if (cachedPoolPromise !== null) return cachedPoolPromise;\n    cachedPoolPromise = (async () => {\n      const jsc = (await import(\"@absolutejs/isolated-jsc\")) as IsolatedJsc;\n      const pool = jsc.createIsolatePool({\n        isolate: { backend, memoryLimit },\n        maxSize: poolSize,\n        recycleAfter,\n      });\n      cachedPool = { pool, jsc };\n      return cachedPool;\n    })();\n    return cachedPoolPromise;\n  };\n\n  const runCode = async (code: string): Promise<Run> => {\n    const log: string[] = [];\n    let cpuMs = 0;\n    let heapBytes = 0;\n    try {\n      const { pool, jsc } = await loadPool();\n      return await pool.run(\"default\", async (isolate) => {\n        const context = await isolate.createContext();\n        try {\n          // Built-in log capture. Sync host fn → works on FFI + Worker.\n          await context.setGlobal(\n            \"log\",\n            new jsc.Reference((...args: unknown[]) => {\n              log.push(\n                args\n                  .map((a) =>\n                    typeof a === \"string\" ? a : JSON.stringify(a),\n                  )\n                  .join(\" \"),\n              );\n            }),\n          );\n          // Exposed host fns. Names become globals; user code calls them\n          // directly (FFI sync path) or with `await` (Worker path).\n          for (const [name, fn] of Object.entries(expose)) {\n            await context.setGlobal(name, new jsc.Reference(fn));\n          }\n          // Wrap the user code so the last expression is what's returned\n          // (matching the conventional script-result semantics).\n          const script = await isolate.compileScript(code);\n          const { result, metrics } = await script.runWithMetrics(\n            context,\n            { timeout },\n          );\n          cpuMs = metrics.cpuMs;\n          heapBytes = metrics.heapBytes;\n          return { ok: true, result, log, cpuMs, heapBytes };\n        } finally {\n          await context.dispose().catch(() => {\n            /* dead context — fine */\n          });\n        }\n      });\n    } catch (error) {\n      const name =\n        error instanceof Error ? error.name : \"Error\";\n      const message =\n        error instanceof Error ? error.message : String(error);\n      return {\n        ok: false,\n        log,\n        error: { name, message },\n        cpuMs,\n        heapBytes,\n      };\n    }\n  };\n\n  return {\n    description,\n    input: {\n      type: \"object\",\n      properties: {\n        code: {\n          type: \"string\",\n          description:\n            \"JavaScript source to evaluate. The script's last expression \" +\n            \"is the return value. Use `log(...)` for stdout-like output.\",\n        },\n      },\n      required: [\"code\"],\n    },\n    handler: async (input: unknown) => {\n      const code =\n        input && typeof input === \"object\" && \"code\" in input\n          ? (input as { code: unknown }).code\n          : undefined;\n      if (typeof code !== \"string\") {\n        return JSON.stringify({\n          ok: false,\n          error: { name: \"InvalidInput\", message: \"expected `{ code: string }`\" },\n          log: [],\n          cpuMs: 0,\n          heapBytes: 0,\n        });\n      }\n      const run = await runCode(code);\n      return JSON.stringify(run);\n    },\n  };\n};\n"
+    "/**\n * `codeExecutionTool` — an `AIToolDefinition` that runs model-generated\n * JavaScript inside an `@absolutejs/isolated-jsc` sandbox.\n *\n * Drop into any `tools: {...}` map:\n *\n * ```ts\n * import { codeExecutionTool } from '@absolutejs/ai/tools';\n *\n * const tools = {\n *   run_code: codeExecutionTool({\n *     memoryLimit: 64,\n *     timeout: 1000,\n *     expose: {\n *       lookup_user: async (id) => db.users.findById(id as string),\n *       round: (n) => Math.round(n as number),\n *     },\n *   }),\n * };\n * ```\n *\n * The model emits `{ code: '<JS source>' }` as the tool input; the host\n * runs the code in a fresh context inside a pooled isolate and returns\n * a JSON-stringified result containing:\n *\n *   - `result` — the script's return value (JSON-clonable).\n *   - `log` — array of strings captured via the host-injected `log(...)`.\n *   - `error` — error message + name if the script threw or timed out.\n *   - `cpuMs`, `heapBytes` — per-call telemetry (Phase 3 docs / monitoring).\n *\n * Defaults to the FFI backend on macOS + Linux (with libJSC installed),\n * Worker fallback elsewhere. Per-isolate pool is created once per\n * `codeExecutionTool()` call; pool key is `'default'` (one isolate for\n * all calls). For per-tenant isolation, create one tool instance per\n * tenant.\n *\n * Constraint: when using the FFI backend, **exposed host fns must be\n * synchronous**. Async host fns (returning a Promise that doesn't settle\n * synchronously — `fetch`, `setTimeout`-resolved Promises, real I/O)\n * require `backend: 'worker'` per isolated-jsc 0.3 documented limit.\n * Set `backend: 'worker'` in the tool options if any of your `expose`d\n * fns are async-settling.\n */\n\nimport type { AIToolDefinition } from \"../../../types/ai\";\n\n/** Options for {@link codeExecutionTool}. */\nexport type CodeExecutionToolOptions = {\n  /**\n   * Per-isolate heap memory cap (MB). Default 64. Note that the\n   * sandbox's cold-start baseline differs by backend (FFI ~300 KB vs\n   * Worker ~46 MB), so the practical floor for Worker is ~64 MB.\n   */\n  memoryLimit?: number;\n  /** Wall-clock timeout per `run_code` call (ms). Default 1000. */\n  timeout?: number;\n  /**\n   * isolated-jsc backend. Default `\"auto\"` (FFI when reachable, Worker\n   * otherwise). Set to `\"worker\"` if your `expose`d fns are async-settling\n   * — the FFI backend only supports sync host fns (see Reference docs).\n   */\n  backend?: \"auto\" | \"ffi\" | \"worker\";\n  /**\n   * Host functions the model can call from inside the sandbox. Names\n   * become globals; the model invokes them with `await name(...)`.\n   * The function's description (`.toString()` first line, if a doc\n   * comment) is included in the tool's description so the model knows\n   * what's available.\n   */\n  expose?: Record<string, (...args: unknown[]) => unknown>;\n  /**\n   * Override the tool's description string. Default is auto-generated\n   * from the exposed function list.\n   */\n  description?: string;\n  /**\n   * Pool size cap — max concurrent isolates across all parallel tool\n   * calls. Default 8.\n   */\n  poolSize?: number;\n  /**\n   * Recycle the isolate after N successful runs to bound per-context\n   * heap creep. Default 50.\n   */\n  recycleAfter?: number;\n};\n\ntype Run = {\n  ok: boolean;\n  result?: unknown;\n  log: string[];\n  error?: { name: string; message: string };\n  cpuMs: number;\n  heapBytes: number;\n};\n\nconst defaultDescription = (\n  expose: Record<string, (...args: unknown[]) => unknown> | undefined,\n): string => {\n  const lines = [\n    \"Execute JavaScript code in a sandboxed environment.\",\n    \"\",\n    \"Input: `{ code: string }` — the JS source to evaluate. The script's last\",\n    \"expression is the return value (vm.Script semantics).\",\n    \"\",\n    \"Output: JSON with `{ result, log, error?, cpuMs, heapBytes }`.\",\n    \"\",\n    \"Built-in: `log(...args)` captures stdout-like output into the result.log\",\n    \"array.\",\n  ];\n  const exposed = expose ? Object.keys(expose) : [];\n  if (exposed.length > 0) {\n    lines.push(\"\");\n    lines.push(\"Host functions available in the sandbox:\");\n    for (const name of exposed) {\n      lines.push(`  - ${name}(...)`);\n    }\n  }\n  return lines.join(\"\\n\");\n};\n\nexport const codeExecutionTool = (\n  options: CodeExecutionToolOptions = {},\n): AIToolDefinition => {\n  const memoryLimit = options.memoryLimit ?? 64;\n  const timeout = options.timeout ?? 1000;\n  const backend = options.backend ?? \"auto\";\n  const expose = options.expose ?? {};\n  const poolSize = options.poolSize ?? 8;\n  const recycleAfter = options.recycleAfter ?? 50;\n  const description = options.description ?? defaultDescription(expose);\n\n  // Lazy import isolated-jsc so this module loads without it (consumers\n  // who never call the tool don't pay the dep). The first call resolves\n  // and caches the pool; later calls reuse it.\n  type IsolatedJsc = typeof import(\"@absolutejs/isolated-jsc\");\n  let cachedPool:\n    | { pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>; jsc: IsolatedJsc }\n    | null = null;\n  let cachedPoolPromise: Promise<{\n    pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>;\n    jsc: IsolatedJsc;\n  }> | null = null;\n\n  const loadPool = async () => {\n    if (cachedPool !== null) return cachedPool;\n    if (cachedPoolPromise !== null) return cachedPoolPromise;\n    cachedPoolPromise = (async () => {\n      const jsc = (await import(\"@absolutejs/isolated-jsc\")) as IsolatedJsc;\n      const pool = jsc.createIsolatePool({\n        isolate: { backend, memoryLimit },\n        maxSize: poolSize,\n        recycleAfter,\n      });\n      cachedPool = { pool, jsc };\n      return cachedPool;\n    })();\n    return cachedPoolPromise;\n  };\n\n  const runCode = async (code: string): Promise<Run> => {\n    const log: string[] = [];\n    let cpuMs = 0;\n    let heapBytes = 0;\n    try {\n      const { pool, jsc } = await loadPool();\n      return await pool.run(\"default\", async (isolate) => {\n        const context = await isolate.createContext();\n        try {\n          // Built-in log capture. Sync host fn → works on FFI + Worker.\n          await context.setGlobal(\n            \"log\",\n            new jsc.Reference((...args: unknown[]) => {\n              log.push(\n                args\n                  .map((a) =>\n                    typeof a === \"string\" ? a : JSON.stringify(a),\n                  )\n                  .join(\" \"),\n              );\n            }),\n          );\n          // Exposed host fns. Names become globals; user code calls them\n          // directly (FFI sync path) or with `await` (Worker path).\n          for (const [name, fn] of Object.entries(expose)) {\n            await context.setGlobal(name, new jsc.Reference(fn));\n          }\n          // Wrap the user code so the last expression is what's returned\n          // (matching the conventional script-result semantics).\n          const script = await isolate.compileScript(code);\n          const { result, metrics } = await script.runWithMetrics(\n            context,\n            { timeout },\n          );\n          cpuMs = metrics.cpuMs;\n          heapBytes = metrics.heapBytes;\n          return { ok: true, result, log, cpuMs, heapBytes };\n        } finally {\n          await context.dispose().catch(() => {\n            /* dead context — fine */\n          });\n        }\n      });\n    } catch (error) {\n      const name =\n        error instanceof Error ? error.name : \"Error\";\n      const message =\n        error instanceof Error ? error.message : String(error);\n      return {\n        ok: false,\n        log,\n        error: { name, message },\n        cpuMs,\n        heapBytes,\n      };\n    }\n  };\n\n  return {\n    description,\n    input: {\n      type: \"object\",\n      properties: {\n        code: {\n          type: \"string\",\n          description:\n            \"JavaScript source to evaluate. The script's last expression \" +\n            \"is the return value. Use `log(...)` for stdout-like output.\",\n        },\n      },\n      required: [\"code\"],\n    },\n    handler: async (input: unknown) => {\n      const code =\n        input && typeof input === \"object\" && \"code\" in input\n          ? (input as { code: unknown }).code\n          : undefined;\n      if (typeof code !== \"string\") {\n        return JSON.stringify({\n          ok: false,\n          error: { name: \"InvalidInput\", message: \"expected `{ code: string }`\" },\n          log: [],\n          cpuMs: 0,\n          heapBytes: 0,\n        });\n      }\n      const run = await runCode(code);\n      return JSON.stringify(run);\n    },\n  };\n};\n",
+    "/**\n * `codeModeTool` — Code Mode for AI agents.\n *\n * Instead of exposing N tools to the model and having it call them one\n * at a time (N round-trips per turn, N tool-call tokens, the model has\n * to track intermediate state in context), Code Mode exposes ONE tool:\n * `run_code`. The model sees the typed TypeScript signatures of all\n * underlying tools and emits a single function that chains them.\n *\n * Pattern was popularized by Cloudflare's Dynamic Workers (April 2026\n * blog post: \"100× faster than containers\"). Anthropic's programmatic\n * tool calling is the same idea — execution pauses on a sub-tool call,\n * the API yields a tool_use, you return a result, execution resumes.\n * Both vendors report ~80% token reduction on multi-tool turns.\n *\n * ```ts\n * import { codeModeTool } from '@absolutejs/ai/tools';\n *\n * const tools = {\n *   run_code: codeModeTool({\n *     timeout: 5000,\n *     tools: {\n *       search_products: {\n *         description: 'Full-text search the product catalogue.',\n *         tsSignature: '(query: string) => Promise<Product[]>',\n *         handler: async (q) => db.products.search(q as string),\n *       },\n *       get_product: {\n *         description: 'Fetch one product by id.',\n *         tsSignature: '(id: string) => Promise<Product | null>',\n *         handler: async (id) => db.products.findById(id as string),\n *       },\n *     },\n *     types: `\n *       type Product = { id: string; name: string; price: number };\n *     `,\n *   }),\n * };\n * ```\n *\n * The model emits a single function:\n *\n * ```js\n * const items = await search_products('hat');\n * const cheapest = items.sort((a, b) => a.price - b.price)[0];\n * const detail = await get_product(cheapest.id);\n * return { name: detail.name, price: detail.price };\n * ```\n *\n * One sandbox eval. Two host-fn calls. One returned value. The model's\n * context only ever sees the final return — intermediate tool results\n * don't enter the conversation window, so multi-step workflows are\n * dramatically cheaper.\n *\n * Each underlying tool's `handler` runs on the HOST side (not in the\n * sandbox). Async host fns work on both FFI (via the 0.4 pump) and\n * Worker backends since isolated-jsc 0.4+. Errors thrown by host\n * handlers propagate into the sandbox as JS Errors the model can\n * catch and recover from.\n */\n\nimport type { AIToolDefinition } from \"../../../types/ai\";\n\n/**\n * One callable surfaced to the sandbox. The `tsSignature` shows up in\n * the model-visible description; `handler` runs on the host when the\n * sandbox calls it.\n */\nexport type CodeModeHostTool = {\n  /** One-line human description of what this tool does. */\n  description: string;\n  /** TypeScript signature shown to the model. Example:\n   * `'(query: string, options?: { limit?: number }) => Promise<Item[]>'`.\n   * The model writes JS against this signature; we don't enforce it at\n   * runtime — type-check is the model's responsibility. */\n  tsSignature: string;\n  /** Host implementation. Receives positional args as the model passed\n   * them. Return value is structure-cloned back into the sandbox. */\n  handler: (...args: unknown[]) => unknown;\n};\n\n/** Options for {@link codeModeTool}. */\nexport type CodeModeToolOptions = {\n  /** Map of host-tool name → {@link CodeModeHostTool}. */\n  tools: Record<string, CodeModeHostTool>;\n  /**\n   * Optional shared TypeScript declarations stitched into the prompt\n   * (type aliases, interfaces, etc.) so signatures can reference them.\n   * Use raw TS source; no parsing happens host-side.\n   */\n  types?: string;\n  /**\n   * Per-isolate heap memory cap (MB). Default 64. As with the regular\n   * code-execution tool, FFI's cold heap is much smaller than Worker's,\n   * but per-call retention scales similarly.\n   */\n  memoryLimit?: number;\n  /** Wall-clock timeout per `run_code` call (ms). Default 5000. */\n  timeout?: number;\n  /**\n   * isolated-jsc backend. Defaults to `'auto'`. Since isolated-jsc 0.4\n   * both backends support async host fns, so the choice is purely\n   * about cold spawn (FFI wins ~6×) vs Web APIs availability (Worker\n   * has `URL` / `TextEncoder` / `WebSocket`; FFI does not).\n   */\n  backend?: \"auto\" | \"ffi\" | \"worker\";\n  /**\n   * Override the auto-generated description. By default we emit the\n   * model-facing prompt: a short instruction header + the host fn\n   * signatures + any shared `types`.\n   */\n  description?: string;\n  /** Pool size cap. Default 8. */\n  poolSize?: number;\n  /** Recycle the isolate after N successful runs. Default 50. */\n  recycleAfter?: number;\n};\n\ntype RunResult = {\n  ok: boolean;\n  result?: unknown;\n  log: string[];\n  toolCalls: Array<{\n    name: string;\n    args: unknown[];\n    durationMs: number;\n    ok: boolean;\n    error?: string;\n  }>;\n  error?: { name: string; message: string };\n  cpuMs: number;\n  heapBytes: number;\n};\n\nconst buildDescription = (\n  tools: Record<string, CodeModeHostTool>,\n  types: string | undefined,\n): string => {\n  const lines: string[] = [\n    \"Execute JavaScript that calls one or more host tools, returning a\",\n    \"single value. Prefer this over calling individual tools when you'd\",\n    \"otherwise need multiple sequential tool calls — one Code Mode call\",\n    \"replaces N tool calls plus the intermediate context.\",\n    \"\",\n    \"Input: `{ code: string }`. The code is a function BODY (not a full\",\n    \"function). It can use `await`, `const`/`let`, control flow, etc.\",\n    \"Whatever you `return` becomes the tool output.\",\n    \"\",\n    \"Built-in: `log(...args)` captures messages for debugging. Logs are\",\n    \"returned alongside the result; they don't enter the model context.\",\n    \"\",\n    \"Available host functions (calling these from your code is what runs\",\n    \"the real work; everything else is plain JS):\",\n    \"\",\n  ];\n  for (const [name, tool] of Object.entries(tools)) {\n    lines.push(`// ${tool.description}`);\n    lines.push(`declare const ${name}: ${tool.tsSignature};`);\n    lines.push(\"\");\n  }\n  if (types !== undefined && types.trim().length > 0) {\n    lines.push(\"// Shared types referenced by the signatures above:\");\n    lines.push(types.trim());\n    lines.push(\"\");\n  }\n  lines.push(\"Example:\");\n  lines.push(\"```js\");\n  lines.push(\"// Get the cheapest matching product and its full record.\");\n  const firstTool = Object.keys(tools)[0];\n  if (firstTool !== undefined) {\n    lines.push(`const items = await ${firstTool}('search query');`);\n    lines.push(\n      \"const cheapest = items.sort((a, b) => a.price - b.price)[0];\",\n    );\n    lines.push(\"return cheapest;\");\n  } else {\n    lines.push(\"return 42;\");\n  }\n  lines.push(\"```\");\n  lines.push(\"\");\n  lines.push(\"Output: JSON with `{ result, log, toolCalls, cpuMs, heapBytes }`.\");\n  return lines.join(\"\\n\");\n};\n\nexport const codeModeTool = (\n  options: CodeModeToolOptions,\n): AIToolDefinition => {\n  const memoryLimit = options.memoryLimit ?? 64;\n  const timeout = options.timeout ?? 5000;\n  const backend = options.backend ?? \"auto\";\n  const poolSize = options.poolSize ?? 8;\n  const recycleAfter = options.recycleAfter ?? 50;\n  const tools = options.tools;\n  const description =\n    options.description ?? buildDescription(tools, options.types);\n\n  type IsolatedJsc = typeof import(\"@absolutejs/isolated-jsc\");\n  let cachedPool:\n    | { pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>; jsc: IsolatedJsc }\n    | null = null;\n  let cachedPoolPromise: Promise<{\n    pool: ReturnType<IsolatedJsc[\"createIsolatePool\"]>;\n    jsc: IsolatedJsc;\n  }> | null = null;\n\n  const loadPool = async () => {\n    if (cachedPool !== null) return cachedPool;\n    if (cachedPoolPromise !== null) return cachedPoolPromise;\n    cachedPoolPromise = (async () => {\n      const jsc = (await import(\"@absolutejs/isolated-jsc\")) as IsolatedJsc;\n      const pool = jsc.createIsolatePool({\n        isolate: { backend, memoryLimit },\n        maxSize: poolSize,\n        recycleAfter,\n      });\n      cachedPool = { pool, jsc };\n      return cachedPool;\n    })();\n    return cachedPoolPromise;\n  };\n\n  const runCode = async (code: string): Promise<RunResult> => {\n    const log: string[] = [];\n    const toolCalls: RunResult[\"toolCalls\"] = [];\n    let cpuMs = 0;\n    let heapBytes = 0;\n    try {\n      const { pool, jsc } = await loadPool();\n      return await pool.run(\"default\", async (isolate) => {\n        const context = await isolate.createContext();\n        try {\n          // Built-in log capture.\n          await context.setGlobal(\n            \"log\",\n            new jsc.Reference((...args: unknown[]) => {\n              log.push(\n                args\n                  .map((a) =>\n                    typeof a === \"string\" ? a : JSON.stringify(a),\n                  )\n                  .join(\" \"),\n              );\n            }),\n          );\n\n          // Bind each host tool as a global Reference. Wrap so we\n          // capture per-call telemetry (durationMs, error). Async\n          // host fns work on both FFI (0.4+) and Worker backends.\n          for (const [name, tool] of Object.entries(tools)) {\n            await context.setGlobal(\n              name,\n              new jsc.Reference(((...args: unknown[]) => {\n                const startedAt = performance.now();\n                const recordSuccess = () => {\n                  toolCalls.push({\n                    args,\n                    durationMs: performance.now() - startedAt,\n                    name,\n                    ok: true,\n                  });\n                };\n                const recordError = (err: unknown) => {\n                  toolCalls.push({\n                    args,\n                    durationMs: performance.now() - startedAt,\n                    error: err instanceof Error ? err.message : String(err),\n                    name,\n                    ok: false,\n                  });\n                };\n                let outcome: unknown;\n                try {\n                  outcome = tool.handler(...args);\n                } catch (err) {\n                  recordError(err);\n                  throw err;\n                }\n                if (\n                  outcome !== null &&\n                  typeof outcome === \"object\" &&\n                  \"then\" in outcome &&\n                  typeof (outcome as { then: unknown }).then === \"function\"\n                ) {\n                  return (outcome as Promise<unknown>).then(\n                    (v) => {\n                      recordSuccess();\n                      return v;\n                    },\n                    (err) => {\n                      recordError(err);\n                      throw err;\n                    },\n                  );\n                }\n                recordSuccess();\n                return outcome;\n              }) as (...args: unknown[]) => unknown),\n            );\n          }\n\n          // Wrap the model's code as an async function body. Whatever\n          // it `return`s becomes the tool output.\n          const wrapped = `(async () => { ${code}\\n})()`;\n          const script = await isolate.compileScript(wrapped);\n          const { result, metrics } = await script.runWithMetrics(context, {\n            timeout,\n          });\n          cpuMs = metrics.cpuMs;\n          heapBytes = metrics.heapBytes;\n          return { cpuMs, heapBytes, log, ok: true, result, toolCalls };\n        } finally {\n          await context.dispose().catch(() => {\n            /* ok */\n          });\n        }\n      });\n    } catch (error) {\n      const name = error instanceof Error ? error.name : \"Error\";\n      const message =\n        error instanceof Error ? error.message : String(error);\n      return {\n        cpuMs,\n        error: { message, name },\n        heapBytes,\n        log,\n        ok: false,\n        toolCalls,\n      };\n    }\n  };\n\n  return {\n    description,\n    handler: async (input: unknown) => {\n      const code =\n        input !== null &&\n        typeof input === \"object\" &&\n        \"code\" in input\n          ? (input as { code: unknown }).code\n          : undefined;\n      if (typeof code !== \"string\") {\n        return JSON.stringify({\n          cpuMs: 0,\n          error: {\n            message: \"expected `{ code: string }`\",\n            name: \"InvalidInput\",\n          },\n          heapBytes: 0,\n          log: [],\n          ok: false,\n          toolCalls: [],\n        });\n      }\n      const run = await runCode(code);\n      return JSON.stringify(run);\n    },\n    input: {\n      properties: {\n        code: {\n          description:\n            \"JavaScript function-body source. Use `await` to call host \" +\n            \"tools; `return` the final value. Multiple tool calls in one \" +\n            \"block are encouraged — that's the whole point of Code Mode.\",\n          type: \"string\",\n        },\n      },\n      required: [\"code\"],\n      type: \"object\",\n    },\n  };\n};\n"
   ],
-  "mappings": ";;;;AAgGA,IAAM,qBAAqB,CACzB,WACW;AAAA,EACX,MAAM,QAAQ;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,MAAM,UAAU,SAAS,OAAO,KAAK,MAAM,IAAI,CAAC;AAAA,EAChD,IAAI,QAAQ,SAAS,GAAG;AAAA,IACtB,MAAM,KAAK,EAAE;AAAA,IACb,MAAM,KAAK,0CAA0C;AAAA,IACrD,WAAW,QAAQ,SAAS;AAAA,MAC1B,MAAM,KAAK,OAAO,WAAW;AAAA,IAC/B;AAAA,EACF;AAAA,EACA,OAAO,MAAM,KAAK;AAAA,CAAI;AAAA;AAGjB,IAAM,oBAAoB,CAC/B,UAAoC,CAAC,MAChB;AAAA,EACrB,MAAM,cAAc,QAAQ,eAAe;AAAA,EAC3C,MAAM,UAAU,QAAQ,WAAW;AAAA,EACnC,MAAM,UAAU,QAAQ,WAAW;AAAA,EACnC,MAAM,SAAS,QAAQ,UAAU,CAAC;AAAA,EAClC,MAAM,WAAW,QAAQ,YAAY;AAAA,EACrC,MAAM,eAAe,QAAQ,gBAAgB;AAAA,EAC7C,MAAM,cAAc,QAAQ,eAAe,mBAAmB,MAAM;AAAA,EAMpE,IAAI,aAEO;AAAA,EACX,IAAI,oBAGQ;AAAA,EAEZ,MAAM,WAAW,YAAY;AAAA,IAC3B,IAAI,eAAe;AAAA,MAAM,OAAO;AAAA,IAChC,IAAI,sBAAsB;AAAA,MAAM,OAAO;AAAA,IACvC,qBAAqB,YAAY;AAAA,MAC/B,MAAM,MAAO,MAAa;AAAA,MAC1B,MAAM,OAAO,IAAI,kBAAkB;AAAA,QACjC,SAAS,EAAE,SAAS,YAAY;AAAA,QAChC,SAAS;AAAA,QACT;AAAA,MACF,CAAC;AAAA,MACD,aAAa,EAAE,MAAM,IAAI;AAAA,MACzB,OAAO;AAAA,OACN;AAAA,IACH,OAAO;AAAA;AAAA,EAGT,MAAM,UAAU,OAAO,SAA+B;AAAA,IACpD,MAAM,MAAgB,CAAC;AAAA,IACvB,IAAI,QAAQ;AAAA,IACZ,IAAI,YAAY;AAAA,IAChB,IAAI;AAAA,MACF,QAAQ,MAAM,QAAQ,MAAM,SAAS;AAAA,MACrC,OAAO,MAAM,KAAK,IAAI,WAAW,OAAO,YAAY;AAAA,QAClD,MAAM,UAAU,MAAM,QAAQ,cAAc;AAAA,QAC5C,IAAI;AAAA,UAEF,MAAM,QAAQ,UACZ,OACA,IAAI,IAAI,UAAU,IAAI,SAAoB;AAAA,YACxC,IAAI,KACF,KACG,IAAI,CAAC,MACJ,OAAO,MAAM,WAAW,IAAI,KAAK,UAAU,CAAC,CAC9C,EACC,KAAK,GAAG,CACb;AAAA,WACD,CACH;AAAA,UAGA,YAAY,MAAM,OAAO,OAAO,QAAQ,MAAM,GAAG;AAAA,YAC/C,MAAM,QAAQ,UAAU,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;AAAA,UACrD;AAAA,UAGA,MAAM,SAAS,MAAM,QAAQ,cAAc,IAAI;AAAA,UAC/C,QAAQ,QAAQ,YAAY,MAAM,OAAO,eACvC,SACA,EAAE,QAAQ,CACZ;AAAA,UACA,QAAQ,QAAQ;AAAA,UAChB,YAAY,QAAQ;AAAA,UACpB,OAAO,EAAE,IAAI,MAAM,QAAQ,KAAK,OAAO,UAAU;AAAA,kBACjD;AAAA,UACA,MAAM,QAAQ,QAAQ,EAAE,MAAM,MAAM,EAEnC;AAAA;AAAA,OAEJ;AAAA,MACD,OAAO,OAAO;AAAA,MACd,MAAM,OACJ,iBAAiB,QAAQ,MAAM,OAAO;AAAA,MACxC,MAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,MACvD,OAAO;AAAA,QACL,IAAI;AAAA,QACJ;AAAA,QACA,OAAO,EAAE,MAAM,QAAQ;AAAA,QACvB;AAAA,QACA;AAAA,MACF;AAAA;AAAA;AAAA,EAIJ,OAAO;AAAA,IACL;AAAA,IACA,OAAO;AAAA,MACL,MAAM;AAAA,MACN,YAAY;AAAA,QACV,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,aACE;AAAA,QAEJ;AAAA,MACF;AAAA,MACA,UAAU,CAAC,MAAM;AAAA,IACnB;AAAA,IACA,SAAS,OAAO,UAAmB;AAAA,MACjC,MAAM,OACJ,SAAS,OAAO,UAAU,YAAY,UAAU,QAC3C,MAA4B,OAC7B;AAAA,MACN,IAAI,OAAO,SAAS,UAAU;AAAA,QAC5B,OAAO,KAAK,UAAU;AAAA,UACpB,IAAI;AAAA,UACJ,OAAO,EAAE,MAAM,gBAAgB,SAAS,8BAA8B;AAAA,UACtE,KAAK,CAAC;AAAA,UACN,OAAO;AAAA,UACP,WAAW;AAAA,QACb,CAAC;AAAA,MACH;AAAA,MACA,MAAM,MAAM,MAAM,QAAQ,IAAI;AAAA,MAC9B,OAAO,KAAK,UAAU,GAAG;AAAA;AAAA,EAE7B;AAAA;",
-  "debugId": "3DCC3269A76159BC64756E2164756E21",
+  "mappings": "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",
+  "debugId": "05A8D1541DB1A68E64756E2164756E21",
   "names": []
 }

package/dist/src/ai/tools/codeMode.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `codeModeTool` — Code Mode for AI agents.
+ *
+ * Instead of exposing N tools to the model and having it call them one
+ * at a time (N round-trips per turn, N tool-call tokens, the model has
+ * to track intermediate state in context), Code Mode exposes ONE tool:
+ * `run_code`. The model sees the typed TypeScript signatures of all
+ * underlying tools and emits a single function that chains them.
+ *
+ * Pattern was popularized by Cloudflare's Dynamic Workers (April 2026
+ * blog post: "100× faster than containers"). Anthropic's programmatic
+ * tool calling is the same idea — execution pauses on a sub-tool call,
+ * the API yields a tool_use, you return a result, execution resumes.
+ * Both vendors report ~80% token reduction on multi-tool turns.
+ *
+ * ```ts
+ * import { codeModeTool } from '@absolutejs/ai/tools';
+ *
+ * const tools = {
+ *   run_code: codeModeTool({
+ *     timeout: 5000,
+ *     tools: {
+ *       search_products: {
+ *         description: 'Full-text search the product catalogue.',
+ *         tsSignature: '(query: string) => Promise<Product[]>',
+ *         handler: async (q) => db.products.search(q as string),
+ *       },
+ *       get_product: {
+ *         description: 'Fetch one product by id.',
+ *         tsSignature: '(id: string) => Promise<Product | null>',
+ *         handler: async (id) => db.products.findById(id as string),
+ *       },
+ *     },
+ *     types: `
+ *       type Product = { id: string; name: string; price: number };
+ *     `,
+ *   }),
+ * };
+ * ```
+ *
+ * The model emits a single function:
+ *
+ * ```js
+ * const items = await search_products('hat');
+ * const cheapest = items.sort((a, b) => a.price - b.price)[0];
+ * const detail = await get_product(cheapest.id);
+ * return { name: detail.name, price: detail.price };
+ * ```
+ *
+ * One sandbox eval. Two host-fn calls. One returned value. The model's
+ * context only ever sees the final return — intermediate tool results
+ * don't enter the conversation window, so multi-step workflows are
+ * dramatically cheaper.
+ *
+ * Each underlying tool's `handler` runs on the HOST side (not in the
+ * sandbox). Async host fns work on both FFI (via the 0.4 pump) and
+ * Worker backends since isolated-jsc 0.4+. Errors thrown by host
+ * handlers propagate into the sandbox as JS Errors the model can
+ * catch and recover from.
+ */
+import type { AIToolDefinition } from "../../../types/ai";
+/**
+ * One callable surfaced to the sandbox. The `tsSignature` shows up in
+ * the model-visible description; `handler` runs on the host when the
+ * sandbox calls it.
+ */
+export type CodeModeHostTool = {
+    /** One-line human description of what this tool does. */
+    description: string;
+    /** TypeScript signature shown to the model. Example:
+     * `'(query: string, options?: { limit?: number }) => Promise<Item[]>'`.
+     * The model writes JS against this signature; we don't enforce it at
+     * runtime — type-check is the model's responsibility. */
+    tsSignature: string;
+    /** Host implementation. Receives positional args as the model passed
+     * them. Return value is structure-cloned back into the sandbox. */
+    handler: (...args: unknown[]) => unknown;
+};
+/** Options for {@link codeModeTool}. */
+export type CodeModeToolOptions = {
+    /** Map of host-tool name → {@link CodeModeHostTool}. */
+    tools: Record<string, CodeModeHostTool>;
+    /**
+     * Optional shared TypeScript declarations stitched into the prompt
+     * (type aliases, interfaces, etc.) so signatures can reference them.
+     * Use raw TS source; no parsing happens host-side.
+     */
+    types?: string;
+    /**
+     * Per-isolate heap memory cap (MB). Default 64. As with the regular
+     * code-execution tool, FFI's cold heap is much smaller than Worker's,
+     * but per-call retention scales similarly.
+     */
+    memoryLimit?: number;
+    /** Wall-clock timeout per `run_code` call (ms). Default 5000. */
+    timeout?: number;
+    /**
+     * isolated-jsc backend. Defaults to `'auto'`. Since isolated-jsc 0.4
+     * both backends support async host fns, so the choice is purely
+     * about cold spawn (FFI wins ~6×) vs Web APIs availability (Worker
+     * has `URL` / `TextEncoder` / `WebSocket`; FFI does not).
+     */
+    backend?: "auto" | "ffi" | "worker";
+    /**
+     * Override the auto-generated description. By default we emit the
+     * model-facing prompt: a short instruction header + the host fn
+     * signatures + any shared `types`.
+     */
+    description?: string;
+    /** Pool size cap. Default 8. */
+    poolSize?: number;
+    /** Recycle the isolate after N successful runs. Default 50. */
+    recycleAfter?: number;
+};
+export declare const codeModeTool: (options: CodeModeToolOptions) => AIToolDefinition;

package/dist/src/ai/tools/index.d.ts

@@ -5,5 +5,9 @@
  * - {@link codeExecutionTool} — execute model-generated JavaScript in a
  *   sandboxed `@absolutejs/isolated-jsc` isolate. Optional peer; install
  *   `@absolutejs/isolated-jsc` to use it.
+ * - {@link codeModeTool} — "Code Mode" wrapper for N host tools: model
+ *   sees typed TS signatures, emits one function chaining several
+ *   tool calls, ~80% token reduction vs N separate tool calls.
  */
 export { codeExecutionTool, type CodeExecutionToolOptions, } from "./codeExecution";
+export { type CodeModeHostTool, codeModeTool, type CodeModeToolOptions, } from "./codeMode";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/ai",
-	"version": "0.0.11",
+	"version": "0.0.12",
 	"description": "AI runtime, providers, streaming, and framework adapters extracted from AbsoluteJS",
 	"license": "BSL-1.1",
 	"type": "module",
@@ -73,7 +73,7 @@
 		"@absolutejs/sync": "0.7.0"
 	},
 	"peerDependencies": {
-		"@absolutejs/isolated-jsc": ">= 0.3.0",
+		"@absolutejs/isolated-jsc": ">= 0.4.0",
 		"@angular/core": "^21.0.0",
 		"elysia": "^1.4.18",
 		"react": "^19.2.0",
@@ -99,7 +99,7 @@
 	},
 	"devDependencies": {
 		"@absolutejs/absolute": "^0.19.0-beta.1051",
-		"@absolutejs/isolated-jsc": "^0.3.0",
+		"@absolutejs/isolated-jsc": "0.6.0",
 		"@angular/core": "^21.0.0",
 		"@eslint/js": "^10.0.1",
 		"@types/bun": "1.3.9",