@tanstack/ai 0.8.1 → 0.9.2

package/src/activities/chat/index.ts

@@ -7,6 +7,7 @@
 
 import { devtoolsMiddleware } from '@tanstack/ai-event-client'
 import { streamToText } from '../../stream-to-response.js'
+import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
   ToolCallManager,
@@ -237,7 +238,8 @@ class TextEngine<
   private systemPrompts: Array<string>
   private tools: Array<Tool>
   private readonly loopStrategy: AgentLoopStrategy
-  private readonly toolCallManager: ToolCallManager
+  private toolCallManager: ToolCallManager
+  private readonly lazyToolManager: LazyToolManager
   private readonly initialMessageCount: number
   private readonly requestId: string
   private readonly streamId: string
@@ -273,10 +275,8 @@ class TextEngine<
     this.adapter = config.adapter
     this.params = config.params
     this.systemPrompts = config.params.systemPrompts || []
-    this.tools = config.params.tools || []
     this.loopStrategy =
       config.params.agentLoopStrategy || maxIterationsStrategy(5)
-    this.toolCallManager = new ToolCallManager(this.tools)
     this.initialMessageCount = config.params.messages.length
 
     // Extract client state (approvals, client tool results) from original messages BEFORE conversion
@@ -293,6 +293,14 @@ class TextEngine<
     this.messages = convertMessagesToModelMessages(
       config.params.messages as Array<any>,
     )
+
+    // Initialize lazy tool manager after messages are converted (needs message history for scanning)
+    this.lazyToolManager = new LazyToolManager(
+      config.params.tools || [],
+      this.messages,
+    )
+    this.tools = this.lazyToolManager.getActiveTools()
+    this.toolCallManager = new ToolCallManager(this.tools)
     this.requestId = this.createId('chat')
     this.streamId = this.createId('stream')
     this.effectiveRequest = config.params.abortController
@@ -643,10 +651,42 @@ class TextEngine<
 
     const finishEvent = this.createSyntheticFinishedEvent()
 
+    // Handle undiscovered lazy tool calls with self-correcting error messages
+    const undiscoveredLazyResults: Array<ToolResult> = []
+    const executablePendingCalls = pendingToolCalls.filter((tc) => {
+      if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
+        undiscoveredLazyResults.push({
+          toolCallId: tc.id,
+          toolName: tc.function.name,
+          result: {
+            error: this.lazyToolManager.getUndiscoveredToolError(
+              tc.function.name,
+            ),
+          },
+          state: 'output-error',
+        })
+        return false
+      }
+      return true
+    })
+
+    if (undiscoveredLazyResults.length > 0) {
+      for (const chunk of this.buildToolResultChunks(
+        undiscoveredLazyResults,
+        finishEvent,
+      )) {
+        yield chunk
+      }
+    }
+
+    if (executablePendingCalls.length === 0) {
+      return 'continue'
+    }
+
     const { approvals, clientToolResults } = this.collectClientState()
 
     const generator = executeToolCalls(
-      pendingToolCalls,
+      executablePendingCalls,
       this.tools,
       approvals,
       clientToolResults,
@@ -750,12 +790,47 @@ class TextEngine<
 
     this.addAssistantToolCallMessage(toolCalls)
 
+    // Handle undiscovered lazy tool calls with self-correcting error messages
+    const undiscoveredLazyResults: Array<ToolResult> = []
+    const executableToolCalls = toolCalls.filter((tc) => {
+      if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
+        undiscoveredLazyResults.push({
+          toolCallId: tc.id,
+          toolName: tc.function.name,
+          result: {
+            error: this.lazyToolManager.getUndiscoveredToolError(
+              tc.function.name,
+            ),
+          },
+          state: 'output-error',
+        })
+        return false
+      }
+      return true
+    })
+
+    if (undiscoveredLazyResults.length > 0) {
+      const finishEvt = this.finishedEvent!
+      for (const chunk of this.buildToolResultChunks(
+        undiscoveredLazyResults,
+        finishEvt,
+      )) {
+        yield chunk
+      }
+    }
+
+    if (executableToolCalls.length === 0) {
+      // All tool calls were undiscovered lazy tools — errors emitted, continue loop
+      this.toolCallManager.clear()
+      this.setToolPhase('continue')
+      return
+    }
     this.middlewareCtx.phase = 'beforeTools'
 
     const { approvals, clientToolResults } = this.collectClientState()
 
     const generator = executeToolCalls(
-      toolCalls,
+      executableToolCalls,
       this.tools,
       approvals,
       clientToolResults,
@@ -842,6 +917,14 @@ class TextEngine<
       yield chunk
     }
 
+    // Refresh tools if lazy tools were discovered in this batch
+    if (this.lazyToolManager.hasNewlyDiscoveredTools()) {
+      this.tools = this.lazyToolManager.getActiveTools()
+      this.toolCallManager = new ToolCallManager(this.tools)
+      this.setToolPhase('continue')
+      return
+    }
+
     this.toolCallManager.clear()
 
     this.setToolPhase('continue')

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

