@tanstack/ai 0.59.0 → 0.61.0

package/dist/esm/utilities/tool-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-result.js","names":[],"sources":["../../../src/utilities/tool-result.ts"],"sourcesContent":["import type { ContentPart } from '../types'\n\nconst CONTENT_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n])\n\n/**\n * Structural check for a single `ContentPart`. A text part must carry a string\n * `content`; every other modality must carry a `source` with `type` of\n * `'url' | 'data'` and a string `value`.\n */\nexport function isContentPart(value: unknown): value is ContentPart {\n  if (typeof value !== 'object' || value === null) return false\n  const part = value as Record<string, unknown>\n  if (typeof part.type !== 'string' || !CONTENT_PART_TYPES.has(part.type)) {\n    return false\n  }\n  if (part.type === 'text') {\n    return typeof part.content === 'string'\n  }\n  const source = part.source\n  if (typeof source !== 'object' || source === null) return false\n  const src = source as Record<string, unknown>\n  if (typeof src.value !== 'string') return false\n  // `data` sources require a mimeType (matches ContentPartDataSource); `url`\n  // sources don't. Requiring it here keeps the runtime guard consistent with\n  // the type and avoids emitting `data:undefined;base64,...` downstream.\n  if (src.type === 'data') return typeof src.mimeType === 'string'\n  return src.type === 'url'\n}\n\n/**\n * True iff `value` is a NON-EMPTY array whose every element is a valid\n * `ContentPart`. Empty arrays and mixed arrays return false so they continue\n * to be treated as ordinary (stringified) data — this keeps the auto-detection\n * footgun narrow.\n */\nexport function isContentPartArray(\n  value: unknown,\n): value is Array<ContentPart> {\n  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)\n}\n\n/**\n * Normalize a tool's return value for transport:\n * - string            → unchanged\n * - ContentPart array → unchanged (multimodal, passed through to the adapter)\n * - anything else     → `JSON.stringify`\n */\nexport function normalizeToolResult(\n  result: unknown,\n): string | Array<ContentPart> {\n  if (typeof result === 'string') return result\n  if (isContentPartArray(result)) return result\n  return JSON.stringify(result)\n}\n"],"mappings":";AAEA,IAAM,qCAAqB,IAAI,IAAI;CACjC;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;AAOD,SAAgB,cAAc,OAAsC;CAClE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,OAAO;CACb,IAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GACpE,OAAO;CAET,IAAI,KAAK,SAAS,QAChB,OAAO,OAAO,KAAK,YAAY;CAEjC,MAAM,SAAS,KAAK;CACpB,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO;CAC1D,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,UAAU,UAAU,OAAO;CAI1C,IAAI,IAAI,SAAS,QAAQ,OAAO,OAAO,IAAI,aAAa;CACxD,OAAO,IAAI,SAAS;AACtB;;;;;;;AAQA,SAAgB,mBACd,OAC6B;CAC7B,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;;;;;;;AAQA,SAAgB,oBACd,QAC6B;CAC7B,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI,mBAAmB,MAAM,GAAG,OAAO;CACvC,OAAO,KAAK,UAAU,MAAM;AAC9B"}
+{"version":3,"file":"tool-result.js","names":[],"sources":["../../../src/utilities/tool-result.ts"],"sourcesContent":["import type { ContentPart } from '../types'\n\nconst CONTENT_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n])\n\n/**\n * Structural check for a single `ContentPart`. A text part must carry a string\n * `content`. Every other part carries a source with a string `value`; a file\n * source's `value` is a non-empty opaque handle, and its optional `provider`\n * is a string.\n */\nexport function isContentPart(value: unknown): value is ContentPart {\n  if (typeof value !== 'object' || value === null) return false\n  const part = value as Record<string, unknown>\n  if (typeof part.type !== 'string' || !CONTENT_PART_TYPES.has(part.type)) {\n    return false\n  }\n  if (part.type === 'text') {\n    return typeof part.content === 'string'\n  }\n  const source = part.source\n  if (typeof source !== 'object' || source === null) return false\n  const src = source as Record<string, unknown>\n  if (typeof src.value !== 'string') return false\n  // `file` sources carry an opaque handle in `value`; `provider`, when set,\n  // names the issuer.\n  if (src.type === 'file') {\n    return (\n      src.value.length > 0 &&\n      (src.provider === undefined || typeof src.provider === 'string')\n    )\n  }\n  // `data` sources require a mimeType (matches ContentPartDataSource); `url`\n  // sources don't. Requiring it here keeps the runtime guard consistent with\n  // the type and avoids emitting `data:undefined;base64,...` downstream.\n  if (src.type === 'data') return typeof src.mimeType === 'string'\n  return src.type === 'url'\n}\n\n/**\n * True iff `value` is a NON-EMPTY array whose every element is a valid\n * `ContentPart`. Empty arrays and mixed arrays return false so they continue\n * to be treated as ordinary (stringified) data — this keeps the auto-detection\n * footgun narrow.\n */\nexport function isContentPartArray(\n  value: unknown,\n): value is Array<ContentPart> {\n  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)\n}\n\n/**\n * Error text for a failed tool result: `output.error` when it is a string,\n * else the output itself when it is a string, else a generic message.\n * `StreamProcessor` and `chat()` history share it, so a reload shows the\n * same text as the live stream.\n */\nexport function toolResultErrorText(output: unknown): string {\n  if (\n    output &&\n    typeof output === 'object' &&\n    'error' in output &&\n    typeof output.error === 'string'\n  ) {\n    return output.error\n  }\n  return typeof output === 'string' ? output : 'Tool execution failed'\n}\n\n/** Parse tool result content as JSON. Plain text stays a string. */\nexport function parseToolOutput(content: string): unknown {\n  try {\n    return JSON.parse(content)\n  } catch {\n    return content\n  }\n}\n\n/**\n * Normalize a tool's return value for transport:\n * - string            → unchanged\n * - ContentPart array → unchanged (multimodal, passed through to the adapter)\n * - anything else     → `JSON.stringify`\n */\nexport function normalizeToolResult(\n  result: unknown,\n): string | Array<ContentPart> {\n  if (typeof result === 'string') return result\n  if (isContentPartArray(result)) return result\n  return JSON.stringify(result)\n}\n"],"mappings":";AAEA,IAAM,qCAAqB,IAAI,IAAI;CACjC;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;AAQD,SAAgB,cAAc,OAAsC;CAClE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,OAAO;CACb,IAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GACpE,OAAO;CAET,IAAI,KAAK,SAAS,QAChB,OAAO,OAAO,KAAK,YAAY;CAEjC,MAAM,SAAS,KAAK;CACpB,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO;CAC1D,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,UAAU,UAAU,OAAO;CAG1C,IAAI,IAAI,SAAS,QACf,OACE,IAAI,MAAM,SAAS,MAClB,IAAI,aAAa,KAAA,KAAa,OAAO,IAAI,aAAa;CAM3D,IAAI,IAAI,SAAS,QAAQ,OAAO,OAAO,IAAI,aAAa;CACxD,OAAO,IAAI,SAAS;AACtB;;;;;;;AAQA,SAAgB,mBACd,OAC6B;CAC7B,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;;;;;;;AAQA,SAAgB,oBAAoB,QAAyB;CAC3D,IACE,UACA,OAAO,WAAW,YAClB,WAAW,UACX,OAAO,OAAO,UAAU,UAExB,OAAO,OAAO;CAEhB,OAAO,OAAO,WAAW,WAAW,SAAS;AAC/C;;AAGA,SAAgB,gBAAgB,SAA0B;CACxD,IAAI;EACF,OAAO,KAAK,MAAM,OAAO;CAC3B,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,oBACd,QAC6B;CAC7B,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI,mBAAmB,MAAM,GAAG,OAAO;CACvC,OAAO,KAAK,UAAU,MAAM;AAC9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -88,7 +88,7 @@
     "@ag-ui/core": "1.0.0",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "^0.12.1",
+    "@tanstack/ai-event-client": "^0.13.0",
     "@tanstack/ai-utils": "^0.4.1"
   },
   "peerDependencies": {

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -456,6 +456,68 @@ compatible providers speak.
 > Verify the provider's current `baseURL` and model ids against its live docs —
 > they drift. See `docs/adapters/openai-compatible.md` for the full provider table.
 
+### 7. Files Adapters (upload once, reference by handle)
+
+Four providers expose a native Files/storage API as a tree-shakeable `files`
+adapter: `openaiFiles()`, `anthropicFiles()`, `geminiFiles()` (each reads the
+same env var as the provider's text adapter; `create*Files(apiKey)` variants
+take an explicit key), and `falFiles(config)`. Upload media once with
+`uploadFile()`, then reference the returned `FileHandle` in messages via a
+`{ type: 'file' }` content source instead of re-sending base64 each request:
+
+```typescript
+import { chat, fileSourceFromHandle, uploadFile } from '@tanstack/ai'
+import { openaiFiles, openaiText } from '@tanstack/ai-openai'
+import { pdfBase64 } from './pdf-data'
+
+const handle = await uploadFile({
+  adapter: openaiFiles(),
+  input: { data: pdfBase64, mimeType: 'application/pdf' },
+})
+
+chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', content: 'Summarize this document' },
+        { type: 'document', source: fileSourceFromHandle(handle) },
+      ],
+    },
+  ],
+})
+```
+
+Rules agents must respect:
+
+- **The source is one opaque handle plus its issuer.** `fileSourceFromHandle`
+  builds `{ type: 'file', value: 'file-…', provider: 'openai' }`, matching the
+  AG-UI `FileSource` arm. A handle only resolves at the provider that issued
+  it, so an adapter throws when `provider` names a different adapter.
+  `provider` is optional, as on the AG-UI wire; a source without it is taken
+  as-is. To use the same bytes with two providers,
+  upload to each and send the matching handle.
+- **Adapters declare `supportsFileSources`.** For adapters that don't (Groq, Bedrock, Mistral, OpenRouter, Ollama, BytePlus, Cohere, and anything
+  written before this feature), `chat()` / `generateImage()` /
+  `generateVideo()` / `embed()` reject file sources in preflight, before any
+  request is built — pass `data`/`url` sources there instead.
+- **Lifecycle:** `getFile()` / `deleteFile()` work for OpenAI, Anthropic,
+  Gemini, and Grok, and accept the handle itself (provider-literal typed, so a
+  foreign handle is a compile error). fal storage is upload-only, so those
+  calls throw for `falFiles()`. `grokFiles().get()` mints the public URL again,
+  so do not call it after `revokePublicUrl()`.
+- **Some endpoints need raw bytes even on supporting providers:** OpenAI
+  `images/edits` + Sora `input_reference`, Gemini Veo, and Chat Completions
+  image inputs throw endpoint-specific errors for file sources.
+- **A file source crosses the chat wire.** A browser that holds a handle puts
+  `fileSourceFromHandle(handle)` straight into the `sendMessage` content, and
+  the server passes the messages to `chat()` as usual. `fileSourceFromHandle`
+  and the `FileHandle` type are exported from the browser-safe
+  `@tanstack/ai/client` entry.
+
+See `docs/advanced/files-api.md` for the full guide.
+
 ## Behind a proxy or gateway
 
 Every adapter's client config accepts `baseURL` and `defaultHeaders`. Use these

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

@@ -299,6 +299,8 @@ import type { UIMessage } from '@tanstack/ai-react'
 
 function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
   if (part.type !== 'image') return null
+  // A provider file handle is an opaque id, so the browser cannot load it.
+  if (part.source.type === 'file') return null
   const src =
     part.source.type === 'url'
       ? part.source.value
@@ -307,6 +309,18 @@ function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
 }
 ```
 
+For media reused across turns, upload once via a provider Files adapter
+(`openaiFiles()`, `anthropicFiles()`, `geminiFiles()`, `grokFiles()`,
+`falFiles()`) and send a `{ type: 'file' }` source built with
+`fileSourceFromHandle(handle)` instead of re-sending base64 each request. The
+source is `{ type: 'file', value, provider }`: an opaque handle and the adapter
+that issued it. A different provider (or one without Files API support at all)
+rejects it with a clear error before any request is sent.
+The source crosses the chat wire, so the browser can put it straight into the
+`sendMessage` content. Import `fileSourceFromHandle` from the browser-safe
+`@tanstack/ai/client` entry. See `ai-core/adapter-configuration/SKILL.md` §7
+and `docs/advanced/files-api.md`.
+
 ### 4. Sending Audio Messages (Browser Recording)
 
 Use `useAudioRecorder` from `@tanstack/ai-react` (or `createAudioRecorder` in Svelte) to capture audio in the browser. The resolved `AudioRecording` includes a ready-to-use `part` that slots directly into `sendMessage`.

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

@@ -283,6 +283,14 @@ await generateVideo({
 })
 ```
 
