@tanstack/ai-code-mode 0.3.0 → 0.3.1

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 readonly 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,29 @@
+class InMemoryAgentStore {
+  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 readonly 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,EACnC,+BAAe,IAAA;AAAA,EAEhC,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,25 @@
+import { ToolExecutionContext } from '@tanstack/ai';
+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: ToolExecutionContext['emitCustomEvent']): Record<string, ToolBinding>;

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

@@ -0,0 +1,94 @@
+import { convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema } 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;
+  if (typeof tool.execute !== "function") {
+    throw new Error(
+      `Tool "${tool.name}" does not have an execute function. Code Mode requires server tools with implementations.`
+    );
+  }
+  const toolExecute = tool.execute;
+  const execute = async (args, context) => {
+    let input = args;
+    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {
+      try {
+        input = parseWithStandardSchema(tool.inputSchema, args);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Validation failed";
+        throw new Error(
+          `Input validation failed for tool ${tool.name}: ${message}`
+        );
+      }
+    }
+    let result = await Promise.resolve(toolExecute(input, context));
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
+      try {
+        result = parseWithStandardSchema(tool.outputSchema, result);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Validation failed";
+        throw new Error(
+          `Output validation failed for tool ${tool.name}: ${message}`
+        );
+      }
+    }
+    return result;
+  };
+  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 {\n  convertSchemaToJsonSchema,\n  isStandardSchema,\n  parseWithStandardSchema,\n} 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  if (typeof tool.execute !== 'function') {\n    throw new Error(\n      `Tool \"${tool.name}\" does not have an execute function. ` +\n        `Code Mode requires server tools with implementations.`,\n    )\n  }\n\n  const toolExecute = tool.execute\n  const execute = async (args: unknown, context?: ToolExecutionContext) => {\n    let input = args\n    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {\n      try {\n        input = parseWithStandardSchema(tool.inputSchema, args)\n      } catch (error) {\n        const message =\n          error instanceof Error ? error.message : 'Validation failed'\n        throw new Error(\n          `Input validation failed for tool ${tool.name}: ${message}`,\n        )\n      }\n    }\n\n    let result = await Promise.resolve(toolExecute(input, context))\n\n    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n      try {\n        result = parseWithStandardSchema(tool.outputSchema, result)\n      } catch (error) {\n        const message =\n          error instanceof Error ? error.message : 'Validation failed'\n        throw new Error(\n          `Output validation failed for tool ${tool.name}: ${message}`,\n        )\n      }\n    }\n\n    return result\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: ToolExecutionContext['emitCustomEvent'],\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":";AAcO,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;AAEJ,MAAI,OAAO,KAAK,YAAY,YAAY;AACtC,UAAM,IAAI;AAAA,MACR,SAAS,KAAK,IAAI;AAAA,IAAA;AAAA,EAGtB;AAEA,QAAM,cAAc,KAAK;AACzB,QAAM,UAAU,OAAO,MAAe,YAAmC;AACvE,QAAI,QAAQ;AACZ,QAAI,KAAK,eAAe,iBAAiB,KAAK,WAAW,GAAG;AAC1D,UAAI;AACF,gBAAQ,wBAAwB,KAAK,aAAa,IAAI;AAAA,MACxD,SAAS,OAAO;AACd,cAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU;AAC3C,cAAM,IAAI;AAAA,UACR,oCAAoC,KAAK,IAAI,KAAK,OAAO;AAAA,QAAA;AAAA,MAE7D;AAAA,IACF;AAEA,QAAI,SAAS,MAAM,QAAQ,QAAQ,YAAY,OAAO,OAAO,CAAC;AAE9D,QAAI,KAAK,gBAAgB,iBAAiB,KAAK,YAAY,GAAG;AAC5D,UAAI;AACF,iBAAS,wBAAwB,KAAK,cAAc,MAAM;AAAA,MAC5D,SAAS,OAAO;AACd,cAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU;AAC3C,cAAM,IAAI;AAAA,UACR,qCAAqC,KAAK,IAAI,KAAK,OAAO;AAAA,QAAA;AAAA,MAE9D;AAAA,IACF;AAEA,WAAO;AAAA,EACT;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,146 @@
+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,
+    transpile = stripTypeScript
+  } = 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 transpile(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 eager = tools.filter((t) => !t.lazy);
+  const hasLazy = tools.some((t) => t.lazy);
+  const externalFunctions = eager.map((t) => `external_${t.name}`).join(", ");
+  const discoverable = hasLazy ? ` Additional functions can be discovered via the discover_tools tool.` : "";
+  return `Execute TypeScript code in a secure sandbox environment. The code can use these external API functions: ${externalFunctions}.${discoverable} 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    transpile = stripTypeScript,\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 the\n        // transpiler — sucrase by default, or a user-supplied `transpile`)\n        let strippedCode: string\n        try {\n          strippedCode = await transpile(typescriptCode)\n        } catch (error) {\n          // Type/syntax error from the transpiler\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 eager = tools.filter((t) => !t.lazy)\n  const hasLazy = tools.some((t) => t.lazy)\n  const externalFunctions = eager.map((t) => `external_${t.name}`).join(', ')\n\n  const discoverable = hasLazy\n    ? ` Additional functions can be discovered via the discover_tools tool.`\n    : ''\n\n  return (\n    `Execute TypeScript code in a secure sandbox environment. ` +\n    `The code can use these external API functions: ${externalFunctions}.${discoverable} ` +\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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"}

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

@@ -0,0 +1,23 @@
+import { CodeModeToolConfig, CreateCodeModeResult } from './types.js';
+/**
+ * Create the `execute_typescript` tool, its matching system prompt, and (when
+ * any tools are marked `lazy: true`) a `discover_tools` companion tool.
+ *
+ * @example
+ * ```typescript
+ * import { createCodeMode } from '@tanstack/ai-code-mode'
+ * import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
+ *
+ * const { tools, systemPrompt } = createCodeMode({
+ *   driver: createNodeIsolateDriver(),
+ *   tools: [weatherTool, rarelyUsedTool], // mark rarelyUsedTool lazy: true
+ * })
+ *
+ * chat({
+ *   systemPrompts: [myPrompt, systemPrompt],
+ *   tools: [...tools, ...otherTools],
+ *   messages,
+ * })
+ * ```
+ */
+export declare function createCodeMode(config: CodeModeToolConfig): CreateCodeModeResult;

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

@@ -0,0 +1,19 @@
+import { createCodeModeTool } from "./create-code-mode-tool.js";
+import { createCodeModeSystemPrompt } from "./create-system-prompt.js";
+import { createDiscoveryTool } from "./create-discovery-tool.js";
+function createCodeMode(config) {
+  const tool = createCodeModeTool(config);
+  const systemPrompt = createCodeModeSystemPrompt(config);
+  const lazyTools = config.tools.filter((t) => t.lazy);
+  const discoveryTool = lazyTools.length > 0 ? createDiscoveryTool(lazyTools, config.lazyToolsConfig) : null;
+  return {
+    tool,
+    discoveryTool,
+    tools: discoveryTool ? [tool, discoveryTool] : [tool],
+    systemPrompt
+  };
+}
+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 { createDiscoveryTool } from './create-discovery-tool'\nimport type { CodeModeToolConfig, CreateCodeModeResult } from './types'\n\n/**\n * Create the `execute_typescript` tool, its matching system prompt, and (when\n * any tools are marked `lazy: true`) a `discover_tools` companion tool.\n *\n * @example\n * ```typescript\n * import { createCodeMode } from '@tanstack/ai-code-mode'\n * import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'\n *\n * const { tools, systemPrompt } = createCodeMode({\n *   driver: createNodeIsolateDriver(),\n *   tools: [weatherTool, rarelyUsedTool], // mark rarelyUsedTool lazy: true\n * })\n *\n * chat({\n *   systemPrompts: [myPrompt, systemPrompt],\n *   tools: [...tools, ...otherTools],\n *   messages,\n * })\n * ```\n */\nexport function createCodeMode(\n  config: CodeModeToolConfig,\n): CreateCodeModeResult {\n  const tool = createCodeModeTool(config)\n  const systemPrompt = createCodeModeSystemPrompt(config)\n\n  const lazyTools = config.tools.filter((t) => t.lazy)\n  const discoveryTool =\n    lazyTools.length > 0\n      ? createDiscoveryTool(lazyTools, config.lazyToolsConfig)\n      : null\n\n  return {\n    tool,\n    discoveryTool,\n    tools: discoveryTool ? [tool, discoveryTool] : [tool],\n    systemPrompt,\n  }\n}\n"],"names":[],"mappings":";;;AA0BO,SAAS,eACd,QACsB;AACtB,QAAM,OAAO,mBAAmB,MAAM;AACtC,QAAM,eAAe,2BAA2B,MAAM;AAEtD,QAAM,YAAY,OAAO,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI;AACnD,QAAM,gBACJ,UAAU,SAAS,IACf,oBAAoB,WAAW,OAAO,eAAe,IACrD;AAEN,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,OAAO,gBAAgB,CAAC,MAAM,aAAa,IAAI,CAAC,IAAI;AAAA,IACpD;AAAA,EAAA;AAEJ;"}

package/dist/esm/create-discovery-tool.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { LazyToolsConfig, ServerTool } from '@tanstack/ai';
+import { CodeModeTool } from './types.js';
+declare const discoverInputSchema: z.ZodObject<{
+    toolNames: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const discoverOutputSchema: z.ZodObject<{
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        typeStub: z.ZodString;
+    }, z.core.$strip>>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Build the `discover_tools` sibling tool for Code Mode lazy tools. The model
+ * calls it with lazy tool names and receives each one's TypeScript type stub +
+ * description, which it can then use to write correctly-typed `external_*`
+ * calls inside `execute_typescript`. The bindings themselves are always present
+ * in the sandbox — this only reveals documentation.
+ *
+ * Tools are catalogued in `external_<name>` form to match the "Discoverable
+ * APIs" section of the Code Mode system prompt; lookups tolerate either form.
+ * `lazyToolsConfig.includeDescription` controls how much of each tool's
+ * description appears in this tool's own catalog (mirroring the system prompt).
+ */
+export declare function createDiscoveryTool(lazyTools: Array<CodeModeTool>, lazyToolsConfig?: LazyToolsConfig): ServerTool<typeof discoverInputSchema, typeof discoverOutputSchema, 'discover_tools'>;
+export {};

package/dist/esm/create-discovery-tool.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { renderLazyCatalogEntry, toolDefinition } from "@tanstack/ai";
+import { toolToBinding } from "./bindings/tool-to-binding.js";
+import { generateTypeStubs } from "./type-generator/json-schema-to-ts.js";
+const discoverInputSchema = z.object({
+  toolNames: z.array(z.string()).describe(
+    'Names of tools to discover, exactly as shown in the Discoverable APIs catalog. The external_ prefix is optional — both "external_fetchStocks" and "fetchStocks" resolve.'
+  )
+});
+const discoverOutputSchema = z.object({
+  tools: z.array(
+    z.object({
+      name: z.string().describe("The sandbox function name, e.g. external_fetchStocks"),
+      description: z.string(),
+      typeStub: z.string().describe("TypeScript declaration for the function")
+    })
+  ),
+  errors: z.array(z.string()).optional()
+});
+const EXTERNAL_PREFIX = "external_";
+function stripExternalPrefix(name) {
+  return name.startsWith(EXTERNAL_PREFIX) ? name.slice(EXTERNAL_PREFIX.length) : name;
+}
+function createDiscoveryTool(lazyTools, lazyToolsConfig) {
+  const lazyMap = new Map(lazyTools.map((t) => [t.name, t]));
+  const include = lazyToolsConfig?.includeDescription ?? "none";
+  const catalog = lazyTools.map(
+    (t) => renderLazyCatalogEntry(
+      `${EXTERNAL_PREFIX}${t.name}`,
+      t.description,
+      include
+    )
+  ).join(", ");
+  return toolDefinition({
+    name: "discover_tools",
+    description: `Discover full TypeScript signatures for additional sandbox APIs before using them inside execute_typescript. Discoverable tools: [${catalog}]. Pass the names exactly as shown (the external_ prefix is optional).`,
+    inputSchema: discoverInputSchema,
+    outputSchema: discoverOutputSchema
+  }).server(async ({ toolNames }) => {
+    const tools = [];
+    const errors = [];
+    for (const name of toolNames) {
+      const tool = lazyMap.get(stripExternalPrefix(name));
+      if (!tool) {
+        errors.push(`Unknown tool: '${name}'. Discoverable tools: [${catalog}]`);
+        continue;
+      }
+      const binding = toolToBinding(tool, EXTERNAL_PREFIX);
+      const typeStub = generateTypeStubs({ [binding.name]: binding });
+      tools.push({
+        name: binding.name,
+        description: tool.description,
+        typeStub
+      });
+    }
+    return errors.length > 0 ? { tools, errors } : { tools };
+  });
+}
+export {
+  createDiscoveryTool
+};
+//# sourceMappingURL=create-discovery-tool.js.map

package/dist/esm/create-discovery-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-discovery-tool.js","sources":["../../src/create-discovery-tool.ts"],"sourcesContent":["import { z } from 'zod'\nimport { renderLazyCatalogEntry, toolDefinition } from '@tanstack/ai'\nimport { toolToBinding } from './bindings/tool-to-binding'\nimport { generateTypeStubs } from './type-generator/json-schema-to-ts'\nimport type { LazyToolsConfig, ServerTool } from '@tanstack/ai'\nimport type { CodeModeTool } from './types'\n\nconst discoverInputSchema = z.object({\n  toolNames: z\n    .array(z.string())\n    .describe(\n      'Names of tools to discover, exactly as shown in the Discoverable APIs ' +\n        'catalog. The external_ prefix is optional — both \"external_fetchStocks\" ' +\n        'and \"fetchStocks\" resolve.',\n    ),\n})\n\nconst discoverOutputSchema = z.object({\n  tools: z.array(\n    z.object({\n      name: z\n        .string()\n        .describe('The sandbox function name, e.g. external_fetchStocks'),\n      description: z.string(),\n      typeStub: z.string().describe('TypeScript declaration for the function'),\n    }),\n  ),\n  errors: z.array(z.string()).optional(),\n})\n\nconst EXTERNAL_PREFIX = 'external_'\n\n/**\n * Strip a single leading `external_` prefix so the model can pass either the\n * catalog name (`external_fetchStocks`) or the bare name (`fetchStocks`).\n */\nfunction stripExternalPrefix(name: string): string {\n  return name.startsWith(EXTERNAL_PREFIX)\n    ? name.slice(EXTERNAL_PREFIX.length)\n    : name\n}\n\n/**\n * Build the `discover_tools` sibling tool for Code Mode lazy tools. The model\n * calls it with lazy tool names and receives each one's TypeScript type stub +\n * description, which it can then use to write correctly-typed `external_*`\n * calls inside `execute_typescript`. The bindings themselves are always present\n * in the sandbox — this only reveals documentation.\n *\n * Tools are catalogued in `external_<name>` form to match the \"Discoverable\n * APIs\" section of the Code Mode system prompt; lookups tolerate either form.\n * `lazyToolsConfig.includeDescription` controls how much of each tool's\n * description appears in this tool's own catalog (mirroring the system prompt).\n */\nexport function createDiscoveryTool(\n  lazyTools: Array<CodeModeTool>,\n  lazyToolsConfig?: LazyToolsConfig,\n): ServerTool<\n  typeof discoverInputSchema,\n  typeof discoverOutputSchema,\n  'discover_tools'\n> {\n  const lazyMap = new Map(lazyTools.map((t) => [t.name, t]))\n  const include = lazyToolsConfig?.includeDescription ?? 'none'\n  const catalog = lazyTools\n    .map((t) =>\n      renderLazyCatalogEntry(\n        `${EXTERNAL_PREFIX}${t.name}`,\n        t.description,\n        include,\n      ),\n    )\n    .join(', ')\n\n  return toolDefinition({\n    name: 'discover_tools' as const,\n    description:\n      `Discover full TypeScript signatures for additional sandbox APIs before ` +\n      `using them inside execute_typescript. Discoverable tools: [${catalog}]. ` +\n      `Pass the names exactly as shown (the external_ prefix is optional).`,\n    inputSchema: discoverInputSchema,\n    outputSchema: discoverOutputSchema,\n  }).server(async ({ toolNames }) => {\n    const tools: Array<{\n      name: string\n      description: string\n      typeStub: string\n    }> = []\n    const errors: Array<string> = []\n\n    for (const name of toolNames) {\n      const tool = lazyMap.get(stripExternalPrefix(name))\n      if (!tool) {\n        errors.push(`Unknown tool: '${name}'. Discoverable tools: [${catalog}]`)\n        continue\n      }\n      const binding = toolToBinding(tool, EXTERNAL_PREFIX)\n      const typeStub = generateTypeStubs({ [binding.name]: binding })\n      tools.push({\n        name: binding.name,\n        description: tool.description,\n        typeStub,\n      })\n    }\n\n    return errors.length > 0 ? { tools, errors } : { tools }\n  })\n}\n"],"names":[],"mappings":";;;;AAOA,MAAM,sBAAsB,EAAE,OAAO;AAAA,EACnC,WAAW,EACR,MAAM,EAAE,OAAA,CAAQ,EAChB;AAAA,IACC;AAAA,EAAA;AAIN,CAAC;AAED,MAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,OAAO,EAAE;AAAA,IACP,EAAE,OAAO;AAAA,MACP,MAAM,EACH,SACA,SAAS,sDAAsD;AAAA,MAClE,aAAa,EAAE,OAAA;AAAA,MACf,UAAU,EAAE,OAAA,EAAS,SAAS,yCAAyC;AAAA,IAAA,CACxE;AAAA,EAAA;AAAA,EAEH,QAAQ,EAAE,MAAM,EAAE,OAAA,CAAQ,EAAE,SAAA;AAC9B,CAAC;AAED,MAAM,kBAAkB;AAMxB,SAAS,oBAAoB,MAAsB;AACjD,SAAO,KAAK,WAAW,eAAe,IAClC,KAAK,MAAM,gBAAgB,MAAM,IACjC;AACN;AAcO,SAAS,oBACd,WACA,iBAKA;AACA,QAAM,UAAU,IAAI,IAAI,UAAU,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACzD,QAAM,UAAU,iBAAiB,sBAAsB;AACvD,QAAM,UAAU,UACb;AAAA,IAAI,CAAC,MACJ;AAAA,MACE,GAAG,eAAe,GAAG,EAAE,IAAI;AAAA,MAC3B,EAAE;AAAA,MACF;AAAA,IAAA;AAAA,EACF,EAED,KAAK,IAAI;AAEZ,SAAO,eAAe;AAAA,IACpB,MAAM;AAAA,IACN,aACE,qIAC8D,OAAO;AAAA,IAEvE,aAAa;AAAA,IACb,cAAc;AAAA,EAAA,CACf,EAAE,OAAO,OAAO,EAAE,gBAAgB;AACjC,UAAM,QAID,CAAA;AACL,UAAM,SAAwB,CAAA;AAE9B,eAAW,QAAQ,WAAW;AAC5B,YAAM,OAAO,QAAQ,IAAI,oBAAoB,IAAI,CAAC;AAClD,UAAI,CAAC,MAAM;AACT,eAAO,KAAK,kBAAkB,IAAI,2BAA2B,OAAO,GAAG;AACvE;AAAA,MACF;AACA,YAAM,UAAU,cAAc,MAAM,eAAe;AACnD,YAAM,WAAW,kBAAkB,EAAE,CAAC,QAAQ,IAAI,GAAG,SAAS;AAC9D,YAAM,KAAK;AAAA,QACT,MAAM,QAAQ;AAAA,QACd,aAAa,KAAK;AAAA,QAClB;AAAA,MAAA,CACD;AAAA,IACH;AAEA,WAAO,OAAO,SAAS,IAAI,EAAE,OAAO,OAAA,IAAW,EAAE,MAAA;AAAA,EACnD,CAAC;AACH;"}

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;