@tanstack/ai-code-mode 0.3.0 → 0.3.2

package/dist/esm/create-system-prompt.js

@@ -0,0 +1,76 @@
+import { renderLazyCatalogEntry } from "@tanstack/ai";
+import { toolsToBindings } from "./bindings/tool-to-binding.js";
+import { generateTypeStubs } from "./type-generator/json-schema-to-ts.js";
+function createCodeModeSystemPrompt(config) {
+  const { tools } = config;
+  const include = config.lazyToolsConfig?.includeDescription ?? "none";
+  const eagerTools = tools.filter((t) => !t.lazy);
+  const lazyTools = tools.filter((t) => t.lazy);
+  const bindings = toolsToBindings(eagerTools, "external_");
+  const typeStubs = generateTypeStubs(bindings);
+  const functionDocs = Object.entries(bindings).map(([name, binding]) => `- \`${name}(input)\`: ${binding.description}`).join("\n");
+  const discoverableSection = lazyTools.length > 0 ? `
+
+### Discoverable APIs
+
+These additional functions are available but not yet documented. Before calling \`external_<name>\` for any of them inside \`execute_typescript\`, call the \`discover_tools\` tool with their names to get full TypeScript signatures:
+
+${lazyTools.map(
+    (t) => `- ${renderLazyCatalogEntry(`external_${t.name}`, t.description, include)}`
+  ).join("\n")}` : "";
+  return `## Code Execution Tool
+
+You have access to \`execute_typescript\` which runs TypeScript code in a sandboxed environment.
+
+### When to Use
+
+Use \`execute_typescript\` when you need to:
+- Process data with loops, conditionals, or complex logic
+- Make multiple API calls in parallel (Promise.all)
+- Transform, filter, or aggregate data
+- Perform calculations or data analysis
+
+For simple operations, prefer calling tools directly.
+
+### Available External APIs
+
+Inside your TypeScript code, you can call these async functions:
+
+${functionDocs}
+
+### Type Definitions
+
+\`\`\`typescript
+${typeStubs}
+\`\`\`${discoverableSection}
+
+### Example
+
+\`\`\`typescript
+// Fetch weather for multiple cities in parallel
+const cities = ["Tokyo", "Paris", "NYC"];
+const results = await Promise.all(
+  cities.map(city => external_fetchWeather({ location: city }))
+);
+
+// Find the warmest city
+const warmest = results.reduce((prev, curr) =>
+  curr.temperature > prev.temperature ? curr : prev
+);
+
+return { warmestCity: warmest.location, temperature: warmest.temperature };
+\`\`\`
+
+### Important Notes
+
+- All \`external_*\` calls are async - always use \`await\`
+- Return a value to pass results back to you
+- Use \`console.log()\` for debugging (logs are captured)
+- The sandbox is isolated - no network access or file system
+- Each execution is independent (no shared state between calls)
+`;
+}
+export {
+  createCodeModeSystemPrompt
+};
+//# sourceMappingURL=create-system-prompt.js.map

