@tanstack/ai 0.37.0 → 0.38.0

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

@@ -1 +1 @@
-{"version":3,"file":"tool-calls.js","sources":["../../../../../src/activities/chat/tools/tool-calls.ts"],"sourcesContent":["import { normalizeToolResult } from '../../../utilities/tool-result'\nimport { isStandardSchema, parseWithStandardSchema } from './schema-converter'\nimport type {\n  AnyTool,\n  ContentPart,\n  CustomEvent,\n  ModelMessage,\n  RunFinishedEvent,\n  Tool,\n  ToolCall,\n  ToolCallArgsEvent,\n  ToolCallEndEvent,\n  ToolCallStartEvent,\n  ToolExecutionContext,\n  ToolOutputState,\n} from '../../../types'\nimport type {\n  AfterToolCallInfo,\n  BeforeToolCallDecision,\n} from '../middleware/types'\nimport type {\n  ContextFromTool,\n  DefinedContext,\n  MergeContext,\n  UnionToIntersection,\n} from '../runtime-context-types'\n\nfunction safeJsonParse(value: string): unknown {\n  try {\n    return JSON.parse(value)\n  } catch {\n    return value\n  }\n}\n\n/**\n * Optional middleware hooks for tool execution.\n * When provided, these callbacks are invoked before/after each tool execution.\n */\nexport interface ToolExecutionMiddlewareHooks {\n  onBeforeToolCall?: (\n    toolCall: ToolCall,\n    tool: Tool | undefined,\n    args: unknown,\n  ) => Promise<BeforeToolCallDecision>\n  onAfterToolCall?: (info: AfterToolCallInfo) => Promise<void>\n}\n\n/**\n * Error thrown when middleware decides to abort the chat run during tool execution.\n */\nexport class MiddlewareAbortError extends Error {\n  constructor(reason: string) {\n    super(reason)\n    this.name = 'MiddlewareAbortError'\n  }\n}\n\n// The leaf context-inference primitives (ContextFromTool, MergeContext,\n// UnionToIntersection, DefinedContext) are shared with the chat activity\n// options layer — see ../runtime-context-types.\ntype RequiredContextFromToolUnion<T> = T extends unknown\n  ? undefined extends ContextFromTool<T>\n    ? never\n    : ContextFromTool<T>\n  : never\n\ntype ContextFromToolUnion<T> = [\n  UnionToIntersection<DefinedContext<ContextFromTool<T>>>,\n] extends [never]\n  ? unknown\n  : [RequiredContextFromToolUnion<T>] extends [never]\n    ? UnionToIntersection<DefinedContext<ContextFromTool<T>>> | undefined\n    : UnionToIntersection<DefinedContext<ContextFromTool<T>>>\n\ntype ContextFromTools<TTools> = TTools extends readonly [\n  infer THead,\n  ...infer TTail,\n]\n  ? MergeContext<ContextFromTool<THead>, ContextFromTools<TTail>>\n  : TTools extends ReadonlyArray<infer TTool>\n    ? ContextFromToolUnion<TTool>\n    : unknown\n\ntype ExecuteToolsContextArgs<TContext> = undefined extends TContext\n  ? [userContext?: TContext]\n  : [userContext: TContext]\n\n/**\n * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.\n *\n * Responsibilities:\n * - Accumulates streaming tool call events (ID, name, arguments)\n * - Validates tool calls (filters out incomplete ones)\n * - Executes tool `execute` functions with parsed arguments\n * - Emits `TOOL_CALL_END` events for client visibility\n * - Returns tool result messages for conversation history\n *\n * This class is used internally by the AI.chat() method to handle the automatic\n * tool execution loop. It can also be used independently for custom tool execution logic.\n *\n * @example\n * ```typescript\n * const manager = new ToolCallManager(tools);\n *\n * // During streaming, accumulate tool calls\n * for await (const chunk of stream) {\n *   if (chunk.type === 'TOOL_CALL_START') {\n *     manager.addToolCallStartEvent(chunk);\n *   } else if (chunk.type === 'TOOL_CALL_ARGS') {\n *     manager.addToolCallArgsEvent(chunk);\n *   }\n * }\n *\n * // After stream completes, execute tools\n * if (manager.hasToolCalls()) {\n *   const toolResults = yield* manager.executeTools(finishEvent);\n *   messages = [...messages, ...toolResults];\n *   manager.clear();\n * }\n * ```\n */\nexport class ToolCallManager<\n  TToolsOrContext = ReadonlyArray<AnyTool>,\n  TContext = TToolsOrContext extends ReadonlyArray<AnyTool>\n    ? ContextFromTools<TToolsOrContext>\n    : TToolsOrContext,\n> {\n  private readonly toolCallsMap = new Map<number, ToolCall>()\n  private readonly tools: TToolsOrContext extends ReadonlyArray<AnyTool>\n    ? TToolsOrContext\n    : ReadonlyArray<AnyTool>\n\n  constructor(\n    tools: TToolsOrContext extends ReadonlyArray<AnyTool>\n      ? TToolsOrContext\n      : ReadonlyArray<AnyTool>,\n  ) {\n    this.tools = tools\n  }\n\n  /**\n   * Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)\n   */\n  addToolCallStartEvent(event: ToolCallStartEvent): void {\n    const index = event.index ?? this.toolCallsMap.size\n    const runtimeEvent = event as Partial<ToolCallStartEvent> &\n      Pick<ToolCallStartEvent, 'toolName'>\n    const name = runtimeEvent.toolCallName ?? runtimeEvent.toolName\n    this.toolCallsMap.set(index, {\n      id: event.toolCallId,\n      type: 'function',\n      function: {\n        name,\n        arguments: '',\n      },\n      ...(event.metadata !== undefined && { metadata: event.metadata }),\n    })\n  }\n\n  /**\n   * Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)\n   */\n  addToolCallArgsEvent(event: ToolCallArgsEvent): void {\n    // Find the tool call by ID\n    for (const [, toolCall] of this.toolCallsMap.entries()) {\n      if (toolCall.id === event.toolCallId) {\n        toolCall.function.arguments += event.delta\n        break\n      }\n    }\n  }\n\n  /**\n   * Complete a tool call with its final input\n   * Called when TOOL_CALL_END is received\n   */\n  completeToolCall(event: ToolCallEndEvent): void {\n    for (const [, toolCall] of this.toolCallsMap.entries()) {\n      if (toolCall.id === event.toolCallId) {\n        if (event.input !== undefined) {\n          // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)\n          const normalized =\n            event.input && typeof event.input === 'object' ? event.input : {}\n          toolCall.function.arguments = JSON.stringify(normalized)\n        }\n        break\n      }\n    }\n  }\n\n  /**\n   * Check if there are any complete tool calls to execute\n   */\n  hasToolCalls(): boolean {\n    return this.getToolCalls().length > 0\n  }\n\n  /**\n   * Get all complete tool calls (filtered for valid ID and name)\n   */\n  getToolCalls(): Array<ToolCall> {\n    return Array.from(this.toolCallsMap.values()).filter(\n      (tc) => tc.id && tc.function.name && tc.function.name.trim().length > 0,\n    )\n  }\n\n  /**\n   * Execute all tool calls and return tool result messages\n   * Yields TOOL_CALL_END events for streaming\n   * @param finishEvent - RUN_FINISHED event from the stream\n   */\n  async *executeTools(\n    finishEvent: RunFinishedEvent,\n    ...contextArgs: ExecuteToolsContextArgs<TContext>\n  ): AsyncGenerator<ToolCallEndEvent, Array<ModelMessage>, void> {\n    const toolCallsArray = this.getToolCalls()\n    const toolResults: Array<ModelMessage> = []\n    const hasRuntimeContext = contextArgs.length > 0\n    const userContext = contextArgs[0]\n\n    for (const toolCall of toolCallsArray) {\n      const tool = this.tools.find((t) => t.name === toolCall.function.name)\n\n      let toolResultContent: string | Array<ContentPart>\n      let toolResultState: ToolOutputState | undefined\n      if (tool?.execute) {\n        try {\n          // Parse arguments (normalize null/non-object to {} for empty tool_use blocks)\n          let args: unknown\n          try {\n            const argsString = toolCall.function.arguments.trim() || '{}'\n            const parsed = JSON.parse(argsString)\n            args = parsed && typeof parsed === 'object' ? parsed : {}\n          } catch (parseError) {\n            throw new Error(\n              `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`,\n            )\n          }\n\n          // Validate input against inputSchema (for Standard Schema compliant schemas)\n          if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {\n            try {\n              args = parseWithStandardSchema(tool.inputSchema, args)\n            } catch (validationError: unknown) {\n              const message =\n                validationError instanceof Error\n                  ? validationError.message\n                  : 'Validation failed'\n              throw new Error(\n                `Input validation failed for tool ${tool.name}: ${message}`,\n              )\n            }\n          }\n\n          // Execute the tool\n          const executionContext = {\n            toolCallId: toolCall.id,\n            context: userContext,\n            emitCustomEvent: () => {},\n          } as ToolExecutionContext<TContext>\n          let result = hasRuntimeContext\n            ? await tool.execute(args, executionContext)\n            : await tool.execute(args)\n\n          // Validate output against outputSchema if provided (for Standard\n          // Schema compliant schemas). Unlike the previous implementation we\n          // intentionally validate `undefined`/`null` results too, so a tool\n          // whose schema forbids them surfaces a validation error instead of\n          // silently passing — the schema itself decides whether they're valid.\n          if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n            try {\n              result = parseWithStandardSchema(tool.outputSchema, result)\n            } catch (validationError: unknown) {\n              const message =\n                validationError instanceof Error\n                  ? validationError.message\n                  : 'Validation failed'\n              throw new Error(\n                `Output validation failed for tool ${tool.name}: ${message}`,\n              )\n            }\n          }\n\n          toolResultContent = normalizeToolResult(result)\n        } catch (error: unknown) {\n          // If tool execution fails, add error message\n          const message =\n            error instanceof Error ? error.message : 'Unknown error'\n          toolResultContent = `Error executing tool: ${message}`\n          toolResultState = 'output-error'\n        }\n      } else {\n        // Tool doesn't have execute function, add placeholder\n        toolResultContent = `Tool ${toolCall.function.name} does not have an execute function`\n      }\n\n      // Emit TOOL_CALL_END event\n      yield {\n        type: 'TOOL_CALL_END',\n        toolCallId: toolCall.id,\n        toolCallName: toolCall.function.name,\n        toolName: toolCall.function.name,\n        model: finishEvent.model,\n        timestamp: Date.now(),\n        result: toolResultContent,\n        ...(toolResultState !== undefined && { state: toolResultState }),\n      } as ToolCallEndEvent\n\n      // Add tool result message\n      toolResults.push({\n        role: 'tool',\n        content: toolResultContent,\n        toolCallId: toolCall.id,\n      })\n    }\n\n    return toolResults\n  }\n\n  /**\n   * Clear the tool calls map for the next iteration\n   */\n  clear(): void {\n    this.toolCallsMap.clear()\n  }\n}\n\nexport interface ToolResult {\n  toolCallId: string\n  toolName: string\n  result: any\n  state?: 'output-available' | 'output-error'\n  /** Duration of tool execution in milliseconds (only for server-executed tools) */\n  duration?: number\n}\n\nexport interface ApprovalRequest {\n  toolCallId: string\n  toolName: string\n  input: any\n  approvalId: string\n}\n\nexport interface ClientToolRequest {\n  toolCallId: string\n  toolName: string\n  input: any\n}\n\ninterface ExecuteToolCallsResult {\n  /** Tool results ready to send to LLM */\n  results: Array<ToolResult>\n  /** Tools that need user approval before execution */\n  needsApproval: Array<ApprovalRequest>\n  /** Tools that need client-side execution */\n  needsClientExecution: Array<ClientToolRequest>\n}\n\n/**\n * Helper that runs a tool execution promise while polling for pending custom events.\n * Yields any custom events that are emitted during execution, then returns the\n * execution result.\n */\nasync function* executeWithEventPolling<T>(\n  executionPromise: Promise<T>,\n  pendingEvents: Array<CustomEvent>,\n): AsyncGenerator<CustomEvent, T, void> {\n  // Use an object to track mutable state across the async boundary\n  const state = { done: false, result: undefined as T }\n  const executionWithFlag = executionPromise.then((r) => {\n    state.done = true\n    state.result = r\n    return r\n  })\n\n  while (!state.done) {\n    // Wait for either the execution to complete or a short timeout\n    await Promise.race([\n      executionWithFlag,\n      new Promise((resolve) => setTimeout(resolve, 10)),\n    ])\n\n    // Flush any pending events\n    let event: CustomEvent | undefined\n    while ((event = pendingEvents.shift()) !== undefined) {\n      yield event\n    }\n  }\n\n  // Final flush in case events were emitted right at completion\n  let event: CustomEvent | undefined\n  while ((event = pendingEvents.shift()) !== undefined) {\n    yield event\n  }\n\n  return state.result\n}\n\n/**\n * Apply a middleware onBeforeToolCall decision.\n * Returns the (possibly transformed) input if execution should proceed,\n * or undefined if the tool call was skipped (result already pushed).\n * Throws MiddlewareAbortError if the decision is 'abort'.\n */\nasync function applyBeforeToolCallDecision(\n  toolCall: ToolCall,\n  tool: Tool,\n  input: unknown,\n  toolName: string,\n  middlewareHooks: ToolExecutionMiddlewareHooks,\n  results: Array<ToolResult>,\n): Promise<{ proceed: true; input: unknown } | { proceed: false }> {\n  if (!middlewareHooks.onBeforeToolCall) {\n    return { proceed: true, input }\n  }\n\n  const decision = await middlewareHooks.onBeforeToolCall(toolCall, tool, input)\n  if (!decision) {\n    return { proceed: true, input }\n  }\n\n  if (decision.type === 'abort') {\n    throw new MiddlewareAbortError(decision.reason || 'Aborted by middleware')\n  }\n\n  if (decision.type === 'skip') {\n    const skipResult = decision.result\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result:\n        typeof skipResult === 'string'\n          ? safeJsonParse(skipResult)\n          : (skipResult ?? null),\n      duration: 0,\n    })\n    if (middlewareHooks.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: true,\n        duration: 0,\n        result: skipResult,\n      })\n    }\n    return { proceed: false }\n  }\n\n  return { proceed: true, input: decision.args }\n}\n\n/**\n * Execute a server-side tool with event polling, output validation, and middleware hooks.\n * Yields CustomEvent chunks during execution and pushes the result to the results array.\n */\nasync function* executeServerTool<TContext = unknown>(\n  toolCall: ToolCall,\n  tool: AnyTool,\n  toolName: string,\n  input: unknown,\n  context: ToolExecutionContext<TContext>,\n  pendingEvents: Array<CustomEvent>,\n  results: Array<ToolResult>,\n  middlewareHooks?: ToolExecutionMiddlewareHooks,\n): AsyncGenerator<CustomEvent, void, void> {\n  const startTime = Date.now()\n  try {\n    if (!tool.execute) {\n      throw new Error(`Tool ${toolName} has no execute() implementation`)\n    }\n    const executionPromise = Promise.resolve(tool.execute(input, context))\n    let result = yield* executeWithEventPolling(executionPromise, pendingEvents)\n    const duration = Date.now() - startTime\n\n    // Flush remaining events\n    let pendingEvent: CustomEvent | undefined\n    while ((pendingEvent = pendingEvents.shift()) !== undefined) {\n      yield pendingEvent\n    }\n\n    // Validate output against outputSchema if provided. Validates\n    // `undefined`/`null` too — the schema decides whether they're valid.\n    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n      result = parseWithStandardSchema(tool.outputSchema, result)\n    }\n\n    const finalResult =\n      typeof result === 'string' ? safeJsonParse(result) : (result ?? null)\n\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result: finalResult,\n      duration,\n    })\n\n    if (middlewareHooks?.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: true,\n        duration,\n        result: finalResult,\n      })\n    }\n  } catch (error: unknown) {\n    const duration = Date.now() - startTime\n\n    // Flush remaining events\n    let pendingEvent: CustomEvent | undefined\n    while ((pendingEvent = pendingEvents.shift()) !== undefined) {\n      yield pendingEvent\n    }\n\n    if (error instanceof MiddlewareAbortError) {\n      throw error\n    }\n\n    const message = error instanceof Error ? error.message : 'Unknown error'\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result: { error: message },\n      state: 'output-error',\n      duration,\n    })\n\n    if (middlewareHooks?.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: false,\n        duration,\n        error,\n      })\n    }\n  }\n}\n\nfunction buildClientToolResult(\n  toolCallId: string,\n  toolName: string,\n  tool: AnyTool,\n  rawResult: unknown,\n): ToolResult {\n  try {\n    let result = rawResult\n    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n      result = parseWithStandardSchema(tool.outputSchema, result)\n    }\n\n    return {\n      toolCallId,\n      toolName,\n      result:\n        typeof result === 'string' ? safeJsonParse(result) : (result ?? null),\n    }\n  } catch (error: unknown) {\n    const message = error instanceof Error ? error.message : 'Validation failed'\n    return {\n      toolCallId,\n      toolName,\n      result: { error: message },\n      state: 'output-error',\n    }\n  }\n}\n\n/**\n * Execute tool calls based on their configuration.\n * Yields CustomEvent chunks during tool execution for real-time progress updates.\n *\n * Handles three cases:\n * 1. Client tools (no execute) - request client to execute\n * 2. Server tools with approval - check approval before executing\n * 3. Normal server tools - execute immediately\n *\n * @param toolCalls - Tool calls from the LLM\n * @param tools - Available tools with their configurations\n * @param approvals - Map of approval decisions (approval.id -> approved boolean)\n * @param clientResults - Map of client-side execution results (toolCallId -> result)\n * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)\n */\nexport async function* executeToolCalls<TContext = unknown>(\n  toolCalls: Array<ToolCall>,\n  tools: ReadonlyArray<AnyTool>,\n  approvals: Map<string, boolean> = new Map(),\n  clientResults: Map<string, any> = new Map(),\n  createCustomEventChunk?: (\n    eventName: string,\n    value: Record<string, any>,\n  ) => CustomEvent,\n  middlewareHooks?: ToolExecutionMiddlewareHooks,\n  userContext?: TContext,\n  abortSignal?: AbortSignal,\n): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {\n  const results: Array<ToolResult> = []\n  const needsApproval: Array<ApprovalRequest> = []\n  const needsClientExecution: Array<ClientToolRequest> = []\n\n  // Create tool lookup map\n  const toolMap = new Map<string, AnyTool>()\n  for (const tool of tools) {\n    toolMap.set(tool.name, tool)\n  }\n\n  // Batch gating: when any tool in the batch still needs an approval decision,\n  // defer all execution so side effects don't happen before the user decides.\n  const hasPendingApprovals = toolCalls.some((tc) => {\n    const t = toolMap.get(tc.function.name)\n    return t?.needsApproval && !approvals.has(`approval_${tc.id}`)\n  })\n\n  for (const toolCall of toolCalls) {\n    const tool = toolMap.get(toolCall.function.name)\n    const toolName = toolCall.function.name\n\n    if (!tool) {\n      // Unknown tool - return error\n      results.push({\n        toolCallId: toolCall.id,\n        toolName,\n        result: { error: `Unknown tool: ${toolName}` },\n        state: 'output-error',\n      })\n      continue\n    }\n\n    // Skip non-pending tools while approvals are outstanding\n    if (hasPendingApprovals) {\n      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {\n        continue\n      }\n    }\n\n    // Parse arguments, throwing error if invalid JSON\n    let input: unknown = {}\n    const argsStr = toolCall.function.arguments.trim() || '{}'\n    if (argsStr) {\n      try {\n        const parsed = JSON.parse(argsStr)\n        // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)\n        input = parsed && typeof parsed === 'object' ? parsed : {}\n      } catch (parseError) {\n        // If parsing fails, throw error to fail fast\n        throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`)\n      }\n    }\n\n    // Validate input against inputSchema (for Standard Schema compliant schemas)\n    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {\n      try {\n        input = parseWithStandardSchema(tool.inputSchema, input)\n      } catch (validationError: unknown) {\n        const message =\n          validationError instanceof Error\n            ? validationError.message\n            : 'Validation failed'\n        results.push({\n          toolCallId: toolCall.id,\n          toolName,\n          result: {\n            error: `Input validation failed for tool ${tool.name}: ${message}`,\n          },\n          state: 'output-error',\n        })\n        continue\n      }\n    }\n\n    // Create a ToolExecutionContext for this tool call with event emission\n    const pendingEvents: Array<CustomEvent> = []\n    const context = {\n      toolCallId: toolCall.id,\n      context: userContext,\n      abortSignal,\n      emitCustomEvent: (eventName: string, value: Record<string, any>) => {\n        if (createCustomEventChunk) {\n          pendingEvents.push(\n            createCustomEventChunk(eventName, {\n              ...value,\n              toolCallId: toolCall.id,\n            }),\n          )\n        }\n      },\n    } as ToolExecutionContext<TContext>\n\n    // CASE 1: Client-side tool (no execute function)\n    if (!tool.execute) {\n      // Check if tool needs approval\n      if (tool.needsApproval) {\n        const approvalId = `approval_${toolCall.id}`\n\n        // Check if approval decision exists\n        if (approvals.has(approvalId)) {\n          const approved = approvals.get(approvalId)\n\n          if (approved) {\n            // Approved - check if client has executed\n            if (clientResults.has(toolCall.id)) {\n              results.push(\n                buildClientToolResult(\n                  toolCall.id,\n                  toolName,\n                  tool,\n                  clientResults.get(toolCall.id),\n                ),\n              )\n            } else {\n              // Approved but not executed yet - request client execution\n              needsClientExecution.push({\n                toolCallId: toolCall.id,\n                toolName,\n                input,\n              })\n            }\n          } else {\n            // User declined\n            results.push({\n              toolCallId: toolCall.id,\n              toolName,\n              result: { error: 'User declined tool execution' },\n              state: 'output-error',\n            })\n          }\n        } else {\n          // Need approval first\n          needsApproval.push({\n            toolCallId: toolCall.id,\n            toolName: toolCall.function.name,\n            input,\n            approvalId,\n          })\n        }\n      } else {\n        // No approval needed - check if client has executed\n        if (clientResults.has(toolCall.id)) {\n          results.push(\n            buildClientToolResult(\n              toolCall.id,\n              toolName,\n              tool,\n              clientResults.get(toolCall.id),\n            ),\n          )\n        } else {\n          // Request client execution\n          needsClientExecution.push({\n            toolCallId: toolCall.id,\n            toolName,\n            input,\n          })\n        }\n      }\n      continue\n    }\n\n    // CASE 2: Server tool with approval required\n    if (tool.needsApproval) {\n      const approvalId = `approval_${toolCall.id}`\n\n      // Check if approval decision exists\n      if (approvals.has(approvalId)) {\n        const approved = approvals.get(approvalId)\n\n        if (approved) {\n          // Apply middleware before-hook for approved tools\n          if (middlewareHooks) {\n            const decision = await applyBeforeToolCallDecision(\n              toolCall,\n              tool,\n              input,\n              toolName,\n              middlewareHooks,\n              results,\n            )\n            if (!decision.proceed) continue\n            input = decision.input\n          }\n\n          yield* executeServerTool(\n            toolCall,\n            tool,\n            toolName,\n            input,\n            context,\n            pendingEvents,\n            results,\n            middlewareHooks,\n          )\n        } else {\n          // User declined\n          results.push({\n            toolCallId: toolCall.id,\n            toolName,\n            result: { error: 'User declined tool execution' },\n            state: 'output-error',\n          })\n        }\n      } else {\n        // Need approval\n        needsApproval.push({\n          toolCallId: toolCall.id,\n          toolName,\n          input,\n          approvalId,\n        })\n      }\n      continue\n    }\n\n    // CASE 3: Normal server tool - execute immediately\n    if (middlewareHooks) {\n      const decision = await applyBeforeToolCallDecision(\n        toolCall,\n        tool,\n        input,\n        toolName,\n        middlewareHooks,\n        results,\n      )\n      if (!decision.proceed) continue\n      input = decision.input\n    }\n\n    yield* executeServerTool(\n      toolCall,\n      tool,\n      toolName,\n      input,\n      context,\n      pendingEvents,\n      results,\n      middlewareHooks,\n    )\n  }\n\n  return { results, needsApproval, needsClientExecution }\n}\n"],"names":["event"],"mappings":";;AA2BA,SAAS,cAAc,OAAwB;AAC7C,MAAI;AACF,WAAO,KAAK,MAAM,KAAK;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAkBO,MAAM,6BAA6B,MAAM;AAAA,EAC9C,YAAY,QAAgB;AAC1B,UAAM,MAAM;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAkEO,MAAM,gBAKX;AAAA,EACiB,mCAAmB,IAAA;AAAA,EACnB;AAAA,EAIjB,YACE,OAGA;AACA,SAAK,QAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA,EAKA,sBAAsB,OAAiC;AACrD,UAAM,QAAQ,MAAM,SAAS,KAAK,aAAa;AAC/C,UAAM,eAAe;AAErB,UAAM,OAAO,aAAa,gBAAgB,aAAa;AACvD,SAAK,aAAa,IAAI,OAAO;AAAA,MAC3B,IAAI,MAAM;AAAA,MACV,MAAM;AAAA,MACN,UAAU;AAAA,QACR;AAAA,QACA,WAAW;AAAA,MAAA;AAAA,MAEb,GAAI,MAAM,aAAa,UAAa,EAAE,UAAU,MAAM,SAAA;AAAA,IAAS,CAChE;AAAA,EACH;AAAA;AAAA;AAAA;AAAA,EAKA,qBAAqB,OAAgC;AAEnD,eAAW,CAAA,EAAG,QAAQ,KAAK,KAAK,aAAa,WAAW;AACtD,UAAI,SAAS,OAAO,MAAM,YAAY;AACpC,iBAAS,SAAS,aAAa,MAAM;AACrC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,iBAAiB,OAA+B;AAC9C,eAAW,CAAA,EAAG,QAAQ,KAAK,KAAK,aAAa,WAAW;AACtD,UAAI,SAAS,OAAO,MAAM,YAAY;AACpC,YAAI,MAAM,UAAU,QAAW;AAE7B,gBAAM,aACJ,MAAM,SAAS,OAAO,MAAM,UAAU,WAAW,MAAM,QAAQ,CAAA;AACjE,mBAAS,SAAS,YAAY,KAAK,UAAU,UAAU;AAAA,QACzD;AACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,eAAwB;AACtB,WAAO,KAAK,eAAe,SAAS;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA,EAKA,eAAgC;AAC9B,WAAO,MAAM,KAAK,KAAK,aAAa,OAAA,CAAQ,EAAE;AAAA,MAC5C,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,QAAQ,GAAG,SAAS,KAAK,KAAA,EAAO,SAAS;AAAA,IAAA;AAAA,EAE1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,aACL,gBACG,aAC0D;AAC7D,UAAM,iBAAiB,KAAK,aAAA;AAC5B,UAAM,cAAmC,CAAA;AACzC,UAAM,oBAAoB,YAAY,SAAS;AAC/C,UAAM,cAAc,YAAY,CAAC;AAEjC,eAAW,YAAY,gBAAgB;AACrC,YAAM,OAAO,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,SAAS,SAAS,IAAI;AAErE,UAAI;AACJ,UAAI;AACJ,UAAI,MAAM,SAAS;AACjB,YAAI;AAEF,cAAI;AACJ,cAAI;AACF,kBAAM,aAAa,SAAS,SAAS,UAAU,UAAU;AACzD,kBAAM,SAAS,KAAK,MAAM,UAAU;AACpC,mBAAO,UAAU,OAAO,WAAW,WAAW,SAAS,CAAA;AAAA,UACzD,SAAS,YAAY;AACnB,kBAAM,IAAI;AAAA,cACR,2CAA2C,SAAS,SAAS,SAAS;AAAA,YAAA;AAAA,UAE1E;AAGA,cAAI,KAAK,eAAe,iBAAiB,KAAK,WAAW,GAAG;AAC1D,gBAAI;AACF,qBAAO,wBAAwB,KAAK,aAAa,IAAI;AAAA,YACvD,SAAS,iBAA0B;AACjC,oBAAM,UACJ,2BAA2B,QACvB,gBAAgB,UAChB;AACN,oBAAM,IAAI;AAAA,gBACR,oCAAoC,KAAK,IAAI,KAAK,OAAO;AAAA,cAAA;AAAA,YAE7D;AAAA,UACF;AAGA,gBAAM,mBAAmB;AAAA,YACvB,YAAY,SAAS;AAAA,YACrB,SAAS;AAAA,YACT,iBAAiB,MAAM;AAAA,YAAC;AAAA,UAAA;AAE1B,cAAI,SAAS,oBACT,MAAM,KAAK,QAAQ,MAAM,gBAAgB,IACzC,MAAM,KAAK,QAAQ,IAAI;AAO3B,cAAI,KAAK,gBAAgB,iBAAiB,KAAK,YAAY,GAAG;AAC5D,gBAAI;AACF,uBAAS,wBAAwB,KAAK,cAAc,MAAM;AAAA,YAC5D,SAAS,iBAA0B;AACjC,oBAAM,UACJ,2BAA2B,QACvB,gBAAgB,UAChB;AACN,oBAAM,IAAI;AAAA,gBACR,qCAAqC,KAAK,IAAI,KAAK,OAAO;AAAA,cAAA;AAAA,YAE9D;AAAA,UACF;AAEA,8BAAoB,oBAAoB,MAAM;AAAA,QAChD,SAAS,OAAgB;AAEvB,gBAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU;AAC3C,8BAAoB,yBAAyB,OAAO;AACpD,4BAAkB;AAAA,QACpB;AAAA,MACF,OAAO;AAEL,4BAAoB,QAAQ,SAAS,SAAS,IAAI;AAAA,MACpD;AAGA,YAAM;AAAA,QACJ,MAAM;AAAA,QACN,YAAY,SAAS;AAAA,QACrB,cAAc,SAAS,SAAS;AAAA,QAChC,UAAU,SAAS,SAAS;AAAA,QAC5B,OAAO,YAAY;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,QAChB,QAAQ;AAAA,QACR,GAAI,oBAAoB,UAAa,EAAE,OAAO,gBAAA;AAAA,MAAgB;AAIhE,kBAAY,KAAK;AAAA,QACf,MAAM;AAAA,QACN,SAAS;AAAA,QACT,YAAY,SAAS;AAAA,MAAA,CACtB;AAAA,IACH;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,aAAa,MAAA;AAAA,EACpB;AACF;AAsCA,gBAAgB,wBACd,kBACA,eACsC;AAEtC,QAAM,QAAQ,EAAE,MAAM,OAAO,QAAQ,OAAA;AACrC,QAAM,oBAAoB,iBAAiB,KAAK,CAAC,MAAM;AACrD,UAAM,OAAO;AACb,UAAM,SAAS;AACf,WAAO;AAAA,EACT,CAAC;AAED,SAAO,CAAC,MAAM,MAAM;AAElB,UAAM,QAAQ,KAAK;AAAA,MACjB;AAAA,MACA,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAAA,IAAA,CACjD;AAGD,QAAIA;AACJ,YAAQA,SAAQ,cAAc,MAAA,OAAa,QAAW;AACpD,YAAMA;AAAAA,IACR;AAAA,EACF;AAGA,MAAI;AACJ,UAAQ,QAAQ,cAAc,MAAA,OAAa,QAAW;AACpD,UAAM;AAAA,EACR;AAEA,SAAO,MAAM;AACf;AAQA,eAAe,4BACb,UACA,MACA,OACA,UACA,iBACA,SACiE;AACjE,MAAI,CAAC,gBAAgB,kBAAkB;AACrC,WAAO,EAAE,SAAS,MAAM,MAAA;AAAA,EAC1B;AAEA,QAAM,WAAW,MAAM,gBAAgB,iBAAiB,UAAU,MAAM,KAAK;AAC7E,MAAI,CAAC,UAAU;AACb,WAAO,EAAE,SAAS,MAAM,MAAA;AAAA,EAC1B;AAEA,MAAI,SAAS,SAAS,SAAS;AAC7B,UAAM,IAAI,qBAAqB,SAAS,UAAU,uBAAuB;AAAA,EAC3E;AAEA,MAAI,SAAS,SAAS,QAAQ;AAC5B,UAAM,aAAa,SAAS;AAC5B,YAAQ,KAAK;AAAA,MACX,YAAY,SAAS;AAAA,MACrB;AAAA,MACA,QACE,OAAO,eAAe,WAClB,cAAc,UAAU,IACvB,cAAc;AAAA,MACrB,UAAU;AAAA,IAAA,CACX;AACD,QAAI,gBAAgB,iBAAiB;AACnC,YAAM,gBAAgB,gBAAgB;AAAA,QACpC;AAAA,QACA;AAAA,QACA;AAAA,QACA,YAAY,SAAS;AAAA,QACrB,IAAI;AAAA,QACJ,UAAU;AAAA,QACV,QAAQ;AAAA,MAAA,CACT;AAAA,IACH;AACA,WAAO,EAAE,SAAS,MAAA;AAAA,EACpB;AAEA,SAAO,EAAE,SAAS,MAAM,OAAO,SAAS,KAAA;AAC1C;AAMA,gBAAgB,kBACd,UACA,MACA,UACA,OACA,SACA,eACA,SACA,iBACyC;AACzC,QAAM,YAAY,KAAK,IAAA;AACvB,MAAI;AACF,QAAI,CAAC,KAAK,SAAS;AACjB,YAAM,IAAI,MAAM,QAAQ,QAAQ,kCAAkC;AAAA,IACpE;AACA,UAAM,mBAAmB,QAAQ,QAAQ,KAAK,QAAQ,OAAO,OAAO,CAAC;AACrE,QAAI,SAAS,OAAO,wBAAwB,kBAAkB,aAAa;AAC3E,UAAM,WAAW,KAAK,IAAA,IAAQ;AAG9B,QAAI;AACJ,YAAQ,eAAe,cAAc,MAAA,OAAa,QAAW;AAC3D,YAAM;AAAA,IACR;AAIA,QAAI,KAAK,gBAAgB,iBAAiB,KAAK,YAAY,GAAG;AAC5D,eAAS,wBAAwB,KAAK,cAAc,MAAM;AAAA,IAC5D;AAEA,UAAM,cACJ,OAAO,WAAW,WAAW,cAAc,MAAM,IAAK,UAAU;AAElE,YAAQ,KAAK;AAAA,MACX,YAAY,SAAS;AAAA,MACrB;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,IAAA,CACD;AAED,QAAI,iBAAiB,iBAAiB;AACpC,YAAM,gBAAgB,gBAAgB;AAAA,QACpC;AAAA,QACA;AAAA,QACA;AAAA,QACA,YAAY,SAAS;AAAA,QACrB,IAAI;AAAA,QACJ;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AAAA,IACH;AAAA,EACF,SAAS,OAAgB;AACvB,UAAM,WAAW,KAAK,IAAA,IAAQ;AAG9B,QAAI;AACJ,YAAQ,eAAe,cAAc,MAAA,OAAa,QAAW;AAC3D,YAAM;AAAA,IACR;AAEA,QAAI,iBAAiB,sBAAsB;AACzC,YAAM;AAAA,IACR;AAEA,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;AACzD,YAAQ,KAAK;AAAA,MACX,YAAY,SAAS;AAAA,MACrB;AAAA,MACA,QAAQ,EAAE,OAAO,QAAA;AAAA,MACjB,OAAO;AAAA,MACP;AAAA,IAAA,CACD;AAED,QAAI,iBAAiB,iBAAiB;AACpC,YAAM,gBAAgB,gBAAgB;AAAA,QACpC;AAAA,QACA;AAAA,QACA;AAAA,QACA,YAAY,SAAS;AAAA,QACrB,IAAI;AAAA,QACJ;AAAA,QACA;AAAA,MAAA,CACD;AAAA,IACH;AAAA,EACF;AACF;AAEA,SAAS,sBACP,YACA,UACA,MACA,WACY;AACZ,MAAI;AACF,QAAI,SAAS;AACb,QAAI,KAAK,gBAAgB,iBAAiB,KAAK,YAAY,GAAG;AAC5D,eAAS,wBAAwB,KAAK,cAAc,MAAM;AAAA,IAC5D;AAEA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,QACE,OAAO,WAAW,WAAW,cAAc,MAAM,IAAK,UAAU;AAAA,IAAA;AAAA,EAEtE,SAAS,OAAgB;AACvB,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;AACzD,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,QAAQ,EAAE,OAAO,QAAA;AAAA,MACjB,OAAO;AAAA,IAAA;AAAA,EAEX;AACF;AAiBA,gBAAuB,iBACrB,WACA,OACA,gCAAsC,IAAA,GACtC,gBAAkC,oBAAI,IAAA,GACtC,wBAIA,iBACA,aACA,aAC2D;AAC3D,QAAM,UAA6B,CAAA;AACnC,QAAM,gBAAwC,CAAA;AAC9C,QAAM,uBAAiD,CAAA;AAGvD,QAAM,8BAAc,IAAA;AACpB,aAAW,QAAQ,OAAO;AACxB,YAAQ,IAAI,KAAK,MAAM,IAAI;AAAA,EAC7B;AAIA,QAAM,sBAAsB,UAAU,KAAK,CAAC,OAAO;AACjD,UAAM,IAAI,QAAQ,IAAI,GAAG,SAAS,IAAI;AACtC,WAAO,GAAG,iBAAiB,CAAC,UAAU,IAAI,YAAY,GAAG,EAAE,EAAE;AAAA,EAC/D,CAAC;AAED,aAAW,YAAY,WAAW;AAChC,UAAM,OAAO,QAAQ,IAAI,SAAS,SAAS,IAAI;AAC/C,UAAM,WAAW,SAAS,SAAS;AAEnC,QAAI,CAAC,MAAM;AAET,cAAQ,KAAK;AAAA,QACX,YAAY,SAAS;AAAA,QACrB;AAAA,QACA,QAAQ,EAAE,OAAO,iBAAiB,QAAQ,GAAA;AAAA,QAC1C,OAAO;AAAA,MAAA,CACR;AACD;AAAA,IACF;AAGA,QAAI,qBAAqB;AACvB,UAAI,CAAC,KAAK,iBAAiB,UAAU,IAAI,YAAY,SAAS,EAAE,EAAE,GAAG;AACnE;AAAA,MACF;AAAA,IACF;AAGA,QAAI,QAAiB,CAAA;AACrB,UAAM,UAAU,SAAS,SAAS,UAAU,UAAU;AACzC;AACX,UAAI;AACF,cAAM,SAAS,KAAK,MAAM,OAAO;AAEjC,gBAAQ,UAAU,OAAO,WAAW,WAAW,SAAS,CAAA;AAAA,MAC1D,SAAS,YAAY;AAEnB,cAAM,IAAI,MAAM,2CAA2C,OAAO,EAAE;AAAA,MACtE;AAAA,IACF;AAGA,QAAI,KAAK,eAAe,iBAAiB,KAAK,WAAW,GAAG;AAC1D,UAAI;AACF,gBAAQ,wBAAwB,KAAK,aAAa,KAAK;AAAA,MACzD,SAAS,iBAA0B;AACjC,cAAM,UACJ,2BAA2B,QACvB,gBAAgB,UAChB;AACN,gBAAQ,KAAK;AAAA,UACX,YAAY,SAAS;AAAA,UACrB;AAAA,UACA,QAAQ;AAAA,YACN,OAAO,oCAAoC,KAAK,IAAI,KAAK,OAAO;AAAA,UAAA;AAAA,UAElE,OAAO;AAAA,QAAA,CACR;AACD;AAAA,MACF;AAAA,IACF;AAGA,UAAM,gBAAoC,CAAA;AAC1C,UAAM,UAAU;AAAA,MACd,YAAY,SAAS;AAAA,MACrB,SAAS;AAAA,MACT;AAAA,MACA,iBAAiB,CAAC,WAAmB,UAA+B;AAClE,YAAI,wBAAwB;AAC1B,wBAAc;AAAA,YACZ,uBAAuB,WAAW;AAAA,cAChC,GAAG;AAAA,cACH,YAAY,SAAS;AAAA,YAAA,CACtB;AAAA,UAAA;AAAA,QAEL;AAAA,MACF;AAAA,IAAA;AAIF,QAAI,CAAC,KAAK,SAAS;AAEjB,UAAI,KAAK,eAAe;AACtB,cAAM,aAAa,YAAY,SAAS,EAAE;AAG1C,YAAI,UAAU,IAAI,UAAU,GAAG;AAC7B,gBAAM,WAAW,UAAU,IAAI,UAAU;AAEzC,cAAI,UAAU;AAEZ,gBAAI,cAAc,IAAI,SAAS,EAAE,GAAG;AAClC,sBAAQ;AAAA,gBACN;AAAA,kBACE,SAAS;AAAA,kBACT;AAAA,kBACA;AAAA,kBACA,cAAc,IAAI,SAAS,EAAE;AAAA,gBAAA;AAAA,cAC/B;AAAA,YAEJ,OAAO;AAEL,mCAAqB,KAAK;AAAA,gBACxB,YAAY,SAAS;AAAA,gBACrB;AAAA,gBACA;AAAA,cAAA,CACD;AAAA,YACH;AAAA,UACF,OAAO;AAEL,oBAAQ,KAAK;AAAA,cACX,YAAY,SAAS;AAAA,cACrB;AAAA,cACA,QAAQ,EAAE,OAAO,+BAAA;AAAA,cACjB,OAAO;AAAA,YAAA,CACR;AAAA,UACH;AAAA,QACF,OAAO;AAEL,wBAAc,KAAK;AAAA,YACjB,YAAY,SAAS;AAAA,YACrB,UAAU,SAAS,SAAS;AAAA,YAC5B;AAAA,YACA;AAAA,UAAA,CACD;AAAA,QACH;AAAA,MACF,OAAO;AAEL,YAAI,cAAc,IAAI,SAAS,EAAE,GAAG;AAClC,kBAAQ;AAAA,YACN;AAAA,cACE,SAAS;AAAA,cACT;AAAA,cACA;AAAA,cACA,cAAc,IAAI,SAAS,EAAE;AAAA,YAAA;AAAA,UAC/B;AAAA,QAEJ,OAAO;AAEL,+BAAqB,KAAK;AAAA,YACxB,YAAY,SAAS;AAAA,YACrB;AAAA,YACA;AAAA,UAAA,CACD;AAAA,QACH;AAAA,MACF;AACA;AAAA,IACF;AAGA,QAAI,KAAK,eAAe;AACtB,YAAM,aAAa,YAAY,SAAS,EAAE;AAG1C,UAAI,UAAU,IAAI,UAAU,GAAG;AAC7B,cAAM,WAAW,UAAU,IAAI,UAAU;AAEzC,YAAI,UAAU;AAEZ,cAAI,iBAAiB;AACnB,kBAAM,WAAW,MAAM;AAAA,cACrB;AAAA,cACA;AAAA,cACA;AAAA,cACA;AAAA,cACA;AAAA,cACA;AAAA,YAAA;AAEF,gBAAI,CAAC,SAAS,QAAS;AACvB,oBAAQ,SAAS;AAAA,UACnB;AAEA,iBAAO;AAAA,YACL;AAAA,YACA;AAAA,YACA;AAAA,YACA;AAAA,YACA;AAAA,YACA;AAAA,YACA;AAAA,YACA;AAAA,UAAA;AAAA,QAEJ,OAAO;AAEL,kBAAQ,KAAK;AAAA,YACX,YAAY,SAAS;AAAA,YACrB;AAAA,YACA,QAAQ,EAAE,OAAO,+BAAA;AAAA,YACjB,OAAO;AAAA,UAAA,CACR;AAAA,QACH;AAAA,MACF,OAAO;AAEL,sBAAc,KAAK;AAAA,UACjB,YAAY,SAAS;AAAA,UACrB;AAAA,UACA;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AACA;AAAA,IACF;AAGA,QAAI,iBAAiB;AACnB,YAAM,WAAW,MAAM;AAAA,QACrB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAEF,UAAI,CAAC,SAAS,QAAS;AACvB,cAAQ,SAAS;AAAA,IACnB;AAEA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO,EAAE,SAAS,eAAe,qBAAA;AACnC;"}
+{"version":3,"file":"tool-calls.js","sources":["../../../../../src/activities/chat/tools/tool-calls.ts"],"sourcesContent":["import { normalizeToolResult } from '../../../utilities/tool-result'\nimport { isStandardSchema, parseWithStandardSchema } from './schema-converter'\nimport type {\n  AnyTool,\n  ContentPart,\n  CustomEvent,\n  ModelMessage,\n  RunFinishedEvent,\n  Tool,\n  ToolCall,\n  ToolCallArgsEvent,\n  ToolCallEndEvent,\n  ToolCallStartEvent,\n  ToolExecutionContext,\n  ToolOutputState,\n} from '../../../types'\nimport type {\n  AfterToolCallInfo,\n  BeforeToolCallDecision,\n} from '../middleware/types'\nimport type { McpResourceReadResult } from '../mcp/types'\nimport type {\n  ContextFromTool,\n  DefinedContext,\n  MergeContext,\n  UnionToIntersection,\n} from '../runtime-context-types'\n\nfunction safeJsonParse(value: string): unknown {\n  try {\n    return JSON.parse(value)\n  } catch {\n    return value\n  }\n}\n\n/**\n * MCP Apps metadata attached to a server tool at discovery (see\n * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).\n *\n * - `uiResourceUri` / `serverId` are stamped by ai-mcp at tool discovery.\n * - `readResource` is bound by `MCPManager.discover()` (the one site that has\n *   both the tool and its originating source) so the resource can be eagerly\n *   read at the emit site. Under `chat()`-managed MCP lifecycle\n *   (`connection:'close'`), the MCP source is not disposed until the run\n *   drains, so `readResource` is still live at this emit point. Note: a caller\n *   who closes the MCP source early (outside `chat()`'s managed lifecycle)\n *   degrades fail-soft — `readResource` may reject, the widget is absent, but\n *   the tool result still flows to the model.\n *   `@tanstack/ai` never imports `@tanstack/ai-mcp`; this travels structurally\n *   on the tool.\n */\ninterface McpToolAppMeta {\n  uiResourceUri?: string\n  serverId?: string\n  /** Server-native (unprefixed) MCP tool name — used as the renderer's toolName. */\n  serverToolName?: string\n  readResource?: (uri: string) => Promise<McpResourceReadResult>\n}\n\nfunction readMcpAppMeta(tool: AnyTool): McpToolAppMeta | undefined {\n  const meta = (tool.metadata as { mcp?: McpToolAppMeta } | undefined)?.mcp\n  return meta\n}\n\n/**\n * Eagerly read a tool's linked `ui://` resource (MCP Apps) and emit a\n * `ui-resource` CUSTOM event so the client can render the widget. The model\n * still receives the normal text tool-result; the widget rides alongside and\n * never enters model input.\n *\n * Fail-soft: any read error logs a warning and emits nothing — it never throws,\n * so the normal tool-result still flows and a broken widget cannot break the run.\n */\nasync function emitUiResourceIfLinked<TContext>(\n  tool: AnyTool,\n  context: ToolExecutionContext<TContext>,\n): Promise<void> {\n  const mcp = readMcpAppMeta(tool)\n  const uiUri = mcp?.uiResourceUri\n  if (!uiUri || !mcp.readResource) return\n\n  // The try covers ONLY the fallible read — keep `emitCustomEvent` out of it so\n  // an exception from the emit path can't be mislabeled as a read failure.\n  let matched: McpResourceReadResult['contents'][number] | undefined\n  try {\n    const res = await mcp.readResource(uiUri)\n    // Emit ONLY the content whose uri matches the requested `uiUri`. A source\n    // can return unrelated contents; falling back to `contents[0]` would risk\n    // rendering a widget that doesn't correspond to the linked resource. This\n    // is a display widget — a mismatched resource is worse than none, so if no\n    // content matches we fail-soft (warn + return) rather than emit.\n    matched = res.contents.find((c) => c.uri === uiUri)\n  } catch (err) {\n    // fail-soft — the text tool-result already flows; a broken widget must\n    // not break the run.\n    console.warn(`[mcp-apps] failed to read ui resource ${uiUri}:`, err)\n    return\n  }\n  if (!matched) {\n    console.warn(\n      `[mcp-apps] ui resource ${uiUri} returned no content matching that uri; not emitting`,\n    )\n    return\n  }\n  // NOTE: `toolCallId` is intentionally NOT set here — it is stamped onto\n  // every emitted event by the `executeToolCalls` context wrapper, so the\n  // UIResourceEvent.value.toolCallId / UIResourcePart.toolCallId contract is\n  // still satisfied downstream.\n  context.emitCustomEvent('ui-resource', {\n    resource: {\n      uri: matched.uri,\n      mimeType: matched.mimeType ?? 'text/html',\n      text: matched.text,\n      blob: matched.blob,\n    },\n    serverId: mcp.serverId,\n    toolName: mcp.serverToolName ?? tool.name,\n    meta: undefined,\n  })\n}\n\n/**\n * Optional middleware hooks for tool execution.\n * When provided, these callbacks are invoked before/after each tool execution.\n */\nexport interface ToolExecutionMiddlewareHooks {\n  onBeforeToolCall?: (\n    toolCall: ToolCall,\n    tool: Tool | undefined,\n    args: unknown,\n  ) => Promise<BeforeToolCallDecision>\n  onAfterToolCall?: (info: AfterToolCallInfo) => Promise<void>\n}\n\n/**\n * Error thrown when middleware decides to abort the chat run during tool execution.\n */\nexport class MiddlewareAbortError extends Error {\n  constructor(reason: string) {\n    super(reason)\n    this.name = 'MiddlewareAbortError'\n  }\n}\n\n// The leaf context-inference primitives (ContextFromTool, MergeContext,\n// UnionToIntersection, DefinedContext) are shared with the chat activity\n// options layer — see ../runtime-context-types.\ntype RequiredContextFromToolUnion<T> = T extends unknown\n  ? undefined extends ContextFromTool<T>\n    ? never\n    : ContextFromTool<T>\n  : never\n\ntype ContextFromToolUnion<T> = [\n  UnionToIntersection<DefinedContext<ContextFromTool<T>>>,\n] extends [never]\n  ? unknown\n  : [RequiredContextFromToolUnion<T>] extends [never]\n    ? UnionToIntersection<DefinedContext<ContextFromTool<T>>> | undefined\n    : UnionToIntersection<DefinedContext<ContextFromTool<T>>>\n\ntype ContextFromTools<TTools> = TTools extends readonly [\n  infer THead,\n  ...infer TTail,\n]\n  ? MergeContext<ContextFromTool<THead>, ContextFromTools<TTail>>\n  : TTools extends ReadonlyArray<infer TTool>\n    ? ContextFromToolUnion<TTool>\n    : unknown\n\ntype ExecuteToolsContextArgs<TContext> = undefined extends TContext\n  ? [userContext?: TContext]\n  : [userContext: TContext]\n\n/**\n * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.\n *\n * Responsibilities:\n * - Accumulates streaming tool call events (ID, name, arguments)\n * - Validates tool calls (filters out incomplete ones)\n * - Executes tool `execute` functions with parsed arguments\n * - Emits `TOOL_CALL_END` events for client visibility\n * - Returns tool result messages for conversation history\n *\n * This class is used internally by the AI.chat() method to handle the automatic\n * tool execution loop. It can also be used independently for custom tool execution logic.\n *\n * @example\n * ```typescript\n * const manager = new ToolCallManager(tools);\n *\n * // During streaming, accumulate tool calls\n * for await (const chunk of stream) {\n *   if (chunk.type === 'TOOL_CALL_START') {\n *     manager.addToolCallStartEvent(chunk);\n *   } else if (chunk.type === 'TOOL_CALL_ARGS') {\n *     manager.addToolCallArgsEvent(chunk);\n *   }\n * }\n *\n * // After stream completes, execute tools\n * if (manager.hasToolCalls()) {\n *   const toolResults = yield* manager.executeTools(finishEvent);\n *   messages = [...messages, ...toolResults];\n *   manager.clear();\n * }\n * ```\n */\nexport class ToolCallManager<\n  TToolsOrContext = ReadonlyArray<AnyTool>,\n  TContext = TToolsOrContext extends ReadonlyArray<AnyTool>\n    ? ContextFromTools<TToolsOrContext>\n    : TToolsOrContext,\n> {\n  private readonly toolCallsMap = new Map<number, ToolCall>()\n  private readonly tools: TToolsOrContext extends ReadonlyArray<AnyTool>\n    ? TToolsOrContext\n    : ReadonlyArray<AnyTool>\n\n  constructor(\n    tools: TToolsOrContext extends ReadonlyArray<AnyTool>\n      ? TToolsOrContext\n      : ReadonlyArray<AnyTool>,\n  ) {\n    this.tools = tools\n  }\n\n  /**\n   * Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)\n   */\n  addToolCallStartEvent(event: ToolCallStartEvent): void {\n    const index = event.index ?? this.toolCallsMap.size\n    const runtimeEvent = event as Partial<ToolCallStartEvent> &\n      Pick<ToolCallStartEvent, 'toolName'>\n    const name = runtimeEvent.toolCallName ?? runtimeEvent.toolName\n    this.toolCallsMap.set(index, {\n      id: event.toolCallId,\n      type: 'function',\n      function: {\n        name,\n        arguments: '',\n      },\n      ...(event.metadata !== undefined && { metadata: event.metadata }),\n    })\n  }\n\n  /**\n   * Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)\n   */\n  addToolCallArgsEvent(event: ToolCallArgsEvent): void {\n    // Find the tool call by ID\n    for (const [, toolCall] of this.toolCallsMap.entries()) {\n      if (toolCall.id === event.toolCallId) {\n        toolCall.function.arguments += event.delta\n        break\n      }\n    }\n  }\n\n  /**\n   * Complete a tool call with its final input\n   * Called when TOOL_CALL_END is received\n   */\n  completeToolCall(event: ToolCallEndEvent): void {\n    for (const [, toolCall] of this.toolCallsMap.entries()) {\n      if (toolCall.id === event.toolCallId) {\n        if (event.input !== undefined) {\n          // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)\n          const normalized =\n            event.input && typeof event.input === 'object' ? event.input : {}\n          toolCall.function.arguments = JSON.stringify(normalized)\n        }\n        break\n      }\n    }\n  }\n\n  /**\n   * Check if there are any complete tool calls to execute\n   */\n  hasToolCalls(): boolean {\n    return this.getToolCalls().length > 0\n  }\n\n  /**\n   * Get all complete tool calls (filtered for valid ID and name)\n   */\n  getToolCalls(): Array<ToolCall> {\n    return Array.from(this.toolCallsMap.values()).filter(\n      (tc) => tc.id && tc.function.name && tc.function.name.trim().length > 0,\n    )\n  }\n\n  /**\n   * Execute all tool calls and return tool result messages\n   * Yields TOOL_CALL_END events for streaming\n   * @param finishEvent - RUN_FINISHED event from the stream\n   */\n  async *executeTools(\n    finishEvent: RunFinishedEvent,\n    ...contextArgs: ExecuteToolsContextArgs<TContext>\n  ): AsyncGenerator<ToolCallEndEvent, Array<ModelMessage>, void> {\n    const toolCallsArray = this.getToolCalls()\n    const toolResults: Array<ModelMessage> = []\n    const hasRuntimeContext = contextArgs.length > 0\n    const userContext = contextArgs[0]\n\n    for (const toolCall of toolCallsArray) {\n      const tool = this.tools.find((t) => t.name === toolCall.function.name)\n\n      let toolResultContent: string | Array<ContentPart>\n      let toolResultState: ToolOutputState | undefined\n      if (tool?.execute) {\n        try {\n          // Parse arguments (normalize null/non-object to {} for empty tool_use blocks)\n          let args: unknown\n          try {\n            const argsString = toolCall.function.arguments.trim() || '{}'\n            const parsed = JSON.parse(argsString)\n            args = parsed && typeof parsed === 'object' ? parsed : {}\n          } catch (parseError) {\n            throw new Error(\n              `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`,\n            )\n          }\n\n          // Validate input against inputSchema (for Standard Schema compliant schemas)\n          if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {\n            try {\n              args = parseWithStandardSchema(tool.inputSchema, args)\n            } catch (validationError: unknown) {\n              const message =\n                validationError instanceof Error\n                  ? validationError.message\n                  : 'Validation failed'\n              throw new Error(\n                `Input validation failed for tool ${tool.name}: ${message}`,\n              )\n            }\n          }\n\n          // Execute the tool\n          const executionContext = {\n            toolCallId: toolCall.id,\n            context: userContext,\n            emitCustomEvent: () => {},\n          } as ToolExecutionContext<TContext>\n          let result = hasRuntimeContext\n            ? await tool.execute(args, executionContext)\n            : await tool.execute(args)\n\n          // Validate output against outputSchema if provided (for Standard\n          // Schema compliant schemas). Unlike the previous implementation we\n          // intentionally validate `undefined`/`null` results too, so a tool\n          // whose schema forbids them surfaces a validation error instead of\n          // silently passing — the schema itself decides whether they're valid.\n          if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n            try {\n              result = parseWithStandardSchema(tool.outputSchema, result)\n            } catch (validationError: unknown) {\n              const message =\n                validationError instanceof Error\n                  ? validationError.message\n                  : 'Validation failed'\n              throw new Error(\n                `Output validation failed for tool ${tool.name}: ${message}`,\n              )\n            }\n          }\n\n          toolResultContent = normalizeToolResult(result)\n        } catch (error: unknown) {\n          // If tool execution fails, add error message\n          const message =\n            error instanceof Error ? error.message : 'Unknown error'\n          toolResultContent = `Error executing tool: ${message}`\n          toolResultState = 'output-error'\n        }\n      } else {\n        // Tool doesn't have execute function, add placeholder\n        toolResultContent = `Tool ${toolCall.function.name} does not have an execute function`\n      }\n\n      // Emit TOOL_CALL_END event\n      yield {\n        type: 'TOOL_CALL_END',\n        toolCallId: toolCall.id,\n        toolCallName: toolCall.function.name,\n        toolName: toolCall.function.name,\n        model: finishEvent.model,\n        timestamp: Date.now(),\n        result: toolResultContent,\n        ...(toolResultState !== undefined && { state: toolResultState }),\n      } as ToolCallEndEvent\n\n      // Add tool result message\n      toolResults.push({\n        role: 'tool',\n        content: toolResultContent,\n        toolCallId: toolCall.id,\n      })\n    }\n\n    return toolResults\n  }\n\n  /**\n   * Clear the tool calls map for the next iteration\n   */\n  clear(): void {\n    this.toolCallsMap.clear()\n  }\n}\n\nexport interface ToolResult {\n  toolCallId: string\n  toolName: string\n  result: any\n  state?: 'output-available' | 'output-error'\n  /** Duration of tool execution in milliseconds (only for server-executed tools) */\n  duration?: number\n}\n\nexport interface ApprovalRequest {\n  toolCallId: string\n  toolName: string\n  input: any\n  approvalId: string\n}\n\nexport interface ClientToolRequest {\n  toolCallId: string\n  toolName: string\n  input: any\n}\n\ninterface ExecuteToolCallsResult {\n  /** Tool results ready to send to LLM */\n  results: Array<ToolResult>\n  /** Tools that need user approval before execution */\n  needsApproval: Array<ApprovalRequest>\n  /** Tools that need client-side execution */\n  needsClientExecution: Array<ClientToolRequest>\n}\n\n/**\n * Helper that runs a tool execution promise while polling for pending custom events.\n * Yields any custom events that are emitted during execution, then returns the\n * execution result.\n */\nasync function* executeWithEventPolling<T>(\n  executionPromise: Promise<T>,\n  pendingEvents: Array<CustomEvent>,\n): AsyncGenerator<CustomEvent, T, void> {\n  // Use an object to track mutable state across the async boundary\n  const state = { done: false, result: undefined as T }\n  const executionWithFlag = executionPromise.then((r) => {\n    state.done = true\n    state.result = r\n    return r\n  })\n\n  while (!state.done) {\n    // Wait for either the execution to complete or a short timeout\n    await Promise.race([\n      executionWithFlag,\n      new Promise((resolve) => setTimeout(resolve, 10)),\n    ])\n\n    // Flush any pending events\n    let event: CustomEvent | undefined\n    while ((event = pendingEvents.shift()) !== undefined) {\n      yield event\n    }\n  }\n\n  // Final flush in case events were emitted right at completion\n  let event: CustomEvent | undefined\n  while ((event = pendingEvents.shift()) !== undefined) {\n    yield event\n  }\n\n  return state.result\n}\n\n/**\n * Apply a middleware onBeforeToolCall decision.\n * Returns the (possibly transformed) input if execution should proceed,\n * or undefined if the tool call was skipped (result already pushed).\n * Throws MiddlewareAbortError if the decision is 'abort'.\n */\nasync function applyBeforeToolCallDecision(\n  toolCall: ToolCall,\n  tool: Tool,\n  input: unknown,\n  toolName: string,\n  middlewareHooks: ToolExecutionMiddlewareHooks,\n  results: Array<ToolResult>,\n): Promise<{ proceed: true; input: unknown } | { proceed: false }> {\n  if (!middlewareHooks.onBeforeToolCall) {\n    return { proceed: true, input }\n  }\n\n  const decision = await middlewareHooks.onBeforeToolCall(toolCall, tool, input)\n  if (!decision) {\n    return { proceed: true, input }\n  }\n\n  if (decision.type === 'abort') {\n    throw new MiddlewareAbortError(decision.reason || 'Aborted by middleware')\n  }\n\n  if (decision.type === 'skip') {\n    const skipResult = decision.result\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result:\n        typeof skipResult === 'string'\n          ? safeJsonParse(skipResult)\n          : (skipResult ?? null),\n      duration: 0,\n    })\n    if (middlewareHooks.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: true,\n        duration: 0,\n        result: skipResult,\n      })\n    }\n    return { proceed: false }\n  }\n\n  return { proceed: true, input: decision.args }\n}\n\n/**\n * Execute a server-side tool with event polling, output validation, and middleware hooks.\n * Yields CustomEvent chunks during execution and pushes the result to the results array.\n */\nexport async function* executeServerTool<TContext = unknown>(\n  toolCall: ToolCall,\n  tool: AnyTool,\n  toolName: string,\n  input: unknown,\n  context: ToolExecutionContext<TContext>,\n  pendingEvents: Array<CustomEvent>,\n  results: Array<ToolResult>,\n  middlewareHooks?: ToolExecutionMiddlewareHooks,\n): AsyncGenerator<CustomEvent, void, void> {\n  const startTime = Date.now()\n  try {\n    if (!tool.execute) {\n      throw new Error(`Tool ${toolName} has no execute() implementation`)\n    }\n    const executionPromise = Promise.resolve(tool.execute(input, context))\n    let result = yield* executeWithEventPolling(executionPromise, pendingEvents)\n    const duration = Date.now() - startTime\n\n    // MCP Apps: if this tool links a ui:// resource, eagerly read it and queue\n    // a `ui-resource` CUSTOM event. The MCP source stays live until the run\n    // drains (MCPManager's `connection:'close'` policy disposes on completion),\n    // so `readResource` is callable here. Fail-soft: a read error warns and\n    // emits nothing — the text result still flows.\n    await emitUiResourceIfLinked(tool, context)\n\n    // Flush remaining events (including any queued ui-resource event)\n    let pendingEvent: CustomEvent | undefined\n    while ((pendingEvent = pendingEvents.shift()) !== undefined) {\n      yield pendingEvent\n    }\n\n    // Validate output against outputSchema if provided. Validates\n    // `undefined`/`null` too — the schema decides whether they're valid.\n    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n      result = parseWithStandardSchema(tool.outputSchema, result)\n    }\n\n    const finalResult =\n      typeof result === 'string' ? safeJsonParse(result) : (result ?? null)\n\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result: finalResult,\n      duration,\n    })\n\n    if (middlewareHooks?.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: true,\n        duration,\n        result: finalResult,\n      })\n    }\n  } catch (error: unknown) {\n    const duration = Date.now() - startTime\n\n    // Flush remaining events\n    let pendingEvent: CustomEvent | undefined\n    while ((pendingEvent = pendingEvents.shift()) !== undefined) {\n      yield pendingEvent\n    }\n\n    if (error instanceof MiddlewareAbortError) {\n      throw error\n    }\n\n    const message = error instanceof Error ? error.message : 'Unknown error'\n    results.push({\n      toolCallId: toolCall.id,\n      toolName,\n      result: { error: message },\n      state: 'output-error',\n      duration,\n    })\n\n    if (middlewareHooks?.onAfterToolCall) {\n      await middlewareHooks.onAfterToolCall({\n        toolCall,\n        tool,\n        toolName,\n        toolCallId: toolCall.id,\n        ok: false,\n        duration,\n        error,\n      })\n    }\n  }\n}\n\nfunction buildClientToolResult(\n  toolCallId: string,\n  toolName: string,\n  tool: AnyTool,\n  rawResult: unknown,\n): ToolResult {\n  try {\n    let result = rawResult\n    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {\n      result = parseWithStandardSchema(tool.outputSchema, result)\n    }\n\n    return {\n      toolCallId,\n      toolName,\n      result:\n        typeof result === 'string' ? safeJsonParse(result) : (result ?? null),\n    }\n  } catch (error: unknown) {\n    const message = error instanceof Error ? error.message : 'Validation failed'\n    return {\n      toolCallId,\n      toolName,\n      result: { error: message },\n      state: 'output-error',\n    }\n  }\n}\n\n/**\n * Execute tool calls based on their configuration.\n * Yields CustomEvent chunks during tool execution for real-time progress updates.\n *\n * Handles three cases:\n * 1. Client tools (no execute) - request client to execute\n * 2. Server tools with approval - check approval before executing\n * 3. Normal server tools - execute immediately\n *\n * @param toolCalls - Tool calls from the LLM\n * @param tools - Available tools with their configurations\n * @param approvals - Map of approval decisions (approval.id -> approved boolean)\n * @param clientResults - Map of client-side execution results (toolCallId -> result)\n * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)\n */\nexport async function* executeToolCalls<TContext = unknown>(\n  toolCalls: Array<ToolCall>,\n  tools: ReadonlyArray<AnyTool>,\n  approvals: Map<string, boolean> = new Map(),\n  clientResults: Map<string, any> = new Map(),\n  createCustomEventChunk?: (\n    eventName: string,\n    value: Record<string, any>,\n  ) => CustomEvent,\n  middlewareHooks?: ToolExecutionMiddlewareHooks,\n  userContext?: TContext,\n  abortSignal?: AbortSignal,\n): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {\n  const results: Array<ToolResult> = []\n  const needsApproval: Array<ApprovalRequest> = []\n  const needsClientExecution: Array<ClientToolRequest> = []\n\n  // Create tool lookup map\n  const toolMap = new Map<string, AnyTool>()\n  for (const tool of tools) {\n    toolMap.set(tool.name, tool)\n  }\n\n  // Batch gating: when any tool in the batch still needs an approval decision,\n  // defer all execution so side effects don't happen before the user decides.\n  const hasPendingApprovals = toolCalls.some((tc) => {\n    const t = toolMap.get(tc.function.name)\n    return t?.needsApproval && !approvals.has(`approval_${tc.id}`)\n  })\n\n  for (const toolCall of toolCalls) {\n    const tool = toolMap.get(toolCall.function.name)\n    const toolName = toolCall.function.name\n\n    if (!tool) {\n      // Unknown tool - return error\n      results.push({\n        toolCallId: toolCall.id,\n        toolName,\n        result: { error: `Unknown tool: ${toolName}` },\n        state: 'output-error',\n      })\n      continue\n    }\n\n    // Skip non-pending tools while approvals are outstanding\n    if (hasPendingApprovals) {\n      if (!tool.needsApproval || approvals.has(`approval_${toolCall.id}`)) {\n        continue\n      }\n    }\n\n    // Parse arguments, throwing error if invalid JSON\n    let input: unknown = {}\n    const argsStr = toolCall.function.arguments.trim() || '{}'\n    if (argsStr) {\n      try {\n        const parsed = JSON.parse(argsStr)\n        // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)\n        input = parsed && typeof parsed === 'object' ? parsed : {}\n      } catch (parseError) {\n        // If parsing fails, throw error to fail fast\n        throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`)\n      }\n    }\n\n    // Validate input against inputSchema (for Standard Schema compliant schemas)\n    if (tool.inputSchema && isStandardSchema(tool.inputSchema)) {\n      try {\n        input = parseWithStandardSchema(tool.inputSchema, input)\n      } catch (validationError: unknown) {\n        const message =\n          validationError instanceof Error\n            ? validationError.message\n            : 'Validation failed'\n        results.push({\n          toolCallId: toolCall.id,\n          toolName,\n          result: {\n            error: `Input validation failed for tool ${tool.name}: ${message}`,\n          },\n          state: 'output-error',\n        })\n        continue\n      }\n    }\n\n    // Create a ToolExecutionContext for this tool call with event emission\n    const pendingEvents: Array<CustomEvent> = []\n    const context = {\n      toolCallId: toolCall.id,\n      context: userContext,\n      abortSignal,\n      emitCustomEvent: (eventName: string, value: Record<string, any>) => {\n        if (createCustomEventChunk) {\n          pendingEvents.push(\n            createCustomEventChunk(eventName, {\n              ...value,\n              toolCallId: toolCall.id,\n            }),\n          )\n        }\n      },\n    } as ToolExecutionContext<TContext>\n\n    // CASE 1: Client-side tool (no execute function)\n    if (!tool.execute) {\n      // Check if tool needs approval\n      if (tool.needsApproval) {\n        const approvalId = `approval_${toolCall.id}`\n\n        // Check if approval decision exists\n        if (approvals.has(approvalId)) {\n          const approved = approvals.get(approvalId)\n\n          if (approved) {\n            // Approved - check if client has executed\n            if (clientResults.has(toolCall.id)) {\n              results.push(\n                buildClientToolResult(\n                  toolCall.id,\n                  toolName,\n                  tool,\n                  clientResults.get(toolCall.id),\n                ),\n              )\n            } else {\n              // Approved but not executed yet - request client execution\n              needsClientExecution.push({\n                toolCallId: toolCall.id,\n                toolName,\n                input,\n              })\n            }\n          } else {\n            // User declined\n            results.push({\n              toolCallId: toolCall.id,\n              toolName,\n              result: { error: 'User declined tool execution' },\n              state: 'output-error',\n            })\n          }\n        } else {\n          // Need approval first\n          needsApproval.push({\n            toolCallId: toolCall.id,\n            toolName: toolCall.function.name,\n            input,\n            approvalId,\n          })\n        }\n      } else {\n        // No approval needed - check if client has executed\n        if (clientResults.has(toolCall.id)) {\n          results.push(\n            buildClientToolResult(\n              toolCall.id,\n              toolName,\n              tool,\n              clientResults.get(toolCall.id),\n            ),\n          )\n        } else {\n          // Request client execution\n          needsClientExecution.push({\n            toolCallId: toolCall.id,\n            toolName,\n            input,\n          })\n        }\n      }\n      continue\n    }\n\n    // CASE 2: Server tool with approval required\n    if (tool.needsApproval) {\n      const approvalId = `approval_${toolCall.id}`\n\n      // Check if approval decision exists\n      if (approvals.has(approvalId)) {\n        const approved = approvals.get(approvalId)\n\n        if (approved) {\n          // Apply middleware before-hook for approved tools\n          if (middlewareHooks) {\n            const decision = await applyBeforeToolCallDecision(\n              toolCall,\n              tool,\n              input,\n              toolName,\n              middlewareHooks,\n              results,\n            )\n            if (!decision.proceed) continue\n            input = decision.input\n          }\n\n          yield* executeServerTool(\n            toolCall,\n            tool,\n            toolName,\n            input,\n            context,\n            pendingEvents,\n            results,\n            middlewareHooks,\n          )\n        } else {\n          // User declined\n          results.push({\n            toolCallId: toolCall.id,\n            toolName,\n            result: { error: 'User declined tool execution' },\n            state: 'output-error',\n          })\n        }\n      } else {\n        // Need approval\n        needsApproval.push({\n          toolCallId: toolCall.id,\n          toolName,\n          input,\n          approvalId,\n        })\n      }\n      continue\n    }\n\n    // CASE 3: Normal server tool - execute immediately\n    if (middlewareHooks) {\n      const decision = await applyBeforeToolCallDecision(\n        toolCall,\n        tool,\n        input,\n        toolName,\n        middlewareHooks,\n        results,\n      )\n      if (!decision.proceed) continue\n      input = decision.input\n    }\n\n    yield* executeServerTool(\n      toolCall,\n      tool,\n      toolName,\n      input,\n      context,\n      pendingEvents,\n      results,\n      middlewareHooks,\n    )\n  }\n\n  return { results, needsApproval, needsClientExecution }\n}\n"],"names":["event"],"mappings":"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"}

