@tanstack/ai-code-mode 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# @tanstack/ai-code-mode
+
+Code Mode for TanStack AI — let LLMs write and execute TypeScript in secure sandboxes with typed tool access.
+
+## Overview
+
+Code Mode gives your AI agent an `execute_typescript` tool. Instead of one tool call per action, the LLM writes a small TypeScript program that orchestrates multiple tool calls with loops, conditionals, `Promise.all`, and data transformations — all running in an isolated sandbox.
+
+## Installation
+
+```bash
+pnpm add @tanstack/ai-code-mode
+```
+
+You also need an isolate driver:
+
+```bash
+# Node.js (fastest, uses V8 isolates via isolated-vm)
+pnpm add @tanstack/ai-isolate-node
+
+# QuickJS WASM (browser-compatible, no native deps)
+pnpm add @tanstack/ai-isolate-quickjs
+
+# Cloudflare Workers (edge execution)
+pnpm add @tanstack/ai-isolate-cloudflare
+```
+
+## Quick Start
+
+```typescript
+import { chat, toolDefinition } from '@tanstack/ai'
+import { createCodeMode } from '@tanstack/ai-code-mode'
+import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
+import { z } from 'zod'
+
+// Define tools that the LLM can call from inside the sandbox
+const weatherTool = toolDefinition({
+  name: 'fetchWeather',
+  description: 'Get weather for a city',
+  inputSchema: z.object({ location: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), condition: z.string() }),
+}).server(async ({ location }) => {
+  // Your implementation
+  return { temperature: 72, condition: 'sunny' }
+})
+
+// Create the execute_typescript tool and system prompt
+const { tool, systemPrompt } = createCodeMode({
+  driver: createNodeIsolateDriver(),
+  tools: [weatherTool],
+})
+
+const result = await chat({
+  adapter: yourAdapter,
+  model: 'gpt-4o',
+  systemPrompts: ['You are a helpful assistant.', systemPrompt],
+  tools: [tool],
+  messages: [
+    { role: 'user', content: 'Compare weather in Tokyo, Paris, and NYC' },
+  ],
+})
+```
+
+The LLM will generate code like:
+
+```typescript
+const cities = ['Tokyo', 'Paris', 'NYC']
+const results = await Promise.all(
+  cities.map((city) => external_fetchWeather({ location: city })),
+)
+const warmest = results.reduce((prev, curr) =>
+  curr.temperature > prev.temperature ? curr : prev,
+)
+return { warmestCity: warmest.location, temperature: warmest.temperature }
+```
+
+## API Reference
+
+### `createCodeMode(config)`
+
+Creates both the `execute_typescript` tool and its matching system prompt. This is the recommended entry point.
+
+**Config:**
+
+- `driver` — An `IsolateDriver` (Node, QuickJS, or Cloudflare)
+- `tools` — Array of `ServerTool` or `ToolDefinition` instances. Exposed as `external_*` functions in the sandbox
+- `timeout` — Execution timeout in ms (default: 30000)
+- `memoryLimit` — Memory limit in MB (default: 128, supported by Node and QuickJS drivers)
+- `getSkillBindings` — Optional async function returning dynamic bindings
+
+### `createCodeModeTool(config)` / `createCodeModeSystemPrompt(config)`
+
+Lower-level functions if you need only the tool or only the prompt. `createCodeMode` calls both internally.
+
+### Advanced
+
+These utilities are used internally and exported for custom pipelines:
+
+- **`stripTypeScript(code)`** — Strips TypeScript syntax using esbuild.
+- **`toolsToBindings(tools, prefix?)`** — Converts tools to `ToolBinding` records for sandbox injection.
+- **`generateTypeStubs(bindings, options?)`** — Generates TypeScript type declarations from tool bindings.
+
+## Driver Selection Guide
+
+| Driver                            | Best For                                     | Native Deps         | Browser | Memory Limit |
+| --------------------------------- | -------------------------------------------- | ------------------- | ------- | ------------ |
+| `@tanstack/ai-isolate-node`       | Server-side Node.js apps                     | Yes (`isolated-vm`) | No      | Yes          |
+| `@tanstack/ai-isolate-quickjs`    | Browser, edge, or no-native-dep environments | No (WASM)           | Yes     | Yes          |
+| `@tanstack/ai-isolate-cloudflare` | Cloudflare Workers deployments               | No                  | N/A     | N/A          |
+
+## Custom Events
+
+Code Mode emits custom events during execution that you can observe via the TanStack AI event system:
+
+| Event                         | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `code_mode:execution_started` | Emitted when code execution begins                  |
+| `code_mode:console`           | Emitted for each `console.log/error/warn/info` call |
+| `code_mode:external_call`     | Emitted before each `external_*` function call      |
+| `code_mode:external_result`   | Emitted after a successful `external_*` call        |
+| `code_mode:external_error`    | Emitted when an `external_*` call fails             |
+
+## Models eval (development)
+
+The benchmark lives in a **separate workspace package** so `@tanstack/ai-code-mode` does not depend on `@tanstack/ai-isolate-node` (avoids an Nx build cycle). See `models-eval/package.json` (`@tanstack/ai-code-mode-models-eval`).
+
+1. `packages/typescript/ai-code-mode/models-eval/pull-models.sh` — pull recommended Ollama models
+2. `pnpm --filter @tanstack/ai-code-mode-models-eval eval:capture` — run models and capture raw outputs/telemetry only (no judge LLM call)
+3. `pnpm --filter @tanstack/ai-code-mode-models-eval eval:judge` — judge latest captured session from logs (no model rerun)
+4. `pnpm --filter @tanstack/ai-code-mode-models-eval eval` — single-pass run+judge (legacy convenience mode)
+5. `pnpm --filter @tanstack/ai-code-mode-models-eval eval -- --ollama-only` — only Ollama models from `eval-config.ts`
+6. `pnpm --filter @tanstack/ai-code-mode-models-eval eval -- --ollama-only --models qwen3-coder` — one or more model ids (comma-separated)
+
+Judge-phase flags:
+
+- `--judge-latest` judge latest captured session
+- `--rejudge` re-run judging even if logs already contain judge fields
+
+The default list omits some small Ollama models that rarely complete code-mode successfully (see comments in `eval-config.ts`). You can still benchmark them with `--models granite4:3b` etc. if pulled locally.
+
+### Model comparison metrics
+
+The models eval now tracks seven decision-oriented metrics plus an overall rating:
+
+- `accuracy` (1-10): numerical/factual correctness vs gold report
+- `comprehensiveness` (1-10): whether the response covers everything requested by the user query
+- `typescriptQuality` (1-10): quality/readability/type-safety of generated TypeScript
+- `codeModeEfficiency` (1-10): how efficiently the model uses code-mode/tooling to reach the answer
+- `speedTier` (1-5): relative wall-clock speed against peers in the same category (`local` or `cloud`)
+- `tokenEfficiencyTier` (1-5): relative token efficiency against peers in the same category
+- `stabilityTier` (1-5): success consistency over the latest 5 logged runs for that model
+- `stars` (1-3): weighted rollup score across all metrics
+
+Raw run telemetry also includes compile/runtime failures, redundant schema checks, total tool calls, TTFT, token totals, stability sample size/rate, and per-model logs.
+
+### Methodology
+
+Canonical output is written to `packages/typescript/ai-code-mode/models-eval/results.json` after each capture or judge run.
+
+- Benchmark: single code-mode benchmark prompt over the in-memory `customers` / `products` / `purchases` dataset
+- Primary quality scores (judge): `accuracy`, `comprehensiveness`, `typescriptQuality`, `codeModeEfficiency`
+- Computed comparative scores: `speedTier`, `tokenEfficiencyTier`, `stabilityTier`
+- Stability definition: a run is "stable" if it has no top-level run error, produces a non-empty candidate report, and has at least one successful `execute_typescript` call
+- Star rollup weights:
+  - accuracy: 25%
+  - comprehensiveness: 15%
+  - typescriptQuality: 15%
+  - codeModeEfficiency (with compile/runtime failure penalty): 10%
+  - speedTier: 10%
+  - tokenEfficiencyTier: 10%
+  - stabilityTier: 15%
+
+### Model comparison table
+
+The table below is transcribed from canonical `models-eval/results.json` (session `2026-03-26T15:38:44.006Z`).
+
+| Provider  | Model                         | Category | Stars | Accuracy | Comprehensiveness | TypeScript | Code-Mode | Speed Tier | Token Tier | Stability Tier |
+| --------- | ----------------------------- | -------- | ----- | -------- | ----------------- | ---------- | --------- | ---------- | ---------- | -------------- |
+| Ollama    | `gpt-oss:20b`                 | local    | ★★★   | 10       | 8                 | 5          | 5         | 5          | 5          | 5              |
+| Ollama    | `nemotron-cascade-2`          | local    | ★★☆   | 3        | 5                 | 6          | 5         | 1          | 5          | 5              |
+| Anthropic | `claude-haiku-4-5`            | cloud    | ★★★   | 10       | 10                | 6          | 7         | 3          | 2          | 5              |
+| OpenAI    | `gpt-4o-mini`                 | cloud    | ★★★   | 10       | 8                 | 7          | 9         | 3          | 1          | 5              |
+| Gemini    | `gemini-2.5-flash`            | cloud    | ★★★   | 10       | 8                 | 7          | 10        | 4          | 2          | 5              |
+| xAI       | `grok-4-1-fast-non-reasoning` | cloud    | ★★★   | 10       | 8                 | 6          | 10        | 4          | 5          | 5              |
+| Groq      | `llama-3.3-70b-versatile`     | cloud    | ★★★   | 10       | 7                 | 6          | 9         | 5          | 3          | 4              |
+| Groq      | `qwen/qwen3-32b`              | cloud    | ★★☆   | 10       | 8                 | 5          | 4         | 1          | 2          | 5              |
+
+Suggested interpretation:
+
+- **Local-first**: favor `stars >= 2` with high speed tier.
+- **Cloud-first quality**: favor high `accuracy` + `typescriptQuality`, then compare stars.
+- **Cost-sensitive**: prioritize `tokenEfficiencyTier` and `speedTier` together.
+
+## License
+
+MIT

