@tanstack/ai-code-mode 0.1.0

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

@@ -0,0 +1,41 @@
+import { CodeModeToolConfig } from './types.js';
+/**
+ * Create both the `execute_typescript` tool and its matching system prompt
+ * from a single config object.
+ *
+ * This is the recommended way to set up Code Mode — it ensures the tool and
+ * system prompt always stay in sync.
+ *
+ * @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],
+ *   timeout: 30000,
+ * })
+ *
+ * chat({
+ *   systemPrompts: [myPrompt, systemPrompt],
+ *   tools: [tool, ...otherTools],
+ *   messages,
+ * })
+ * ```
+ */
+export declare function createCodeMode(config: CodeModeToolConfig): {
+    tool: import('@tanstack/ai').ServerTool<import('zod').ZodObject<{
+        typescriptCode: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        success: import('zod').ZodBoolean;
+        result: import('zod').ZodOptional<import('zod').ZodUnknown>;
+        logs: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodString>>;
+        error: import('zod').ZodOptional<import('zod').ZodObject<{
+            message: import('zod').ZodString;
+            name: import('zod').ZodOptional<import('zod').ZodString>;
+            line: import('zod').ZodOptional<import('zod').ZodNumber>;
+        }, import('zod/v4/core').$strip>>;
+    }, import('zod/v4/core').$strip>, "execute_typescript">;
+    systemPrompt: string;
+};

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

@@ -0,0 +1,12 @@
+import { createCodeModeTool } from "./create-code-mode-tool.js";
+import { createCodeModeSystemPrompt } from "./create-system-prompt.js";
+function createCodeMode(config) {
+  return {
+    tool: createCodeModeTool(config),
+    systemPrompt: createCodeModeSystemPrompt(config)
+  };
+}
+export {
+  createCodeMode
+};
+//# sourceMappingURL=create-code-mode.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-code-mode.js","sources":["../../src/create-code-mode.ts"],"sourcesContent":["import { createCodeModeTool } from './create-code-mode-tool'\nimport { createCodeModeSystemPrompt } from './create-system-prompt'\nimport type { CodeModeToolConfig } from './types'\n\n/**\n * Create both the `execute_typescript` tool and its matching system prompt\n * from a single config object.\n *\n * This is the recommended way to set up Code Mode — it ensures the tool and\n * system prompt always stay in sync.\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 *   timeout: 30000,\n * })\n *\n * chat({\n *   systemPrompts: [myPrompt, systemPrompt],\n *   tools: [tool, ...otherTools],\n *   messages,\n * })\n * ```\n */\nexport function createCodeMode(config: CodeModeToolConfig) {\n  return {\n    tool: createCodeModeTool(config),\n    systemPrompt: createCodeModeSystemPrompt(config),\n  }\n}\n"],"names":[],"mappings":";;AA6BO,SAAS,eAAe,QAA4B;AACzD,SAAO;AAAA,IACL,MAAM,mBAAmB,MAAM;AAAA,IAC/B,cAAc,2BAA2B,MAAM;AAAA,EAAA;AAEnD;"}

package/dist/esm/create-system-prompt.d.ts

@@ -0,0 +1,24 @@
+import { CodeModeToolConfig } from './types.js';
+/**
+ * Create a system prompt snippet that documents the execute_typescript tool
+ * and all available external_* functions.
+ *
+ * Add this to your system prompts array when using createCodeModeTool.
+ *
+ * @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],
+ * })
+ *
+ * chat({
+ *   systemPrompts: ['You are a helpful assistant.', systemPrompt],
+ *   tools: [tool, ...otherTools],
+ * })
+ * ```
+ */
+export declare function createCodeModeSystemPrompt(config: CodeModeToolConfig): string;

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

