@tanstack/ai 0.35.0 → 0.37.0

package/dist/esm/activities/chat/tools/lazy-tool-manager.d.ts

@@ -1,4 +1,4 @@
-import { AnyTool, Tool } from '../../../types.js';
+import { AnyTool, LazyToolsConfig, Tool } from '../../../types.js';
 /**
  * Name of the synthetic tool the LLM calls to discover lazy tools.
  *
@@ -20,6 +20,7 @@ export declare class LazyToolManager {
     private readonly discoveredTools;
     private hasNewDiscoveries;
     private readonly discoveryTool;
+    private readonly lazyToolsConfig;
     constructor(tools: ReadonlyArray<Tool>, messages: ReadonlyArray<{
         role: string;
         content?: any;
@@ -32,7 +33,7 @@ export declare class LazyToolManager {
             };
         }>;
         toolCallId?: string;
-    }>);
+    }>, lazyToolsConfig?: LazyToolsConfig);
     /**
      * Returns the set of tools that should be sent to the LLM:
      * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).

package/dist/esm/activities/chat/tools/lazy-tool-manager.js

@@ -1,4 +1,5 @@
 import { convertSchemaToJsonSchema } from "./schema-converter.js";
+import { renderLazyCatalogEntry } from "./lazy-tools.js";
 const DISCOVERY_TOOL_NAME = "__lazy__tool__discovery__";
 class LazyToolManager {
   eagerTools;
@@ -6,7 +7,9 @@ class LazyToolManager {
   discoveredTools;
   hasNewDiscoveries;
   discoveryTool;
-  constructor(tools, messages) {
+  lazyToolsConfig;
+  constructor(tools, messages, lazyToolsConfig = {}) {
+    this.lazyToolsConfig = lazyToolsConfig;
     const eager = [];
     this.lazyToolMap = /* @__PURE__ */ new Map();
     this.discoveredTools = /* @__PURE__ */ new Set();
@@ -133,8 +136,11 @@ class LazyToolManager {
       return names;
     };
     const lazyToolMap = this.lazyToolMap;