package/dist/esm/create-system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-system-prompt.js","sources":["../../src/create-system-prompt.ts"],"sourcesContent":["import { renderLazyCatalogEntry } from '@tanstack/ai'\nimport { toolsToBindings } from './bindings/tool-to-binding'\nimport { generateTypeStubs } from './type-generator/json-schema-to-ts'\nimport type { CodeModeToolConfig } from './types'\n\n/**\n * Create a system prompt snippet that documents the execute_typescript tool\n * and all available external_* functions.\n *\n * Add this to your system prompts array when using createCodeModeTool.\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],\n * })\n *\n * chat({\n *   systemPrompts: ['You are a helpful assistant.', systemPrompt],\n *   tools: [tool, ...otherTools],\n * })\n * ```\n */\nexport function createCodeModeSystemPrompt(config: CodeModeToolConfig): string {\n  const { tools } = config\n  const include = config.lazyToolsConfig?.includeDescription ?? 'none'\n\n  const eagerTools = tools.filter((t) => !t.lazy)\n  const lazyTools = tools.filter((t) => t.lazy)\n\n  // Only eager tools get full type stubs + doc lines.\n  const bindings = toolsToBindings(eagerTools, 'external_')\n  const typeStubs = generateTypeStubs(bindings)\n\n  const functionDocs = Object.entries(bindings)\n    .map(([name, binding]) => `- \\`${name}(input)\\`: ${binding.description}`)\n    .join('\\n')\n\n  const discoverableSection =\n    lazyTools.length > 0\n      ? `\n\n### Discoverable APIs\n\nThese additional functions are available but not yet documented. Before calling \\`external_<name>\\` for any of them inside \\`execute_typescript\\`, call the \\`discover_tools\\` tool with their names to get full TypeScript signatures:\n\n${lazyTools\n  .map(\n    (t) =>\n      `- ${renderLazyCatalogEntry(`external_${t.name}`, t.description, include)}`,\n  )\n  .join('\\n')}`\n      : ''\n\n  return `## Code Execution Tool\n\nYou have access to \\`execute_typescript\\` which runs TypeScript code in a sandboxed environment.\n\n### When to Use\n\nUse \\`execute_typescript\\` when you need to:\n- Process data with loops, conditionals, or complex logic\n- Make multiple API calls in parallel (Promise.all)\n- Transform, filter, or aggregate data\n- Perform calculations or data analysis\n\nFor simple operations, prefer calling tools directly.\n\n### Available External APIs\n\nInside your TypeScript code, you can call these async functions:\n\n${functionDocs}\n\n### Type Definitions\n\n\\`\\`\\`typescript\n${typeStubs}\n\\`\\`\\`${discoverableSection}\n\n### Example\n\n\\`\\`\\`typescript\n// Fetch weather for multiple cities in parallel\nconst cities = [\"Tokyo\", \"Paris\", \"NYC\"];\nconst results = await Promise.all(\n  cities.map(city => external_fetchWeather({ location: city }))\n);\n\n// Find the warmest city\nconst warmest = results.reduce((prev, curr) =>\n  curr.temperature > prev.temperature ? curr : prev\n);\n\nreturn { warmestCity: warmest.location, temperature: warmest.temperature };\n\\`\\`\\`\n\n### Important Notes\n\n- All \\`external_*\\` calls are async - always use \\`await\\`\n- Return a value to pass results back to you\n- Use \\`console.log()\\` for debugging (logs are captured)\n- The sandbox is isolated - no network access or file system\n- Each execution is independent (no shared state between calls)\n`\n}\n"],"names":[],"mappings":";;;AA2BO,SAAS,2BAA2B,QAAoC;AAC7E,QAAM,EAAE,UAAU;AAClB,QAAM,UAAU,OAAO,iBAAiB,sBAAsB;AAE9D,QAAM,aAAa,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI;AAC9C,QAAM,YAAY,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI;AAG5C,QAAM,WAAW,gBAAgB,YAAY,WAAW;AACxD,QAAM,YAAY,kBAAkB,QAAQ;AAE5C,QAAM,eAAe,OAAO,QAAQ,QAAQ,EACzC,IAAI,CAAC,CAAC,MAAM,OAAO,MAAM,OAAO,IAAI,cAAc,QAAQ,WAAW,EAAE,EACvE,KAAK,IAAI;AAEZ,QAAM,sBACJ,UAAU,SAAS,IACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMN,UACC;AAAA,IACC,CAAC,MACC,KAAK,uBAAuB,YAAY,EAAE,IAAI,IAAI,EAAE,aAAa,OAAO,CAAC;AAAA,EAAA,EAE5E,KAAK,IAAI,CAAC,KACL;AAEN,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBP,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA,EAKZ,SAAS;AAAA,QACH,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2B3B;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,11 @@
+export { createCodeModeTool } from './create-code-mode-tool.js';
+export type { ExecuteTypescriptInput, ExecuteTypescriptOutput, } from './create-code-mode-tool.js';
+export { createCodeModeSystemPrompt } from './create-system-prompt.js';
+export { createCodeMode } from './create-code-mode.js';
+export { createDiscoveryTool } from './create-discovery-tool.js';
+export { InMemoryAgentStore, generateAgentName, type AgentSession, type AgentStore, } from './agent-store.js';
+export { toolToBinding, toolsToBindings, createEventAwareBindings, } from './bindings/tool-to-binding.js';
+export { generateTypeStubs, jsonSchemaToTypeScript, type TypeGeneratorOptions, } from './type-generator/json-schema-to-ts.js';
+export { stripTypeScript } from './strip-typescript.js';
+export { wrapCode } from './code-wrapper.js';
+export type { CodeModeToolConfig, CreateCodeModeResult, CodeModeToolResult, IsolateDriver, IsolateConfig, IsolateContext, ExecutionResult, NormalizedError, ToolBinding, CodeModeTool, ToolExecutionContext, } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,25 @@
+import { createCodeModeTool } from "./create-code-mode-tool.js";
+import { createCodeModeSystemPrompt } from "./create-system-prompt.js";
+import { createCodeMode } from "./create-code-mode.js";
+import { createDiscoveryTool } from "./create-discovery-tool.js";
+import { InMemoryAgentStore, generateAgentName } from "./agent-store.js";
+import { createEventAwareBindings, toolToBinding, toolsToBindings } from "./bindings/tool-to-binding.js";
+import { generateTypeStubs, jsonSchemaToTypeScript } from "./type-generator/json-schema-to-ts.js";
+import { stripTypeScript } from "./strip-typescript.js";
+import { wrapCode } from "./code-wrapper.js";
+export {
+  InMemoryAgentStore,
+  createCodeMode,
+  createCodeModeSystemPrompt,
+  createCodeModeTool,
+  createDiscoveryTool,
+  createEventAwareBindings,
+  generateAgentName,
+  generateTypeStubs,
+  jsonSchemaToTypeScript,
+  stripTypeScript,
+  toolToBinding,
+  toolsToBindings,
+  wrapCode
+};
+//# 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/strip-typescript.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Strip TypeScript syntax from code, converting it to plain JavaScript.
+ *
+ * This is a safety net to ensure that even if an LLM generates TypeScript
+ * code with type annotations, it will be converted to valid JavaScript
+ * before being sent to the sandbox for execution.
+ *
+ * Uses sucrase's pure-JavaScript `transform`, which strips the TypeScript
+ * syntax that LLM-generated snippets use in practice:
+ * - Type annotations (: string, : number, etc.)
+ * - Generic types (Array<T>, Record<K, V>, etc.)
+ * - Interface and type declarations
+ * - Type assertions
+ * - Enums (converted to JavaScript objects)
+ *
+ * Unlike esbuild, sucrase has no native binary and pulls in no Node-only
+ * built-ins on its `transform` path, so this module is safe to bundle for
+ * browsers and edge runtimes (Cloudflare Workers/Pages etc.).
+ *
+ * Limitations vs esbuild: sucrase is a type-stripper, not a down-leveler.
+ * `disableESTransforms` leaves modern ECMAScript syntax untouched (the sandbox
+ * engines are modern), and sucrase does NOT compile a few exotic constructs:
+ * - TypeScript value `namespace`/`module` blocks are DROPPED (not emitted as an
+ *   IIFE), so referencing the namespace at runtime throws `ReferenceError`.
+ * - Decorators and the `accessor` keyword pass through un-lowered, so the
+ *   sandbox sees invalid syntax.
+ * - Post-ES2022 syntax (`using` declarations, RegExp `/v`·`/d` flags) is passed
+ *   through; it runs on modern V8/Node sandboxes but may fail on older engines
+ *   (e.g. QuickJS).
+ * If you need any of these, supply a heavier (Node-only) transpiler via the
+ * `transpile` option on `createCodeModeTool`.
+ *
+ * The code is wrapped in an async function before transformation to allow
+ * top-level `return` and `await` statements, then unwrapped after.
+ *
+ * Note on errors: sucrase reports syntax errors with a position relative to the
+ * *wrapped* code (offset by the one-line wrapper prefix), so any line numbers
+ * surfaced downstream (e.g. `CodeModeToolResult.error.line`) are approximate.
+ *
+ * @param code - TypeScript or JavaScript code
+ * @returns Plain JavaScript code with all type syntax removed
+ * @throws Error if sucrase fails (e.g., syntax error) or wrapper extraction fails
+ */
+export declare function stripTypeScript(code: string): Promise<string>;

package/dist/esm/strip-typescript.js

@@ -0,0 +1,49 @@
+import { transform } from "sucrase";
+const WRAPPER_START = "___TANSTACK_WRAPPER_START___";
+const WRAPPER_END = "___TANSTACK_WRAPPER_END___";
+async function stripTypeScript(code) {
+  const wrappedCode = `async function ${WRAPPER_START}() {
+${code}
+}; ${WRAPPER_END}`;
+  const result = transform(wrappedCode, {
+    // Only strip/lower TypeScript-specific syntax...
+    transforms: ["typescript"],
+    // ...and leave modern ECMAScript syntax untouched for the sandbox engines.
+    disableESTransforms: true
+  });
+  const transformed = result.code;
+  const functionStart = transformed.indexOf(`async function ${WRAPPER_START}()`);
+  if (functionStart === -1) {
+    throw new Error(
+      "[stripTypeScript] Could not find wrapper function start in transformed output"
+    );
+  }
+  const openBrace = transformed.indexOf("{", functionStart);
+  if (openBrace === -1) {
+    throw new Error(
+      "[stripTypeScript] Could not find opening brace in transformed output"
+    );
+  }
+  const endMarkerIndex = transformed.indexOf(WRAPPER_END);
+  if (endMarkerIndex === -1) {
+    throw new Error(
+      "[stripTypeScript] Could not find end marker in transformed output"
+    );
+  }
+  const codeBeforeEndMarker = transformed.substring(
+    openBrace + 1,
+    endMarkerIndex
+  );
+  const closingBraceIndex = codeBeforeEndMarker.lastIndexOf("}");
+  if (closingBraceIndex === -1) {
+    throw new Error(
+      "[stripTypeScript] Could not find closing brace in transformed output"
+    );
+  }
+  const functionBody = codeBeforeEndMarker.substring(0, closingBraceIndex).trim();
+  return functionBody;
+}
+export {
+  stripTypeScript
+};
+//# sourceMappingURL=strip-typescript.js.map

package/dist/esm/strip-typescript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-typescript.js","sources":["../../src/strip-typescript.ts"],"sourcesContent":["import { transform } from 'sucrase'\n\n// Unique markers for wrapping/unwrapping code\nconst WRAPPER_START = '___TANSTACK_WRAPPER_START___'\nconst WRAPPER_END = '___TANSTACK_WRAPPER_END___'\n\n/**\n * Strip TypeScript syntax from code, converting it to plain JavaScript.\n *\n * This is a safety net to ensure that even if an LLM generates TypeScript\n * code with type annotations, it will be converted to valid JavaScript\n * before being sent to the sandbox for execution.\n *\n * Uses sucrase's pure-JavaScript `transform`, which strips the TypeScript\n * syntax that LLM-generated snippets use in practice:\n * - Type annotations (: string, : number, etc.)\n * - Generic types (Array<T>, Record<K, V>, etc.)\n * - Interface and type declarations\n * - Type assertions\n * - Enums (converted to JavaScript objects)\n *\n * Unlike esbuild, sucrase has no native binary and pulls in no Node-only\n * built-ins on its `transform` path, so this module is safe to bundle for\n * browsers and edge runtimes (Cloudflare Workers/Pages etc.).\n *\n * Limitations vs esbuild: sucrase is a type-stripper, not a down-leveler.\n * `disableESTransforms` leaves modern ECMAScript syntax untouched (the sandbox\n * engines are modern), and sucrase does NOT compile a few exotic constructs:\n * - TypeScript value `namespace`/`module` blocks are DROPPED (not emitted as an\n *   IIFE), so referencing the namespace at runtime throws `ReferenceError`.\n * - Decorators and the `accessor` keyword pass through un-lowered, so the\n *   sandbox sees invalid syntax.\n * - Post-ES2022 syntax (`using` declarations, RegExp `/v`·`/d` flags) is passed\n *   through; it runs on modern V8/Node sandboxes but may fail on older engines\n *   (e.g. QuickJS).\n * If you need any of these, supply a heavier (Node-only) transpiler via the\n * `transpile` option on `createCodeModeTool`.\n *\n * The code is wrapped in an async function before transformation to allow\n * top-level `return` and `await` statements, then unwrapped after.\n *\n * Note on errors: sucrase reports syntax errors with a position relative to the\n * *wrapped* code (offset by the one-line wrapper prefix), so any line numbers\n * surfaced downstream (e.g. `CodeModeToolResult.error.line`) are approximate.\n *\n * @param code - TypeScript or JavaScript code\n * @returns Plain JavaScript code with all type syntax removed\n * @throws Error if sucrase fails (e.g., syntax error) or wrapper extraction fails\n */\n// sucrase's transform is synchronous, but we keep the published Promise-returning\n// signature so existing `await stripTypeScript(...)` callers (and a custom async\n// `transpile` hook) stay source-compatible across this swap.\n// eslint-disable-next-line @typescript-eslint/require-await\nexport async function stripTypeScript(code: string): Promise<string> {\n  // Wrap the code in an async function to allow top-level return/await.\n  // This is necessary because top-level `return` is invalid outside a function.\n  const wrappedCode = `async function ${WRAPPER_START}() {\\n${code}\\n}; ${WRAPPER_END}`\n\n  const result = transform(wrappedCode, {\n    // Only strip/lower TypeScript-specific syntax...\n    transforms: ['typescript'],\n    // ...and leave modern ECMAScript syntax untouched for the sandbox engines.\n    disableESTransforms: true,\n  })\n\n  // Extract the code from inside the wrapper function\n  const transformed = result.code\n\n  // Find the function declaration start\n  const functionStart = transformed.indexOf(`async function ${WRAPPER_START}()`)\n  if (functionStart === -1) {\n    throw new Error(\n      '[stripTypeScript] Could not find wrapper function start in transformed output',\n    )\n  }\n\n  // Find the opening brace of the function\n  const openBrace = transformed.indexOf('{', functionStart)\n  if (openBrace === -1) {\n    throw new Error(\n      '[stripTypeScript] Could not find opening brace in transformed output',\n    )\n  }\n\n  // Find the end marker (regardless of formatting)\n  const endMarkerIndex = transformed.indexOf(WRAPPER_END)\n  if (endMarkerIndex === -1) {\n    throw new Error(\n      '[stripTypeScript] Could not find end marker in transformed output',\n    )\n  }\n\n  // Find the closing brace of the function (last } before the end marker)\n  // We need to find the } that matches the function opening\n  const codeBeforeEndMarker = transformed.substring(\n    openBrace + 1,\n    endMarkerIndex,\n  )\n\n  // Find the last } before the end marker, accounting for the semicolon\n  // The code will be: ...function body...}; WRAPPER_END or ...};\\nWRAPPER_END\n  const closingBraceIndex = codeBeforeEndMarker.lastIndexOf('}')\n\n  if (closingBraceIndex === -1) {\n    throw new Error(\n      '[stripTypeScript] Could not find closing brace in transformed output',\n    )\n  }\n\n  // Extract the function body (between { and })\n  const functionBody = codeBeforeEndMarker\n    .substring(0, closingBraceIndex)\n    .trim()\n\n  return functionBody\n}\n"],"names":[],"mappings":";AAGA,MAAM,gBAAgB;AACtB,MAAM,cAAc;AAiDpB,eAAsB,gBAAgB,MAA+B;AAGnE,QAAM,cAAc,kBAAkB,aAAa;AAAA,EAAS,IAAI;AAAA,KAAQ,WAAW;AAEnF,QAAM,SAAS,UAAU,aAAa;AAAA;AAAA,IAEpC,YAAY,CAAC,YAAY;AAAA;AAAA,IAEzB,qBAAqB;AAAA,EAAA,CACtB;AAGD,QAAM,cAAc,OAAO;AAG3B,QAAM,gBAAgB,YAAY,QAAQ,kBAAkB,aAAa,IAAI;AAC7E,MAAI,kBAAkB,IAAI;AACxB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAGA,QAAM,YAAY,YAAY,QAAQ,KAAK,aAAa;AACxD,MAAI,cAAc,IAAI;AACpB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAGA,QAAM,iBAAiB,YAAY,QAAQ,WAAW;AACtD,MAAI,mBAAmB,IAAI;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAIA,QAAM,sBAAsB,YAAY;AAAA,IACtC,YAAY;AAAA,IACZ;AAAA,EAAA;AAKF,QAAM,oBAAoB,oBAAoB,YAAY,GAAG;AAE7D,MAAI,sBAAsB,IAAI;AAC5B,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAGA,QAAM,eAAe,oBAClB,UAAU,GAAG,iBAAiB,EAC9B,KAAA;AAEH,SAAO;AACT;"}

package/dist/esm/type-generator/json-schema-to-ts.d.ts

@@ -0,0 +1,31 @@
+import { ToolBinding } from '../types.js';
+/**
+ * Options for type stub generation
+ */
+export interface TypeGeneratorOptions {
+    /**
+     * Include JSDoc comments with descriptions
+     * @default true
+     */
+    includeDescriptions?: boolean;
+}
+/**
+ * Generate TypeScript type stubs for all tool bindings
+ *
+ * These stubs are included in the LLM system prompt so it knows
+ * the exact type signatures of available tools.
+ *
+ * Tool names match the actual function names injected into the sandbox.
+ */
+export declare function generateTypeStubs(bindings: Record<string, ToolBinding>, options?: TypeGeneratorOptions): string;
+interface TypeResult {
+    name: string;
+    declaration: string;
+}
+/**
+ * Convert a JSON Schema to a TypeScript type
+ *
+ * Supports basic types: string, number, boolean, object, array
+ */
+export declare function jsonSchemaToTypeScript(schema: Record<string, unknown>, typeName: string): TypeResult;
+export {};

package/dist/esm/type-generator/json-schema-to-ts.js

@@ -0,0 +1,100 @@
+function generateTypeStubs(bindings, options = {}) {
+  const { includeDescriptions = true } = options;
+  const declarations = [];
+  for (const [name, binding] of Object.entries(bindings)) {
+    const inputTypeName = `${capitalize(name)}Input`;
+    const outputTypeName = `${capitalize(name)}Output`;
+    const inputType = jsonSchemaToTypeScript(binding.inputSchema, inputTypeName);
+    if (inputType.declaration) {
+      declarations.push(inputType.declaration);
+    }
+    let outputTypeRef = "unknown";
+    if (binding.outputSchema) {
+      const outputType = jsonSchemaToTypeScript(
+        binding.outputSchema,
+        outputTypeName
+      );
+      if (outputType.declaration) {
+        declarations.push(outputType.declaration);
+      }
+      outputTypeRef = outputType.name;
+    }
+    const description = includeDescriptions && binding.description ? `/** ${binding.description} */
+` : "";
+    declarations.push(
+      `${description}declare function ${name}(input: ${inputType.name}): Promise<${outputTypeRef}>;`
+    );
+  }
+  return declarations.join("\n\n");
+}
+function jsonSchemaToTypeScript(schema, typeName) {
+  const type = schemaToType(schema);
+  if (schema.type === "object" && schema.properties && Object.keys(schema.properties).length > 0) {
+    return {
+      name: typeName,
+      declaration: `interface ${typeName} ${type}`
+    };
+  }
+  return {
+    name: type,
+    declaration: ""
+  };
+}
+function schemaToType(schema) {
+  if (typeof schema !== "object") {
+    return "unknown";
+  }
+  const schemaType = schema.type;
+  if (schemaType === "string") return "string";
+  if (schemaType === "number" || schemaType === "integer") return "number";
+  if (schemaType === "boolean") return "boolean";
+  if (schemaType === "null") return "null";
+  if (schemaType === "array") {
+    const items = schema.items;
+    const itemType = items ? schemaToType(items) : "unknown";
+    return `Array<${itemType}>`;
+  }
+  if (schemaType === "object" && schema.properties) {
+    const properties = schema.properties;
+    const required = new Set(
+      schema.required ?? []
+    );
+    const props = Object.entries(properties).map(([key, propSchema]) => {
+      const optional = required.has(key) ? "" : "?";
+      const propType = schemaToType(propSchema);
+      const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `"${key}"`;
+      return `  ${safeName}${optional}: ${propType};`;
+    }).join("\n");
+    return `{
+${props}
+}`;
+  }
+  if (schema.enum) {
+    const enumValues = schema.enum;
+    return enumValues.map((v) => JSON.stringify(v)).join(" | ");
+  }
+  if (schema.anyOf || schema.oneOf) {
+    const variants = schema.anyOf || schema.oneOf;
+    return variants.map((v) => schemaToType(v)).join(" | ");
+  }
+  if (Array.isArray(schemaType)) {
+    return schemaType.map((t) => {
+      if (t === "string") return "string";
+      if (t === "number" || t === "integer") return "number";
+      if (t === "boolean") return "boolean";
+      if (t === "null") return "null";
+      if (t === "array") return "Array<unknown>";
+      if (t === "object") return "object";
+      return "unknown";
+    }).join(" | ");
+  }
+  return "unknown";
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+export {
+  generateTypeStubs,
+  jsonSchemaToTypeScript
+};
+//# sourceMappingURL=json-schema-to-ts.js.map

package/dist/esm/type-generator/json-schema-to-ts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-ts.js","sources":["../../../src/type-generator/json-schema-to-ts.ts"],"sourcesContent":["import type { ToolBinding } from '../types'\n\n/**\n * Options for type stub generation\n */\nexport interface TypeGeneratorOptions {\n  /**\n   * Include JSDoc comments with descriptions\n   * @default true\n   */\n  includeDescriptions?: boolean\n}\n\n/**\n * Generate TypeScript type stubs for all tool bindings\n *\n * These stubs are included in the LLM system prompt so it knows\n * the exact type signatures of available tools.\n *\n * Tool names match the actual function names injected into the sandbox.\n */\nexport function generateTypeStubs(\n  bindings: Record<string, ToolBinding>,\n  options: TypeGeneratorOptions = {},\n): string {\n  const { includeDescriptions = true } = options\n\n  const declarations: Array<string> = []\n\n  for (const [name, binding] of Object.entries(bindings)) {\n    const inputTypeName = `${capitalize(name)}Input`\n    const outputTypeName = `${capitalize(name)}Output`\n\n    // Generate input type\n    const inputType = jsonSchemaToTypeScript(binding.inputSchema, inputTypeName)\n    if (inputType.declaration) {\n      declarations.push(inputType.declaration)\n    }\n\n    // Generate output type if present\n    let outputTypeRef = 'unknown'\n    if (binding.outputSchema) {\n      const outputType = jsonSchemaToTypeScript(\n        binding.outputSchema,\n        outputTypeName,\n      )\n      if (outputType.declaration) {\n        declarations.push(outputType.declaration)\n      }\n      outputTypeRef = outputType.name\n    }\n\n    // Generate function declaration matching the actual sandbox function name\n    const description =\n      includeDescriptions && binding.description\n        ? `/** ${binding.description} */\\n`\n        : ''\n\n    declarations.push(\n      `${description}declare function ${name}(input: ${inputType.name}): Promise<${outputTypeRef}>;`,\n    )\n  }\n\n  return declarations.join('\\n\\n')\n}\n\ninterface TypeResult {\n  name: string\n  declaration: string\n}\n\n/**\n * Convert a JSON Schema to a TypeScript type\n *\n * Supports basic types: string, number, boolean, object, array\n */\nexport function jsonSchemaToTypeScript(\n  schema: Record<string, unknown>,\n  typeName: string,\n): TypeResult {\n  const type = schemaToType(schema)\n\n  // For object schemas with properties, create a named interface\n  if (\n    schema.type === 'object' &&\n    schema.properties &&\n    Object.keys(schema.properties).length > 0\n  ) {\n    return {\n      name: typeName,\n      declaration: `interface ${typeName} ${type}`,\n    }\n  }\n\n  // For simple types or empty objects, create a type alias\n  return {\n    name: type,\n    declaration: '',\n  }\n}\n\n/**\n * Convert a JSON Schema to a TypeScript type string\n */\nfunction schemaToType(schema: Record<string, unknown>): string {\n  if (typeof schema !== 'object') {\n    return 'unknown'\n  }\n\n  const schemaType = schema.type\n\n  // Handle basic types\n  if (schemaType === 'string') return 'string'\n  if (schemaType === 'number' || schemaType === 'integer') return 'number'\n  if (schemaType === 'boolean') return 'boolean'\n  if (schemaType === 'null') return 'null'\n\n  // Handle arrays\n  if (schemaType === 'array') {\n    const items = schema.items as Record<string, unknown> | undefined\n    const itemType = items ? schemaToType(items) : 'unknown'\n    return `Array<${itemType}>`\n  }\n\n  // Handle objects with properties\n  if (schemaType === 'object' && schema.properties) {\n    const properties = schema.properties as Record<\n      string,\n      Record<string, unknown>\n    >\n    const required = new Set(\n      (schema.required as Array<string> | undefined) ?? [],\n    )\n\n    const props = Object.entries(properties)\n      .map(([key, propSchema]) => {\n        const optional = required.has(key) ? '' : '?'\n        const propType = schemaToType(propSchema)\n        // Handle property names that need quoting\n        const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)\n          ? key\n          : `\"${key}\"`\n        return `  ${safeName}${optional}: ${propType};`\n      })\n      .join('\\n')\n\n    return `{\\n${props}\\n}`\n  }\n\n  // Handle enums\n  if (schema.enum) {\n    const enumValues = schema.enum as Array<unknown>\n    return enumValues.map((v) => JSON.stringify(v)).join(' | ')\n  }\n\n  // Handle union types (anyOf, oneOf)\n  if (schema.anyOf || schema.oneOf) {\n    const variants = (schema.anyOf || schema.oneOf) as Array<\n      Record<string, unknown>\n    >\n    return variants.map((v) => schemaToType(v)).join(' | ')\n  }\n\n  // Handle type arrays (e.g., [\"string\", \"null\"])\n  if (Array.isArray(schemaType)) {\n    return schemaType\n      .map((t) => {\n        if (t === 'string') return 'string'\n        if (t === 'number' || t === 'integer') return 'number'\n        if (t === 'boolean') return 'boolean'\n        if (t === 'null') return 'null'\n        if (t === 'array') return 'Array<unknown>'\n        if (t === 'object') return 'object'\n        return 'unknown'\n      })\n      .join(' | ')\n  }\n\n  // Fallback for unknown schemas\n  return 'unknown'\n}\n\n/**\n * Capitalize the first letter of a string\n */\nfunction capitalize(str: string): string {\n  return str.charAt(0).toUpperCase() + str.slice(1)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -0,0 +1,238 @@
+import { LazyToolsConfig, SchemaInput, ServerTool, ToolExecutionContext } from '@tanstack/ai';
+/**
+ * Interface for isolate/sandbox drivers
+ * Each runtime environment implements this to provide sandboxed code execution
+ */
+export interface IsolateDriver {
+    /**
+     * Create a new isolated execution context with tool bindings
+     */
+    createContext: (config: IsolateConfig) => Promise<IsolateContext>;
+}
+/**
+ * Configuration for creating an isolate context
+ */
+export interface IsolateConfig {
+    /**
+     * Tools transformed into callable bindings for the sandbox
+     */
+    bindings: Record<string, ToolBinding>;
+    /**
+     * Execution timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Memory limit in MB (default: 128)
+     */
+    memoryLimit?: number;
+}
+/**
+ * Isolated execution context with tool bindings injected
+ */
+export interface IsolateContext {
+    /**
+     * Execute generated code and return results
+     */
+    execute: <T = unknown>(code: string) => Promise<ExecutionResult<T>>;
+    /**
+     * Clean up sandbox resources
+     */
+    dispose: () => Promise<void>;
+}
+/**
+ * Result of code execution in the sandbox
+ */
+export interface ExecutionResult<T = unknown> {
+    /**
+     * Whether execution completed without errors
+     */
+    success: boolean;
+    /**
+     * Return value from the executed code (if successful)
+     */
+    value?: T;
+    /**
+     * Normalized error information (if failed)
+     */
+    error?: NormalizedError;
+    /**
+     * Console output captured during execution
+     */
+    logs?: Array<string>;
+}
+/**
+ * Normalized error format for cross-runtime compatibility
+ */
+export interface NormalizedError {
+    /**
+     * Error name/type
+     */
+    name: string;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Stack trace (if available)
+     */
+    stack?: string;
+    /**
+     * Error code (if available)
+     */
+    code?: string;
+}
+/**
+ * A tool transformed into a format suitable for sandbox injection
+ */
+export interface ToolBinding {
+    /**
+     * Unique tool identifier
+     */
+    name: string;
+    /**
+     * Human-readable description for the LLM
+     */
+    description: string;
+    /**
+     * JSON Schema for tool input parameters
+     */
+    inputSchema: Record<string, unknown>;
+    /**
+     * JSON Schema for tool output (optional)
+     */
+    outputSchema?: Record<string, unknown> | undefined;
+    /**
+     * The execute function that will be injected into the sandbox.
+     * Accepts optional context for emitting custom events.
+     */
+    execute: (args: unknown, context?: ToolExecutionContext) => Promise<unknown>;
+}
+export type { ToolExecutionContext };
+/**
+ * Server-side tool types that can be passed to Code Mode.
+ *
+ * Code Mode executes tools inside a server-managed sandbox. Client tools and
+ * bare tool definitions are intentionally excluded because they do not provide
+ * a server execution implementation for the sandbox binding.
+ */
+export type CodeModeTool = ServerTool<SchemaInput, SchemaInput, string, unknown>;
+/**
+ * Configuration for createCodeModeTool
+ */
+export interface CodeModeToolConfig {
+    /**
+     * Isolate driver for sandboxed code execution
+     */
+    driver: IsolateDriver;
+    /**
+     * Tools to expose as external_* functions in the sandbox
+     */
+    tools: Array<CodeModeTool>;
+    /**
+     * Execution timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Memory limit for isolate in MB (default: 128)
+     */
+    memoryLimit?: number;
+    /**
+     * Optional function to get additional bindings dynamically.
+     * Called at execution time (each execute_typescript call) to get current skill bindings.
+     * These are merged with the static external_* bindings.
+     *
+     * @returns Record of skill bindings with skill_ prefix
+     *
+     * @example
+     * ```typescript
+     * getSkillBindings: async () => {
+     *   const skills = await storage.loadAll()
+     *   return skillsToBindings(skills, 'skill_')
+     * }
+     * ```
+     */
+    getSkillBindings?: () => Promise<Record<string, ToolBinding>>;
+    /**
+     * Optional lazy-tool discovery config. Tools marked `lazy: true` are kept out
+     * of the system prompt's full documentation and listed in a Discoverable APIs
+     * catalog instead; this tunes how much of each lazy tool's description that
+     * catalog shows. Optional — defaults to `{ includeDescription: 'none' }`.
+     */
+    lazyToolsConfig?: LazyToolsConfig;
+    /**
+     * Optional escape hatch to swap out the TypeScript-stripping step.
+     *
+     * Receives the raw model-generated code and must return runnable JavaScript
+     * with all TypeScript syntax removed. Defaults to the built-in
+     * {@link stripTypeScript}, which uses sucrase and is safe to bundle for
+     * browsers and edge runtimes (Cloudflare Workers/Pages etc.).
+     *
+     * Provide your own only to trade the edge-safe default for a faster
+     * Node-only transpiler. A custom transpiler MUST tolerate top-level `return`
+     * and `await` in its input (the default wraps the code in an async function
+     * internally to allow this).
+     *
+     * NOTE: This only affects `createCodeModeTool`. The skills helpers
+     * (`skillsToTools`, `codeModeWithSkills` in `@tanstack/ai-code-mode-skills`)
+     * call the exported `stripTypeScript` directly, so they ignore this hook — but
+     * they still get the edge-safe sucrase default, so #487 is fixed for them too;
+     * they just can't be pointed at a different transpiler.
+     *
+     * @example
+     * ```typescript
+     * // Node-only fast path using esbuild (NOT edge-safe — Node only). esbuild
+     * // rejects top-level `return`, so reuse the same async-function wrapper the
+     * // default uses, then slice the body back out. `keepNames: false` stops
+     * // esbuild injecting `__name()` helpers the sandbox can't resolve.
+     * import { transformSync } from 'esbuild'
+     * transpile: (code) => {
+     *   const out = transformSync(`async function _w(){\n${code}\n}`, {
+     *     loader: 'ts',
+     *     keepNames: false,
+     *   }).code
+     *   return out.slice(out.indexOf('{') + 1, out.lastIndexOf('}'))
+     * }
+     * ```
+     */
+    transpile?: (code: string) => string | Promise<string>;
+}
+/**
+ * Result returned by the execute_typescript tool
+ */
+export interface CodeModeToolResult {
+    /**
+     * Whether execution completed without errors
+     */
+    success: boolean;
+    /**
+     * Return value from the executed code (if successful)
+     */
+    result?: unknown;
+    /**
+     * Console output captured during execution
+     */
+    logs?: Array<string>;
+    /**
+     * Error details if execution failed
+     */
+    error?: {
+        message: string;
+        name?: string | undefined;
+        line?: number | undefined;
+    } | undefined;
+}
+/**
+ * Return shape of `createCodeMode`. `tool` (execute_typescript) and
+ * `systemPrompt` are preserved for backward compatibility; `discoveryTool` and
+ * `tools` are additive. Spread `tools` into `chat({ tools })`.
+ */
+export interface CreateCodeModeResult {
+    /** The execute_typescript tool. */
+    tool: ServerTool<SchemaInput, SchemaInput, 'execute_typescript'>;
+    /** The discover_tools tool, or null when there are no lazy tools. */
+    discoveryTool: ServerTool<SchemaInput, SchemaInput, 'discover_tools'> | null;
+    /** [tool] or [tool, discoveryTool] — the array to spread into chat({ tools }). */
+    tools: Array<ServerTool<SchemaInput, SchemaInput, string>>;
+    /** The matching system prompt. */
+    systemPrompt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-code-mode",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Secure TypeScript Code Mode for TanStack AI agents to execute sandboxed tool orchestration programs.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -54,12 +54,12 @@
   },
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0",
-    "@tanstack/ai": "0.36.0"
+    "@tanstack/ai": "0.38.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.36.0"
+    "@tanstack/ai": "0.38.0"
   },
   "scripts": {
     "build": "vite build",