@@ -0,0 +1,66 @@
+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 bindings = toolsToBindings(tools, "external_");
+  const typeStubs = generateTypeStubs(bindings);
+  const functionDocs = Object.entries(bindings).map(([name, binding]) => {
+    const doc = `- \`${name}(input)\`: ${binding.description}`;
+    return doc;
+  }).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}
+\`\`\`
+
+### 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 { 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\n  // Transform tools to bindings with external_ prefix to generate correct type stubs\n  const bindings = toolsToBindings(tools, 'external_')\n\n  // Generate TypeScript type stubs for the external functions\n  const typeStubs = generateTypeStubs(bindings)\n\n  // Build function documentation\n  const functionDocs = Object.entries(bindings)\n    .map(([name, binding]) => {\n      const doc = `- \\`${name}(input)\\`: ${binding.description}`\n      return doc\n    })\n    .join('\\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\\`\\`\\`\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":";;AA0BO,SAAS,2BAA2B,QAAoC;AAC7E,QAAM,EAAE,UAAU;AAGlB,QAAM,WAAW,gBAAgB,OAAO,WAAW;AAGnD,QAAM,YAAY,kBAAkB,QAAQ;AAG5C,QAAM,eAAe,OAAO,QAAQ,QAAQ,EACzC,IAAI,CAAC,CAAC,MAAM,OAAO,MAAM;AACxB,UAAM,MAAM,OAAO,IAAI,cAAc,QAAQ,WAAW;AACxD,WAAO;AAAA,EACT,CAAC,EACA,KAAK,IAAI;AAEZ,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;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;AA4BX;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,10 @@
+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 { 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, CodeModeToolResult, IsolateDriver, IsolateConfig, IsolateContext, ExecutionResult, NormalizedError, ToolBinding, CodeModeTool, ToolExecutionContext, } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,23 @@
+import { createCodeModeTool } from "./create-code-mode-tool.js";
+import { createCodeModeSystemPrompt } from "./create-system-prompt.js";
+import { createCodeMode } from "./create-code-mode.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,
+  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,23 @@
+/**
+ * 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 esbuild's transform API which is extremely fast and handles all
+ * TypeScript syntax including:
+ * - Type annotations (: string, : number, etc.)
+ * - Generic types (Array<T>, Record<K, V>, etc.)
+ * - Interface and type declarations
+ * - Type assertions
+ * - Enums (converted to JavaScript objects)
+ *
+ * The code is wrapped in an async function before transformation to allow
+ * top-level `return` and `await` statements, then unwrapped after.
+ *
+ * @param code - TypeScript or JavaScript code
+ * @returns Plain JavaScript code with all type syntax removed
+ * @throws Error if esbuild 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,52 @@
+import { transform } from "esbuild";
+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 = await transform(wrappedCode, {
+    loader: "ts",
+    // Don't minify - keep the code readable for debugging
+    minify: false,
+    // Don't use keepNames as it adds __name() helper calls that aren't available in the sandbox
+    keepNames: false,
+    // Target modern JavaScript (ES2022 has top-level await)
+    target: "es2022"
+  });
+  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 'esbuild'\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 esbuild's transform API which is extremely fast and handles all\n * TypeScript syntax including:\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 * The code is wrapped in an async function before transformation to allow\n * top-level `return` and `await` statements, then unwrapped after.\n *\n * @param code - TypeScript or JavaScript code\n * @returns Plain JavaScript code with all type syntax removed\n * @throws Error if esbuild fails (e.g., syntax error) or wrapper extraction fails\n */\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 esbuild's ESM format doesn't allow top-level returns\n  const wrappedCode = `async function ${WRAPPER_START}() {\\n${code}\\n}; ${WRAPPER_END}`\n\n  const result = await transform(wrappedCode, {\n    loader: 'ts',\n    // Don't minify - keep the code readable for debugging\n    minify: false,\n    // Don't use keepNames as it adds __name() helper calls that aren't available in the sandbox\n    keepNames: false,\n    // Target modern JavaScript (ES2022 has top-level await)\n    target: 'es2022',\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;AAwBpB,eAAsB,gBAAgB,MAA+B;AAGnE,QAAM,cAAc,kBAAkB,aAAa;AAAA,EAAS,IAAI;AAAA,KAAQ,WAAW;AAEnF,QAAM,SAAS,MAAM,UAAU,aAAa;AAAA,IAC1C,QAAQ;AAAA;AAAA,IAER,QAAQ;AAAA;AAAA,IAER,WAAW;AAAA;AAAA,IAEX,QAAQ;AAAA,EAAA,CACT;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 as object).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,176 @@
+import { ServerTool, ToolDefinition, 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>;
+    /**
+     * 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 };
+/**
+ * Tool types that can be passed to Code Mode
+ */
+export type CodeModeTool = ServerTool<any, any, any> | ToolDefinition<any, any, any>;
+/**
+ * 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>>;
+}
+/**
+ * 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;
+        line?: number;
+    };
+}