@tanstack/ai 0.61.0 → 0.63.0

package/src/activities/chat/index.ts

@@ -113,6 +113,7 @@ import type {
 import type {
   ApprovalRequest,
   ClientToolRequest,
+  McpInputRequest,
   ToolResult,
 } from './tools/tool-calls'
 import type { ApprovalSchemaConfig } from './tools/tool-definition'
@@ -148,6 +149,7 @@ import type {
   ToolCallEndEvent,
   ToolCallResultEvent,
   ToolCallStartEvent,
+  ToolInputResponse,
   UIMessage,
 } from '../../types'
 import type {
@@ -880,8 +882,10 @@ class TextEngine<
   private readonly initialClientToolResults: Map<string, any>
   private readonly resumeApprovals = new Map<string, ToolApprovalResolution>()
   private readonly resumeClientToolResults = new Map<string, any>()
+  private readonly resumeClientToolErrors = new Map<string, string>()
   private readonly resumeDeniedToolResults = new Map<string, unknown>()
   private readonly resumeCancelledToolCallIds = new Set<string>()
+  private readonly resumeInputResponses = new Map<string, ToolInputResponse>()
   private readonly resumeGenericInterrupts = new Map<
     string,
     ChatResumeGenericResolution
@@ -952,6 +956,8 @@ class TextEngine<
     message: string
     code?: string
     cause?: unknown
+    /** Full model text, when a structured-output parse failed (#1485). */
+    rawText?: string
   } | null = null
   private combinedCompleteEmitted = false
   private readonly finalStructuredOutput?: {
@@ -1189,10 +1195,54 @@ class TextEngine<
     message: string
     code?: string
     cause?: unknown
+    rawText?: string
   } | null {
     return this.finalizationError
   }
 
+  private async runTerminalHook(): Promise<void> {
+    if (this.terminalHookCalled || this.isCancelled()) return
+
+    this.terminalHookCalled = true
+
+    if (this.finalizationError) {
+      const errForHook = new Error(
+        this.finalizationError.message,
+        this.finalizationError.cause !== undefined
+          ? { cause: this.finalizationError.cause }
+          : undefined,
+      )
+      if (this.finalizationError.code !== undefined) {
+        Object.defineProperty(errForHook, 'code', {
+          value: this.finalizationError.code,
+          enumerable: true,
+        })
+      }
+      if (this.finalizationError.rawText !== undefined) {
+        Object.defineProperty(errForHook, 'rawText', {
+          value: this.finalizationError.rawText,
+          enumerable: true,
+        })
+      }
+      await this.middlewareRunner.runOnError(this.middlewareCtx, {
+        error: errForHook,
+        duration: Date.now() - this.streamStartTime,
+      })
+      return
+    }
+
+    this.addTerminalAssistantMessages()
+    await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
+      finishReason: this.lastFinishReason,
+      duration: Date.now() - this.streamStartTime,
+      content: this.accumulatedContent,
+      usage: rebuildTokenUsage(
+        this.finishedEvent?.usage,
+        tanstackMetadata(this.finishedEvent ?? undefined)?.usage,
+      ),
+    })
+  }
+
   async *run(): AsyncGenerator<StreamChunk> {
     this.beforeRun()
     this.logger.agentLoop('run started', {
@@ -1238,7 +1288,8 @@ class TextEngine<
       }
 
       const pendingPhase = yield* this.checkForPendingToolCalls()
-      if (pendingPhase === 'wait') {
+      if (pendingPhase === 'stop' || pendingPhase === 'wait') {
+        await this.runTerminalHook()
         return
       }
 
@@ -1347,46 +1398,11 @@ class TextEngine<
         }
       }
 
-      // Call terminal hook (skip when waiting for client — stream is paused, not finished).
-      // Priority: finalizationError → onError; otherwise normal onFinish.
-      // Skip on cancellation — the finally block routes aborts to onAbort.
-      if (
-        !this.terminalHookCalled &&
-        this.toolPhase !== 'wait' &&
-        !this.isCancelled()
-      ) {
-        if (this.finalizationError) {
-          this.terminalHookCalled = true
-          const errForHook = new Error(
-            this.finalizationError.message,
-            this.finalizationError.cause !== undefined
-              ? { cause: this.finalizationError.cause }
-              : undefined,
-          )
-          if (this.finalizationError.code !== undefined) {
-            Object.defineProperty(errForHook, 'code', {
-              value: this.finalizationError.code,
-              enumerable: true,
-            })
-          }
-          await this.middlewareRunner.runOnError(this.middlewareCtx, {
-            error: errForHook,
-            duration: Date.now() - this.streamStartTime,
-          })
-        } else {
-          this.addTerminalAssistantMessages()
-          this.terminalHookCalled = true
-          await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
-            finishReason: this.lastFinishReason,
-            duration: Date.now() - this.streamStartTime,
-            content: this.accumulatedContent,
-            usage: rebuildTokenUsage(
-              this.finishedEvent?.usage,
-              tanstackMetadata(this.finishedEvent ?? undefined)?.usage,
-            ),
-          })
-        }
-      }
+      // A client-tool or approval wait ends this server-side chat invocation.
+      // Structured-output finalization stays paused until the caller submits
+      // the result in a new invocation, but middleware must still observe one
+      // terminal hook for the current invocation.
+      await this.runTerminalHook()
     } catch (error: unknown) {
       if (
         error instanceof Error &&
@@ -2181,8 +2197,10 @@ class TextEngine<
       this.middlewareCtx.context,
       this.toolAbortSignal,
       {
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
+        inputResponses: this.resumeInputResponses,
       },
     )
 
@@ -2207,11 +2225,12 @@ class TextEngine<
       }),
     )
 