package/dist/esm/agent-store.d.ts

@@ -0,0 +1,21 @@
+export interface AgentSession {
+    name: string;
+    systemPrompt: string;
+    memory: Record<string, unknown>;
+    createdAt: number;
+    lastUsedAt: number;
+}
+export interface AgentStore {
+    get: (name: string) => Promise<AgentSession | null>;
+    set: (name: string, session: AgentSession) => Promise<void>;
+    delete: (name: string) => Promise<void>;
+    list: () => Promise<Array<string>>;
+}
+export declare class InMemoryAgentStore implements AgentStore {
+    private sessions;
+    get(name: string): Promise<AgentSession | null>;
+    set(name: string, session: AgentSession): Promise<void>;
+    delete(name: string): Promise<void>;
+    list(): Promise<Array<string>>;
+}
+export declare function generateAgentName(): string;

package/dist/esm/agent-store.js

@@ -0,0 +1,31 @@
+class InMemoryAgentStore {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  get(name) {
+    return Promise.resolve(this.sessions.get(name) ?? null);
+  }
+  set(name, session) {
+    this.sessions.set(name, session);
+    return Promise.resolve();
+  }
+  delete(name) {
+    this.sessions.delete(name);
+    return Promise.resolve();
+  }
+  list() {
+    return Promise.resolve(Array.from(this.sessions.keys()));
+  }
+}
+function generateAgentName() {
+  const hex = Array.from(
+    { length: 8 },
+    () => Math.floor(Math.random() * 16).toString(16)
+  ).join("");
+  return `agent_${hex}`;
+}
+export {
+  InMemoryAgentStore,
+  generateAgentName
+};
+//# sourceMappingURL=agent-store.js.map

