@tanstack/ai 0.61.0 → 0.63.0

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

@@ -344,6 +344,7 @@ export interface ChatMiddlewareConfig {
 export interface ChatResumeToolState {
   approvals?: ReadonlyMap<string, ToolApprovalResolution> | undefined
   clientToolResults?: ReadonlyMap<string, unknown> | undefined
+  clientToolErrors?: ReadonlyMap<string, string> | undefined
   genericInterrupts?:
     | ReadonlyMap<string, ChatResumeGenericResolution>
     | undefined

package/src/activities/chat/stream/message-updaters.ts

@@ -11,6 +11,7 @@ import type {
   StructuredOutputPart,
   ThinkingPart,
   ToolCallPart,
+  ToolResultOutcome,
   ToolResultPart,
   UIMessage,
 } from '../../../types'
@@ -117,6 +118,7 @@ export function updateToolResultPart(
   content: string | Array<ContentPart>,
   state: ToolResultState,
   error?: string,
+  outcome?: ToolResultOutcome,
 ): Array<UIMessage> {
   return messages.map((msg) => {
     if (msg.id !== messageId) {
@@ -134,6 +136,7 @@ export function updateToolResultPart(
       toolCallId,
       content,
       state,
+      ...(outcome !== undefined && { outcome }),
       ...(error && { error }),
     }
 

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

@@ -36,6 +36,8 @@ import {
 import { getChunkRunId } from '../../../utilities/chunk-ids'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import {
+  isContentPartArray,
+  isToolResultOutcome,
   normalizeToolResult,
   toolResultErrorText,
 } from '../../../utilities/tool-result'
@@ -181,6 +183,23 @@ function interruptBatchHasGeneric(interrupts: Array<Interrupt>): boolean {
   })
 }
 
+/**
+ * The canonical arguments string for a `TOOL_CALL_END.input`, or `undefined`
+ * when JSON cannot carry it: `JSON.stringify` returns `undefined` (despite
+ * its declared type) for a top-level function or symbol and throws on BigInt
+ * and circular references. `null` is not tool arguments either, so it also
+ * keeps the streamed value instead of writing `arguments = "null"`.
+ */
+function serializeToolInput(input: unknown): string | undefined {
+  if (input === undefined || input === null) return undefined
+  try {
+    const serialized: unknown = JSON.stringify(input)
+    return typeof serialized === 'string' ? serialized : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * StreamProcessor - State machine for processing AI response streams
  *
@@ -1953,11 +1972,13 @@ export class StreamProcessor {
    * Handle TOOL_CALL_END event — arguments are finalized (input-complete).
    * Tool output arrives on TOOL_CALL_RESULT, not on this event.
    *
-   * If TOOL_CALL_END carries parsed `input`, use it as the canonical arguments:
-   * back-fill the accumulated string when no TOOL_CALL_ARGS deltas were seen
-   * (adapters that deliver the whole input on END — e.g. Anthropic
-   * server_tool_use / web_search — issue #839) and override the rendered part's
-   * `input` with the canonical value.
+   * If TOOL_CALL_END carries parsed `input`, it is the canonical arguments:
+   * write it into the accumulated string and override the rendered part's
+   * `input` with it. That covers adapters that deliver the whole input on END
+   * (e.g. Anthropic server_tool_use / web_search — issue #839) and adapters
+   * that stream the wire arguments and then normalize them (OpenAI strict-mode
+   * null widening, undone by the adapter after #939), so `arguments` and
+   * `input` never disagree on the persisted part.
    *
    * @see docs/chat-architecture.md#single-shot-tool-call-response — End-to-end flow
    */
@@ -1980,16 +2001,15 @@ export class StreamProcessor {
     // Transition the tool call to input-complete (the authoritative completion signal)
     const existingToolCall = msgState.toolCalls.get(chunk.toolCallId)
     if (existingToolCall && existingToolCall.state !== 'input-complete') {
-      // Back-fill the arguments string from the parsed input when no
-      // TOOL_CALL_ARGS deltas were received, so completeToolCall's strict parse
-      // surfaces the correct value on the ToolCallPart.
-      if (input !== undefined && !existingToolCall.arguments) {
-        try {
-          existingToolCall.arguments = JSON.stringify(input)
-        } catch {
-          // circular refs, BigInt, etc. — leave arguments empty rather than
-          // aborting stream processing
-        }
+      // The parsed input replaces the accumulated arguments string, so
+      // completeToolCall's strict parse surfaces the canonical value on the
+      // ToolCallPart even when the streamed deltas carried a provider-side
+      // reshaping of it. An input JSON cannot carry is not canonical: both
+      // `arguments` and `input` then stay with the streamed value, so the
+      // two never disagree.
+      const serializedInput = serializeToolInput(input)
+      if (serializedInput !== undefined) {
+        existingToolCall.arguments = serializedInput
       }
 
       const index = msgState.toolCallOrder.indexOf(chunk.toolCallId)
@@ -1998,7 +2018,7 @@ export class StreamProcessor {
       // Canonicalize on the parsed input: overrides the accumulated-args parse
       // that completeToolCall wrote (adapters may coerce values differently
       // between streamed args and the final structured input).
-      if (input !== undefined) {
+      if (serializedInput !== undefined) {
         existingToolCall.parsedArguments = input
         this.messages = updateToolCallPart(this.messages, messageId, {
           id: existingToolCall.id,
@@ -2042,9 +2062,14 @@ export class StreamProcessor {
     if (!messageId) return
 
     const extra = chunk as AdapterYieldChunk
+    const rawToolResultOutcome = tanstackMetadata(chunk)?.toolResultOutcome
+    const toolResultOutcome = isToolResultOutcome(rawToolResultOutcome)
+      ? rawToolResultOutcome
+      : undefined
     const isOutputError =
       extra.state === 'output-error' ||
-      tanstackMetadata(chunk)?.state === 'output-error'
+      tanstackMetadata(chunk)?.state === 'output-error' ||
+      toolResultOutcome !== undefined
 
     // Step 1: Update the tool-call part's output field
     let output: unknown
@@ -2069,9 +2094,14 @@ export class StreamProcessor {
       this.messages,
       messageId,
       chunk.toolCallId,
-      aguiContentToContentParts(chunk.content),
+      // The server sends a ContentPart[] result as a JSON string. Keep the
+      // parsed array so uiMessagesToWire can carry it in metadata.
+      isContentPartArray(output)
+        ? output
+        : aguiContentToContentParts(chunk.content),
       resultState,
       resultState === 'error' ? toolResultErrorText(output) : undefined,
+      toolResultOutcome,
     )
     this.emitMessagesChange()
   }
@@ -2678,11 +2708,11 @@ export class StreamProcessor {
       toolCall.parsedArguments = undefined
     }
 
-    // Don't downgrade the rendered part of a call that already reached the
-    // terminal 'error' state (e.g. an output-error TOOL_CALL_RESULT arrived
+    // Don't downgrade the rendered part of a call that already reached a
+    // terminal 'error' or 'complete' state (e.g. a tool result arrived
     // without a preceding TOOL_CALL_END). The RUN_FINISHED / finalizeStream
-    // safety net must not clobber a failed call back to 'input-complete'.
-    if (this.isToolCallPartErrored(toolCall.id)) {
+    // safety net must not clobber a finished call back to 'input-complete'.
+    if (this.isToolCallPartTerminal(toolCall.id)) {
       return
     }
 
@@ -2728,11 +2758,11 @@ export class StreamProcessor {
   }
 
   /**
-   * Whether the rendered tool-call part for the given id has reached the
-   * terminal 'error' state. Used to prevent the completion safety net from
-   * downgrading a failed call back to 'input-complete'.
+   * Whether the rendered tool-call part for the given id has reached a
+   * terminal 'error' or 'complete' state. Used to prevent the completion
+   * safety net from downgrading a finished call back to 'input-complete'.
    */
-  private isToolCallPartErrored(toolCallId: string): boolean {
+  private isToolCallPartTerminal(toolCallId: string): boolean {
     // `initialMessages` may be ModelMessage-shaped (no `parts`) — e.g. the
     // common pattern of seeding a processor with the same messages passed to
     // `chat()`. Guard the access so iterating them never throws.
@@ -2742,7 +2772,7 @@ export class StreamProcessor {
         (part) =>
           part.type === 'tool-call' &&
           part.id === toolCallId &&
-          part.state === 'error',
+          (part.state === 'error' || part.state === 'complete'),
       ),
     )
   }

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

@@ -2,7 +2,12 @@ import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
 import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
-import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
+import {
+  StandardSchemaValidationError,
+  isStandardSchema,
+  parseWithStandardSchema,
+  validateWithStandardSchema,
+} from './schema-converter'
 import type { ToolApprovalResolution } from '../../../interrupts'
 import type {
   AnyTool,
@@ -19,6 +24,8 @@ import type {
   ToolCallEndEvent,
   ToolCallStartEvent,
   ToolExecutionContext,
+  ToolInputResponse,
+  ToolResultOutcome,
   ToolOutputState,
 } from '../../../types'
 import type {
@@ -462,6 +469,8 @@ export interface ToolResult {
   toolName: string
   result: any
   state?: 'output-available' | 'output-error'
+  /** Set when the user or middleware cancelled or denied the tool call; state is output-error. */
+  outcome?: ToolResultOutcome
   /** Duration of tool execution in milliseconds (only for server-executed tools) */
   duration?: number
   /**
@@ -490,9 +499,38 @@ export interface ClientToolRequest {
   input: any
 }
 
+/** Form or sampling input that paused a server tool. */
+export interface McpInputRequest {
+  toolCallId: string
+  toolName: string
+  kind: 'form' | 'sampling'
+  request: unknown
+}
+
+interface McpInputRequiredThrow {
+  name: 'MCPInputRequiredError'
+  kind: 'form' | 'sampling'
+  request: unknown
+}
+
+function isMcpInputRequired(value: unknown): value is McpInputRequiredThrow {
+  if (typeof value !== 'object' || value === null) return false
+  if (!('name' in value) || value.name !== 'MCPInputRequiredError') {
+    return false
+  }
+  if (!('kind' in value)) return false
+  const kindIsFormOrSampling =
+    value.kind === 'form' || value.kind === 'sampling'
+  if (!kindIsFormOrSampling) return false
+  return 'request' in value
+}
+
 export interface ToolResumeExecutionState {
+  clientToolErrors?: ReadonlyMap<string, string>
   deniedToolResults?: ReadonlyMap<string, unknown>
   cancelledToolCallIds?: ReadonlySet<string>
+  /** Answers to `mcp_input` interrupts, by tool call id. */
+  inputResponses?: ReadonlyMap<string, ToolInputResponse>
 }
 
 function approvalResolution(
@@ -527,6 +565,8 @@ interface ExecuteToolCallsResult {
   needsApproval: Array<ApprovalRequest>
   /** Tools that need client-side execution */
   needsClientExecution: Array<ClientToolRequest>
+  /** Server tools that paused for MCP form or sampling input */
+  inputRequired: Array<McpInputRequest>
   /** Interrupts raised by subagents that run as tools */
   subagentInterrupts: Array<Interrupt>
 }
@@ -639,6 +679,7 @@ export async function* executeServerTool<TContext = unknown>(
   pendingEvents: Array<CustomEvent | StreamChunk>,
   results: Array<ToolResult>,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
+  inputRequired?: Array<McpInputRequest>,
   subagentInterrupts?: Array<Interrupt>,
 ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
   const startTime = Date.now()
@@ -744,6 +785,18 @@ export async function* executeServerTool<TContext = unknown>(
       throw error
     }
 
+    // Same shape as MCPInputRequiredError. Pause instead of a tool error.
+    if (isMcpInputRequired(error)) {
+      if (!inputRequired) throw error
+      inputRequired.push({
+        toolCallId: toolCall.id,
+        toolName,
+        kind: error.kind,
+        request: error.request,
+      })
+      return
+    }
+
     const message = error instanceof Error ? error.message : 'Unknown error'
     results.push({
       toolCallId: toolCall.id,
@@ -768,17 +821,35 @@ export async function* executeServerTool<TContext = unknown>(
   }
 }
 
-function buildClientToolResult(
+async function buildClientToolResult(
   toolCallId: string,
   toolName: string,
   tool: AnyTool,
   rawResult: unknown,
   input?: unknown,
-): ToolResult {
+  errorText?: string,
+): Promise<ToolResult> {
+  if (errorText !== undefined) {
+    return {
+      toolCallId,
+      toolName,
+      result: { error: errorText },
+      input,
+      state: 'output-error',
+    }
+  }
+
   try {
     let result = rawResult
     if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
-      result = parseWithStandardSchema(tool.outputSchema, result)
+      const validation = await validateWithStandardSchema<unknown>(
+        tool.outputSchema,
+        result,
+      )
+      if (!validation.success) {
+        throw new StandardSchemaValidationError(validation.issues)
+      }
+      result = validation.data
     }
 
     const parsed =
@@ -835,6 +906,7 @@ export async function* executeToolCalls<TContext = unknown>(
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
+  const inputRequired: Array<McpInputRequest> = []
   const subagentInterrupts: Array<Interrupt> = []
 
   // Create tool lookup map
@@ -891,6 +963,7 @@ export async function* executeToolCalls<TContext = unknown>(
         toolName,
         result: { error: 'Tool execution cancelled' },
         state: 'output-error',
+        outcome: 'cancelled',
       })
       continue
     }
@@ -942,10 +1015,12 @@ export async function* executeToolCalls<TContext = unknown>(
 
     // Create a ToolExecutionContext for this tool call with event emission
     const pendingEvents: Array<CustomEvent | StreamChunk> = []
+    const inputResponse = resumeState?.inputResponses?.get(toolCall.id)
     const context = {
       toolCallId: toolCall.id,
       context: userContext,
       abortSignal,
+      ...(inputResponse !== undefined ? { inputResponse } : {}),
       emitCustomEvent: (
         eventName: string,
         value: Record<string, any>,
@@ -980,14 +1055,16 @@ export async function* executeToolCalls<TContext = unknown>(
           if (approved) {
             input = editedApprovalArgs(resolution) ?? input
             // Approved - check if client has executed
-            if (clientResults.has(toolCall.id)) {
+            const clientError = resumeState?.clientToolErrors?.get(toolCall.id)
+            if (clientResults.has(toolCall.id) || clientError !== undefined) {
               results.push(
-                buildClientToolResult(
+                await buildClientToolResult(
                   toolCall.id,
                   toolName,
                   tool,
                   clientResults.get(toolCall.id),
                   input,
+                  clientError,
                 ),
               )
             } else {
@@ -1008,6 +1085,7 @@ export async function* executeToolCalls<TContext = unknown>(
                 deniedApprovalResult(resolution),
               input,
               state: 'output-error',
+              outcome: 'denied',
             })
           }
         } else {
@@ -1021,14 +1099,16 @@ export async function* executeToolCalls<TContext = unknown>(
         }
       } else {
         // No approval needed - check if client has executed
-        if (clientResults.has(toolCall.id)) {
+        const clientError = resumeState?.clientToolErrors?.get(toolCall.id)
+        if (clientResults.has(toolCall.id) || clientError !== undefined) {
           results.push(
-            buildClientToolResult(
+            await buildClientToolResult(
               toolCall.id,
               toolName,
               tool,
               clientResults.get(toolCall.id),
               input,
+              clientError,
             ),
           )
         } else {
@@ -1077,6 +1157,7 @@ export async function* executeToolCalls<TContext = unknown>(
             pendingEvents,
             results,
             middlewareHooks,
+            inputRequired,
             subagentInterrupts,
           )
         } else {
@@ -1089,6 +1170,7 @@ export async function* executeToolCalls<TContext = unknown>(
               deniedApprovalResult(resolution),
             input,
             state: 'output-error',
+            outcome: 'denied',
           })
         }
       } else {
@@ -1126,9 +1208,16 @@ export async function* executeToolCalls<TContext = unknown>(
       pendingEvents,
       results,
       middlewareHooks,
+      inputRequired,
       subagentInterrupts,
     )
   }
 
-  return { results, needsApproval, needsClientExecution, subagentInterrupts }
+  return {
+    results,
+    needsApproval,
+    needsClientExecution,
+    inputRequired,
+    subagentInterrupts,
+  }
 }

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

@@ -99,6 +99,7 @@ export interface ServerTool<
   outputSchema?: TOutput
   needsApproval?: TNeedsApproval
   approvalSchema?: TApprovalSchema
+  execution?: 'task'
 }
 
 /**
@@ -127,6 +128,7 @@ export interface ClientTool<
   outputSchema?: TOutput
   needsApproval?: TNeedsApproval
   approvalSchema?: TApprovalSchema
+  execution?: 'task'
   lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
@@ -158,6 +160,7 @@ export interface ToolDefinitionInstance<
   outputSchema: TOutput
   needsApproval?: TNeedsApproval
   approvalSchema: TApprovalSchema
+  execution?: 'task'
   readonly [toolApprovalCapability]?: {
     needsApproval: TNeedsApproval
     approvalSchema: TApprovalSchema
@@ -221,6 +224,7 @@ export type ToolDefinitionConfig<
   outputSchema?: TOutput
   lazy?: boolean
   metadata?: Record<string, unknown>
+  execution?: 'task'
 } & ApprovalConfig<TNeedsApproval, TApprovalSchema>
 
 /**
@@ -353,6 +357,7 @@ export function toolDefinition<
   const outputSchema = config.outputSchema as TOutput
   const approvalSchema = config.approvalSchema as TApprovalSchema
   const needsApproval = config.needsApproval as TNeedsApproval | undefined
+  const execution = config.execution
 
   const definition: ToolDefinition<
     TInput,
@@ -367,6 +372,7 @@ export function toolDefinition<
     outputSchema,
     approvalSchema,
     needsApproval,
+    execution,
     server<TContext = unknown>(
       execute: ToolExecuteFunction<TInput, TOutput, TContext>,
     ): ServerTool<
@@ -385,6 +391,7 @@ export function toolDefinition<
         outputSchema,
         approvalSchema,
         needsApproval,
+        execution,
         execute,
       }
     },
@@ -407,6 +414,7 @@ export function toolDefinition<
         outputSchema,
         approvalSchema,
         needsApproval,
+        execution,
         ...(execute !== undefined && { execute }),
       }
     },

package/src/activities/evaluate/adapter.ts

@@ -131,6 +131,10 @@ export interface EvaluateAdapterResult {
   model: string
   answers: Record<string, WireAnswer>
   usage: TokenUsage
+  /** Provider response id, for example to look the request up later. */
+  id?: string
+  /** Upstream provider that served the request, when a router reports it. */
+  provider?: string
 }
 
 /**

package/src/activities/evaluate/index.ts

@@ -100,6 +100,10 @@ export interface EvaluateResultMeta {
   /** Resolved model id from the provider. */
   model: string
   usage: TokenUsage
+  /** Provider response id, when the adapter returns one. */
+  id?: string
+  /** Upstream provider that served the request, when the adapter returns one. */
+  provider?: string
 }
 
 /**
@@ -576,6 +580,8 @@ export async function decide<
     return withMeta(answers, {
       model: result.model,
       usage: result.usage,
+      ...(result.id !== undefined && { id: result.id }),
+      ...(result.provider !== undefined && { provider: result.provider }),
     })
   } catch (error) {
     const duration = Date.now() - startTime

package/src/client.ts

@@ -371,6 +371,7 @@ export type {
   ThinkingPart,
   ToolCall,
   ToolCallPart,
+  ToolResultOutcome,
   ToolResultPart,
   UIMessage,
   UIResourcePart,

package/src/index.ts

@@ -535,6 +535,7 @@ export type { WireMessage } from './utilities/ag-ui-wire'
 export {
   isContentPart,
   isContentPartArray,
+  isToolResultOutcome,
   normalizeToolResult,
 } from './utilities/tool-result'
 export {

package/src/interrupt-resume.ts

@@ -14,6 +14,7 @@ import {
   isStandardSchema,
   validateWithStandardSchema,
 } from './activities/chat/tools/schema-converter'
+import { tanstackMetadata } from './utilities/merge-metadata'
 import type {
   InterruptBinding,
   InterruptSubmissionError,
@@ -95,6 +96,33 @@ function stringField(
   return typeof value[key] === 'string' ? value[key] : undefined
 }
 
+type ClientToolResumeResult =
+  | { state: 'output-available'; output: unknown }
+  | { state: 'output-error'; errorText: string }
+
+function clientToolResult(
+  entry: RunAgentResumeItem,
+): ClientToolResumeResult | null {
+  if (tanstackMetadata(entry)?.state === 'output-error') {
+    const result = objectValue(entry.payload)
+    if (
+      !result ||
+      Object.keys(result).length !== 1 ||
+      typeof result.error !== 'string'
+    ) {
+      return null
+    }
+    return {
+      state: 'output-error',
+      errorText: result.error,
+    }
+  }
+  return {
+    state: 'output-available',
+    output: entry.payload,
+  }
+}
+
 function normalizeIssuePath(
   path: ReadonlyArray<unknown> | undefined,
 ): ReadonlyArray<string | number> | undefined {
@@ -528,7 +556,19 @@ export async function validateInterruptResumeBatch(
     if (schemaDrifted) continue
 
     if (binding.kind === 'client-tool-execution') {
-      if (responseSchema !== undefined) {
+      const result = clientToolResult(entry)
+      if (!result) {
+        errors.push(
+          interruptItemError(
+            input,
+            record.interruptId,
+            'invalid-tool-output',
+            `Tool ${binding.toolName} result is invalid.`,
+          ),
+        )
+        continue
+      }
+      if (result.state === 'output-available' && responseSchema !== undefined) {
         await pushSchemaIssues({
           request: input,
           errors,
@@ -539,13 +579,16 @@ export async function validateInterruptResumeBatch(
           label: `Tool ${binding.toolName} output is invalid`,
         })
       }
-      if (tool.outputSchema !== undefined) {
+      if (
+        result.state === 'output-available' &&
+        tool.outputSchema !== undefined
+      ) {
         await pushSchemaIssues({
           request: input,
           errors,
           interruptId: record.interruptId,
           schema: tool.outputSchema,
-          value: entry.payload,
+          value: result.output,
           code: 'invalid-tool-output',
           label: `Tool ${binding.toolName} output is invalid`,
         })
@@ -682,6 +725,7 @@ export async function validateInterruptResumeBatch(
   const canonical = canonicalizeInterruptResolutions(input.resume ?? [])
   const approvals = new Map<string, ToolApprovalResolution>()
   const clientToolResults = new Map<string, unknown>()
+  const clientToolErrors = new Map<string, string>()
   const genericInterrupts = new Map<
     string,
     | { interruptId: string; status: 'resolved'; payload: unknown }
@@ -738,7 +782,13 @@ export async function validateInterruptResumeBatch(
       continue
     }
     if (binding.kind === 'client-tool-execution') {
-      clientToolResults.set(binding.toolCallId, entry.payload)
+      const result = clientToolResult(entry)
+      if (!result) continue
+      if (result.state === 'output-error') {
+        clientToolErrors.set(binding.toolCallId, result.errorText)
+      } else {
+        clientToolResults.set(binding.toolCallId, result.output)
+      }
       continue
     }
     const envelope = objectValue(entry.payload)
@@ -781,6 +831,7 @@ export async function validateInterruptResumeBatch(
     resumeToolState: {
       approvals,
       clientToolResults,
+      clientToolErrors,
       genericInterrupts,
       deniedToolResults,
       cancelledToolCallIds,