-    if (
+    const pauseForDecision =
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0 ||
+      executionResult.inputRequired.length > 0 ||
       executionResult.subagentInterrupts.length > 0
-    ) {
+    if (pauseForDecision) {
       this.discardDeferredToolCallRunFinishedChunks()
 
       if (allResults.length > 0) {
@@ -2228,6 +2247,7 @@ class TextEngine<
         executionResult.needsApproval,
         executionResult.needsClientExecution,
         [],
+        executionResult.inputRequired,
         executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
@@ -2365,8 +2385,10 @@ class TextEngine<
       this.middlewareCtx.context,
       this.toolAbortSignal,
       {
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
+        inputResponses: this.resumeInputResponses,
       },
     )
 
@@ -2414,16 +2436,18 @@ class TextEngine<
         finishEvent,
         toolCalls,
         afterToolRequests,
+        executionResult.inputRequired,
       )
       this.setToolPhase('wait')
       return
     }
 
-    if (
+    const pauseForDecision =
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0 ||
+      executionResult.inputRequired.length > 0 ||
       executionResult.subagentInterrupts.length > 0
-    ) {
+    if (pauseForDecision) {
       if (allResults.length > 0) {
         for (const chunk of afterToolBoundaryChunks) {
           yield* this.pipeThroughMiddleware(chunk)
@@ -2435,6 +2459,7 @@ class TextEngine<
         executionResult.needsApproval,
         executionResult.needsClientExecution,
         [],
+        executionResult.inputRequired,
         executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
@@ -2853,6 +2878,7 @@ class TextEngine<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
     genericInterruptIds: ReadonlyArray<string> = [],
+    inputRequired: ReadonlyArray<McpInputRequest> = [],
     childInterrupts: ReadonlyArray<Interrupt> = [],
   ): Array<Interrupt> {
     const interrupts: Array<Interrupt> = []
@@ -2971,6 +2997,30 @@ class TextEngine<
       })
     }
 
+    for (const pendingInput of inputRequired) {
+      const id = `mcp_input_${pendingInput.toolCallId}`
+      interrupts.push({
+        id,
+        reason: 'mcp_input',
+        message: `Input required to run ${pendingInput.toolName}`,
+        toolCallId: pendingInput.toolCallId,
+        metadata: {
+          toolName: pendingInput.toolName,
+          // A generic binding with no definition id. `useChat` shows it as a
+          // generic interrupt with `resolveInterrupt` and `cancel`. The answer
+          // is not validated here. The MCP server checks it.
+          [interruptBindingMetadataKey]: {
+            v: INTERRUPT_BINDING_VERSION,
+            kind: 'generic',
+            interruptId: id,
+          },
+          [INTERRUPT_PAYLOAD_METADATA_KEY]: {
+            kind: pendingInput.kind,
+            request: pendingInput.request,
+          },
+        },
+      })
+    }
     // A subagent tool call raised these. They keep their `subagentRunId`.
     interrupts.push(...childInterrupts)
 
@@ -2995,6 +3045,7 @@ class TextEngine<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
     genericInterruptIds?: ReadonlyArray<string>,
+    inputRequired: ReadonlyArray<McpInputRequest> = [],
     childInterrupts?: ReadonlyArray<Interrupt>,
   ): StreamChunk {
     return {
@@ -3007,6 +3058,7 @@ class TextEngine<
           clientRequests,
           genericRequests,
           genericInterruptIds,
+          inputRequired,
           childInterrupts,
         ),
       },
