@tanstack/ai 0.61.0 → 0.64.0

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

@@ -1,8 +1,14 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
 import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
+import { mergeStreams } from '../../../utilities/merge-streams'
 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,
@@ -13,12 +19,15 @@ import type {
   ModelMessage,
   RunFinishedEvent,
   StreamChunk,
+  TextOptions,
   Tool,
   ToolCall,
   ToolCallArgsEvent,
   ToolCallEndEvent,
   ToolCallStartEvent,
   ToolExecutionContext,
+  ToolInputResponse,
+  ToolResultOutcome,
   ToolOutputState,
 } from '../../../types'
 import type {
@@ -462,6 +471,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 +501,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 +567,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 +681,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 +787,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 +823,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 =
@@ -816,6 +889,9 @@ function buildClientToolResult(
  * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
+ * @param toolExecution - `'parallel'` (default) prepares every call in call
+ *   order, then starts the server tools together. `'sequential'` runs one
+ *   call at a time. Results come back in call order either way.
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
@@ -831,11 +907,12 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
+  toolExecution: NonNullable<TextOptions['toolExecution']> = 'parallel',
 ): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
-  const subagentInterrupts: Array<Interrupt> = []
+  const inputRequired: Array<McpInputRequest> = []
 
   // Create tool lookup map
   const toolMap = new Map<string, AnyTool>()
@@ -843,6 +920,66 @@ export async function* executeToolCalls<TContext = unknown>(
     toolMap.set(tool.name, tool)
   }
 
+  const runsInOrder = toolExecution === 'sequential'
+  // Parallel mode collects the server runs here. `mergeStreams` starts them
+  // together after the loop.
+  const runs: Array<AsyncGenerator<CustomEvent | StreamChunk, void, void>> = []
+  // Errors thrown by a run or a before-hook. They are rethrown only after every
+  // started tool has finished, so no tool outlives the batch.
+  const failures: Array<unknown> = []
+  // Each call's subagent interrupts, so they come back in call order.
+  const interruptsByCall = new Map<string, Array<Interrupt>>()
+
+  // A tool that has not started when the run aborts never starts. It gets an
+  // error result, so every call of the batch still has a result.
+  async function* runServerTool(
+    toolCall: ToolCall,
+    tool: AnyTool,
+    toolName: string,
+    input: unknown,
+    context: ToolExecutionContext<TContext>,
+    pendingEvents: Array<CustomEvent | StreamChunk>,
+  ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
+    try {
+      if (abortSignal?.aborted) {
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result: { error: 'Operation aborted' },
+          input,
+          state: 'output-error',
+          duration: 0,
+        })
+        await middlewareHooks?.onAfterToolCall?.({
+          toolCall,
+          tool,
+          toolName,
+          toolCallId: toolCall.id,
+          ok: false,
+          duration: 0,
+          error: new Error('Operation aborted'),
+        })
+        return
+      }
+      const interrupts: Array<Interrupt> = []
+      interruptsByCall.set(toolCall.id, interrupts)
+      yield* executeServerTool(
+        toolCall,
+        tool,
+        toolName,
+        input,
+        context,
+        pendingEvents,
+        results,
+        middlewareHooks,
+        inputRequired,
+        interrupts,
+      )
+    } catch (error) {
+      failures.push(error)
+    }
+  }
+
   // Batch gating: when any tool in the batch still needs an approval decision,
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
@@ -891,6 +1028,7 @@ export async function* executeToolCalls<TContext = unknown>(
         toolName,
         result: { error: 'Tool execution cancelled' },
         state: 'output-error',
+        outcome: 'cancelled',
       })
       continue
     }