-    const allLazyNames = Array.from(this.lazyToolMap.keys());
-    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyNames.join(", ")}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`;
+    const include = this.lazyToolsConfig.includeDescription ?? "none";
+    const allLazyEntries = Array.from(this.lazyToolMap.values()).map(
+      (t) => renderLazyCatalogEntry(t.name, t.description, include)
+    );
+    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyEntries.join(", ")}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`;
     const manager = this;
     return {
       name: DISCOVERY_TOOL_NAME,

package/dist/esm/activities/chat/tools/lazy-tool-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazy-tool-manager.js","sources":["../../../../../src/activities/chat/tools/lazy-tool-manager.ts"],"sourcesContent":["import { convertSchemaToJsonSchema } from './schema-converter'\nimport type { AnyTool, Tool } from '../../../types'\n\n/**\n * Name of the synthetic tool the LLM calls to discover lazy tools.\n *\n * Exported so callers building custom message-compaction / history-trimming\n * logic can reference the discovery tool by constant instead of hard-coding\n * the string (which is an internal contract that could change).\n */\nexport const DISCOVERY_TOOL_NAME = '__lazy__tool__discovery__'\n\n/**\n * Manages lazy tool discovery for the chat agent loop.\n *\n * Lazy tools are not sent to the LLM initially. Instead, a synthetic\n * \"discovery tool\" is provided that lets the LLM discover lazy tools\n * by name, receiving their full descriptions and schemas on demand.\n */\nexport class LazyToolManager {\n  private readonly eagerTools: ReadonlyArray<Tool>\n  private readonly lazyToolMap: Map<string, Tool>\n  private readonly discoveredTools: Set<string>\n  private hasNewDiscoveries: boolean\n  private readonly discoveryTool: Tool | null\n\n  constructor(\n    tools: ReadonlyArray<Tool>,\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ) {\n    const eager: Array<Tool> = []\n    this.lazyToolMap = new Map()\n    this.discoveredTools = new Set()\n    this.hasNewDiscoveries = false\n\n    // Separate tools into eager and lazy\n    for (const tool of tools) {\n      if (tool.lazy) {\n        this.lazyToolMap.set(tool.name, tool)\n      } else {\n        eager.push(tool)\n      }\n    }\n    this.eagerTools = eager\n\n    // If no lazy tools, no discovery tool needed\n    if (this.lazyToolMap.size === 0) {\n      this.discoveryTool = null\n      return\n    }\n\n    // Scan message history to pre-populate discoveredTools\n    this.scanMessageHistory(messages)\n\n    // Create the synthetic discovery tool\n    this.discoveryTool = this.createDiscoveryTool()\n  }\n\n  /**\n   * Returns the set of tools that should be sent to the LLM:\n   * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).\n   * Resets the hasNewDiscoveries flag.\n   */\n  getActiveTools(): Array<Tool> {\n    this.hasNewDiscoveries = false\n\n    const active: Array<Tool> = [...this.eagerTools]\n\n    // Add discovered lazy tools\n    for (const name of this.discoveredTools) {\n      const tool = this.lazyToolMap.get(name)\n      if (tool) {\n        active.push(tool)\n      }\n    }\n\n    // Add discovery tool if there are still undiscovered lazy tools\n    if (\n      this.discoveryTool &&\n      this.discoveredTools.size < this.lazyToolMap.size\n    ) {\n      active.push(this.discoveryTool)\n    }\n\n    return active\n  }\n\n  /**\n   * Returns the tools that should be available for *execution* this turn.\n   *\n   * This is the advertised set (`getActiveTools()`, passed in as `activeTools`)\n   * plus the discovery tool when a pending call references it but it is no\n   * longer advertised. Once every lazy tool has been discovered the discovery\n   * tool is dropped from the advertised set, but a model may still re-request\n   * discovery (long context / hallucination); keeping it executable lets that\n   * call return the schemas again instead of failing with \"Unknown tool\".\n   *\n   * The advertised set is intentionally left unchanged — only execution lookup\n   * is widened. Operates on the already-built `activeTools`: it must NOT call\n   * `getActiveTools()`, which would reset `hasNewDiscoveries` before the\n   * post-execution refresh check in the agent loop.\n   */\n  getExecutableTools(\n    activeTools: ReadonlyArray<AnyTool>,\n    pendingToolCallNames: ReadonlyArray<string>,\n  ): ReadonlyArray<AnyTool> {\n    if (\n      this.discoveryTool &&\n      pendingToolCallNames.includes(DISCOVERY_TOOL_NAME) &&\n      !activeTools.some((t) => t.name === DISCOVERY_TOOL_NAME)\n    ) {\n      return [...activeTools, this.discoveryTool]\n    }\n    return activeTools\n  }\n\n  /**\n   * Returns whether new tools have been discovered since the last getActiveTools() call.\n   */\n  hasNewlyDiscoveredTools(): boolean {\n    return this.hasNewDiscoveries\n  }\n\n  /**\n   * Returns true if the given name is a lazy tool that has not yet been discovered.\n   */\n  isUndiscoveredLazyTool(name: string): boolean {\n    return this.lazyToolMap.has(name) && !this.discoveredTools.has(name)\n  }\n\n  /**\n   * Returns a helpful error message for when an undiscovered lazy tool is called.\n   */\n  getUndiscoveredToolError(name: string): string {\n    return `Error: Tool '${name}' must be discovered first. Call ${DISCOVERY_TOOL_NAME} with toolNames: ['${name}'] to discover it.`\n  }\n\n  /**\n   * Scans message history to find previously discovered lazy tools.\n   * Looks for assistant messages with discovery tool calls and their\n   * corresponding tool result messages.\n   */\n  private scanMessageHistory(\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ): void {\n    // Collect tool call IDs for discovery tool invocations\n    const discoveryCallIds = new Set<string>()\n\n    for (const msg of messages) {\n      if (msg.role === 'assistant' && msg.toolCalls) {\n        for (const tc of msg.toolCalls) {\n          if (tc.function.name === DISCOVERY_TOOL_NAME) {\n            discoveryCallIds.add(tc.id)\n          }\n        }\n      }\n    }\n\n    if (discoveryCallIds.size === 0) return\n\n    // Find corresponding tool result messages\n    for (const msg of messages) {\n      if (\n        msg.role === 'tool' &&\n        msg.toolCallId &&\n        discoveryCallIds.has(msg.toolCallId)\n      ) {\n        try {\n          const content =\n            typeof msg.content === 'string'\n              ? msg.content\n              : JSON.stringify(msg.content)\n          const parsed = JSON.parse(content)\n          if (parsed && Array.isArray(parsed.tools)) {\n            for (const tool of parsed.tools) {\n              if (\n                tool &&\n                typeof tool.name === 'string' &&\n                this.lazyToolMap.has(tool.name)\n              ) {\n                this.discoveredTools.add(tool.name)\n              }\n            }\n          }\n        } catch {\n          // Malformed JSON — skip gracefully\n        }\n      }\n    }\n  }\n\n  /**\n   * Creates the synthetic discovery tool that the LLM can call\n   * to discover lazy tools' descriptions and schemas.\n   */\n  private createDiscoveryTool(): Tool {\n    const undiscoveredNames = (): Array<string> => {\n      const names: Array<string> = []\n      for (const [name] of this.lazyToolMap) {\n        if (!this.discoveredTools.has(name)) {\n          names.push(name)\n        }\n      }\n      return names\n    }\n\n    const lazyToolMap = this.lazyToolMap\n\n    // Build the static description with all lazy tool names\n    const allLazyNames = Array.from(this.lazyToolMap.keys())\n    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyNames.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`\n\n    // Use the arrow function to capture `this` context\n    const manager = this\n\n    return {\n      name: DISCOVERY_TOOL_NAME,\n      description,\n      inputSchema: {\n        type: 'object',\n        properties: {\n          toolNames: {\n            type: 'array',\n            items: { type: 'string' },\n            description:\n              'List of tool names to discover. Each name must match one of the available tools.',\n          },\n        },\n        required: ['toolNames'],\n      },\n      execute: (args: { toolNames: Array<string> }) => {\n        const tools: Array<{\n          name: string\n          description: string\n          inputSchema?: any\n        }> = []\n        const errors: Array<string> = []\n\n        for (const name of args.toolNames) {\n          const tool = lazyToolMap.get(name)\n          if (tool) {\n            // Only flag a refresh for genuinely new discoveries. Re-requesting\n            // an already-discovered tool still returns its schema below (the\n            // model asked for it), but must not trigger a redundant tool-list\n            // refresh + continue in the agent loop.\n            if (!manager.discoveredTools.has(name)) {\n              manager.discoveredTools.add(name)\n              manager.hasNewDiscoveries = true\n            }\n            const jsonSchema = tool.inputSchema\n              ? convertSchemaToJsonSchema(tool.inputSchema)\n              : undefined\n            tools.push({\n              name: tool.name,\n              description: tool.description,\n              ...(jsonSchema ? { inputSchema: jsonSchema } : {}),\n            })\n          } else {\n            errors.push(\n              `Unknown tool: '${name}'. Available tools: [${undiscoveredNames().join(', ')}]`,\n            )\n          }\n        }\n\n        const result: {\n          tools: typeof tools\n          errors?: Array<string>\n        } = { tools }\n\n        if (errors.length > 0) {\n          result.errors = errors\n        }\n\n        return result\n      },\n    }\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"lazy-tool-manager.js","sources":["../../../../../src/activities/chat/tools/lazy-tool-manager.ts"],"sourcesContent":["import { convertSchemaToJsonSchema } from './schema-converter'\nimport { renderLazyCatalogEntry } from './lazy-tools'\nimport type { AnyTool, LazyToolsConfig, Tool } from '../../../types'\n\n/**\n * Name of the synthetic tool the LLM calls to discover lazy tools.\n *\n * Exported so callers building custom message-compaction / history-trimming\n * logic can reference the discovery tool by constant instead of hard-coding\n * the string (which is an internal contract that could change).\n */\nexport const DISCOVERY_TOOL_NAME = '__lazy__tool__discovery__'\n\n/**\n * Manages lazy tool discovery for the chat agent loop.\n *\n * Lazy tools are not sent to the LLM initially. Instead, a synthetic\n * \"discovery tool\" is provided that lets the LLM discover lazy tools\n * by name, receiving their full descriptions and schemas on demand.\n */\nexport class LazyToolManager {\n  private readonly eagerTools: ReadonlyArray<Tool>\n  private readonly lazyToolMap: Map<string, Tool>\n  private readonly discoveredTools: Set<string>\n  private hasNewDiscoveries: boolean\n  private readonly discoveryTool: Tool | null\n  private readonly lazyToolsConfig: LazyToolsConfig\n\n  constructor(\n    tools: ReadonlyArray<Tool>,\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n    lazyToolsConfig: LazyToolsConfig = {},\n  ) {\n    this.lazyToolsConfig = lazyToolsConfig\n    const eager: Array<Tool> = []\n    this.lazyToolMap = new Map()\n    this.discoveredTools = new Set()\n    this.hasNewDiscoveries = false\n\n    // Separate tools into eager and lazy\n    for (const tool of tools) {\n      if (tool.lazy) {\n        this.lazyToolMap.set(tool.name, tool)\n      } else {\n        eager.push(tool)\n      }\n    }\n    this.eagerTools = eager\n\n    // If no lazy tools, no discovery tool needed\n    if (this.lazyToolMap.size === 0) {\n      this.discoveryTool = null\n      return\n    }\n\n    // Scan message history to pre-populate discoveredTools\n    this.scanMessageHistory(messages)\n\n    // Create the synthetic discovery tool\n    this.discoveryTool = this.createDiscoveryTool()\n  }\n\n  /**\n   * Returns the set of tools that should be sent to the LLM:\n   * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).\n   * Resets the hasNewDiscoveries flag.\n   */\n  getActiveTools(): Array<Tool> {\n    this.hasNewDiscoveries = false\n\n    const active: Array<Tool> = [...this.eagerTools]\n\n    // Add discovered lazy tools\n    for (const name of this.discoveredTools) {\n      const tool = this.lazyToolMap.get(name)\n      if (tool) {\n        active.push(tool)\n      }\n    }\n\n    // Add discovery tool if there are still undiscovered lazy tools\n    if (\n      this.discoveryTool &&\n      this.discoveredTools.size < this.lazyToolMap.size\n    ) {\n      active.push(this.discoveryTool)\n    }\n\n    return active\n  }\n\n  /**\n   * Returns the tools that should be available for *execution* this turn.\n   *\n   * This is the advertised set (`getActiveTools()`, passed in as `activeTools`)\n   * plus the discovery tool when a pending call references it but it is no\n   * longer advertised. Once every lazy tool has been discovered the discovery\n   * tool is dropped from the advertised set, but a model may still re-request\n   * discovery (long context / hallucination); keeping it executable lets that\n   * call return the schemas again instead of failing with \"Unknown tool\".\n   *\n   * The advertised set is intentionally left unchanged — only execution lookup\n   * is widened. Operates on the already-built `activeTools`: it must NOT call\n   * `getActiveTools()`, which would reset `hasNewDiscoveries` before the\n   * post-execution refresh check in the agent loop.\n   */\n  getExecutableTools(\n    activeTools: ReadonlyArray<AnyTool>,\n    pendingToolCallNames: ReadonlyArray<string>,\n  ): ReadonlyArray<AnyTool> {\n    if (\n      this.discoveryTool &&\n      pendingToolCallNames.includes(DISCOVERY_TOOL_NAME) &&\n      !activeTools.some((t) => t.name === DISCOVERY_TOOL_NAME)\n    ) {\n      return [...activeTools, this.discoveryTool]\n    }\n    return activeTools\n  }\n\n  /**\n   * Returns whether new tools have been discovered since the last getActiveTools() call.\n   */\n  hasNewlyDiscoveredTools(): boolean {\n    return this.hasNewDiscoveries\n  }\n\n  /**\n   * Returns true if the given name is a lazy tool that has not yet been discovered.\n   */\n  isUndiscoveredLazyTool(name: string): boolean {\n    return this.lazyToolMap.has(name) && !this.discoveredTools.has(name)\n  }\n\n  /**\n   * Returns a helpful error message for when an undiscovered lazy tool is called.\n   */\n  getUndiscoveredToolError(name: string): string {\n    return `Error: Tool '${name}' must be discovered first. Call ${DISCOVERY_TOOL_NAME} with toolNames: ['${name}'] to discover it.`\n  }\n\n  /**\n   * Scans message history to find previously discovered lazy tools.\n   * Looks for assistant messages with discovery tool calls and their\n   * corresponding tool result messages.\n   */\n  private scanMessageHistory(\n    messages: ReadonlyArray<{\n      role: string\n      content?: any\n      toolCalls?: Array<{\n        id: string\n        type: string\n        function: { name: string; arguments: string }\n      }>\n      toolCallId?: string\n    }>,\n  ): void {\n    // Collect tool call IDs for discovery tool invocations\n    const discoveryCallIds = new Set<string>()\n\n    for (const msg of messages) {\n      if (msg.role === 'assistant' && msg.toolCalls) {\n        for (const tc of msg.toolCalls) {\n          if (tc.function.name === DISCOVERY_TOOL_NAME) {\n            discoveryCallIds.add(tc.id)\n          }\n        }\n      }\n    }\n\n    if (discoveryCallIds.size === 0) return\n\n    // Find corresponding tool result messages\n    for (const msg of messages) {\n      if (\n        msg.role === 'tool' &&\n        msg.toolCallId &&\n        discoveryCallIds.has(msg.toolCallId)\n      ) {\n        try {\n          const content =\n            typeof msg.content === 'string'\n              ? msg.content\n              : JSON.stringify(msg.content)\n          const parsed = JSON.parse(content)\n          if (parsed && Array.isArray(parsed.tools)) {\n            for (const tool of parsed.tools) {\n              if (\n                tool &&\n                typeof tool.name === 'string' &&\n                this.lazyToolMap.has(tool.name)\n              ) {\n                this.discoveredTools.add(tool.name)\n              }\n            }\n          }\n        } catch {\n          // Malformed JSON — skip gracefully\n        }\n      }\n    }\n  }\n\n  /**\n   * Creates the synthetic discovery tool that the LLM can call\n   * to discover lazy tools' descriptions and schemas.\n   */\n  private createDiscoveryTool(): Tool {\n    const undiscoveredNames = (): Array<string> => {\n      const names: Array<string> = []\n      for (const [name] of this.lazyToolMap) {\n        if (!this.discoveredTools.has(name)) {\n          names.push(name)\n        }\n      }\n      return names\n    }\n\n    const lazyToolMap = this.lazyToolMap\n\n    // Build the static description, rendering each entry per includeDescription.\n    // With the default 'none' this is byte-identical to the legacy output.\n    const include = this.lazyToolsConfig.includeDescription ?? 'none'\n    const allLazyEntries = Array.from(this.lazyToolMap.values()).map((t) =>\n      renderLazyCatalogEntry(t.name, t.description, include),\n    )\n    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyEntries.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`\n\n    // Use the arrow function to capture `this` context\n    const manager = this\n\n    return {\n      name: DISCOVERY_TOOL_NAME,\n      description,\n      inputSchema: {\n        type: 'object',\n        properties: {\n          toolNames: {\n            type: 'array',\n            items: { type: 'string' },\n            description:\n              'List of tool names to discover. Each name must match one of the available tools.',\n          },\n        },\n        required: ['toolNames'],\n      },\n      execute: (args: { toolNames: Array<string> }) => {\n        const tools: Array<{\n          name: string\n          description: string\n          inputSchema?: any\n        }> = []\n        const errors: Array<string> = []\n\n        for (const name of args.toolNames) {\n          const tool = lazyToolMap.get(name)\n          if (tool) {\n            // Only flag a refresh for genuinely new discoveries. Re-requesting\n            // an already-discovered tool still returns its schema below (the\n            // model asked for it), but must not trigger a redundant tool-list\n            // refresh + continue in the agent loop.\n            if (!manager.discoveredTools.has(name)) {\n              manager.discoveredTools.add(name)\n              manager.hasNewDiscoveries = true\n            }\n            const jsonSchema = tool.inputSchema\n              ? convertSchemaToJsonSchema(tool.inputSchema)\n              : undefined\n            tools.push({\n              name: tool.name,\n              description: tool.description,\n              ...(jsonSchema ? { inputSchema: jsonSchema } : {}),\n            })\n          } else {\n            errors.push(\n              `Unknown tool: '${name}'. Available tools: [${undiscoveredNames().join(', ')}]`,\n            )\n          }\n        }\n\n        const result: {\n          tools: typeof tools\n          errors?: Array<string>\n        } = { tools }\n\n        if (errors.length > 0) {\n          result.errors = errors\n        }\n\n        return result\n      },\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/activities/chat/tools/lazy-tools.d.ts

@@ -0,0 +1,15 @@
+import { LazyToolsConfig } from '../../../types.js';
+/**
+ * Extract the first sentence of a description (up to the first ., !, or ?
+ * followed by whitespace or end-of-string). Falls back to the whole trimmed
+ * string when there is no sentence terminator.
+ */
+export declare function firstSentence(text: string): string;
+/**
+ * Render one entry in a lazy-tool catalog according to `includeDescription`.
+ * - 'none' (default) → bare name (preserves legacy chat behavior)
+ * - 'first-sentence' → `name — <first sentence>`
+ * - 'full' → `name — <full description>`
+ * Falls back to the bare name when there is no description.
+ */
+export declare function renderLazyCatalogEntry(name: string, description: string, includeDescription?: LazyToolsConfig['includeDescription']): string;

package/dist/esm/activities/chat/tools/lazy-tools.js

@@ -0,0 +1,16 @@
+function firstSentence(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+  const match = trimmed.match(/^.*?[.!?](?=\s|$)/);
+  return (match ? match[0] : trimmed).trim();
+}
+function renderLazyCatalogEntry(name, description, includeDescription = "none") {
+  if (includeDescription === "none" || !description.trim()) return name;
+  const desc = includeDescription === "first-sentence" ? firstSentence(description) : description.trim();
+  return desc ? `${name} — ${desc}` : name;
+}
+export {
+  firstSentence,
+  renderLazyCatalogEntry
+};
+//# sourceMappingURL=lazy-tools.js.map

package/dist/esm/activities/chat/tools/lazy-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-tools.js","sources":["../../../../../src/activities/chat/tools/lazy-tools.ts"],"sourcesContent":["import type { LazyToolsConfig } from '../../../types'\n\n/**\n * Extract the first sentence of a description (up to the first ., !, or ?\n * followed by whitespace or end-of-string). Falls back to the whole trimmed\n * string when there is no sentence terminator.\n */\nexport function firstSentence(text: string): string {\n  const trimmed = text.trim()\n  if (!trimmed) return ''\n  const match = trimmed.match(/^.*?[.!?](?=\\s|$)/)\n  return (match ? match[0] : trimmed).trim()\n}\n\n/**\n * Render one entry in a lazy-tool catalog according to `includeDescription`.\n * - 'none' (default) → bare name (preserves legacy chat behavior)\n * - 'first-sentence' → `name — <first sentence>`\n * - 'full' → `name — <full description>`\n * Falls back to the bare name when there is no description.\n */\nexport function renderLazyCatalogEntry(\n  name: string,\n  description: string,\n  includeDescription: LazyToolsConfig['includeDescription'] = 'none',\n): string {\n  if (includeDescription === 'none' || !description.trim()) return name\n  const desc =\n    includeDescription === 'first-sentence'\n      ? firstSentence(description)\n      : description.trim()\n  return desc ? `${name} — ${desc}` : name\n}\n"],"names":[],"mappings":"AAOO,SAAS,cAAc,MAAsB;AAClD,QAAM,UAAU,KAAK,KAAA;AACrB,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,QAAQ,QAAQ,MAAM,mBAAmB;AAC/C,UAAQ,QAAQ,MAAM,CAAC,IAAI,SAAS,KAAA;AACtC;AASO,SAAS,uBACd,MACA,aACA,qBAA4D,QACpD;AACR,MAAI,uBAAuB,UAAU,CAAC,YAAY,KAAA,EAAQ,QAAO;AACjE,QAAM,OACJ,uBAAuB,mBACnB,cAAc,WAAW,IACzB,YAAY,KAAA;AAClB,SAAO,OAAO,GAAG,IAAI,MAAM,IAAI,KAAK;AACtC;"}

package/dist/esm/index.d.ts

@@ -23,6 +23,7 @@ export type { GenerationMiddleware, GenerationMiddlewareContext, GenerationActiv
 export { createCapability, defineChatMiddleware, createChatMiddleware, } from './activities/chat/middleware/index.js';
 export type { Capability, CapabilityHandle, CapabilityContext, CapabilityGetter, CapabilityProvider, } from './activities/chat/middleware/index.js';
 export * from './types.js';
+export { firstSentence, renderLazyCatalogEntry, } from './activities/chat/tools/lazy-tools.js';
 export { buildBaseUsage, type BaseUsageInput } from './utilities/usage.js';
 export { resolveMediaPrompt } from './utilities/media-prompt.js';
 export type { ResolvedMediaPrompt } from './utilities/media-prompt.js';

package/dist/esm/index.js

@@ -14,6 +14,7 @@ import { DISCOVERY_TOOL_NAME } from "./activities/chat/tools/lazy-tool-manager.j
 import { brandProviderTool } from "./tools/provider-tool.js";
 import { combineStrategies, maxIterations, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
 import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
+import { firstSentence, renderLazyCatalogEntry } from "./activities/chat/tools/lazy-tools.js";
 import { buildBaseUsage } from "./utilities/usage.js";
 import { resolveMediaPrompt } from "./utilities/media-prompt.js";
 import { normalizeSystemPrompts } from "./system-prompts.js";
@@ -71,6 +72,7 @@ export {
   defineChatMiddleware,
   detectImageMimeType,
   extendAdapter,
+  firstSentence,
   generateAudio,
   generateImage,
   generateMessageId,
@@ -91,6 +93,7 @@ export {
   parsePartialJSON,
   parseWithStandardSchema,
   realtimeToken,
+  renderLazyCatalogEntry,
   resolveMediaPrompt,
   streamToText,
   summarize,

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

@@ -486,11 +486,26 @@ export interface Tool<TInput extends SchemaInput = SchemaInput, TOutput extends
     execute?: ToolExecuteFunction<TInput, TOutput, TContext> | undefined;
     /** If true, tool execution requires user approval before running. Works with both server and client tools. */
     needsApproval?: boolean;
-    /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Only meaningful when used with chat(). */
+    /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). */
     lazy?: boolean;
     /** Additional metadata for adapters or custom extensions */
     metadata?: Record<string, any> | undefined;
 }
+/**
+ * Configuration for the lazy-tool discovery catalog, shared by chat() and
+ * Code Mode. Optional in both — lazy behavior is triggered purely by tools
+ * marked `lazy: true`; this only tunes how much of each lazy tool's
+ * description appears in the pre-discovery catalog. The post-discovery payload
+ * always returns the full description + schema.
+ */
+export interface LazyToolsConfig {
+    /**
+     * How much of each lazy tool's description appears in the pre-discovery
+     * catalog (the names list shown before the model discovers the tool).
+     * @default 'none'
+     */
+    includeDescription?: 'full' | 'first-sentence' | 'none';
+}
 export type AnyTool = Omit<Tool<any, any, any, any>, 'execute'> & {
     execute?: ((args: any, context?: any) => any) | undefined;
 };
@@ -635,6 +650,12 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      */
     systemPrompts?: Array<SystemPrompt>;
     agentLoopStrategy?: AgentLoopStrategy;
+    /**
+     * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
+     * Tunes how much of each lazy tool's description appears in the discovery
+     * catalog. Optional — defaults to `{ includeDescription: 'none' }`.
+     */
+    lazyToolsConfig?: LazyToolsConfig;
     /**
      * Observability metadata attached to this call. Surfaced to middleware,
      * devtools, and the event client; values may be arbitrarily structured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -76,8 +76,8 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.6.6",
-    "@tanstack/ai-utils": "0.3.0"
+    "@tanstack/ai-event-client": "0.6.8",
+    "@tanstack/ai-utils": "0.3.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/tool-calling/SKILL.md

@@ -360,7 +360,7 @@ const compareProducts = compareProductsDef.server(async ({ productIds }) => {
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-4o'),
+    adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, compareProducts],
     agentLoopStrategy: maxIterations(20),
@@ -375,6 +375,31 @@ gets the full schema, then calls `compareProducts` directly.
 Once discovered, a tool stays available for the conversation.
 When all lazy tools are discovered, the discovery tool is removed automatically.
 
+### Tuning the lazy catalog with `lazyToolsConfig`
+
+By default the discovery-tool catalog lists only bare names (`'none'`). Pass
+`lazyToolsConfig` to `chat()` to include more context:
+
+```typescript
+const stream = chat({
+  adapter: openaiText('gpt-5.5'),
+  messages,
+  tools: [getProducts, compareProducts],
+  agentLoopStrategy: maxIterations(20),
+  lazyToolsConfig: { includeDescription: 'first-sentence' },
+})
+```
+
+`includeDescription` values:
+
+| Value              | Catalog entry                                                                            | When to use                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `'none'` (default) | `compareProducts`                                                                        | Smallest prompt; model discovers by name                                           |
+| `'first-sentence'` | `compareProducts — Compare two or more products side by side.`                           | Helps the model decide whether to discover without extra tokens                    |
+| `'full'`           | `compareProducts — Compare two or more products side by side. Accepts productIds array.` | Use when descriptions are short or the model needs full context to route correctly |
+
+The post-discovery payload always returns the full description and schema regardless of this setting.
+
 ## MCP Tools
 
 `@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools

package/src/activities/chat/index.ts

@@ -47,6 +47,7 @@ import type {
   CustomEvent,
   InferSchemaType,
   JSONSchema,
+  LazyToolsConfig,
   ModelMessage,
   RunFinishedEvent,
   SchemaInput,
@@ -235,6 +236,12 @@ export interface TextActivityOptions<
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
+  /**
+   * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
+   * Tunes how much of each lazy tool's description appears in the discovery
+   * catalog. Optional — defaults to `{ includeDescription: 'none' }`.
+   */
+  lazyToolsConfig?: LazyToolsConfig
   /** Unique conversation identifier for tracking */
   conversationId?: TextOptions['conversationId']
   /** Thread/conversation ID for AG-UI protocol. Auto-generated if not provided. */
@@ -606,6 +613,7 @@ class TextEngine<
     this.lazyToolManager = new LazyToolManager(
       config.params.tools || [],
       this.messages,
+      config.params.lazyToolsConfig,
     )
     this.tools = this.lazyToolManager.getActiveTools()
     this.toolCallManager = new ToolCallManager<

package/src/activities/chat/tools/lazy-tool-manager.ts

@@ -1,5 +1,6 @@
 import { convertSchemaToJsonSchema } from './schema-converter'
-import type { AnyTool, Tool } from '../../../types'
+import { renderLazyCatalogEntry } from './lazy-tools'
+import type { AnyTool, LazyToolsConfig, Tool } from '../../../types'
 
 /**
  * Name of the synthetic tool the LLM calls to discover lazy tools.
@@ -23,6 +24,7 @@ export class LazyToolManager {
   private readonly discoveredTools: Set<string>
   private hasNewDiscoveries: boolean
   private readonly discoveryTool: Tool | null
+  private readonly lazyToolsConfig: LazyToolsConfig
 
   constructor(
     tools: ReadonlyArray<Tool>,
@@ -36,7 +38,9 @@ export class LazyToolManager {
       }>
       toolCallId?: string
     }>,
+    lazyToolsConfig: LazyToolsConfig = {},
   ) {
+    this.lazyToolsConfig = lazyToolsConfig
     const eager: Array<Tool> = []
     this.lazyToolMap = new Map()
     this.discoveredTools = new Set()
@@ -224,9 +228,13 @@ export class LazyToolManager {
 
     const lazyToolMap = this.lazyToolMap
 
-    // Build the static description with all lazy tool names
-    const allLazyNames = Array.from(this.lazyToolMap.keys())
-    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyNames.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`
+    // Build the static description, rendering each entry per includeDescription.
+    // With the default 'none' this is byte-identical to the legacy output.
+    const include = this.lazyToolsConfig.includeDescription ?? 'none'
+    const allLazyEntries = Array.from(this.lazyToolMap.values()).map((t) =>
+      renderLazyCatalogEntry(t.name, t.description, include),
+    )
+    const description = `You have access to additional tools that can be discovered. Available tools: [${allLazyEntries.join(', ')}]. Call this tool with a list of tool names to discover their full descriptions and argument schemas before using them.`
 
     // Use the arrow function to capture `this` context
     const manager = this

package/src/activities/chat/tools/lazy-tools.ts

@@ -0,0 +1,33 @@
+import type { LazyToolsConfig } from '../../../types'
+
+/**
+ * Extract the first sentence of a description (up to the first ., !, or ?
+ * followed by whitespace or end-of-string). Falls back to the whole trimmed
+ * string when there is no sentence terminator.
+ */
+export function firstSentence(text: string): string {
+  const trimmed = text.trim()
+  if (!trimmed) return ''
+  const match = trimmed.match(/^.*?[.!?](?=\s|$)/)
+  return (match ? match[0] : trimmed).trim()
+}
+
+/**
+ * Render one entry in a lazy-tool catalog according to `includeDescription`.
+ * - 'none' (default) → bare name (preserves legacy chat behavior)
+ * - 'first-sentence' → `name — <first sentence>`
+ * - 'full' → `name — <full description>`
+ * Falls back to the bare name when there is no description.
+ */
+export function renderLazyCatalogEntry(
+  name: string,
+  description: string,
+  includeDescription: LazyToolsConfig['includeDescription'] = 'none',
+): string {
+  if (includeDescription === 'none' || !description.trim()) return name
+  const desc =
+    includeDescription === 'first-sentence'
+      ? firstSentence(description)
+      : description.trim()
+  return desc ? `${name} — ${desc}` : name
+}

package/src/index.ts

@@ -154,6 +154,11 @@ export type {
 // All types
 export * from './types'
 
+export {
+  firstSentence,
+  renderLazyCatalogEntry,
+} from './activities/chat/tools/lazy-tools'
+
 // Usage utilities
 export { buildBaseUsage, type BaseUsageInput } from './utilities/usage'
 

package/src/types.ts

@@ -654,13 +654,29 @@ export interface Tool<
   /** If true, tool execution requires user approval before running. Works with both server and client tools. */
   needsApproval?: boolean
 
-  /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Only meaningful when used with chat(). */
+  /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). */
   lazy?: boolean
 
   /** Additional metadata for adapters or custom extensions */
   metadata?: Record<string, any> | undefined
 }
 
+/**
+ * Configuration for the lazy-tool discovery catalog, shared by chat() and
+ * Code Mode. Optional in both — lazy behavior is triggered purely by tools
+ * marked `lazy: true`; this only tunes how much of each lazy tool's
+ * description appears in the pre-discovery catalog. The post-discovery payload
+ * always returns the full description + schema.
+ */
+export interface LazyToolsConfig {
+  /**
+   * How much of each lazy tool's description appears in the pre-discovery
+   * catalog (the names list shown before the model discovers the tool).
+   * @default 'none'
+   */
+  includeDescription?: 'full' | 'first-sentence' | 'none'
+}
+
 export type AnyTool = Omit<Tool<any, any, any, any>, 'execute'> & {
   execute?: ((args: any, context?: any) => any) | undefined
 }
@@ -819,6 +835,12 @@ export interface TextOptions<
    */
   systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
+  /**
+   * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
+   * Tunes how much of each lazy tool's description appears in the discovery
+   * catalog. Optional — defaults to `{ includeDescription: 'none' }`.
+   */
+  lazyToolsConfig?: LazyToolsConfig
   /**
    * Observability metadata attached to this call. Surfaced to middleware,
    * devtools, and the event client; values may be arbitrarily structured