@tanstack/ai 0.59.0 → 0.63.0

package/src/activities/chat/index.ts

@@ -43,8 +43,13 @@ import { withDurabilityBatchHint } from '../../utilities/durability-batch'
 import { normalizeStreamChunk } from '../../utilities/normalize-stream-chunk'
 import { restorePublicUsage } from '../../utilities/restore-inbound-chunk'
 import type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'
-import { normalizeToolResult } from '../../utilities/tool-result'
+import {
+  normalizeToolResult,
+  parseToolOutput,
+  toolResultErrorText,
+} from '../../utilities/tool-result'
 import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
+import { assertMessagesFileSourceSupport } from '../../utilities/content-source'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import { assertUniqueToolNames } from './tools/unique-tool-names'
 import type { DefinedAgent } from './agents/define-agent'
@@ -108,6 +113,7 @@ import type {
 import type {
   ApprovalRequest,
   ClientToolRequest,
+  McpInputRequest,
   ToolResult,
 } from './tools/tool-calls'
 import type { ApprovalSchemaConfig } from './tools/tool-definition'
@@ -143,6 +149,7 @@ import type {
   ToolCallEndEvent,
   ToolCallResultEvent,
   ToolCallStartEvent,
+  ToolInputResponse,
   UIMessage,
 } from '../../types'
 import type {
@@ -170,6 +177,12 @@ import type {
 } from './runtime-context-types'
 import type { ChatMCPOptions } from './mcp/types'
 
+/** One entry of the per-iteration arrival order (see `turnParts`). */
+type TurnPart =
+  | { type: 'thinking'; index: number }
+  | { type: 'text'; content: string }
+  | { type: 'call'; id: string; providerExecuted: boolean }
+
 // ===========================
 // Activity Kind
 // ===========================
@@ -186,25 +199,6 @@ const interruptBindingMetadataKey = INTERRUPT_BINDING_METADATA_KEY
 /** Resume entries a subagent tool call owns. The parent run skips them. */
 const CHILD_RESUME_IDS = Symbol('tanstack.ai.childResumeIds')
 
-// ponytail: no adapter maps `{ type: 'file' }` yet, so every one fails closed
-// instead of reading the handle as a URL or base64. The Files API work
-// replaces this with a per-adapter capability check.
-function assertNoFileSources(
-  adapterName: string,
-  messages: ReadonlyArray<ModelMessage>,
-): void {
-  for (const message of messages) {
-    if (!Array.isArray(message.content)) continue
-    for (const part of message.content) {
-      if ('source' in part && part.source.type === 'file') {
-        throw new Error(
-          `${adapterName} does not support provider file-handle sources ({ type: 'file' }). Pass a data or url source.`,
-        )
-      }
-    }
-  }
-}
-
 interface StructuralInterruptFailure {
   error: Error
   errors: ReadonlyArray<InterruptSubmissionError>
@@ -861,6 +855,15 @@ class TextEngine<
   private accumulatedContent = ''
   private accumulatedThinking: Array<{ content: string; signature?: string }> =
     []
+  /**
+   * Arrival order of this iteration's thinking steps, text and tool calls.
+   * A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a
+   * provider turn that thinks between provider-executed tools would otherwise
+   * be recorded as "all thinking, then text, then tools" and the provider
+   * rejects the replay (signed thinking must keep its position). `null` once
+   * the order could no longer be tracked (callers fall back to one message).
+   */
+  private turnParts: Array<TurnPart> | null = []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
   private eventOptions?: Record<string, unknown> | undefined
@@ -879,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
@@ -951,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?: {
@@ -1188,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', {
@@ -1237,7 +1288,8 @@ class TextEngine<
       }
 
       const pendingPhase = yield* this.checkForPendingToolCalls()
-      if (pendingPhase === 'wait') {
+      if (pendingPhase === 'stop' || pendingPhase === 'wait') {
+        await this.runTerminalHook()
         return
       }
 
@@ -1346,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 &&
@@ -1504,6 +1521,7 @@ class TextEngine<
     this.streamIdentityCaptured = false
     this.accumulatedContent = ''
     this.accumulatedThinking = []
+    this.turnParts = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
 
@@ -1571,7 +1589,12 @@ class TextEngine<
       )
     }
 
-    assertNoFileSources(this.adapter.name, this.messages)
+    // Fail closed on `{ type: 'file' }` sources for adapters that haven't
+    // declared support — an adapter written before the file arm existed would
+    // otherwise fall through to its URL/data branch and silently mis-map the
+    // reference. Checked per model call so tool results added mid-loop are
+    // covered too.
+    assertMessagesFileSourceSupport(this.adapter, this.messages)
 
     for await (const raw of this.adapter.chatStream({
       model: this.params.model,
@@ -1805,12 +1828,27 @@ class TextEngine<
     // Adapters still emit leftover cumulative `content` on RAW yields.
     // Alignment suppresses already-delivered deltas, so this snapshot is
     // what a takeover saves as the full assistant text.
+    const before = this.accumulatedContent
     if (typeof extra.content === 'string' && extra.content !== '') {
       this.accumulatedContent = extra.content
     } else {
       this.accumulatedContent += chunk.delta
     }
     this.middlewareCtx.accumulatedContent = this.accumulatedContent
+    if (!this.turnParts) return
+    if (!this.accumulatedContent.startsWith(before)) {
+      // A cumulative `content` snapshot rewrote earlier text; order unknown.
+      this.turnParts = null
+      return
+    }
+    const delta = this.accumulatedContent.slice(before.length)
+    if (delta === '') return
+    const last = this.turnParts[this.turnParts.length - 1]
+    if (last && last.type === 'text') {
+      last.content += delta
+    } else {
+      this.turnParts.push({ type: 'text', content: delta })
+    }
   }
 
   private captureStreamMessageIdentity(messageId: string): void {
@@ -1835,6 +1873,20 @@ class TextEngine<
       this.captureStreamMessageIdentity(chunk.parentMessageId)
     }
     this.toolCallManager.addToolCallStartEvent(chunk)
+    if (
+      this.turnParts &&
+      !this.turnParts.some(
+        (part) => part.type === 'call' && part.id === chunk.toolCallId,
+      )
+    ) {
+      this.turnParts.push({
+        type: 'call',
+        id: chunk.toolCallId,
+        providerExecuted: isProviderExecutedToolCall({
+          metadata: chunk.metadata,
+        }),
+      })
+    }
     const metadata = chunk.metadata
     const thoughtSignature =
       metadata != null &&
@@ -1941,17 +1993,48 @@ class TextEngine<
           signature: this.currentThinkingSignature,
         }),
       })