+Reference images / start frames that are reused (or arrive as inline base64 on
+memory-constrained runtimes) can instead be uploaded once via the provider's
+Files adapter and referenced with `source: fileSourceFromHandle(handle)` —
+supported for Gemini image generation (`geminiFiles()`) and fal image/video
+inputs (`falFiles()`). Endpoints that require raw bytes (OpenAI `images/edits`,
+Sora `input_reference`, Gemini Veo) reject file sources with a clear error.
+See `ai-core/adapter-configuration/SKILL.md` §7.
+
 **URL inputs that require an upload throw by default.** Most adapters pass a
 `type: 'url'` source straight through to the provider. Three paths can't —
 OpenAI `images.edit()`, OpenAI Sora `input_reference`, and Gemini **Veo** —

package/src/activities/chat/adapter.ts

@@ -89,6 +89,15 @@ export interface TextAdapter<
    */
   readonly requires?: ReadonlyArray<CapabilityHandle>
 
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content sources
+   * (provider Files API references). `chat()` rejects file sources in preflight
+   * for adapters that don't declare this, so an adapter written before the
+   * file arm existed fails closed instead of silently mis-mapping a reference
+   * onto its URL/data branch.
+   */
+  readonly supportsFileSources?: boolean
+
   /**
    * @internal Type-only properties for inference. Not assigned at runtime.
    */