@@ -3157,6 +3209,7 @@ class TextEngine<
     genericRequests: ReadonlyArray<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
+    inputRequired: ReadonlyArray<McpInputRequest> = [],
     childInterrupts: ReadonlyArray<Interrupt> = [],
   ): AsyncGenerator<StreamChunk, boolean, void> {
     yield* this.emitSyntheticRunStarted(finishEvent)
@@ -3171,6 +3224,7 @@ class TextEngine<
         clientRequests,
         genericRequests,
         genericInterruptIds,
+        inputRequired,
         childInterrupts,
       ),
     )
@@ -3207,6 +3261,7 @@ class TextEngine<
     requests?: ReadonlyArray<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     >,
+    inputRequired: ReadonlyArray<McpInputRequest> = [],
   ): AsyncGenerator<StreamChunk, boolean, void> {
     this.middlewareCtx.phase = phase
     const boundaryRequests =
@@ -3242,6 +3297,7 @@ class TextEngine<
       actionable.approvals,
       actionable.clientRequests,
       boundaryRequests,
+      inputRequired,
     )
     return true
   }
@@ -3289,6 +3345,7 @@ class TextEngine<
       } else if (
         !tool.execute &&
         !clientToolResults.has(toolCall.id) &&
+        !this.resumeClientToolErrors.has(toolCall.id) &&
         !this.resumeCancelledToolCallIds.has(toolCall.id)
       ) {
         clientRequests.push({
@@ -3396,9 +3453,15 @@ class TextEngine<
         content: wireContent,
         role: 'tool' as const,
       }
+      // An outcome always comes with output-error.
       chunks.push(
         (result.state === 'output-error'
-          ? withTanstackMetadata(resultChunk, { state: result.state })
+          ? withTanstackMetadata(resultChunk, {
+              state: result.state,
+              ...(result.outcome !== undefined && {
+                toolResultOutcome: result.outcome,
+              }),
+            })
           : resultChunk) as StreamChunk,
       )
 
@@ -3419,22 +3482,63 @@ class TextEngine<
           return false
         }
       })