+      if (this.turnParts) {
+        const placeholder = [...this.turnParts]
+          .reverse()
+          .find(
+            (part): part is Extract<TurnPart, { type: 'thinking' }> =>
+              part.type === 'thinking' && part.index === -1,
+          )
+        const index = this.accumulatedThinking.length - 1
+        if (placeholder) {
+          placeholder.index = index
+        } else {
+          this.turnParts.push({ type: 'thinking', index })
+        }
+      }
       this.currentThinkingContent = ''
       this.currentThinkingSignature = ''
     }
   }
 
+  /**
+   * Record where the current thinking step sits among this turn's parts. A
+   * step is finalized only when the next step starts (or the turn ends), by
+   * which time later tool calls have already arrived, so the position has to
+   * be noted when the step's first content or signature shows up.
+   */
+  private noteThinkingStepPosition(): void {
+    if (
+      this.turnParts &&
+      this.currentThinkingContent === '' &&
+      this.currentThinkingSignature === ''
+    ) {
+      this.turnParts.push({ type: 'thinking', index: -1 })
+    }
+  }
+
   private handleStepStartedEvent(): void {
     this.finalizeCurrentThinkingStep()
   }
 
   private handleStepFinishedEvent(chunk: AdapterYieldChunk): void {
     if (typeof chunk.signature === 'string' && chunk.signature !== '') {
+      this.noteThinkingStepPosition()
       this.currentThinkingSignature = chunk.signature
     }
   }