package/dist/esm/client.d.ts

@@ -40,5 +40,5 @@ export { BatchStrategy, CompositeStrategy, defaultJSONParser, ImmediateStrategy,
 export type { ChunkRecording, ChunkStrategy, InternalToolCallState, JSONParser, ProcessorResult, ProcessorState, StreamProcessorEvents, StreamProcessorOptions, ToolCallState, ToolResultState, } from './activities/chat/stream/index.js';
 export { uiMessagesToWire } from './utilities/ag-ui-wire.js';
 export type { WireMessage } from './utilities/ag-ui-wire.js';
-export type { AudioPart, ContentPart, ContentPartDataSource, ContentPartSource, ContentPartUrlSource, CustomEvent, DocumentPart, ImagePart, MediaInputMetadata, MediaInputRole, MediaPrompt, MediaPromptPart, MessagePart, ModelMessage, RunErrorEvent, RunFinishedEvent, SchemaInput, StreamChunk, StructuredOutputPart, TextPart, ThinkingPart, ToolCall, ToolCallPart, ToolResultPart, UIMessage, VideoPart, InferSchemaType, } from './types.js';
+export type { AudioPart, ContentPart, ContentPartDataSource, ContentPartSource, ContentPartUrlSource, CustomEvent, DocumentPart, ImagePart, MediaInputMetadata, MediaInputRole, MediaPrompt, MediaPromptPart, MessagePart, ModelMessage, RunErrorEvent, RunFinishedEvent, SchemaInput, StreamChunk, StructuredOutputPart, TextPart, ThinkingPart, ToolCall, ToolCallPart, ToolResultPart, UIMessage, UIResourcePart, VideoPart, InferSchemaType, } from './types.js';
 export type { AudioVisualization, RealtimeAdapter, RealtimeConnection, RealtimeError, RealtimeErrorCode, RealtimeEvent, RealtimeEventHandler, RealtimeEventPayloads, RealtimeMessage, RealtimeMessagePart, RealtimeMode, RealtimeSessionConfig, RealtimeStatus, RealtimeToken, RealtimeAudioPart, RealtimeImagePart, RealtimeTextPart, RealtimeToolCallPart, RealtimeToolResultPart, VADConfig, } from './realtime/types.js';

package/dist/esm/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sources":["../../src/client.ts"],"sourcesContent":["export enum EventType {\n  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',\n  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',\n  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',\n  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',\n  TOOL_CALL_START = 'TOOL_CALL_START',\n  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',\n  TOOL_CALL_END = 'TOOL_CALL_END',\n  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',\n  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',\n  THINKING_START = 'THINKING_START',\n  THINKING_END = 'THINKING_END',\n  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',\n  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',\n  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',\n  STATE_SNAPSHOT = 'STATE_SNAPSHOT',\n  STATE_DELTA = 'STATE_DELTA',\n  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',\n  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',\n  ACTIVITY_DELTA = 'ACTIVITY_DELTA',\n  RAW = 'RAW',\n  CUSTOM = 'CUSTOM',\n  RUN_STARTED = 'RUN_STARTED',\n  RUN_FINISHED = 'RUN_FINISHED',\n  RUN_ERROR = 'RUN_ERROR',\n  STEP_STARTED = 'STEP_STARTED',\n  STEP_FINISHED = 'STEP_FINISHED',\n  REASONING_START = 'REASONING_START',\n  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',\n  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',\n  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',\n  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',\n  REASONING_END = 'REASONING_END',\n  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',\n}\n\nexport {\n  toolDefinition,\n  type AnyClientTool,\n  type ClientTool,\n  type InferToolInput,\n  type InferToolName,\n  type InferToolOutput,\n  type ToolDefinition,\n  type ToolDefinitionConfig,\n  type ToolDefinitionInstance,\n} from './activities/chat/tools/tool-definition'\n\nexport {\n  convertSchemaToJsonSchema,\n  isStandardSchema,\n  parseWithStandardSchema,\n} from './activities/chat/tools/schema-converter'\n\nexport {\n  convertMessagesToModelMessages,\n  generateMessageId,\n  modelMessageToUIMessage,\n  modelMessagesToUIMessages,\n  normalizeToUIMessage,\n  uiMessageToModelMessages,\n} from './activities/chat/messages'\n\nexport {\n  BatchStrategy,\n  CompositeStrategy,\n  defaultJSONParser,\n  ImmediateStrategy,\n  parsePartialJSON,\n  PartialJSONParser,\n  PunctuationStrategy,\n  StreamProcessor,\n  WordBoundaryStrategy,\n} from './activities/chat/stream/index'\nexport type {\n  ChunkRecording,\n  ChunkStrategy,\n  InternalToolCallState,\n  JSONParser,\n  ProcessorResult,\n  ProcessorState,\n  StreamProcessorEvents,\n  StreamProcessorOptions,\n  ToolCallState,\n  ToolResultState,\n} from './activities/chat/stream/index'\n\nexport { uiMessagesToWire } from './utilities/ag-ui-wire'\nexport type { WireMessage } from './utilities/ag-ui-wire'\n\nexport type {\n  AudioPart,\n  ContentPart,\n  ContentPartDataSource,\n  ContentPartSource,\n  ContentPartUrlSource,\n  CustomEvent,\n  DocumentPart,\n  ImagePart,\n  MediaInputMetadata,\n  MediaInputRole,\n  MediaPrompt,\n  MediaPromptPart,\n  MessagePart,\n  ModelMessage,\n  RunErrorEvent,\n  RunFinishedEvent,\n  SchemaInput,\n  StreamChunk,\n  StructuredOutputPart,\n  TextPart,\n  ThinkingPart,\n  ToolCall,\n  ToolCallPart,\n  ToolResultPart,\n  UIMessage,\n  VideoPart,\n  InferSchemaType,\n} from './types'\n\nexport type {\n  AudioVisualization,\n  RealtimeAdapter,\n  RealtimeConnection,\n  RealtimeError,\n  RealtimeErrorCode,\n  RealtimeEvent,\n  RealtimeEventHandler,\n  RealtimeEventPayloads,\n  RealtimeMessage,\n  RealtimeMessagePart,\n  RealtimeMode,\n  RealtimeSessionConfig,\n  RealtimeStatus,\n  RealtimeToken,\n  RealtimeAudioPart,\n  RealtimeImagePart,\n  RealtimeTextPart,\n  RealtimeToolCallPart,\n  RealtimeToolResultPart,\n  VADConfig,\n} from './realtime/types'\n"],"names":["EventType"],"mappings":";;;;;;;AAAO,IAAK,8BAAAA,eAAL;AACLA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,sBAAA,IAAuB;AACvBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,cAAA,IAAe;AACfA,aAAA,6BAAA,IAA8B;AAC9BA,aAAA,+BAAA,IAAgC;AAChCA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,aAAA,IAAc;AACdA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,KAAA,IAAM;AACNA,aAAA,QAAA,IAAS;AACTA,aAAA,aAAA,IAAc;AACdA,aAAA,cAAA,IAAe;AACfA,aAAA,WAAA,IAAY;AACZA,aAAA,cAAA,IAAe;AACfA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,uBAAA,IAAwB;AACxBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,eAAA,IAAgB;AAChBA,aAAA,2BAAA,IAA4B;AAjClB,SAAAA;AAAA,GAAA,aAAA,CAAA,CAAA;"}
+{"version":3,"file":"client.js","sources":["../../src/client.ts"],"sourcesContent":["export enum EventType {\n  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',\n  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',\n  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',\n  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',\n  TOOL_CALL_START = 'TOOL_CALL_START',\n  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',\n  TOOL_CALL_END = 'TOOL_CALL_END',\n  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',\n  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',\n  THINKING_START = 'THINKING_START',\n  THINKING_END = 'THINKING_END',\n  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',\n  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',\n  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',\n  STATE_SNAPSHOT = 'STATE_SNAPSHOT',\n  STATE_DELTA = 'STATE_DELTA',\n  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',\n  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',\n  ACTIVITY_DELTA = 'ACTIVITY_DELTA',\n  RAW = 'RAW',\n  CUSTOM = 'CUSTOM',\n  RUN_STARTED = 'RUN_STARTED',\n  RUN_FINISHED = 'RUN_FINISHED',\n  RUN_ERROR = 'RUN_ERROR',\n  STEP_STARTED = 'STEP_STARTED',\n  STEP_FINISHED = 'STEP_FINISHED',\n  REASONING_START = 'REASONING_START',\n  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',\n  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',\n  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',\n  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',\n  REASONING_END = 'REASONING_END',\n  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',\n}\n\nexport {\n  toolDefinition,\n  type AnyClientTool,\n  type ClientTool,\n  type InferToolInput,\n  type InferToolName,\n  type InferToolOutput,\n  type ToolDefinition,\n  type ToolDefinitionConfig,\n  type ToolDefinitionInstance,\n} from './activities/chat/tools/tool-definition'\n\nexport {\n  convertSchemaToJsonSchema,\n  isStandardSchema,\n  parseWithStandardSchema,\n} from './activities/chat/tools/schema-converter'\n\nexport {\n  convertMessagesToModelMessages,\n  generateMessageId,\n  modelMessageToUIMessage,\n  modelMessagesToUIMessages,\n  normalizeToUIMessage,\n  uiMessageToModelMessages,\n} from './activities/chat/messages'\n\nexport {\n  BatchStrategy,\n  CompositeStrategy,\n  defaultJSONParser,\n  ImmediateStrategy,\n  parsePartialJSON,\n  PartialJSONParser,\n  PunctuationStrategy,\n  StreamProcessor,\n  WordBoundaryStrategy,\n} from './activities/chat/stream/index'\nexport type {\n  ChunkRecording,\n  ChunkStrategy,\n  InternalToolCallState,\n  JSONParser,\n  ProcessorResult,\n  ProcessorState,\n  StreamProcessorEvents,\n  StreamProcessorOptions,\n  ToolCallState,\n  ToolResultState,\n} from './activities/chat/stream/index'\n\nexport { uiMessagesToWire } from './utilities/ag-ui-wire'\nexport type { WireMessage } from './utilities/ag-ui-wire'\n\nexport type {\n  AudioPart,\n  ContentPart,\n  ContentPartDataSource,\n  ContentPartSource,\n  ContentPartUrlSource,\n  CustomEvent,\n  DocumentPart,\n  ImagePart,\n  MediaInputMetadata,\n  MediaInputRole,\n  MediaPrompt,\n  MediaPromptPart,\n  MessagePart,\n  ModelMessage,\n  RunErrorEvent,\n  RunFinishedEvent,\n  SchemaInput,\n  StreamChunk,\n  StructuredOutputPart,\n  TextPart,\n  ThinkingPart,\n  ToolCall,\n  ToolCallPart,\n  ToolResultPart,\n  UIMessage,\n  UIResourcePart,\n  VideoPart,\n  InferSchemaType,\n} from './types'\n\nexport type {\n  AudioVisualization,\n  RealtimeAdapter,\n  RealtimeConnection,\n  RealtimeError,\n  RealtimeErrorCode,\n  RealtimeEvent,\n  RealtimeEventHandler,\n  RealtimeEventPayloads,\n  RealtimeMessage,\n  RealtimeMessagePart,\n  RealtimeMode,\n  RealtimeSessionConfig,\n  RealtimeStatus,\n  RealtimeToken,\n  RealtimeAudioPart,\n  RealtimeImagePart,\n  RealtimeTextPart,\n  RealtimeToolCallPart,\n  RealtimeToolResultPart,\n  VADConfig,\n} from './realtime/types'\n"],"names":["EventType"],"mappings":";;;;;;;AAAO,IAAK,8BAAAA,eAAL;AACLA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,sBAAA,IAAuB;AACvBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,oBAAA,IAAqB;AACrBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,kBAAA,IAAmB;AACnBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,cAAA,IAAe;AACfA,aAAA,6BAAA,IAA8B;AAC9BA,aAAA,+BAAA,IAAgC;AAChCA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,aAAA,IAAc;AACdA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,mBAAA,IAAoB;AACpBA,aAAA,gBAAA,IAAiB;AACjBA,aAAA,KAAA,IAAM;AACNA,aAAA,QAAA,IAAS;AACTA,aAAA,aAAA,IAAc;AACdA,aAAA,cAAA,IAAe;AACfA,aAAA,WAAA,IAAY;AACZA,aAAA,cAAA,IAAe;AACfA,aAAA,eAAA,IAAgB;AAChBA,aAAA,iBAAA,IAAkB;AAClBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,2BAAA,IAA4B;AAC5BA,aAAA,uBAAA,IAAwB;AACxBA,aAAA,yBAAA,IAA0B;AAC1BA,aAAA,eAAA,IAAgB;AAChBA,aAAA,2BAAA,IAA4B;AAjClB,SAAAA;AAAA,GAAA,aAAA,CAAA,CAAA;"}

package/dist/esm/types.d.ts

@@ -298,7 +298,28 @@ export interface StructuredOutputPart<TData = unknown> {
     /** Populated when `status === 'error'`. */
     errorMessage?: string;
 }
-export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart | StructuredOutputPart<TData>;
+export interface UIResourcePart {
+    type: 'ui-resource';
+    /** The ui:// resource object in MCP-native shape — fed straight to the renderer. */
+    resource: {
+        uri: string;
+        mimeType: string;
+        text?: string;
+        blob?: string;
+    };
+    /** Pool prefix / config key — routes interactive calls to the right MCP server. */
+    serverId?: string;
+    /** Links the widget to the originating tool call — correlates it with the
+     *  sibling ToolCallPart/ToolResultPart in the same message. */
+    toolCallId: string;
+    /** Server-native (unprefixed) MCP tool name whose UI this resource renders.
+     *  Required by the renderer (`@mcp-ui/client`'s `AppRenderer` `toolName` prop). */
+    toolName: string;
+    /** Reserved for future passthrough of the resource/tool `_meta.ui` (e.g. frame-size hints).
+     *  Currently always `undefined` — nothing populates this field yet. */
+    meta?: Record<string, unknown>;
+}
+export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart | StructuredOutputPart<TData> | UIResourcePart;
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
  * Contains parts that can be text, tool calls, or tool results. Generic over
@@ -1082,6 +1103,18 @@ export interface ToolInputAvailableEvent extends CustomEvent {
         input: unknown;
     };
 }
+/** Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into
+ *  a UIResourcePart on the assistant UIMessage. Never enters model input. */
+export interface UIResourceEvent extends CustomEvent {
+    name: 'ui-resource';
+    value: {
+        resource: UIResourcePart['resource'];
+        serverId?: string;
+        toolCallId: string;
+        toolName: string;
+        meta?: Record<string, unknown>;
+    };
+}
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/ai-core/chat-experience/SKILL.md

@@ -278,7 +278,35 @@ if (part.type === 'image') {
 }
 ```
 
-### 4. HTTP Stream Format (Alternative to SSE)
+### 4. Sending Audio Messages (Browser Recording)
+
+Use `useAudioRecorder` from `@tanstack/ai-react` (or `createAudioRecorder` in Svelte) to capture audio in the browser. The resolved `AudioRecording` includes a ready-to-use `part` that slots directly into `sendMessage`.
+
+```typescript
+import {
+  useAudioRecorder,
+  useChat,
+  fetchServerSentEvents,
+} from '@tanstack/ai-react'
+
+const { isRecording, isSupported, start, stop } = useAudioRecorder()
+const { sendMessage } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+})
+
+async function toggle() {
+  if (!isRecording) {
+    await start()
+    return
+  }
+  const recording = await stop()
+  await sendMessage({ content: [recording.part] })
+}
+```
+
+`recording.part` is `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`. Returns the recorder's native format (`audio/webm` or `audio/mp4`) with no transcoding.
+
+### 5. HTTP Stream Format (Alternative to SSE)
 
 Use `toHttpResponse` + `fetchHttpStream` for newline-delimited JSON instead of SSE.
 
@@ -310,7 +338,7 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
-### 5. MCP Tool Discovery via `chat({ mcp })`
+### 6. MCP Tool Discovery via `chat({ mcp })`
 
 Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
 clients. Useful when you want minimal boilerplate and don't need to reuse the

package/skills/ai-core/media-generation/SKILL.md

@@ -359,6 +359,19 @@ const { generate, result, isLoading } = useGenerateSpeech({
 Adapter: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
 gpt-4o-mini-transcribe).
 
+> **Capturing audio in the browser:** Use `useAudioRecorder` from `@tanstack/ai-react` to record directly in the browser, then pass the recording as the `audio` input to `generate()`, or use `recording.part` as a prompt part in chat/generation calls. No transcoding or extra dependencies required — the recorder returns the native browser format (`audio/webm` or `audio/mp4`). For transcription, wrap it as a `data:` URL so the provider gets the real content type; passing raw `recording.base64` makes the adapter assume `audio/mpeg` and mislabel the webm/mp4 bytes.
+>
+> ```typescript
+> const { isRecording, start, stop } = useAudioRecorder()
+> const { generate } = useTranscription({
+>   connection: fetchServerSentEvents('/api/transcribe'),
+> })
+> // ...
+> const recording = await stop()
+> const mimeType = recording.mimeType.split(';')[0] // strip ;codecs=...
+> await generate({ audio: `data:${mimeType};base64,${recording.base64}` })
+> ```
+
 ```typescript
 import { generateTranscription } from '@tanstack/ai'
 import { openaiTranscription } from '@tanstack/ai-openai'

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