-
-      const newToolMessage: ModelMessage = {
-        role: 'tool',
-        content,
-        toolCallId: result.toolCallId,
-        ...(result.state === 'output-error' && {
-          error: toolResultErrorText(parseToolOutput(wireContent)),
-        }),
+      const isDeniedResult = result.outcome === 'denied'
+      const existingToolResultIdx = isDeniedResult
+        ? this.messages.findIndex(
+            (message) =>
+              message.role === 'tool' &&
+              message.toolCallId === result.toolCallId,
+          )
+        : -1
+      const resultMessageIdx =
+        existingToolResultIdx >= 0 ? existingToolResultIdx : placeholderIdx
+
+      // Only a denied result keeps the old message's fields. A replaced
+      // pendingExecution placeholder must not leak into the real result.
+      const existingToolMessage =
+        existingToolResultIdx >= 0
+          ? this.messages[existingToolResultIdx]
+          : undefined
+      const errorField = result.state === 'output-error' && {
+        error: toolResultErrorText(parseToolOutput(wireContent)),
       }
+      const replacementMessage: ModelMessage =
+        existingToolMessage?.role === 'tool'
+          ? {
+              ...existingToolMessage,
+              content,
+              toolCallId: result.toolCallId,
+              ...errorField,
+            }
+          : {
+              role: 'tool',
+              content,
+              toolCallId: result.toolCallId,
+              ...errorField,
+            }
+      const newToolMessage: ModelMessage =
+        result.outcome !== undefined
+          ? withTanstackMetadata(replacementMessage, {
+              toolResultOutcome: result.outcome,
+            })
+          : replacementMessage
 
-      if (placeholderIdx >= 0) {
-        this.messages = [
-          ...this.messages.slice(0, placeholderIdx),
+      if (resultMessageIdx >= 0) {
+        const replacedMessages = [
+          ...this.messages.slice(0, resultMessageIdx),
           newToolMessage,
-          ...this.messages.slice(placeholderIdx + 1),
+          ...this.messages.slice(resultMessageIdx + 1),
         ]
+        this.messages = isDeniedResult
+          ? replacedMessages.filter(
+              (message, index) =>
+                index === resultMessageIdx ||
+                !(
+                  message.role === 'tool' &&
+                  message.toolCallId === result.toolCallId
+                ),
+            )
+          : replacedMessages
       } else {
         this.messages = [...this.messages, newToolMessage]
       }
@@ -3465,7 +3569,10 @@ class TextEngine<
         }
 
         // Only mark as complete if NOT pending execution
-        if (!hasPendingExecution) {
+        if (
+          !hasPendingExecution &&
+          !this.resumeDeniedToolResults.has(message.toolCallId)
+        ) {
           completedToolIds.add(message.toolCallId)
         }
       }
@@ -3853,6 +3960,9 @@ class TextEngine<
     // Track whether a RUN_ERROR has been yielded to streaming consumers so
     // we don't emit a duplicate synthetic one at the end.
     let runErrorYielded = false
+    // The full model text. Adapter errors carry only a 200-character preview,
+    // so a Promise caller could not recover the answer (#1485).
+    let rawText = ''
 
     // Pipe chunks through middleware; yield to consumer only when yieldChunks=true
     for await (const raw of providerStream) {
@@ -3964,14 +4074,20 @@ class TextEngine<
           await this.runOnUsageFromChunk(chunk)
         }
 
+        if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+          rawText += chunk.delta
+        }
+
         if (chunk.type === EventType.RUN_ERROR) {
           // RunErrorEvent already exposes `message` and `code` after narrowing.
+          // A native stream has no adapter error to capture, but its RUN_ERROR
+          // can carry the provider's error body as `rawEvent` (#1005).
+          const cause = fallbackAdapterError ?? chunk.rawEvent
           this.finalizationError = {
             message: chunk.message,
             ...(chunk.code ? { code: chunk.code } : {}),
-            ...(fallbackAdapterError !== undefined
-              ? { cause: fallbackAdapterError }
-              : {}),
+            ...(cause !== undefined ? { cause } : {}),
+            ...(rawText ? { rawText } : {}),
           }
         }
 
@@ -4155,6 +4271,7 @@ class TextEngine<
             message: `Failed to parse structured output as JSON. Content: ${detail}`,
             code: 'structured-output-parse-failed',
             cause: err,
+            rawText,
           }
         }
       }
@@ -4265,6 +4382,7 @@ class TextEngine<
       resumeToolState: {
         approvals: this.resumeApprovals,
         clientToolResults: this.resumeClientToolResults,
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
       },
@@ -4407,6 +4525,26 @@ class TextEngine<
         : []
     })
     pending.push(...genericPending)
+    // An `mcp_input_*` answer is valid only for a server tool call that is
+    // still pending in history.
+    const mcpInputCallIds = new Map<string, string>()
+    for (const toolCall of pendingToolCalls) {
+      const interruptId = `mcp_input_${toolCall.id}`
+      if (!resumeInterruptIds.has(interruptId)) continue
+      if (!toolsByCallId.get(toolCall.id)?.execute) continue
+      mcpInputCallIds.set(interruptId, toolCall.id)
+      pending.push({
+        interruptId,
+        payload: { id: interruptId },
+        binding: {
+          v: INTERRUPT_BINDING_VERSION,
+          kind: 'generic',
+          interruptId,
+          interruptedRunId,
+          generation: 0,
+        },
+      })
+    }
     const validated = await validateInterruptResumeBatch({
       threadId: this.threadId,
       interruptedRunId,
@@ -4436,6 +4574,16 @@ class TextEngine<
     })
 
     const genericResolutions = validated.resumeToolState.genericInterrupts