@@ -1959,6 +2042,7 @@ class TextEngine<
   private handleReasoningMessageContentEvent(
     chunk: Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
   ): void {
+    this.noteThinkingStepPosition()
     this.currentThinkingContent += chunk.delta
   }
 
@@ -1979,6 +2063,7 @@ class TextEngine<
       }
       return
     }
+    this.noteThinkingStepPosition()
     this.currentThinkingSignature = chunk.encryptedValue
   }
 
@@ -2112,8 +2197,10 @@ class TextEngine<
       this.middlewareCtx.context,
       this.toolAbortSignal,
       {
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
+        inputResponses: this.resumeInputResponses,
       },
     )
 
@@ -2138,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) {
@@ -2159,6 +2247,7 @@ class TextEngine<
         executionResult.needsApproval,
         executionResult.needsClientExecution,
         [],
+        executionResult.inputRequired,
         executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
@@ -2296,8 +2385,10 @@ class TextEngine<
       this.middlewareCtx.context,
       this.toolAbortSignal,
       {
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
+        inputResponses: this.resumeInputResponses,
       },
     )
 
@@ -2345,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)
@@ -2366,6 +2459,7 @@ class TextEngine<
         executionResult.needsApproval,
         executionResult.needsClientExecution,
         [],
+        executionResult.inputRequired,
         executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
@@ -2464,21 +2558,110 @@ class TextEngine<
     )
   }
 
+  /**
+   * Split this iteration into assistant ModelMessages that keep the provider's
+   * block order: a new segment starts at every thinking step that follows a
+   * provider-executed tool call (the rule buildAssistantMessages applies to
+   * UIMessages). Segments after the first get `${id}-segment-${n}` ids.
+   * Returns null when no split is needed or the order could not be tracked,
+   * so callers fall back to the single-message shape.
+   */
+  private buildOrderedAssistantSegments(
+    toolCalls: ReadonlyArray<ToolCall>,
+    id: string | undefined,
+    createdAt: Date | undefined,
+  ): Array<ModelMessage> | null {
+    const parts = this.turnParts
+    if (!parts) return null
+    const providerCallIds = new Set(
+      parts.flatMap((part) =>
+        part.type === 'call' && part.providerExecuted ? [part.id] : [],
+      ),
+    )
+    type Segment = {
+      thinking: Array<{ content: string; signature?: string }>
+      text: string
+      callIds: Array<string>
+    }
+    let current: Segment = { thinking: [], text: '', callIds: [] }
+    const segments: Array<Segment> = [current]
+    let split = false
+    for (const part of parts) {
+      if (part.type === 'thinking') {
+        const thinking = this.accumulatedThinking[part.index]
+        if (!thinking) return null
+        if (current.callIds.some((callId) => providerCallIds.has(callId))) {
+          current = { thinking: [thinking], text: '', callIds: [] }
+          segments.push(current)
+          split = true
+        } else {
+          current.thinking.push(thinking)
+        }
+      } else if (part.type === 'text') {
+        current.text += part.content
+      } else {
+        current.callIds.push(part.id)
+      }
+    }
+    if (!split) return null
+    if (
+      segments.map((segment) => segment.text).join('') !==
+      this.accumulatedContent
+    ) {
+      return null
+    }
+    if (
+      segments.reduce((n, segment) => n + segment.thinking.length, 0) !==
+      this.accumulatedThinking.length
+    ) {
+      return null
+    }
+    const placed = new Set(segments.flatMap((segment) => segment.callIds))
+    for (const toolCall of toolCalls) {
+      if (!placed.has(toolCall.id)) current.callIds.push(toolCall.id)
+    }
+    return segments.map((segment, index) => {
+      const segmentCalls = toolCalls.filter((toolCall) =>
+        segment.callIds.includes(toolCall.id),
+      )
+      return {
+        role: 'assistant',
+        content: segment.text || null,
+        ...(segmentCalls.length > 0 && { toolCalls: segmentCalls }),
+        id:
+          id === undefined
+            ? undefined
+            : index === 0
+              ? id
+              : `${id}-segment-${index}`,
+        createdAt,
+        ...(segment.thinking.length > 0 && { thinking: segment.thinking }),
+      }
+    })
+  }
+
   private addAssistantToolCallMessage(toolCalls: Array<ToolCall>): void {
     this.finalizeCurrentThinkingStep()
 
+    const segments = this.buildOrderedAssistantSegments(
+      toolCalls,
+      this.currentMessageId ?? undefined,
+      this.currentMessageCreatedAt ?? undefined,
+    )
     this.messages = [
       ...this.messages,
-      {
-        role: 'assistant',
-        content: this.accumulatedContent || null,
-        toolCalls,
-        id: this.currentMessageId ?? undefined,
-        createdAt: this.currentMessageCreatedAt ?? undefined,
-        ...(this.accumulatedThinking.length > 0 && {
-          thinking: this.accumulatedThinking,
-        }),
-      },
+      ...(segments ?? [
+        {
+          role: 'assistant' as const,
+          content: this.accumulatedContent || null,
+          toolCalls,
+          id: this.currentMessageId ?? undefined,
+          createdAt: this.currentMessageCreatedAt ?? undefined,
+          ...(this.accumulatedThinking.length > 0 && {
+            thinking: this.accumulatedThinking,
+          }),
+        },
+      ]),
     ]
     this.middlewareCtx.messages = this.messages
   }