package/dist/esm/agent-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-store.js","sources":["../../src/agent-store.ts"],"sourcesContent":["export interface AgentSession {\n  name: string\n  systemPrompt: string\n  memory: Record<string, unknown>\n  createdAt: number\n  lastUsedAt: number\n}\n\nexport interface AgentStore {\n  get: (name: string) => Promise<AgentSession | null>\n  set: (name: string, session: AgentSession) => Promise<void>\n  delete: (name: string) => Promise<void>\n  list: () => Promise<Array<string>>\n}\n\nexport class InMemoryAgentStore implements AgentStore {\n  private sessions = new Map<string, AgentSession>()\n\n  get(name: string): Promise<AgentSession | null> {\n    return Promise.resolve(this.sessions.get(name) ?? null)\n  }\n\n  set(name: string, session: AgentSession): Promise<void> {\n    this.sessions.set(name, session)\n    return Promise.resolve()\n  }\n\n  delete(name: string): Promise<void> {\n    this.sessions.delete(name)\n    return Promise.resolve()\n  }\n\n  list(): Promise<Array<string>> {\n    return Promise.resolve(Array.from(this.sessions.keys()))\n  }\n}\n\nexport function generateAgentName(): string {\n  const hex = Array.from({ length: 8 }, () =>\n    Math.floor(Math.random() * 16).toString(16),\n  ).join('')\n  return `agent_${hex}`\n}\n"],"names":[],"mappings":"AAeO,MAAM,mBAAyC;AAAA,EAA/C,cAAA;AACL,SAAQ,+BAAe,IAAA;AAAA,EAA0B;AAAA,EAEjD,IAAI,MAA4C;AAC9C,WAAO,QAAQ,QAAQ,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;AAAA,EACxD;AAAA,EAEA,IAAI,MAAc,SAAsC;AACtD,SAAK,SAAS,IAAI,MAAM,OAAO;AAC/B,WAAO,QAAQ,QAAA;AAAA,EACjB;AAAA,EAEA,OAAO,MAA6B;AAClC,SAAK,SAAS,OAAO,IAAI;AACzB,WAAO,QAAQ,QAAA;AAAA,EACjB;AAAA,EAEA,OAA+B;AAC7B,WAAO,QAAQ,QAAQ,MAAM,KAAK,KAAK,SAAS,KAAA,CAAM,CAAC;AAAA,EACzD;AACF;AAEO,SAAS,oBAA4B;AAC1C,QAAM,MAAM,MAAM;AAAA,IAAK,EAAE,QAAQ,EAAA;AAAA,IAAK,MACpC,KAAK,MAAM,KAAK,WAAW,EAAE,EAAE,SAAS,EAAE;AAAA,EAAA,EAC1C,KAAK,EAAE;AACT,SAAO,SAAS,GAAG;AACrB;"}

package/dist/esm/bindings/tool-to-binding.d.ts

@@ -0,0 +1,24 @@
+import { CodeModeTool, ToolBinding } from '../types.js';
+/**
+ * Convert an array of TanStack AI tools to a Record of ToolBindings
+ *
+ * @param tools - Array of tools to convert
+ * @param prefix - Optional prefix to add to binding names (e.g., 'external_')
+ */
+export declare function toolsToBindings(tools: Array<CodeModeTool>, prefix?: string): Record<string, ToolBinding>;
+/**
+ * Convert a single TanStack AI tool to a ToolBinding
+ *
+ * @param tool - Tool to convert
+ * @param prefix - Optional prefix to add to binding name (e.g., 'external_')
+ * @throws Error if the tool doesn't have an execute function
+ */
+export declare function toolToBinding(tool: CodeModeTool, prefix?: string): ToolBinding;
+/**
+ * Create event-aware bindings that emit custom events for each external function call.
+ * Wraps each binding's execute function to emit events before and after execution.
+ *
+ * @param bindings - Original tool bindings
+ * @param emitCustomEvent - Callback to emit custom events to the stream
+ */
+export declare function createEventAwareBindings(bindings: Record<string, ToolBinding>, emitCustomEvent: (eventName: string, data: Record<string, any>) => void): Record<string, ToolBinding>;

