@tanstack/ai-code-mode 0.2.13 → 0.3.1

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

@@ -134,8 +134,11 @@ function createCodeModeTool(config) {
   );
 }
 function buildToolDescription(tools) {
-  const externalFunctions = tools.map((t) => `external_${t.name}`).join(", ");
-  return `Execute TypeScript code in a secure sandbox environment. The code can use these external API functions: ${externalFunctions}. All external_* calls are async and must be awaited. Return a value to pass results back. Use console.log() for debugging.`;
+  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

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

@@ -1 +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 externalFunctions = tools.map((t) => `external_${t.name}`).join(', ')\n\n  return (\n    `Execute TypeScript code in a secure sandbox environment. ` +\n    `The code can use these external API functions: ${externalFunctions}. ` +\n    `All external_* calls are async and must be awaited. ` +\n    `Return a value to pass results back. Use console.log() for debugging.`\n  )\n}\n"],"names":[],"mappings":"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"}
+{"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

@@ -1,41 +1,23 @@
-import { CodeModeToolConfig } from './types.js';
+import { CodeModeToolConfig, CreateCodeModeResult } 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.
+ * 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 { tool, systemPrompt } = createCodeMode({
+ * const { tools, systemPrompt } = createCodeMode({
  *   driver: createNodeIsolateDriver(),
- *   tools: [weatherTool, dbTool],
- *   timeout: 30000,
+ *   tools: [weatherTool, rarelyUsedTool], // mark rarelyUsedTool lazy: true
  * })
  *
  * chat({
  *   systemPrompts: [myPrompt, systemPrompt],
- *   tools: [tool, ...otherTools],
+ *   tools: [...tools, ...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", unknown>;
-    systemPrompt: string;
-};
+export declare function createCodeMode(config: CodeModeToolConfig): CreateCodeModeResult;

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

@@ -1,9 +1,16 @@
 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: createCodeModeTool(config),
-    systemPrompt: createCodeModeSystemPrompt(config)
+    tool,
+    discoveryTool,
+    tools: discoveryTool ? [tool, discoveryTool] : [tool],
+    systemPrompt
   };
 }
 export {

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

@@ -1 +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;"}
+{"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.js

@@ -1,13 +1,23 @@
+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 bindings = toolsToBindings(tools, "external_");
+  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]) => {
-    const doc = `- \`${name}(input)\`: ${binding.description}`;
-    return doc;
-  }).join("\n");
+  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.
@@ -32,7 +42,7 @@ ${functionDocs}
 
 \`\`\`typescript
 ${typeStubs}
-\`\`\`
+\`\`\`${discoverableSection}
 
 ### Example
 
@@ -44,7 +54,7 @@ const results = await Promise.all(
 );
 
 // Find the warmest city
-const warmest = results.reduce((prev, curr) => 
+const warmest = results.reduce((prev, curr) =>
   curr.temperature > prev.temperature ? curr : prev
 );
 

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

@@ -1 +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;"}
+{"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

@@ -2,9 +2,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 { 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, CodeModeToolResult, IsolateDriver, IsolateConfig, IsolateContext, ExecutionResult, NormalizedError, ToolBinding, CodeModeTool, ToolExecutionContext, } from './types.js';
+export type { CodeModeToolConfig, CreateCodeModeResult, CodeModeToolResult, IsolateDriver, IsolateConfig, IsolateContext, ExecutionResult, NormalizedError, ToolBinding, CodeModeTool, ToolExecutionContext, } from './types.js';

package/dist/esm/index.js

@@ -1,6 +1,7 @@
 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";
@@ -11,6 +12,7 @@ export {
   createCodeMode,
   createCodeModeSystemPrompt,
   createCodeModeTool,
+  createDiscoveryTool,
   createEventAwareBindings,
   generateAgentName,
   generateTypeStubs,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/esm/types.d.ts

@@ -1,4 +1,4 @@
-import { SchemaInput, ServerTool, ToolExecutionContext } from '@tanstack/ai';
+import { LazyToolsConfig, SchemaInput, ServerTool, ToolExecutionContext } from '@tanstack/ai';
 /**
  * Interface for isolate/sandbox drivers
  * Each runtime environment implements this to provide sandboxed code execution
@@ -152,6 +152,13 @@ export interface CodeModeToolConfig {
      * ```
      */
     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.
      *
@@ -214,3 +221,18 @@ export interface CodeModeToolResult {
         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.2.13",
+  "version": "0.3.1",
   "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.35.0"
+    "@tanstack/ai": "0.37.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.35.0"
+    "@tanstack/ai": "0.37.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/ai-code-mode/SKILL.md

@@ -15,6 +15,7 @@ sources:
   - 'TanStack/ai:docs/code-mode/code-mode-isolates.md'
   - 'TanStack/ai:docs/code-mode/code-mode-with-skills.md'
   - 'TanStack/ai:docs/code-mode/client-integration.md'
+  - 'TanStack/ai:docs/code-mode/lazy-tools.md'
 ---
 
 > **Note**: This skill requires familiarity with ai-core and ai-core/chat-experience. Code Mode is always used on top of a chat experience.
@@ -328,6 +329,84 @@ Skill-specific events (when using `codeModeWithSkills`):
 | `code_mode:skill_error`  | Skill failed       | `skill`, `error`, `duration`  |
 | `skill:registered`       | New skill saved    | `id`, `name`, `description`   |
 
+### 4. Lazy Tools
+
+When a large tool catalog would bloat the `execute_typescript` system prompt, mark low-priority tools `lazy: true`. Lazy tools are kept out of the full type-stub documentation and listed in a compact "Discoverable APIs" catalog instead. All sandbox bindings are always injected — `lazy` defers documentation, not callability.
+
+**Marking a tool lazy:**
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const rarelyUsedTool = toolDefinition({
+  name: 'fetchStocks',
+  description: 'Get stock prices for a ticker. Returns a price quote.',
+  inputSchema: z.object({ ticker: z.string() }),
+  outputSchema: z.object({ price: z.number() }),
+  lazy: true, // <-- opt out of full system-prompt documentation
+}).server(async ({ ticker }) => {
+  // ...
+  return { price: 0 }
+})
+```
+
+**`createCodeMode` return shape:**
+
+`createCodeMode()` returns `{ tool, discoveryTool, tools, systemPrompt }`. When lazy tools are present `discoveryTool` is a `discover_tools` server tool; otherwise it is `null`. Always spread `tools` (not just `tool`) into `chat()` so the discovery tool is registered:
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { createCodeMode } from '@tanstack/ai-code-mode'
+import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
+import { openaiText } from '@tanstack/ai-openai'
+
+const { tools, systemPrompt } = createCodeMode({
+  driver: createNodeIsolateDriver(),
+  tools: [eagerTool, rarelyUsedTool], // rarelyUsedTool has lazy: true
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  systemPrompts: ['You are a helpful assistant.', systemPrompt],
+  tools: [...tools, ...otherTools], // spread tools, not just tool
+  messages,
+})
+```
+
+`tools` equals `[tool]` when there are no lazy tools (backward compatible) and `[tool, discoveryTool]` when lazy tools exist.
+
+**`discover_tools` flow:**
+
+When the model encounters a lazy tool it has not seen before, it calls `discover_tools` with the bare name (no `external_` prefix). The tool returns each requested tool's TypeScript type stub and description. The model then writes correctly-typed `external_<name>` calls inside `execute_typescript`.
+
+```text
+Model sees: "Discoverable APIs: external_fetchStocks"
+Model calls: discover_tools({ toolNames: ["fetchStocks"] })
+Response:    { tools: [{ name: "external_fetchStocks", description: "...", typeStub: "declare function external_fetchStocks(...)" }] }
+Model writes inside execute_typescript: const result = await external_fetchStocks({ ticker: "AAPL" })
+```
+
+**`lazyToolsConfig.includeDescription`:**
+
+Control how much of each lazy tool's description appears in the Discoverable APIs catalog (the pre-discovery list):
+
+| Value              | Catalog entry                                                     |
+| ------------------ | ----------------------------------------------------------------- |
+| `'none'`           | `external_fetchStocks` (name only — default)                      |
+| `'first-sentence'` | `external_fetchStocks — Get stock prices.`                        |
+| `'full'`           | `external_fetchStocks — Get stock prices. Returns a price quote.` |
+
+```typescript
+const { tools, systemPrompt } = createCodeMode({
+  driver: createNodeIsolateDriver(),
+  tools: [eagerTool, rarelyUsedTool],
+  lazyToolsConfig: { includeDescription: 'first-sentence' },
+})
+```
+
+The same `lazyToolsConfig` option is accepted by plain `chat()` for its own lazy-tool discovery catalog (see `ai-core/tool-calling/SKILL.md`).
+
 ## Common Mistakes
 
 ### CRITICAL: Passing API keys or secrets to the sandbox environment

package/src/create-code-mode-tool.ts

@@ -245,11 +245,17 @@ export function createCodeModeTool(
  * Build the tool description including available external functions
  */
 function buildToolDescription(tools: Array<CodeModeTool>): string {
-  const externalFunctions = tools.map((t) => `external_${t.name}`).join(', ')
+  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}. ` +
+    `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.`
   )

package/src/create-code-mode.ts

@@ -1,35 +1,45 @@
 import { createCodeModeTool } from './create-code-mode-tool'
 import { createCodeModeSystemPrompt } from './create-system-prompt'
-import type { CodeModeToolConfig } from './types'
+import { createDiscoveryTool } from './create-discovery-tool'
+import type { CodeModeToolConfig, CreateCodeModeResult } from './types'
 
 /**
- * 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.
+ * 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 { tool, systemPrompt } = createCodeMode({
+ * const { tools, systemPrompt } = createCodeMode({
  *   driver: createNodeIsolateDriver(),
- *   tools: [weatherTool, dbTool],
- *   timeout: 30000,
+ *   tools: [weatherTool, rarelyUsedTool], // mark rarelyUsedTool lazy: true
  * })
  *
  * chat({
  *   systemPrompts: [myPrompt, systemPrompt],
- *   tools: [tool, ...otherTools],
+ *   tools: [...tools, ...otherTools],
  *   messages,
  * })
  * ```
  */
-export function createCodeMode(config: CodeModeToolConfig) {
+export function createCodeMode(
+  config: CodeModeToolConfig,
+): CreateCodeModeResult {
+  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: createCodeModeTool(config),
-    systemPrompt: createCodeModeSystemPrompt(config),
+    tool,
+    discoveryTool,
+    tools: discoveryTool ? [tool, discoveryTool] : [tool],
+    systemPrompt,
   }
 }

package/src/create-discovery-tool.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod'
+import { renderLazyCatalogEntry, toolDefinition } from '@tanstack/ai'
+import { toolToBinding } from './bindings/tool-to-binding'
+import { generateTypeStubs } from './type-generator/json-schema-to-ts'
+import type { LazyToolsConfig, ServerTool } from '@tanstack/ai'
+import type { CodeModeTool } from './types'
+
+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_'
+
+/**
+ * Strip a single leading `external_` prefix so the model can pass either the
+ * catalog name (`external_fetchStocks`) or the bare name (`fetchStocks`).
+ */
+function stripExternalPrefix(name: string): string {
+  return name.startsWith(EXTERNAL_PREFIX)
+    ? name.slice(EXTERNAL_PREFIX.length)
+    : name
+}
+
+/**
+ * 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 function createDiscoveryTool(
+  lazyTools: Array<CodeModeTool>,
+  lazyToolsConfig?: LazyToolsConfig,
+): ServerTool<
+  typeof discoverInputSchema,
+  typeof discoverOutputSchema,
+  'discover_tools'
+> {
+  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' as const,
+    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: Array<{
+      name: string
+      description: string
+      typeStub: string
+    }> = []
+    const errors: Array<string> = []
+
+    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 }
+  })
+}

package/src/create-system-prompt.ts

@@ -1,3 +1,4 @@
+import { renderLazyCatalogEntry } from '@tanstack/ai'
 import { toolsToBindings } from './bindings/tool-to-binding'
 import { generateTypeStubs } from './type-generator/json-schema-to-ts'
 import type { CodeModeToolConfig } from './types'
@@ -26,21 +27,35 @@ import type { CodeModeToolConfig } from './types'
  */
 export function createCodeModeSystemPrompt(config: CodeModeToolConfig): string {
   const { tools } = config
+  const include = config.lazyToolsConfig?.includeDescription ?? 'none'
 
-  // Transform tools to bindings with external_ prefix to generate correct type stubs
-  const bindings = toolsToBindings(tools, 'external_')
+  const eagerTools = tools.filter((t) => !t.lazy)
+  const lazyTools = tools.filter((t) => t.lazy)
 
-  // Generate TypeScript type stubs for the external functions
+  // Only eager tools get full type stubs + doc lines.
+  const bindings = toolsToBindings(eagerTools, 'external_')
   const typeStubs = generateTypeStubs(bindings)
 
-  // Build function documentation
   const functionDocs = Object.entries(bindings)
-    .map(([name, binding]) => {
-      const doc = `- \`${name}(input)\`: ${binding.description}`
-      return doc
-    })
+    .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.
@@ -65,7 +80,7 @@ ${functionDocs}
 
 \`\`\`typescript
 ${typeStubs}
-\`\`\`
+\`\`\`${discoverableSection}
 
 ### Example
 
@@ -77,7 +92,7 @@ const results = await Promise.all(
 );
 
 // Find the warmest city
-const warmest = results.reduce((prev, curr) => 
+const warmest = results.reduce((prev, curr) =>
   curr.temperature > prev.temperature ? curr : prev
 );
 

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
 
 export { createCodeModeSystemPrompt } from './create-system-prompt'
 export { createCodeMode } from './create-code-mode'
+export { createDiscoveryTool } from './create-discovery-tool'
 
 export {
   InMemoryAgentStore,
@@ -39,6 +40,7 @@ export { wrapCode } from './code-wrapper'
 export type {
   // Tool-based API types
   CodeModeToolConfig,
+  CreateCodeModeResult,
   CodeModeToolResult,
   // Isolate driver interfaces (used by driver packages)
   IsolateDriver,

package/src/types.ts

@@ -1,4 +1,5 @@
 import type {
+  LazyToolsConfig,
   SchemaInput,
   ServerTool,
   ToolExecutionContext,
@@ -196,6 +197,14 @@ export interface CodeModeToolConfig {
    */
   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.
    *
@@ -264,3 +273,19 @@ export interface CodeModeToolResult {
       }
     | 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
+}