@tanstack/ai 0.0.1

package/src/stream/strategies.ts

@@ -0,0 +1,78 @@
+/**
+ * Built-in Chunk Strategies
+ *
+ * Strategies for controlling when text updates are emitted to the UI
+ */
+
+import type { ChunkStrategy } from './types'
+
+/**
+ * Immediate Strategy - emit on every chunk (default behavior)
+ */
+export class ImmediateStrategy implements ChunkStrategy {
+  shouldEmit(_chunk: string, _accumulated: string): boolean {
+    return true
+  }
+}
+
+/**
+ * Punctuation Strategy - emit when chunk contains punctuation
+ * Useful for natural text flow in UI
+ */
+export class PunctuationStrategy implements ChunkStrategy {
+  private punctuation = /[.,!?;:\n]/
+
+  shouldEmit(chunk: string, _accumulated: string): boolean {
+    return this.punctuation.test(chunk)
+  }
+}
+
+/**
+ * Batch Strategy - emit every N chunks
+ * Useful for reducing UI update frequency
+ */
+export class BatchStrategy implements ChunkStrategy {
+  private chunkCount = 0
+
+  constructor(private batchSize: number = 5) {}
+
+  shouldEmit(_chunk: string, _accumulated: string): boolean {
+    this.chunkCount++
+    if (this.chunkCount >= this.batchSize) {
+      this.chunkCount = 0
+      return true
+    }
+    return false
+  }
+
+  reset(): void {
+    this.chunkCount = 0
+  }
+}
+
+/**
+ * Word Boundary Strategy - emit at word boundaries
+ * Prevents cutting words in half
+ */
+export class WordBoundaryStrategy implements ChunkStrategy {
+  shouldEmit(chunk: string, _accumulated: string): boolean {
+    // Emit if chunk ends with whitespace
+    return /\s$/.test(chunk)
+  }
+}
+
+/**
+ * Composite Strategy - combine multiple strategies (OR logic)
+ * Emits if ANY strategy says to emit
+ */
+export class CompositeStrategy implements ChunkStrategy {
+  constructor(private strategies: Array<ChunkStrategy>) {}
+
+  shouldEmit(chunk: string, accumulated: string): boolean {
+    return this.strategies.some((s) => s.shouldEmit(chunk, accumulated))
+  }
+
+  reset(): void {
+    this.strategies.forEach((s) => s.reset?.())
+  }
+}

package/src/stream/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Stream Processor Types
+ *
+ * Unified types for stream processing used by both server and client.
+ * The canonical chunk format is StreamChunk from @tanstack/ai types.
+ */
+
+import type { StreamChunk, ToolCall } from '../types'
+
+/**
+ * Tool call states - track the lifecycle of a tool call
+ */
+export type ToolCallState =
+  | 'awaiting-input' // Received start but no arguments yet
+  | 'input-streaming' // Partial arguments received
+  | 'input-complete' // All arguments received
+  | 'approval-requested' // Waiting for user approval
+  | 'approval-responded' // User has approved/denied
+
+/**
+ * Tool result states - track the lifecycle of a tool result
+ */
+export type ToolResultState =
+  | 'streaming' // Placeholder for future streamed output
+  | 'complete' // Result is complete
+  | 'error' // Error occurred
+
+/**
+ * Internal state for a tool call being tracked
+ */
+export interface InternalToolCallState {
+  id: string
+  name: string
+  arguments: string
+  state: ToolCallState
+  parsedArguments?: any
+  index: number
+}
+
+/**
+ * Strategy for determining when to emit text updates
+ */
+export interface ChunkStrategy {
+  /**
+   * Called for each text chunk received
+   * @param chunk - The new chunk of text (delta)
+   * @param accumulated - All text accumulated so far
+   * @returns true if an update should be emitted now
+   */
+  shouldEmit: (chunk: string, accumulated: string) => boolean
+
+  /**
+   * Optional: Reset strategy state (called when streaming starts)
+   */
+  reset?: () => void
+}
+
+/**
+ * Result from processing a stream
+ */
+export interface ProcessorResult {
+  content: string
+  thinking?: string
+  toolCalls?: Array<ToolCall>
+  finishReason?: string | null
+}
+
+/**
+ * Current state of the processor
+ */
+export interface ProcessorState {
+  content: string
+  thinking: string
+  toolCalls: Map<string, InternalToolCallState>
+  toolCallOrder: Array<string>
+  finishReason: string | null
+  done: boolean
+}
+
+/**
+ * Recording format for replay testing
+ */
+export interface ChunkRecording {
+  version: '1.0'
+  timestamp: number
+  model?: string
+  provider?: string
+  chunks: Array<{
+    chunk: StreamChunk
+    timestamp: number
+    index: number
+  }>
+  result?: ProcessorResult
+}