package/dist/esm/bindings/tool-to-binding.js

@@ -0,0 +1,78 @@
+import { convertSchemaToJsonSchema } from "@tanstack/ai";
+function toolsToBindings(tools, prefix = "") {
+  const bindings = {};
+  for (const tool of tools) {
+    const bindingName = `${prefix}${tool.name}`;
+    bindings[bindingName] = toolToBinding(tool, prefix);
+  }
+  return bindings;
+}
+function toolToBinding(tool, prefix = "") {
+  const inputSchema = convertSchemaToJsonSchema(tool.inputSchema) || {
+    type: "object",
+    properties: {}
+  };
+  const outputSchema = tool.outputSchema ? convertSchemaToJsonSchema(tool.outputSchema) : void 0;
+  let execute;
+  if ("execute" in tool && typeof tool.execute === "function") {
+    const toolExecute = tool.execute;
+    execute = (args, context) => {
+      return Promise.resolve(toolExecute(args, context));
+    };
+  } else if ("__toolSide" in tool && tool.__toolSide === "definition") {
+    throw new Error(
+      `Tool "${tool.name}" is a ToolDefinition without an execute function. Call .server(fn) to provide an implementation before using with Code Mode.`
+    );
+  } else {
+    throw new Error(
+      `Tool "${tool.name}" does not have an execute function. Code Mode requires tools with implementations.`
+    );
+  }
+  return {
+    name: `${prefix}${tool.name}`,
+    description: tool.description,
+    inputSchema,
+    outputSchema,
+    execute
+  };
+}
+function createEventAwareBindings(bindings, emitCustomEvent) {
+  const wrapped = {};
+  for (const [name, binding] of Object.entries(bindings)) {
+    wrapped[name] = {
+      ...binding,
+      execute: async (args) => {
+        emitCustomEvent("code_mode:external_call", {
+          function: name,
+          args,
+          timestamp: Date.now()
+        });
+        const startTime = Date.now();
+        try {
+          const toolContext = { emitCustomEvent };
+          const result = await binding.execute(args, toolContext);
+          emitCustomEvent("code_mode:external_result", {
+            function: name,
+            result,
+            duration: Date.now() - startTime
+          });
+          return result;
+        } catch (error) {
+          emitCustomEvent("code_mode:external_error", {
+            function: name,
+            error: error instanceof Error ? error.message : String(error),
+            duration: Date.now() - startTime
+          });
+          throw error;
+        }
+      }
+    };
+  }
+  return wrapped;
+}
+export {
+  createEventAwareBindings,
+  toolToBinding,
+  toolsToBindings
+};
+//# sourceMappingURL=tool-to-binding.js.map