+    for (const [interruptId, toolCallId] of mcpInputCallIds) {
+      const resolution = genericResolutions?.get(interruptId)
+      if (!resolution) continue
+      this.resumeInputResponses.set(
+        toolCallId,
+        resolution.status === 'resolved'
+          ? { status: 'resolved', payload: resolution.payload }
+          : { status: 'cancelled' },
+      )
+    }
     if (genericPending.length > 0 && genericResolutions) {
       const resolutions = genericPending
         .sort((left, right) => {
@@ -4485,6 +4633,7 @@ class TextEngine<
         this.earlyTermination = true
       } else if (policy.toolResume === 'cancel') {
         for (const request of pendingToolCalls) {
+          if (this.resumeDeniedToolResults.has(request.id)) continue
           this.resumeCancelledToolCallIds.add(request.id)
         }
       }
@@ -4626,6 +4775,11 @@ class TextEngine<
         this.resumeClientToolResults.set(toolCallId, result)
       }
     }
+    if (state?.clientToolErrors) {
+      for (const [toolCallId, errorText] of state.clientToolErrors) {
+        this.resumeClientToolErrors.set(toolCallId, errorText)
+      }
+    }
     if (state?.deniedToolResults) {
       for (const [toolCallId, result] of state.deniedToolResults) {
         this.resumeDeniedToolResults.set(toolCallId, result)
@@ -4685,6 +4839,7 @@ class TextEngine<
       this.earlyTermination = true
     } else if (policy.toolResume === 'cancel') {
       for (const toolCall of this.getPendingToolCallsFromMessages()) {
+        if (this.resumeDeniedToolResults.has(toolCall.id)) continue
         this.resumeCancelledToolCallIds.add(toolCall.id)
       }
     }
@@ -4839,6 +4994,7 @@ class TextEngine<
         results: Array<ToolResult>
         needsApproval: Array<ApprovalRequest>
         needsClientExecution: Array<ClientToolRequest>
+        inputRequired: Array<McpInputRequest>
         subagentInterrupts: Array<Interrupt>
       },
       void
@@ -4849,6 +5005,7 @@ class TextEngine<
       results: Array<ToolResult>
       needsApproval: Array<ApprovalRequest>
       needsClientExecution: Array<ClientToolRequest>
+      inputRequired: Array<McpInputRequest>
       subagentInterrupts: Array<Interrupt>
     },
     void
@@ -5287,6 +5444,16 @@ async function* runRoutedSubagents(
     yield* runChatEngine(options, engineRef)
     return
   }
+  // ponytail: a router cannot write input yet. Add it to the router pick if
+  // someone needs it.
+  const withInput = bag.agents.find(
+    (agent: DefinedAgent) => agent.inputSchema !== undefined,
+  )
+  if (withInput) {
+    throw new Error(
+      `Subagent "${withInput.name}" has an inputSchema. inputSchema needs tool mode: remove subagents.router so the model writes the input.`,
+    )
+  }
   const threadId = options.threadId ?? `thread-${Date.now()}`
   const runId = options.runId ?? `run-${Date.now()}`
   const messages = options.messages ?? []
@@ -5742,6 +5909,12 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
         enumerable: true,
       })
     }
+    if (finalizationError.rawText !== undefined) {
+      Object.defineProperty(err, 'rawText', {
+        value: finalizationError.rawText,
+        enumerable: true,
+      })
+    }
     throw err
   }
 

package/src/activities/chat/messages.ts

@@ -4,9 +4,13 @@ import {
 } from '../../utilities/provider-executed'
 import {
   isContentPartArray,
+  isToolResultOutcome,
   normalizeToolResult,
 } from '../../utilities/tool-result'