package/src/tools/tool-calls.ts

@@ -0,0 +1,471 @@
+import type {
+  DoneStreamChunk,
+  ModelMessage,
+  Tool,
+  ToolCall,
+  ToolResultStreamChunk,
+} from '../types'
+
+/**
+ * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
+ *
+ * Responsibilities:
+ * - Accumulates streaming tool call chunks (ID, name, arguments)
+ * - Validates tool calls (filters out incomplete ones)
+ * - Executes tool `execute` functions with parsed arguments
+ * - Emits `tool_result` chunks for client visibility
+ * - Returns tool result messages for conversation history
+ *
+ * This class is used internally by the AI.chat() method to handle the automatic
+ * tool execution loop. It can also be used independently for custom tool execution logic.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ToolCallManager(tools);
+ *
+ * // During streaming, accumulate tool calls
+ * for await (const chunk of stream) {
+ *   if (chunk.type === "tool_call") {
+ *     manager.addToolCallChunk(chunk);
+ *   }
+ * }
+ *
+ * // After stream completes, execute tools
+ * if (manager.hasToolCalls()) {
+ *   const toolResults = yield* manager.executeTools(doneChunk);
+ *   messages = [...messages, ...toolResults];
+ *   manager.clear();
+ * }
+ * ```
+ */
+export class ToolCallManager {
+  private toolCallsMap = new Map<number, ToolCall>()
+  private tools: ReadonlyArray<Tool>
+
+  constructor(tools: ReadonlyArray<Tool>) {
+    this.tools = tools
+  }
+
+  /**
+   * Add a tool call chunk to the accumulator
+   * Handles streaming tool calls by accumulating arguments
+   */
+  addToolCallChunk(chunk: {
+    toolCall: {
+      id: string
+      type: 'function'
+      function: {
+        name: string
+        arguments: string
+      }
+    }
+    index: number
+  }): void {
+    const index = chunk.index
+    const existing = this.toolCallsMap.get(index)
+
+    if (!existing) {
+      // Only create entry if we have a tool call ID and name
+      if (chunk.toolCall.id && chunk.toolCall.function.name) {
+        this.toolCallsMap.set(index, {
+          id: chunk.toolCall.id,
+          type: 'function',
+          function: {
+            name: chunk.toolCall.function.name,
+            arguments: chunk.toolCall.function.arguments || '',
+          },
+        })
+      }
+    } else {
+      // Update name if it wasn't set before
+      if (chunk.toolCall.function.name && !existing.function.name) {
+        existing.function.name = chunk.toolCall.function.name
+      }
+      // Accumulate arguments for streaming tool calls
+      if (chunk.toolCall.function.arguments) {
+        existing.function.arguments += chunk.toolCall.function.arguments
+      }
+    }
+  }
+
+  /**
+   * Check if there are any complete tool calls to execute
+   */
+  hasToolCalls(): boolean {
+    return this.getToolCalls().length > 0
+  }
+
+  /**
+   * Get all complete tool calls (filtered for valid ID and name)
+   */
+  getToolCalls(): Array<ToolCall> {
+    return Array.from(this.toolCallsMap.values()).filter(
+      (tc) => tc.id && tc.function.name && tc.function.name.trim().length > 0,
+    )
+  }
+
+  /**
+   * Execute all tool calls and return tool result messages
+   * Also yields tool_result chunks for streaming
+   */
+  async *executeTools(
+    doneChunk: DoneStreamChunk,
+  ): AsyncGenerator<ToolResultStreamChunk, Array<ModelMessage>, void> {
+    const toolCallsArray = this.getToolCalls()
+    const toolResults: Array<ModelMessage> = []
+
+    for (const toolCall of toolCallsArray) {
+      const tool = this.tools.find((t) => t.name === toolCall.function.name)
+
+      let toolResultContent: string
+      if (tool?.execute) {
+        try {
+          // Parse arguments
+          let args: any
+          try {
+            args = JSON.parse(toolCall.function.arguments)
+          } catch (parseError) {
+            throw new Error(
+              `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`,
+            )
+          }
+
+          // Validate input against inputSchema
+          if (tool.inputSchema) {
+            try {
+              args = tool.inputSchema.parse(args)
+            } catch (validationError: any) {
+              throw new Error(
+                `Input validation failed for tool ${tool.name}: ${validationError.message}`,
+              )
+            }
+          }
+
+          // Execute the tool
+          let result = await tool.execute(args)
+
+          // Validate output against outputSchema if provided
+          if (tool.outputSchema && result !== undefined && result !== null) {
+            try {
+              result = tool.outputSchema.parse(result)
+            } catch (validationError: any) {
+              throw new Error(
+                `Output validation failed for tool ${tool.name}: ${validationError.message}`,
+              )
+            }
+          }
+
+          toolResultContent =
+            typeof result === 'string' ? result : JSON.stringify(result)
+        } catch (error: any) {
+          // If tool execution fails, add error message
+          toolResultContent = `Error executing tool: ${error.message}`
+        }
+      } else {
+        // Tool doesn't have execute function, add placeholder
+        toolResultContent = `Tool ${toolCall.function.name} does not have an execute function`
+      }
+
+      // Emit tool_result chunk so callers can track tool execution
+      yield {
+        type: 'tool_result',
+        id: doneChunk.id,
+        model: doneChunk.model,
+        timestamp: Date.now(),
+        toolCallId: toolCall.id,
+        content: toolResultContent,
+      }
+
+      // Add tool result message
+      toolResults.push({
+        role: 'tool',
+        content: toolResultContent,
+        toolCallId: toolCall.id,
+      })
+    }
+
+    return toolResults
+  }
+
+  /**
+   * Clear the tool calls map for the next iteration
+   */
+  clear(): void {
+    this.toolCallsMap.clear()
+  }
+}
+
+export interface ToolResult {
+  toolCallId: string
+  toolName: string
+  result: any
+  state?: 'output-available' | 'output-error'
+  /** Duration of tool execution in milliseconds (only for server-executed tools) */
+  duration?: number
+}
+
+export interface ApprovalRequest {
+  toolCallId: string
+  toolName: string
+  input: any
+  approvalId: string
+}
+
+export interface ClientToolRequest {
+  toolCallId: string
+  toolName: string
+  input: any
+}
+
+interface ExecuteToolCallsResult {
+  /** Tool results ready to send to LLM */
+  results: Array<ToolResult>
+  /** Tools that need user approval before execution */
+  needsApproval: Array<ApprovalRequest>
+  /** Tools that need client-side execution */
+  needsClientExecution: Array<ClientToolRequest>
+}
+
+/**
+ * Execute tool calls based on their configuration
+ *
+ * Handles three cases:
+ * 1. Client tools (no execute) - request client to execute
+ * 2. Server tools with approval - check approval before executing
+ * 3. Normal server tools - execute immediately
+ *
+ * @param toolCalls - Tool calls from the LLM
+ * @param tools - Available tools with their configurations
+ * @param approvals - Map of approval decisions (approval.id -> approved boolean)
+ * @param clientResults - Map of client-side execution results (toolCallId -> result)
+ */
+export async function executeToolCalls(
+  toolCalls: Array<ToolCall>,
+  tools: ReadonlyArray<Tool>,
+  approvals: Map<string, boolean> = new Map(),
+  clientResults: Map<string, any> = new Map(),
+): Promise<ExecuteToolCallsResult> {
+  const results: Array<ToolResult> = []
+  const needsApproval: Array<ApprovalRequest> = []
+  const needsClientExecution: Array<ClientToolRequest> = []
+
+  // Create tool lookup map
+  const toolMap = new Map<string, Tool>()
+  for (const tool of tools) {
+    toolMap.set(tool.name, tool)
+  }
+
+  for (const toolCall of toolCalls) {
+    const tool = toolMap.get(toolCall.function.name)
+    const toolName = toolCall.function.name
+
+    if (!tool) {
+      // Unknown tool - return error
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: `Unknown tool: ${toolName}` },
+        state: 'output-error',
+      })
+      continue
+    }
+
+    // Parse arguments, throwing error if invalid JSON
+    let input: any = {}
+    const argsStr = toolCall.function.arguments.trim() || '{}'
+    if (argsStr) {
+      try {
+        input = JSON.parse(argsStr)
+      } catch (parseError) {
+        // If parsing fails, throw error to fail fast
+        throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`)
+      }
+    }
+
+    // Validate input against inputSchema
+    if (tool.inputSchema) {
+      try {
+        input = tool.inputSchema.parse(input)
+      } catch (validationError: any) {
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result: {
+            error: `Input validation failed for tool ${tool.name}: ${validationError.message}`,
+          },
+          state: 'output-error',
+        })
+        continue
+      }
+    }
+
+    // CASE 1: Client-side tool (no execute function)
+    if (!tool.execute) {
+      // Check if tool needs approval
+      if (tool.needsApproval) {
+        const approvalId = `approval_${toolCall.id}`
+
+        // Check if approval decision exists
+        if (approvals.has(approvalId)) {
+          const approved = approvals.get(approvalId)
+
+          if (approved) {
+            // Approved - check if client has executed
+            if (clientResults.has(toolCall.id)) {
+              results.push({
+                toolCallId: toolCall.id,
+                toolName,
+                result: clientResults.get(toolCall.id),
+              })
+            } else {
+              // Approved but not executed yet - request client execution
+              needsClientExecution.push({
+                toolCallId: toolCall.id,
+                toolName,
+                input,
+              })
+            }
+          } else {
+            // User declined
+            results.push({
+              toolCallId: toolCall.id,
+              toolName,
+              result: { error: 'User declined tool execution' },
+              state: 'output-error',
+            })
+          }
+        } else {
+          // Need approval first
+          needsApproval.push({
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            input,
+            approvalId,
+          })
+        }
+      } else {
+        // No approval needed - check if client has executed
+        if (clientResults.has(toolCall.id)) {
+          results.push({
+            toolCallId: toolCall.id,
+            toolName,
+            result: clientResults.get(toolCall.id),
+          })
+        } else {
+          // Request client execution
+          needsClientExecution.push({
+            toolCallId: toolCall.id,
+            toolName,
+            input,
+          })
+        }
+      }
+      continue
+    }
+
+    // CASE 2: Server tool with approval required
+    if (tool.needsApproval) {
+      const approvalId = `approval_${toolCall.id}`
+
+      // Check if approval decision exists
+      if (approvals.has(approvalId)) {
+        const approved = approvals.get(approvalId)
+
+        if (approved) {
+          // Execute after approval
+          const startTime = Date.now()
+          try {
+            let result = await tool.execute(input)
+            const duration = Date.now() - startTime
+
+            // Validate output against outputSchema if provided
+            if (tool.outputSchema && result !== undefined && result !== null) {
+              const parsed = tool.outputSchema.safeParse(result)
+              if (parsed.success) {
+                result = parsed.data
+              } else {
+                throw new Error(
+                  `Output validation failed for tool ${tool.name}: ${parsed.error.message}`,
+                )
+              }
+            }
+
+            results.push({
+              toolCallId: toolCall.id,
+              toolName,
+              result:
+                typeof result === 'string'
+                  ? JSON.parse(result)
+                  : result || null,
+              duration,
+            })
+          } catch (error: any) {
+            const duration = Date.now() - startTime
+            results.push({
+              toolCallId: toolCall.id,
+              toolName,
+              result: { error: error.message },
+              state: 'output-error',
+              duration,
+            })
+          }
+        } else {
+          // User declined
+          results.push({
+            toolCallId: toolCall.id,
+            toolName,
+            result: { error: 'User declined tool execution' },
+            state: 'output-error',
+          })
+        }
+      } else {
+        // Need approval
+        needsApproval.push({
+          toolCallId: toolCall.id,
+          toolName,
+          input,
+          approvalId,
+        })
+      }
+      continue
+    }
+
+    // CASE 3: Normal server tool - execute immediately
+    const startTime = Date.now()
+    try {
+      let result = await tool.execute(input)
+      const duration = Date.now() - startTime
+
+      // Validate output against outputSchema if provided
+      if (tool.outputSchema && result !== undefined && result !== null) {
+        const parsed = tool.outputSchema.safeParse(result)
+        if (parsed.success) {
+          result = parsed.data
+        } else {
+          throw new Error(
+            `Output validation failed for tool ${tool.name}: ${parsed.error.message}`,
+          )
+        }
+      }
+
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result:
+          typeof result === 'string' ? JSON.parse(result) : result || null,
+        duration,
+      })
+    } catch (error: any) {
+      const duration = Date.now() - startTime
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: error.message },
+        state: 'output-error',
+        duration,
+      })
+    }
+  }
+
+  return { results, needsApproval, needsClientExecution }
+}