@@ -942,10 +1080,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 +1120,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 +1150,7 @@ export async function* executeToolCalls<TContext = unknown>(
                 deniedApprovalResult(resolution),
               input,
               state: 'output-error',
+              outcome: 'denied',
             })
           }
         } else {
@@ -1021,14 +1164,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 {
@@ -1048,50 +1193,7 @@ export async function* executeToolCalls<TContext = unknown>(
       const approvalId = `approval_${toolCall.id}`
       const resolution = approvalResolution(approvals, toolCall.id)
 
-      // Check if approval decision exists
-      if (resolution !== undefined) {
-        const approved = isApproved(resolution)
-
-        if (approved) {
-          input = editedApprovalArgs(resolution) ?? input
-          // Apply middleware before-hook for approved tools
-          if (middlewareHooks) {
-            const decision = await applyBeforeToolCallDecision(
-              toolCall,
-              tool,
-              input,
-              toolName,
-              middlewareHooks,
-              results,
-            )
-            if (!decision.proceed) continue
-            input = decision.input
-          }
-
-          yield* executeServerTool(
-            toolCall,
-            tool,
-            toolName,
-            input,
-            context,
-            pendingEvents,
-            results,
-            middlewareHooks,
-            subagentInterrupts,
-          )
-        } else {
-          // User declined
-          results.push({
-            toolCallId: toolCall.id,
-            toolName,
-            result:
-              resumeState?.deniedToolResults?.get(toolCall.id) ??
-              deniedApprovalResult(resolution),
-            input,
-            state: 'output-error',
-          })
-        }
-      } else {
+      if (resolution === undefined) {
         // Need approval
         needsApproval.push({
           toolCallId: toolCall.id,
@@ -1099,36 +1201,81 @@ export async function* executeToolCalls<TContext = unknown>(
           input,
           approvalId,
         })
+        continue
       }
-      continue
+      if (!isApproved(resolution)) {
+        // User declined
+        results.push({
+          toolCallId: toolCall.id,
+          toolName,
+          result:
+            resumeState?.deniedToolResults?.get(toolCall.id) ??
+            deniedApprovalResult(resolution),
+          input,
+          state: 'output-error',
+          outcome: 'denied',
+        })
+        continue
+      }
+      // Approved: run it like any other server tool below.
+      input = editedApprovalArgs(resolution) ?? input
     }
 
-    // CASE 3: Normal server tool - execute immediately
+    // CASE 3: Server tool, approved or with no approval
     if (middlewareHooks) {
-      const decision = await applyBeforeToolCallDecision(
-        toolCall,
-        tool,
-        input,
-        toolName,
-        middlewareHooks,
-        results,
-      )
+      let decision: Awaited<ReturnType<typeof applyBeforeToolCallDecision>>
+      try {
+        decision = await applyBeforeToolCallDecision(
+          toolCall,
+          tool,
+          input,
+          toolName,
+          middlewareHooks,
+          results,
+        )
+      } catch (error) {
+        // The calls prepared so far still run, as they would one at a time.
+        failures.push(error)
+        break
+      }
       if (!decision.proceed) continue
       input = decision.input
     }
 
-    yield* executeServerTool(
+    const run = runServerTool(
       toolCall,
       tool,
       toolName,
       input,
       context,
       pendingEvents,
-      results,
-      middlewareHooks,
-      subagentInterrupts,
     )
+    if (!runsInOrder) {
+      runs.push(run)
+      continue
+    }
+    yield* run
+    if (failures.length > 0) break
   }
 
-  return { results, needsApproval, needsClientExecution, subagentInterrupts }
+  yield* mergeStreams(runs)
+  if (failures.length > 0) throw failures[0]
+
+  // Parallel tools finish in any order. The model gets the results, input
+  // requests, and interrupts in the order it made the calls.
+  const callOrder = new Map(toolCalls.map((tc, index) => [tc.id, index]))
+  const byCallOrder = (a: { toolCallId: string }, b: { toolCallId: string }) =>
+    (callOrder.get(a.toolCallId) ?? 0) - (callOrder.get(b.toolCallId) ?? 0)
+  results.sort(byCallOrder)
+  inputRequired.sort(byCallOrder)
+
+  return {
+    results,
+    needsApproval,
+    needsClientExecution,
+    inputRequired,
+    subagentInterrupts: toolCalls.flatMap(
+      (tc) => interruptsByCall.get(tc.id) ?? [],
+    ),
+  }
 }

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/activities/generateSpeech/index.ts

@@ -445,7 +445,7 @@ export interface ListVoicesActivityOptions<
  * import { elevenlabsSpeech } from '@tanstack/ai-elevenlabs'
  *
  * const { voices } = await listVoices({
- *   adapter: elevenlabsSpeech('eleven_v3'),
+ *   adapter: elevenlabsSpeech('eleven_v4'),
  *   origins: ['generated', 'cloned'],
  * })
  * ```

package/src/activities/generateVideo/adapter.ts

@@ -1,3 +1,4 @@
+import { snapToDurationOption } from './snap'
 import type {
   ModelInputModalitiesByName,
   VideoGenerationOptions,
@@ -25,6 +26,12 @@ export type DurationOptions<T extends string | number | undefined> =
     }
   | { kind: 'none' }
 
+/**
+ * Spellings of one clip length: the number `6`, the string `"6"`, or the
+ * template `"6s"`.
+ */
+export type VideoDurationSpell<N extends number> = N | `${N}` | `${N}s`
+
 /**
  * Configuration for video adapter instances
  *
@@ -126,10 +133,15 @@ export interface VideoAdapter<
   availableDurations: () => DurationOptions<TModelDurationByName[TModel]>
 
   /**
-   * Coerce a raw seconds value to the closest valid duration for this model.
-   * Returns `undefined` for models with no duration field.
+   * Coerce `input` to the closest duration this model accepts.
+   * `input` may be seconds (`7`), a numeric string (`"7"`), a template
+   * (`"6s"`), or a keyword the model lists (`"auto"`).
+   * Returns `undefined` when the model has no duration field, or when
+   * `input` is a keyword that model does not list.
    */
-  snapDuration: (seconds: number) => TModelDurationByName[TModel] | undefined
+  snapDuration: (
+    input: number | string,
+  ) => TModelDurationByName[TModel] | undefined
 }
 
 /**
@@ -208,11 +220,13 @@ export abstract class BaseVideoAdapter<
   }
 
   /**
-   * Default implementation returns `undefined`. Adapters that have declared
-   * their per-model duration map should override.
+   * Uses `availableDurations()`. Adapters that declare a duration map only
+   * need to override that method.
    */
-  snapDuration(_seconds: number): TModelDurationByName[TModel] | undefined {
-    return undefined
+  snapDuration(
+    input: number | string,
+  ): TModelDurationByName[TModel] | undefined {
+    return snapToDurationOption(input, this.availableDurations())
   }
 
   protected generateId(): string {

package/src/activities/generateVideo/index.ts

@@ -173,10 +173,11 @@ export type VideoCreateOptions<
   /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
   size?: VideoSizeForAdapter<TAdapter>
   /**
-   * Video duration in seconds. Adapters that declare a per-model duration
-   * map narrow this to the model's valid union (e.g. `4 | 6 | 8` for Veo 3).
-   * Pass `adapter.snapDuration(seconds)` to coerce raw seconds to a valid
-   * value.
+   * Video duration. Adapters that declare a per-model duration map narrow
+   * this to that model's union (for example `4 | 6 | 8` for Veo 3, or
+   * `4 | "4" | "4s"` for Sora). Pass `adapter.snapDuration(input)` to coerce
+   * a raw value. `input` may be seconds, a `"6s"` template, or `"auto"` when
+   * the model lists it.
    */
   duration?: VideoDurationForAdapter<TAdapter>
   /**