@@ -75,7 +75,7 @@ import { updateCartUIDef } from '@/tools/definitions'
 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, updateCartUIDef], // server tool + client definition
   })
@@ -158,7 +158,7 @@ const getUserData = getUserDataDef.server(async ({ userId }) => {
 
 // In your route handler:
 const stream = chat({
-  adapter: openaiText('gpt-4o'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   tools: [getUserData],
 })
@@ -188,7 +188,7 @@ Server -- pass definition only (no execute function):
 
 ```typescript
 const stream = chat({
-  adapter: openaiText('gpt-4o'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   tools: [showNotificationDef],
 })
@@ -405,6 +405,13 @@ The post-discovery payload always returns the full description and schema regard
 `@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
 hosted on any MCP server (Streamable HTTP, SSE, or stdio).
 
+**MCP tools and UI resources:** When an MCP tool result carries a `ui://`
+resource URI (via `_meta.ui.resourceUri`), TanStack AI surfaces it as a
+`UIResourcePart` on the assistant `UIMessage` in the client message list.
+`UIResourcePart` is a presentational-only part — it never enters model input.
+See the `@tanstack/ai-mcp` skill for the full MCP Apps API
+(`createMcpAppCallHandler`, `createMcpAppBridge`, `MCPAppResource`).
+
 ### Basic usage — auto-discovery
 
 ```typescript

package/src/activities/chat/mcp/manager.ts

@@ -1,6 +1,33 @@
 import type { ServerTool } from '../tools/tool-definition'
 import type { ChatMCPOptions, MCPToolSource } from './types'
 
+/**
+ * Bind the source's `readResource` onto a ui-linked tool's `metadata.mcp` so it
+ * travels with the tool to the server-tool execution/emit site (`tool-calls.ts`).
+ *
+ * `discover()` is the single place in `@tanstack/ai` that has both a tool and
+ * its originating source, and `@tanstack/ai` must not import `@tanstack/ai-mcp`,
+ * so this is where the source handle is threaded onto the tool. Only tools that
+ * actually link a `ui://` resource (their discovery stamped
+ * `metadata.mcp.uiResourceUri`) and whose source can read resources get bound;
+ * everything else is left untouched.
+ *
+ * This mutates the discovered tool's `metadata.mcp` in place. That is safe
+ * because discovery returns fresh tool objects per `discover()` call: the bound
+ * `readResource` closes over `source`, whose connection stays live until the run
+ * drains. If discovery results were ever cached and reused across runs, this
+ * would bind a closure over an already-closed source — bind onto a copy then.
+ */
+function bindReadResource(tool: ServerTool, source: MCPToolSource): void {
+  if (!source.readResource) return
+  const meta = (
+    tool.metadata as { mcp?: { uiResourceUri?: string } } | undefined
+  )?.mcp
+  if (!meta?.uiResourceUri) return
+  ;(meta as { readResource?: MCPToolSource['readResource'] }).readResource =
+    source.readResource.bind(source)
+}
+
 export class MCPDuplicateToolNameError extends Error {
   constructor(public readonly toolName: string) {
     super(
@@ -57,7 +84,10 @@ export class MCPManager {
       for (const [source, result] of zipped) {
         if (result === undefined) continue
         if (result.status === 'fulfilled') {
-          tools.push(...result.value)
+          for (const t of result.value) {
+            bindReadResource(t, source)
+            tools.push(t)
+          }
         } else if (this.#onDiscoveryError) {
           // throw/reject inside handler ⇒ propagate (fail-fast); return ⇒ skip
           await this.#onDiscoveryError(result.reason, source)

package/src/activities/chat/mcp/types.ts

@@ -1,5 +1,20 @@
 import type { ServerTool } from '../tools/tool-definition'
 
+/**
+ * The shape `readResource` resolves to — a structural subset of MCP's
+ * `ReadResourceResult`. Single source of truth shared by
+ * `MCPToolSource.readResource` (this file) and the tool-bound
+ * `McpToolAppMeta.readResource` (tool-calls.ts) so the two copies cannot drift.
+ */
+export interface McpResourceReadResult {
+  contents: Array<{
+    uri: string
+    mimeType?: string
+    text?: string
+    blob?: string
+  }>
+}
+
 /**
  * Minimal structural shape that `chat({ mcp })` needs from an MCP client.
  *
@@ -13,6 +28,14 @@ export interface MCPToolSource {
   // forwards what is declared here.
   tools: (options?: { lazy?: boolean }) => Promise<Array<ServerTool>>
   close: () => Promise<void>
+  /**
+   * Reads an MCP resource by URI. Used by the chat manager to eagerly fetch
+   * `ui://` resource widgets (MCP Apps) after a tool result resolves.
+   *
+   * Optional — sources that do not serve `ui://` resources need not implement
+   * this method. `ai-mcp`'s `MCPClient` satisfies this structurally.
+   */
+  readResource?: (uri: string) => Promise<McpResourceReadResult>
 }
 
 /**

package/src/activities/chat/messages.ts

@@ -322,6 +322,11 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         }
         break
 
+      case 'ui-resource':
+        // MCP Apps widget — rendered client-side only. It must never enter
+        // model input, so it is intentionally dropped from the model message.
+        break
+
       default:
         break
     }

package/src/activities/chat/stream/processor.ts

@@ -56,6 +56,8 @@ import type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
+  UIResourceEvent,
+  UIResourcePart,
 } from '../../../types'
 
 /**
@@ -1624,6 +1626,46 @@ export class StreamProcessor {
       return
     }
 
+    // Handle MCP Apps ui-resource events — materialize a UIResourcePart on the
+    // active assistant message. Never falls through to onCustomEvent because
+    // ui-resource is a system event, not a user-defined custom event.
+    if (chunk.name === 'ui-resource' && chunk.value) {
+      const v: UIResourceEvent['value'] = chunk.value
+      // Resolve the target assistant message. When a toolCallId is present, the
+      // tool call's OWNER message is authoritative, so prefer it first; fall
+      // back to the active assistant id only if the tool call isn't mapped.
+      // This avoids misattaching the widget to a different active message in a
+      // multi-message session.
+      const resolvedMessageId =
+        this.toolCallToMessage.get(v.toolCallId) ?? messageId
+      if (resolvedMessageId) {
+        const part: UIResourcePart = {
+          type: 'ui-resource',
+          resource: v.resource,
+          toolCallId: v.toolCallId,
+          toolName: v.toolName,
+          ...(v.serverId !== undefined && { serverId: v.serverId }),
+          ...(v.meta !== undefined && { meta: v.meta }),
+        }
+        this.messages = this.messages.map((msg) =>
+          msg.id === resolvedMessageId
+            ? { ...msg, parts: [...msg.parts, part] }
+            : msg,
+        )
+        this.emitMessagesChange()
+      } else {
+        // No owner message and no active assistant id — the server read and
+        // streamed a widget that has nowhere to attach (e.g. a toolCallId never
+        // registered, or the event arrived after the run cleared its active
+        // ids). Drop fail-soft, but warn: a vanished widget is otherwise
+        // undebuggable from the client.
+        console.warn(
+          `[mcp-apps] dropped ui-resource: no target message for toolCallId "${v.toolCallId}" (toolName "${v.toolName}")`,
+        )
+      }
+      return
+    }
+
     // Forward non-system custom events to onCustomEvent callback
     if (this.events.onCustomEvent) {
       const toolCallId =