package/dist/esm/bindings/tool-to-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-to-binding.js","sources":["../../../src/bindings/tool-to-binding.ts"],"sourcesContent":["import { convertSchemaToJsonSchema } from '@tanstack/ai'\nimport type { ToolExecutionContext } from '@tanstack/ai'\nimport type { CodeModeTool, ToolBinding } from '../types'\n\n/**\n * Convert an array of TanStack AI tools to a Record of ToolBindings\n *\n * @param tools - Array of tools to convert\n * @param prefix - Optional prefix to add to binding names (e.g., 'external_')\n */\nexport function toolsToBindings(\n  tools: Array<CodeModeTool>,\n  prefix: string = '',\n): Record<string, ToolBinding> {\n  const bindings: Record<string, ToolBinding> = {}\n\n  for (const tool of tools) {\n    const bindingName = `${prefix}${tool.name}`\n    bindings[bindingName] = toolToBinding(tool, prefix)\n  }\n\n  return bindings\n}\n\n/**\n * Convert a single TanStack AI tool to a ToolBinding\n *\n * @param tool - Tool to convert\n * @param prefix - Optional prefix to add to binding name (e.g., 'external_')\n * @throws Error if the tool doesn't have an execute function\n */\nexport function toolToBinding(\n  tool: CodeModeTool,\n  prefix: string = '',\n): ToolBinding {\n  // Convert schemas (Zod or Standard Schema) to JSON Schema\n  const inputSchema = convertSchemaToJsonSchema(tool.inputSchema) || {\n    type: 'object',\n    properties: {},\n  }\n\n  const outputSchema = tool.outputSchema\n    ? convertSchemaToJsonSchema(tool.outputSchema)\n    : undefined\n\n  // Get execute function\n  // ServerTool has execute, ToolDefinition (without .server()) does not\n  let execute: (\n    args: unknown,\n    context?: ToolExecutionContext,\n  ) => Promise<unknown>\n\n  if ('execute' in tool && typeof tool.execute === 'function') {\n    const toolExecute = tool.execute\n    execute = (args: unknown, context?: ToolExecutionContext) => {\n      // Pass context to the underlying tool so it can emit custom events\n      return Promise.resolve(toolExecute(args, context))\n    }\n  } else if ('__toolSide' in tool && tool.__toolSide === 'definition') {\n    throw new Error(\n      `Tool \"${tool.name}\" is a ToolDefinition without an execute function. ` +\n        `Call .server(fn) to provide an implementation before using with Code Mode.`,\n    )\n  } else {\n    throw new Error(\n      `Tool \"${tool.name}\" does not have an execute function. ` +\n        `Code Mode requires tools with implementations.`,\n    )\n  }\n\n  return {\n    name: `${prefix}${tool.name}`,\n    description: tool.description,\n    inputSchema,\n    outputSchema,\n    execute,\n  }\n}\n\n/**\n * Create event-aware bindings that emit custom events for each external function call.\n * Wraps each binding's execute function to emit events before and after execution.\n *\n * @param bindings - Original tool bindings\n * @param emitCustomEvent - Callback to emit custom events to the stream\n */\nexport function createEventAwareBindings(\n  bindings: Record<string, ToolBinding>,\n  emitCustomEvent: (eventName: string, data: Record<string, any>) => void,\n): Record<string, ToolBinding> {\n  const wrapped: Record<string, ToolBinding> = {}\n\n  for (const [name, binding] of Object.entries(bindings)) {\n    wrapped[name] = {\n      ...binding,\n      execute: async (args: unknown) => {\n        // Emit call event\n        emitCustomEvent('code_mode:external_call', {\n          function: name,\n          args,\n          timestamp: Date.now(),\n        })\n\n        const startTime = Date.now()\n        try {\n          // Create context for the underlying tool so it can also emit events\n          const toolContext: ToolExecutionContext = { emitCustomEvent }\n          const result = await binding.execute(args, toolContext)\n\n          // Emit result event\n          emitCustomEvent('code_mode:external_result', {\n            function: name,\n            result,\n            duration: Date.now() - startTime,\n          })\n\n          return result\n        } catch (error) {\n          // Emit error event\n          emitCustomEvent('code_mode:external_error', {\n            function: name,\n            error: error instanceof Error ? error.message : String(error),\n            duration: Date.now() - startTime,\n          })\n          throw error\n        }\n      },\n    }\n  }\n\n  return wrapped\n}\n"],"names":[],"mappings":";AAUO,SAAS,gBACd,OACA,SAAiB,IACY;AAC7B,QAAM,WAAwC,CAAA;AAE9C,aAAW,QAAQ,OAAO;AACxB,UAAM,cAAc,GAAG,MAAM,GAAG,KAAK,IAAI;AACzC,aAAS,WAAW,IAAI,cAAc,MAAM,MAAM;AAAA,EACpD;AAEA,SAAO;AACT;AASO,SAAS,cACd,MACA,SAAiB,IACJ;AAEb,QAAM,cAAc,0BAA0B,KAAK,WAAW,KAAK;AAAA,IACjE,MAAM;AAAA,IACN,YAAY,CAAA;AAAA,EAAC;AAGf,QAAM,eAAe,KAAK,eACtB,0BAA0B,KAAK,YAAY,IAC3C;AAIJ,MAAI;AAKJ,MAAI,aAAa,QAAQ,OAAO,KAAK,YAAY,YAAY;AAC3D,UAAM,cAAc,KAAK;AACzB,cAAU,CAAC,MAAe,YAAmC;AAE3D,aAAO,QAAQ,QAAQ,YAAY,MAAM,OAAO,CAAC;AAAA,IACnD;AAAA,EACF,WAAW,gBAAgB,QAAQ,KAAK,eAAe,cAAc;AACnE,UAAM,IAAI;AAAA,MACR,SAAS,KAAK,IAAI;AAAA,IAAA;AAAA,EAGtB,OAAO;AACL,UAAM,IAAI;AAAA,MACR,SAAS,KAAK,IAAI;AAAA,IAAA;AAAA,EAGtB;AAEA,SAAO;AAAA,IACL,MAAM,GAAG,MAAM,GAAG,KAAK,IAAI;AAAA,IAC3B,aAAa,KAAK;AAAA,IAClB;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;AASO,SAAS,yBACd,UACA,iBAC6B;AAC7B,QAAM,UAAuC,CAAA;AAE7C,aAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACtD,YAAQ,IAAI,IAAI;AAAA,MACd,GAAG;AAAA,MACH,SAAS,OAAO,SAAkB;AAEhC,wBAAgB,2BAA2B;AAAA,UACzC,UAAU;AAAA,UACV;AAAA,UACA,WAAW,KAAK,IAAA;AAAA,QAAI,CACrB;AAED,cAAM,YAAY,KAAK,IAAA;AACvB,YAAI;AAEF,gBAAM,cAAoC,EAAE,gBAAA;AAC5C,gBAAM,SAAS,MAAM,QAAQ,QAAQ,MAAM,WAAW;AAGtD,0BAAgB,6BAA6B;AAAA,YAC3C,UAAU;AAAA,YACV;AAAA,YACA,UAAU,KAAK,QAAQ;AAAA,UAAA,CACxB;AAED,iBAAO;AAAA,QACT,SAAS,OAAO;AAEd,0BAAgB,4BAA4B;AAAA,YAC1C,UAAU;AAAA,YACV,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,YAC5D,UAAU,KAAK,QAAQ;AAAA,UAAA,CACxB;AACD,gBAAM;AAAA,QACR;AAAA,MACF;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;"}

package/dist/esm/code-wrapper.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrap user code in an async IIFE to support top-level await
+ *
+ * The code is wrapped so that:
+ * 1. Top-level await works
+ * 2. Return values are captured and serialized (for isolate boundary transfer)
+ * 3. Errors propagate correctly
+ */
+export declare function wrapCode(code: string): string;

package/dist/esm/code-wrapper.js

@@ -0,0 +1,18 @@
+function wrapCode(code) {
+  return `
+(async function() {
+  try {
+    const __userResult = await (async function() {
+${code}
+    })();
+    return JSON.stringify(__userResult);
+  } catch (__error) {
+    throw __error;
+  }
+})()
+`;
+}
+export {
+  wrapCode
+};
+//# sourceMappingURL=code-wrapper.js.map

package/dist/esm/code-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-wrapper.js","sources":["../../src/code-wrapper.ts"],"sourcesContent":["/**\n * Wrap user code in an async IIFE to support top-level await\n *\n * The code is wrapped so that:\n * 1. Top-level await works\n * 2. Return values are captured and serialized (for isolate boundary transfer)\n * 3. Errors propagate correctly\n */\nexport function wrapCode(code: string): string {\n  // Results must be serialized to JSON because objects can't be transferred\n  // directly across the isolate boundary in isolated-vm\n  return `\n(async function() {\n  try {\n    const __userResult = await (async function() {\n${code}\n    })();\n    return JSON.stringify(__userResult);\n  } catch (__error) {\n    throw __error;\n  }\n})()\n`\n}\n"],"names":[],"mappings":"AAQO,SAAS,SAAS,MAAsB;AAG7C,SAAO;AAAA;AAAA;AAAA;AAAA,EAIP,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQN;"}

package/dist/esm/create-code-mode-tool.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { ServerTool } from '@tanstack/ai';
+import { CodeModeToolConfig } from './types.js';
+/**
+ * Schema for the execute_typescript tool input
+ */
+declare const executeTypescriptInputSchema: z.ZodObject<{
+    typescriptCode: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for the execute_typescript tool output
+ */
+declare const executeTypescriptOutputSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    result: z.ZodOptional<z.ZodUnknown>;
+    logs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExecuteTypescriptInput = z.infer<typeof executeTypescriptInputSchema>;
+export type ExecuteTypescriptOutput = z.infer<typeof executeTypescriptOutputSchema>;
+/**
+ * Create an execute_typescript tool that can be used alongside other agent tools.
+ *
+ * This tool allows an LLM to execute TypeScript code in a secure sandbox.
+ * Tools passed in the config become `external_*` functions available inside the sandbox.
+ *
+ * @example
+ * ```typescript
+ * import { createCodeMode } from '@tanstack/ai-code-mode'
+ * import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
+ *
+ * const { tool, systemPrompt } = createCodeMode({
+ *   driver: createNodeIsolateDriver(),
+ *   tools: [weatherTool, dbTool],  // Become external_fetchWeather, external_dbQuery
+ *   timeout: 30000,
+ * })
+ *
+ * chat({
+ *   systemPrompts: [myPrompt, systemPrompt],
+ *   tools: [tool, searchTool, emailTool],
+ *   messages,
+ * })
+ * ```
+ */
+export declare function createCodeModeTool(config: CodeModeToolConfig): ServerTool<typeof executeTypescriptInputSchema, typeof executeTypescriptOutputSchema, 'execute_typescript'>;
+export {};

package/dist/esm/create-code-mode-tool.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { toolDefinition } from "@tanstack/ai";
+import { toolsToBindings, createEventAwareBindings } from "./bindings/tool-to-binding.js";
+import { stripTypeScript } from "./strip-typescript.js";
+const executeTypescriptInputSchema = z.object({
+  typescriptCode: z.string().describe(
+    "TypeScript code to execute in the sandbox. Use external_* functions to call available APIs. Return a value to pass results back."
+  )
+});
+const executeTypescriptOutputSchema = z.object({
+  success: z.boolean().describe("Whether execution completed without errors"),
+  result: z.unknown().optional().describe("Return value from the executed code"),
+  logs: z.array(z.string()).optional().describe("Console output captured during execution"),
+  error: z.object({
+    message: z.string(),
+    name: z.string().optional(),
+    line: z.number().optional()
+  }).optional().describe("Error details if execution failed")
+});
+function createCodeModeTool(config) {
+  const {
+    driver,
+    tools,
+    timeout = 3e4,
+    memoryLimit = 128,
+    getSkillBindings
+  } = config;
+  if (tools.length === 0) {
+    throw new Error("At least one tool must be provided to createCodeModeTool");
+  }
+  const staticBindings = toolsToBindings(tools, "external_");
+  const definition = toolDefinition({
+    name: "execute_typescript",
+    description: buildToolDescription(tools),
+    inputSchema: executeTypescriptInputSchema,
+    outputSchema: executeTypescriptOutputSchema
+  });
+  return definition.server(
+    async (input, toolContext) => {
+      const { typescriptCode } = input;
+      const emitCustomEvent = toolContext?.emitCustomEvent || (() => {
+      });
+      if (!typescriptCode || typeof typescriptCode !== "string") {
+        return {
+          success: false,
+          error: {
+            message: "typescriptCode must be a non-empty string",
+            name: "ValidationError"
+          }
+        };
+      }
+      let isolateContext = null;
+      emitCustomEvent("code_mode:execution_started", {
+        timestamp: Date.now(),
+        codeLength: typescriptCode.length
+      });
+      try {
+        let strippedCode;
+        try {
+          strippedCode = await stripTypeScript(typescriptCode);
+        } catch (error) {
+          return {
+            success: false,
+            error: {
+              message: error instanceof Error ? error.message : String(error),
+              name: "TypeScriptError"
+            }
+          };
+        }
+        const skillBindings = getSkillBindings ? await getSkillBindings() : {};
+        const allBindings = { ...staticBindings, ...skillBindings };
+        const eventAwareBindings = createEventAwareBindings(
+          allBindings,
+          emitCustomEvent
+        );
+        isolateContext = await driver.createContext({
+          bindings: eventAwareBindings,
+          timeout,
+          memoryLimit
+        });
+        const executionResult = await isolateContext.execute(strippedCode);
+        if (executionResult.logs && executionResult.logs.length > 0) {
+          for (const log of executionResult.logs) {
+            let level = "log";
+            let message = log;
+            if (log.startsWith("ERROR: ")) {
+              level = "error";
+              message = log.slice(7);
+            } else if (log.startsWith("WARN: ")) {
+              level = "warn";
+              message = log.slice(6);
+            } else if (log.startsWith("INFO: ")) {
+              level = "info";
+              message = log.slice(6);
+            }
+            emitCustomEvent("code_mode:console", {
+              level,
+              message,
+              timestamp: Date.now()
+            });
+          }
+        }
+        if (executionResult.success) {
+          return {
+            success: true,
+            result: executionResult.value,
+            logs: executionResult.logs
+          };
+        } else {
+          return {
+            success: false,
+            error: executionResult.error ? {
+              message: executionResult.error.message,
+              name: executionResult.error.name
+            } : { message: "Unknown execution error" },
+            logs: executionResult.logs
+          };
+        }
+      } catch (error) {
+        return {
+          success: false,
+          error: {
+            message: error instanceof Error ? error.message : String(error),
+            name: error instanceof Error ? error.name : "Error"
+          }
+        };
+      } finally {
+        if (isolateContext) {
+          await isolateContext.dispose();
+        }
+      }
+    }
+  );
+}
+function buildToolDescription(tools) {
+  const externalFunctions = tools.map((t) => `external_${t.name}`).join(", ");
+  return `Execute TypeScript code in a secure sandbox environment. The code can use these external API functions: ${externalFunctions}. All external_* calls are async and must be awaited. Return a value to pass results back. Use console.log() for debugging.`;
+}
+export {
+  createCodeModeTool
+};
+//# sourceMappingURL=create-code-mode-tool.js.map

package/dist/esm/create-code-mode-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-code-mode-tool.js","sources":["../../src/create-code-mode-tool.ts"],"sourcesContent":["import { z } from 'zod'\nimport { toolDefinition } from '@tanstack/ai'\nimport {\n  createEventAwareBindings,\n  toolsToBindings,\n} from './bindings/tool-to-binding'\nimport { stripTypeScript } from './strip-typescript'\nimport type { ServerTool, ToolExecutionContext } from '@tanstack/ai'\nimport type {\n  CodeModeTool,\n  CodeModeToolConfig,\n  CodeModeToolResult,\n  IsolateContext,\n} from './types'\n\n/**\n * Schema for the execute_typescript tool input\n */\nconst executeTypescriptInputSchema = z.object({\n  typescriptCode: z\n    .string()\n    .describe(\n      'TypeScript code to execute in the sandbox. ' +\n        'Use external_* functions to call available APIs. ' +\n        'Return a value to pass results back.',\n    ),\n})\n\n/**\n * Schema for the execute_typescript tool output\n */\nconst executeTypescriptOutputSchema = z.object({\n  success: z.boolean().describe('Whether execution completed without errors'),\n  result: z\n    .unknown()\n    .optional()\n    .describe('Return value from the executed code'),\n  logs: z\n    .array(z.string())\n    .optional()\n    .describe('Console output captured during execution'),\n  error: z\n    .object({\n      message: z.string(),\n      name: z.string().optional(),\n      line: z.number().optional(),\n    })\n    .optional()\n    .describe('Error details if execution failed'),\n})\n\nexport type ExecuteTypescriptInput = z.infer<\n  typeof executeTypescriptInputSchema\n>\nexport type ExecuteTypescriptOutput = z.infer<\n  typeof executeTypescriptOutputSchema\n>\n\n/**\n * Create an execute_typescript tool that can be used alongside other agent tools.\n *\n * This tool allows an LLM to execute TypeScript code in a secure sandbox.\n * Tools passed in the config become `external_*` functions available inside the sandbox.\n *\n * @example\n * ```typescript\n * import { createCodeMode } from '@tanstack/ai-code-mode'\n * import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'\n *\n * const { tool, systemPrompt } = createCodeMode({\n *   driver: createNodeIsolateDriver(),\n *   tools: [weatherTool, dbTool],  // Become external_fetchWeather, external_dbQuery\n *   timeout: 30000,\n * })\n *\n * chat({\n *   systemPrompts: [myPrompt, systemPrompt],\n *   tools: [tool, searchTool, emailTool],\n *   messages,\n * })\n * ```\n */\nexport function createCodeModeTool(\n  config: CodeModeToolConfig,\n): ServerTool<\n  typeof executeTypescriptInputSchema,\n  typeof executeTypescriptOutputSchema,\n  'execute_typescript'\n> {\n  const {\n    driver,\n    tools,\n    timeout = 30000,\n    memoryLimit = 128,\n    getSkillBindings,\n  } = config\n\n  // Validate tools\n  if (tools.length === 0) {\n    throw new Error('At least one tool must be provided to createCodeModeTool')\n  }\n\n  // Transform tools to bindings with external_ prefix (static bindings)\n  const staticBindings = toolsToBindings(tools, 'external_')\n\n  // Create the tool definition\n  const definition = toolDefinition({\n    name: 'execute_typescript' as const,\n    description: buildToolDescription(tools),\n    inputSchema: executeTypescriptInputSchema,\n    outputSchema: executeTypescriptOutputSchema,\n  })\n\n  // Return server tool with execute function that accepts context\n  return definition.server(\n    async (\n      input,\n      toolContext?: ToolExecutionContext,\n    ): Promise<CodeModeToolResult> => {\n      const { typescriptCode } = input\n\n      // Get emitCustomEvent from context or use no-op\n      const emitCustomEvent = toolContext?.emitCustomEvent || (() => {})\n\n      if (!typescriptCode || typeof typescriptCode !== 'string') {\n        return {\n          success: false,\n          error: {\n            message: 'typescriptCode must be a non-empty string',\n            name: 'ValidationError',\n          },\n        }\n      }\n\n      // Create a fresh sandbox context for this execution\n      let isolateContext: IsolateContext | null = null\n\n      // Emit execution started event immediately\n      emitCustomEvent('code_mode:execution_started', {\n        timestamp: Date.now(),\n        codeLength: typescriptCode.length,\n      })\n\n      try {\n        // Step 1: Strip TypeScript (also serves as syntax validation via esbuild)\n        let strippedCode: string\n        try {\n          strippedCode = await stripTypeScript(typescriptCode)\n        } catch (error) {\n          // Type/syntax error from esbuild\n          return {\n            success: false,\n            error: {\n              message: error instanceof Error ? error.message : String(error),\n              name: 'TypeScriptError',\n            },\n          }\n        }\n\n        // Step 2: Get dynamic skill bindings if available\n        const skillBindings = getSkillBindings ? await getSkillBindings() : {}\n\n        // Step 3: Merge static and dynamic bindings, then wrap with event awareness\n        const allBindings = { ...staticBindings, ...skillBindings }\n        const eventAwareBindings = createEventAwareBindings(\n          allBindings,\n          emitCustomEvent,\n        )\n\n        // Step 4: Create sandbox context with event-aware bindings\n        isolateContext = await driver.createContext({\n          bindings: eventAwareBindings,\n          timeout,\n          memoryLimit,\n        })\n\n        // Step 5: Execute the code in the sandbox\n        const executionResult = await isolateContext.execute(strippedCode)\n\n        // Emit console logs as custom events\n        if (executionResult.logs && executionResult.logs.length > 0) {\n          for (const log of executionResult.logs) {\n            // Parse log level from prefix (added by sandbox console implementation)\n            let level: 'log' | 'warn' | 'error' | 'info' = 'log'\n            let message = log\n\n            if (log.startsWith('ERROR: ')) {\n              level = 'error'\n              message = log.slice(7)\n            } else if (log.startsWith('WARN: ')) {\n              level = 'warn'\n              message = log.slice(6)\n            } else if (log.startsWith('INFO: ')) {\n              level = 'info'\n              message = log.slice(6)\n            }\n\n            emitCustomEvent('code_mode:console', {\n              level,\n              message,\n              timestamp: Date.now(),\n            })\n          }\n        }\n\n        if (executionResult.success) {\n          return {\n            success: true,\n            result: executionResult.value,\n            logs: executionResult.logs,\n          }\n        } else {\n          return {\n            success: false,\n            error: executionResult.error\n              ? {\n                  message: executionResult.error.message,\n                  name: executionResult.error.name,\n                }\n              : { message: 'Unknown execution error' },\n            logs: executionResult.logs,\n          }\n        }\n      } catch (error) {\n        return {\n          success: false,\n          error: {\n            message: error instanceof Error ? error.message : String(error),\n            name: error instanceof Error ? error.name : 'Error',\n          },\n        }\n      } finally {\n        // Always clean up the sandbox context\n        if (isolateContext) {\n          await isolateContext.dispose()\n        }\n      }\n    },\n  )\n}\n\n/**\n * Build the tool description including available external functions\n */\nfunction buildToolDescription(tools: Array<CodeModeTool>): string {\n  const externalFunctions = tools.map((t) => `external_${t.name}`).join(', ')\n\n  return (\n    `Execute TypeScript code in a secure sandbox environment. ` +\n    `The code can use these external API functions: ${externalFunctions}. ` +\n    `All external_* calls are async and must be awaited. ` +\n    `Return a value to pass results back. Use console.log() for debugging.`\n  )\n}\n"],"names":[],"mappings":"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"}