@@ -0,0 +1,254 @@
+import { convertSchemaToJsonSchema } from './schema-converter'
+import type { Tool } from '../../../types'
+
+const DISCOVERY_TOOL_NAME = '__lazy__tool__discovery__'
+
+/**
+ * Manages lazy tool discovery for the chat agent loop.
+ *
+ * Lazy tools are not sent to the LLM initially. Instead, a synthetic
+ * "discovery tool" is provided that lets the LLM discover lazy tools
+ * by name, receiving their full descriptions and schemas on demand.
+ */
+export class LazyToolManager {
+  private readonly eagerTools: ReadonlyArray<Tool>
+  private readonly lazyToolMap: Map<string, Tool>
+  private readonly discoveredTools: Set<string>
+  private hasNewDiscoveries: boolean
+  private readonly discoveryTool: Tool | null
+
+  constructor(
+    tools: ReadonlyArray<Tool>,
+    messages: ReadonlyArray<{
+      role: string
+      content?: any
+      toolCalls?: Array<{
+        id: string
+        type: string
+        function: { name: string; arguments: string }
+      }>
+      toolCallId?: string
+    }>,
+  ) {
+    const eager: Array<Tool> = []
+    this.lazyToolMap = new Map()
+    this.discoveredTools = new Set()
+    this.hasNewDiscoveries = false
+
+    // Separate tools into eager and lazy
+    for (const tool of tools) {
+      if (tool.lazy) {
+        this.lazyToolMap.set(tool.name, tool)
+      } else {
+        eager.push(tool)
+      }
+    }
+    this.eagerTools = eager
+
+    // If no lazy tools, no discovery tool needed
+    if (this.lazyToolMap.size === 0) {
+      this.discoveryTool = null
+      return
+    }
+
+    // Scan message history to pre-populate discoveredTools
+    this.scanMessageHistory(messages)
+
+    // Create the synthetic discovery tool
+    this.discoveryTool = this.createDiscoveryTool()
+  }
+
+  /**
+   * Returns the set of tools that should be sent to the LLM:
+   * eager tools + discovered lazy tools + discovery tool (if undiscovered tools remain).
+   * Resets the hasNewDiscoveries flag.
+   */
+  getActiveTools(): Array<Tool> {
+    this.hasNewDiscoveries = false
+
+    const active: Array<Tool> = [...this.eagerTools]
+
+    // Add discovered lazy tools
+    for (const name of this.discoveredTools) {
+      const tool = this.lazyToolMap.get(name)
+      if (tool) {
+        active.push(tool)
+      }
+    }
+
+    // Add discovery tool if there are still undiscovered lazy tools
+    if (
+      this.discoveryTool &&
+      this.discoveredTools.size < this.lazyToolMap.size
+    ) {
+      active.push(this.discoveryTool)
+    }
+
+    return active
+  }
+
+  /**
+   * Returns whether new tools have been discovered since the last getActiveTools() call.
+   */
+  hasNewlyDiscoveredTools(): boolean {
+    return this.hasNewDiscoveries
+  }
+
+  /**
+   * Returns true if the given name is a lazy tool that has not yet been discovered.
+   */
+  isUndiscoveredLazyTool(name: string): boolean {
+    return this.lazyToolMap.has(name) && !this.discoveredTools.has(name)
+  }
+
+  /**
+   * Returns a helpful error message for when an undiscovered lazy tool is called.
+   */
+  getUndiscoveredToolError(name: string): string {
+    return `Error: Tool '${name}' must be discovered first. Call ${DISCOVERY_TOOL_NAME} with toolNames: ['${name}'] to discover it.`
+  }
+
+  /**
+   * Scans message history to find previously discovered lazy tools.
+   * Looks for assistant messages with discovery tool calls and their
+   * corresponding tool result messages.
+   */
+  private scanMessageHistory(
+    messages: ReadonlyArray<{
+      role: string
+      content?: any
+      toolCalls?: Array<{
+        id: string
+        type: string
+        function: { name: string; arguments: string }
+      }>
+      toolCallId?: string
+    }>,
+  ): void {
+    // Collect tool call IDs for discovery tool invocations
+    const discoveryCallIds = new Set<string>()
+
+    for (const msg of messages) {
+      if (msg.role === 'assistant' && msg.toolCalls) {
+        for (const tc of msg.toolCalls) {
+          if (tc.function.name === DISCOVERY_TOOL_NAME) {
+            discoveryCallIds.add(tc.id)
+          }
+        }
+      }
+    }
+
+    if (discoveryCallIds.size === 0) return
+
+    // Find corresponding tool result messages
+    for (const msg of messages) {
+      if (
+        msg.role === 'tool' &&
+        msg.toolCallId &&
+        discoveryCallIds.has(msg.toolCallId)
+      ) {
+        try {
+          const content =
+            typeof msg.content === 'string'
+              ? msg.content
+              : JSON.stringify(msg.content)
+          const parsed = JSON.parse(content)
+          if (parsed && Array.isArray(parsed.tools)) {
+            for (const tool of parsed.tools) {
+              if (
+                tool &&
+                typeof tool.name === 'string' &&
+                this.lazyToolMap.has(tool.name)
+              ) {
+                this.discoveredTools.add(tool.name)
+              }
+            }
+          }
+        } catch {
+          // Malformed JSON — skip gracefully
+        }
+      }
+    }
+  }
+
+  /**
+   * Creates the synthetic discovery tool that the LLM can call
+   * to discover lazy tools' descriptions and schemas.
+   */
+  private createDiscoveryTool(): Tool {
+    const undiscoveredNames = (): Array<string> => {
+      const names: Array<string> = []
+      for (const [name] of this.lazyToolMap) {
+        if (!this.discoveredTools.has(name)) {
+          names.push(name)
+        }
+      }
+      return names
+    }
+
+    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.`
+
+    // Use the arrow function to capture `this` context
+    const manager = this
+
+    return {
+      name: DISCOVERY_TOOL_NAME,
+      description,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          toolNames: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'List of tool names to discover. Each name must match one of the available tools.',
+          },
+        },
+        required: ['toolNames'],
+      },
+      execute: (args: { toolNames: Array<string> }) => {
+        const tools: Array<{
+          name: string
+          description: string
+          inputSchema?: any
+        }> = []
+        const errors: Array<string> = []
+
+        for (const name of args.toolNames) {
+          const tool = lazyToolMap.get(name)
+          if (tool) {
+            manager.discoveredTools.add(name)
+            manager.hasNewDiscoveries = true
+            const jsonSchema = tool.inputSchema
+              ? convertSchemaToJsonSchema(tool.inputSchema)
+              : undefined
+            tools.push({
+              name: tool.name,
+              description: tool.description,
+              ...(jsonSchema ? { inputSchema: jsonSchema } : {}),
+            })
+          } else {
+            errors.push(
+              `Unknown tool: '${name}'. Available tools: [${undiscoveredNames().join(', ')}]`,
+            )
+          }
+        }
+
+        const result: {
+          tools: typeof tools
+          errors?: Array<string>
+        } = { tools }
+
+        if (errors.length > 0) {
+          result.errors = errors
+        }
+
+        return result
+      },
+    }
+  }
+}

package/src/activities/chat/tools/tool-calls.ts

@@ -100,6 +100,9 @@ export class ToolCallManager {
         name: event.toolName,
         arguments: '',
       },
+      ...(event.providerMetadata && {
+        providerMetadata: event.providerMetadata,
+      }),
     })
   }
 

package/src/activities/chat/tools/tool-definition.ts

@@ -32,6 +32,7 @@ export interface ClientTool<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
+  lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: (
     args: InferSchemaType<TInput>,
@@ -96,6 +97,7 @@ export interface ToolDefinitionConfig<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
+  lazy?: boolean
   metadata?: Record<string, unknown>
 }
 

package/src/activities/generateVideo/index.ts

@@ -427,25 +427,25 @@ export async function getVideoJobStatus<
         url: urlResult.url,
       }
     } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Failed to get video URL'
       aiEventClient.emit('video:request:completed', {
         requestId,
         provider: adapter.name,
         model: adapter.model,
         requestType: 'status',
         jobId,
-        status: statusResult.status,
+        status: 'failed',
         progress: statusResult.progress,
-        error:
-          error instanceof Error ? error.message : 'Failed to get video URL',
+        error: errorMessage,
         duration: Date.now() - startTime,
         timestamp: Date.now(),
       })
-      // If URL fetch fails, still return status
+      // Provider reported completed but result fetch failed — treat as failed
       return {
-        status: statusResult.status,
+        status: 'failed' as const,
         progress: statusResult.progress,
-        error:
-          error instanceof Error ? error.message : 'Failed to get video URL',
+        error: errorMessage,
       }
     }
   }

package/src/types.ts

@@ -91,6 +91,8 @@ export interface ToolCall {
     name: string
     arguments: string // JSON string
   }
+  /** Provider-specific metadata to carry through the tool call lifecycle */
+  providerMetadata?: Record<string, unknown>
 }
 
 // ============================================================================
@@ -493,6 +495,9 @@ 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(). */
+  lazy?: boolean
+
   /** Additional metadata for adapters or custom extensions */
   metadata?: Record<string, any>
 }
@@ -846,6 +851,8 @@ export interface ToolCallStartEvent extends BaseAGUIEvent {
   parentMessageId?: string
   /** Index for parallel tool calls */
   index?: number
+  /** Provider-specific metadata to carry into the ToolCall */
+  providerMetadata?: Record<string, unknown>
 }
 
 /**