-import { tanstackMetadata } from '../../utilities/merge-metadata'
+import {
+  tanstackMetadata,
+  withTanstackMetadata,
+} from '../../utilities/merge-metadata'
 import {
   splitSubagentWire,
   subagentWireText,
@@ -29,6 +33,7 @@ import type {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
 // ===========================
 // Message Converters
 // ===========================
@@ -546,6 +551,7 @@ function assistantMetadata(
   const tanstack: TanStackMessageMetadata = {}
   if (previous?.model !== undefined) tanstack.model = previous.model
   if (previous?.runId !== undefined) tanstack.runId = previous.runId
+  if (previous?.run?.id !== undefined) tanstack.run = { id: previous.run.id }
   if (previous?.signature !== undefined) tanstack.signature = previous.signature
   if (fromParts.length > 0) tanstack.uiResources = fromParts
   const result = { ...current }
@@ -729,6 +735,11 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
           (part.state === 'complete' || part.state === 'error') &&
           !emittedToolResultIds.has(part.toolCallId)
         ) {
+          const metadata =
+            part.outcome === undefined
+              ? part.metadata
+              : withTanstackMetadata(part, { toolResultOutcome: part.outcome })
+                  .metadata
           messageList.push({
             ...(part.id !== undefined && { id: part.id }),
             ...optionalCreatedAt(part),
@@ -736,7 +747,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             content: part.content,
             toolCallId: part.toolCallId,
             ...(part.name !== undefined && { name: part.name }),
-            ...(part.metadata !== undefined && { metadata: part.metadata }),
+            ...(metadata !== undefined && { metadata }),
             ...(part.error !== undefined && { error: part.error }),
           })
           emittedToolResultIds.add(part.toolCallId)
@@ -841,6 +852,9 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             : 'User denied this action',
         }),
         toolCallId: part.id,
+        ...(approved === false && {
+          metadata: { tanstack: { toolResultOutcome: 'denied' } },
+        }),
       })
       emittedToolResultIds.add(part.id)
     }
@@ -908,11 +922,21 @@ export function modelMessageToUIMessage(
     }
     parts.push(structuredOutput)
   } else if (modelMessage.role === 'tool' && modelMessage.toolCallId) {
+    const rawToolResultOutcome =
+      tanstackMetadata(modelMessage)?.toolResultOutcome
+    const toolResultOutcome = isToolResultOutcome(rawToolResultOutcome)
+      ? rawToolResultOutcome
+      : undefined
+    const resultState =
+      modelMessage.error === undefined && toolResultOutcome === undefined
+        ? 'complete'
+        : 'error'
     parts.push({
       type: 'tool-result',
       toolCallId: modelMessage.toolCallId,
       content: toolResultContent(modelMessage.content),
-      state: modelMessage.error === undefined ? 'complete' : 'error',
+      state: resultState,
+      ...(toolResultOutcome !== undefined && { outcome: toolResultOutcome }),
       ...(modelMessage.id !== undefined && { id: modelMessage.id }),
       ...(modelMessage.name !== undefined && { name: modelMessage.name }),
       ...(modelMessage.metadata !== undefined && {
@@ -1228,6 +1252,14 @@ export function modelMessagesToUIMessages(
         currentAssistantMessage.role === 'assistant'
       ) {
         const content = toolResultContent(msg.content)
+        const rawToolResultOutcome = tanstackMetadata(msg)?.toolResultOutcome
+        const toolResultOutcome = isToolResultOutcome(rawToolResultOutcome)
+          ? rawToolResultOutcome
+          : undefined
+        const resultState =
+          msg.error === undefined && toolResultOutcome === undefined
+            ? 'complete'
+            : 'error'
         const toolCallPart = currentAssistantMessage.parts.find(
           (part): part is ToolCallPart =>
             part.type === 'tool-call' && part.id === msg.toolCallId,
@@ -1238,14 +1270,17 @@ export function modelMessagesToUIMessages(
             typeof content === 'string'
               ? parseToolResultContent(content)
               : content
-          toolCallPart.state = msg.error === undefined ? 'complete' : 'error'
+          toolCallPart.state = resultState
         }
 
         currentAssistantMessage.parts.push({
           type: 'tool-result',
           toolCallId: msg.toolCallId,
           content,
-          state: msg.error === undefined ? 'complete' : 'error',
+          state: resultState,
+          ...(toolResultOutcome !== undefined && {
+            outcome: toolResultOutcome,
+          }),
           ...(msg.id !== undefined &&
             msg.id !== currentAssistantMessage.id && { id: msg.id }),
           ...(msg.name !== undefined && { name: msg.name }),