@@ -2557,13 +2740,23 @@ class TextEngine<
         !currentTurnAlreadyRecorded &&
         (this.accumulatedContent !== '' || thinking)
       ) {
-        messages.push({
-          role: 'assistant',
-          content: this.accumulatedContent || null,
-          id: this.currentMessageId ?? this.createId('msg'),
-          createdAt: this.currentMessageCreatedAt ?? new Date(),
-          ...(thinking ? { thinking } : {}),
-        })
+        const id = this.currentMessageId ?? this.createId('msg')
+        const createdAt = this.currentMessageCreatedAt ?? new Date()
+        messages.push(
+          ...(this.buildOrderedAssistantSegments(
+            this.toolCallManager.getToolCalls(),
+            id,
+            createdAt,
+          ) ?? [
+            {
+              role: 'assistant',
+              content: this.accumulatedContent || null,
+              id,
+              createdAt,
+              ...(thinking ? { thinking } : {}),
+            },
+          ]),
+        )
       }
       if (structuredOutput) {
         messages.push({
@@ -2685,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> = []
@@ -2803,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)
 
@@ -2827,6 +3045,7 @@ class TextEngine<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
     genericInterruptIds?: ReadonlyArray<string>,
+    inputRequired: ReadonlyArray<McpInputRequest> = [],
     childInterrupts?: ReadonlyArray<Interrupt>,
   ): StreamChunk {
     return {
@@ -2839,6 +3058,7 @@ class TextEngine<
           clientRequests,
           genericRequests,
           genericInterruptIds,
+          inputRequired,
           childInterrupts,
         ),
       },
@@ -2989,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)
@@ -3003,6 +3224,7 @@ class TextEngine<
         clientRequests,
         genericRequests,
         genericInterruptIds,
+        inputRequired,
         childInterrupts,
       ),
     )
@@ -3039,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 =
@@ -3074,6 +3297,7 @@ class TextEngine<
       actionable.approvals,
       actionable.clientRequests,
       boundaryRequests,