@@ -209,6 +218,7 @@ export abstract class BaseTextAdapter<
   abstract readonly name: string
   readonly model: TModel
   readonly requires?: ReadonlyArray<CapabilityHandle> = undefined
+  readonly supportsFileSources: boolean = false
 
   // Type-only property - never assigned at runtime
   declare '~types': {

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'
@@ -170,6 +175,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 +197,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 +853,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
@@ -1504,6 +1505,7 @@ class TextEngine<
     this.streamIdentityCaptured = false
     this.accumulatedContent = ''
     this.accumulatedThinking = []
+    this.turnParts = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
 
@@ -1571,7 +1573,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 +1812,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 +1857,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 +1977,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 +2026,7 @@ class TextEngine<
   private handleReasoningMessageContentEvent(
     chunk: Extract<StreamChunk, { type: 'REASONING_MESSAGE_CONTENT' }>,
   ): void {
+    this.noteThinkingStepPosition()
     this.currentThinkingContent += chunk.delta
   }
 
@@ -1979,6 +2047,7 @@ class TextEngine<
       }
       return
     }
+    this.noteThinkingStepPosition()
     this.currentThinkingSignature = chunk.encryptedValue
   }
 
@@ -2464,21 +2533,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 +2715,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({
@@ -3097,6 +3265,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
@@ -3254,6 +3424,9 @@ class TextEngine<
         role: 'tool',
         content,
         toolCallId: result.toolCallId,
+        ...(result.state === 'output-error' && {
+          error: toolResultErrorText(parseToolOutput(wireContent)),
+        }),
       }
 
       if (placeholderIdx >= 0) {
@@ -3589,7 +3762,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
@@ -3932,7 +4109,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',

package/src/activities/chat/messages.ts

@@ -1,4 +1,7 @@
-import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
+import {
+  isAssistantSegmentOf,
+  isProviderExecutedToolCall,
+} from '../../utilities/provider-executed'
 import {
   isContentPartArray,
   normalizeToolResult,
@@ -1259,6 +1262,14 @@ export function modelMessagesToUIMessages(
       // Regular message. Preserve a persisted stable id so a hydrated message
       // keeps the same identity as its live stream (enables in-place resume).
       const uiMessage = modelMessageToUIMessage(msg, msg.id)
+      if (
+        msg.role === 'assistant' &&
+        currentAssistantMessage &&
+        isAssistantSegmentOf(msg.id, currentAssistantMessage.id)
+      ) {
+        currentAssistantMessage.parts.push(...uiMessage.parts)
+        continue
+      }
       uiMessages.push(uiMessage)
 
       // Track assistant messages for potential tool result merging

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

@@ -455,15 +455,37 @@ export function updateThinkingPart(
     }
 
     const parts = [...msg.parts]
-    const thinkingPartIndex = parts.findIndex(
+    let thinkingPartIndex = parts.findIndex(
       (p) => p.type === 'thinking' && p.stepId === stepId,
     )
 
+    // A hydrated message carries its thinking without a stepId: the stored form
+    // has no field for one, so `modelMessageToUIMessage` cannot put it back.
+    // When a run is rejoined mid-stream the replayed reasoning is keyed by
+    // stepId, matches nothing, and gets appended -- leaving a second thinking
+    // part sitting after the answer text. Adopt the first stepId-less thinking
+    // part instead, so the replay lands on the part it belongs to. Live
+    // streaming always writes a stepId, so the only parts this can match are
+    // hydrated ones.
+    let adopted: ThinkingPart | undefined
+    if (thinkingPartIndex < 0) {
+      thinkingPartIndex = parts.findIndex(
+        (p) => p.type === 'thinking' && p.stepId === undefined,
+      )
+      const candidate = parts[thinkingPartIndex]
+      if (candidate?.type === 'thinking') adopted = candidate
+    }
+
+    // Keep the signature the hydrated part already had when this update does
+    // not carry one; losing it would strip the provider's encrypted reasoning
+    // from a message that is about to be sent back.
+    const nextSignature = signature ?? adopted?.signature
+
     const thinkingPart: ThinkingPart = {
       type: 'thinking',
       content,
       stepId,
-      ...(signature && { signature }),
+      ...(nextSignature && { signature: nextSignature }),
     }
 
     if (thinkingPartIndex >= 0) {