+      inputRequired,
     )
     return true
   }
@@ -3097,6 +3321,8 @@ class TextEngine<
     const approvalRequests: Array<ApprovalRequest> = []
     const clientRequests: Array<ClientToolRequest> = []
     for (const toolCall of toolCalls) {
+      // Provider-executed calls are complete; never surface them as client work.
+      if (isProviderExecutedToolCall(toolCall)) continue
       const tool = this.resolveExecutableTools([toolCall]).find(
         (candidate) => candidate.name === toolCall.function.name,
       ) as RuntimeToolWithApproval | undefined
@@ -3119,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({
@@ -3226,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,
       )
 
@@ -3249,19 +3482,63 @@ class TextEngine<
           return false
         }
       })
-
-      const newToolMessage: ModelMessage = {
-        role: 'tool',
-        content,
-        toolCallId: result.toolCallId,
+      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]
       }
@@ -3292,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)
         }
       }
@@ -3589,7 +3869,11 @@ class TextEngine<
     // Apply merged config back to engine state
     this.applyMiddlewareConfig(postOnConfig)
 
-    assertNoFileSources(this.adapter.name, this.messages)
+    // Schema-only structured output with no tools skips the agent loop, so
+    // `streamModelResponse` never runs this check. Middleware can also
+    // replace `this.messages` above. Fail closed here before the
+    // structured-output adapter call.
+    assertMessagesFileSourceSupport(this.adapter, this.messages)
 
     // Build the StructuredOutputOptions the adapter expects.
     // `this.adapter` is already `TAdapter extends AnyTextAdapter` per the
@@ -3676,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) {
@@ -3787,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 } : {}),
           }
         }
 
@@ -3932,7 +4225,16 @@ class TextEngine<
     const yieldChunks = this.finalStructuredOutput.yieldChunks
     const source = this.finalStructuredOutput.source ?? 'text'
 
-    if (source === 'event') {
+    // A final turn cut off at the output cap holds truncated JSON, or none
+    // for a reasoning model that spent the budget. Report the token limit
+    // instead of a parse or missing-result error (#1426).
+    if (this.lastFinishReason === 'length') {
+      this.finalizationError = {
+        message:
+          'The response was cut off because the maximum token limit was reached (finish_reason=length); raise the output token limit.',
+        code: 'max_tokens',
+      }
+    } else if (source === 'event') {
       if (!this.structuredOutputResult) {
         this.finalizationError = {
           message: 'missing structured result',
@@ -3969,6 +4271,7 @@ class TextEngine<
             message: `Failed to parse structured output as JSON. Content: ${detail}`,
             code: 'structured-output-parse-failed',
             cause: err,
+            rawText,
           }
         }
       }
@@ -4079,6 +4382,7 @@ class TextEngine<
       resumeToolState: {
         approvals: this.resumeApprovals,
         clientToolResults: this.resumeClientToolResults,
+        clientToolErrors: this.resumeClientToolErrors,
         deniedToolResults: this.resumeDeniedToolResults,
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
       },
@@ -4221,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,
@@ -4250,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) => {
@@ -4299,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)
         }
       }
@@ -4440,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)
@@ -4499,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)
       }
     }
@@ -4653,6 +4994,7 @@ class TextEngine<
         results: Array<ToolResult>
         needsApproval: Array<ApprovalRequest>
         needsClientExecution: Array<ClientToolRequest>
+        inputRequired: Array<McpInputRequest>
         subagentInterrupts: Array<Interrupt>
       },
       void
@@ -4663,6 +5005,7 @@ class TextEngine<
       results: Array<ToolResult>
       needsApproval: Array<ApprovalRequest>
       needsClientExecution: Array<ClientToolRequest>
+      inputRequired: Array<McpInputRequest>
       subagentInterrupts: Array<Interrupt>
     },
     void
@@ -5101,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 ?? []
@@ -5556,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
   }