@tanstack/ai 0.44.1 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -93,7 +93,7 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@vitest/coverage-v8": "4.0.14",
+    "@vitest/coverage-v8": "4.1.10",
     "arktype": "^2.1.28",
     "zod": "^4.2.0"
   },

package/skills/ai-core/adapter-configuration/references/gemini-adapter.md

@@ -94,8 +94,12 @@ Note: `GOOGLE_GENAI_API_KEY` does NOT work.
 ## Gotchas
 
 - All Gemini models are multimodal (text, image, audio, video, document input).
-- Image generation models (`gemini-3-pro-image-preview`, etc.) have smaller
-  input limits (65K tokens) compared to text models (1M tokens).
+- Image generation models (`gemini-3-pro-image`, `gemini-3.1-flash-image`, etc.)
+  have smaller input limits (65K tokens) compared to text models (1M tokens).
+- Use the GA image ids. `gemini-3-pro-image-preview` and
+  `gemini-3.1-flash-image-preview` were shut down on 2026-06-25 and now 404;
+  they remain in the type union only as deprecated aliases, so a call to them
+  compiles and then fails at runtime.
 - `thinkingConfig.thinkingLevel` (level-based) and `thinkingConfig.thinkingBudget`
   (budget-based) serve different models. Check which your model supports.
 - `cachedContent` must follow the format `cachedContents/{id}`.

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

@@ -151,9 +151,16 @@ function ImageGenerator() {
 ### 1. Image Generation
 
 Supported adapters: `openaiImage` (dall-e-2, dall-e-3, gpt-image-1,
-gpt-image-1-mini, gpt-image-2), `geminiImage` (gemini-3.1-flash-image-preview,
-gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.) and `byteplusImage`
-(Seedream — `seedream-4-0-250828`, `seedream-4-5-251128`, the 5.0 family).
+gpt-image-1-mini, gpt-image-2), `geminiImage` (gemini-3.1-flash-image,
+gemini-3.1-flash-lite-image, gemini-3-pro-image, imagen-4.0-generate-001, etc.)
+and `byteplusImage` (Seedream — `seedream-4-0-250828`, `seedream-4-5-251128`,
+the 5.0 family).
+
+> **Use the GA Gemini image ids.** `gemini-3.1-flash-image-preview` and
+> `gemini-3-pro-image-preview` were shut down on 2026-06-25 and now 404. They
+> survive in the type union only as deprecated aliases so existing code keeps
+> compiling — a call to them typechecks and then fails at runtime. Use
+> `gemini-3.1-flash-image` / `gemini-3-pro-image` instead.
 
 > **Seedream quirks:** `watermark` defaults to **`true`** (pass
 > `modelOptions: { watermark: false }` for a clean image), `size` is a token
@@ -182,7 +189,7 @@ const openaiResult = await generateImage({
 
 // Gemini native model with aspect-ratio sizes
 const geminiResult = await generateImage({
-  adapter: geminiImage('gemini-3.1-flash-image-preview'),
+  adapter: geminiImage('gemini-3.1-flash-image'),
   prompt: 'A futuristic cityscape at night',
   size: '16:9_4K',
 })
@@ -295,18 +302,19 @@ with `allowUrlFetch: true` on the adapter config
 
 **Provider support matrix:**
 
-| Provider   | `generateImage` image parts                                                                                                                                                                              | `generateVideo` image parts                                                                                                                                                                                                                                                                    |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                                                                                                                      |
-| Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | Veo → first un-roled / `'start_frame'` image is the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages`. Omni Flash sends image/video parts as interaction content blocks (no role routing).                                                           |
-| fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`.                                                                                             |
-| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | n/a                                                                                                                                                                                                                                                                                            |
-| OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | Dedicated async API (`openRouterVideo`): `start_frame`/`end_frame` → `frame_images[]` (`first_frame`/`last_frame`); `reference`/`character` → `input_references[]`; an unroled image defaults to the start frame. Frame roles validated against the model's `supported_frame_images` metadata. |
-| Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                                                                                                            |
+| Provider   | `generateImage` image parts                                                                                                                                                                              | `generateVideo` image parts                                                                                                                                                                                                                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                                                                                                                                    |
+| Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | Veo → first un-roled / `'start_frame'` image is the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages`. Omni Flash sends image/video parts as interaction content blocks (no role routing).                                                                         |
+| fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`.                                                                                                           |
+| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | Un-roled / `'start_frame'` image → starting frame; `'reference'` / `'character'` → `reference_images` (1.5). Starting frame and reference inputs cannot be combined. A `video` part + `modelOptions.mode: 'edit' \| 'extend'` routes to `/videos/edits` / `/videos/extensions` on `grok-imagine-video` only. |
+| OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | Dedicated async API (`openRouterVideo`): `start_frame`/`end_frame` → `frame_images[]` (`first_frame`/`last_frame`); `reference`/`character` → `input_references[]`; an unroled image defaults to the start frame. Frame roles validated against the model's `supported_frame_images` metadata.               |
+| Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                                                                                                                          |
 
 Video and audio prompt parts follow the same `metadata.role` convention
-for video-to-video and lipsync flows on fal; other providers throw when
-they're passed.
+for video-to-video and lipsync flows on fal. Grok accepts one source
+`video` part on `grok-imagine-video` with `modelOptions.mode: 'edit' | 'extend'`
+and rejects audio parts. Other providers throw when those parts are passed.
 
 ### 2. Audio Generation (Music, Sound Effects)
 
@@ -544,10 +552,16 @@ const edited = await generateVideo({
 
 Other video adapters: `openaiVideo('sora-2')` (pixel sizes like `'1280x720'`,
 durations 4/8/12s, single `input_reference` image prompt part), `grokVideo(...)`
-(`grok-imagine-video` does text-to-video + image-to-video; `grok-imagine-video-1.5` is
-image-to-video only — needs an `image` prompt part as the starting frame, text-only throws;
-aspect-ratio size template like `'16:9_720p'`, integer durations 1-15s, reports
-`usage.unitsBilled` seconds and exact `usage.cost`), `byteplusVideo(...)` (Seedance —
+(`grok-imagine-video` and `grok-imagine-video-1.5` both do text-to-video + image-to-video;
+1.5 adds reference-to-video — `'reference'`/`'character'`-roled image parts →
+`reference_images` (max 7), preset voices via `modelOptions.reference_audios` (max 3) —
+1.5-only, capped at 720p, and not combinable with a starting-frame image; only
+`grok-imagine-video` edits/extends a source `video` prompt part via
+`modelOptions.mode: 'edit' | 'extend'` (extend `duration` = added tail). Edit/extend
+outputs inherit the source clip's properties, so `size`/`aspect_ratio`/`resolution`
+throw in both modes and `duration` throws in edit mode — pass none of them there;
+generation uses the aspect-ratio size template like `'16:9_720p'` (1080p is 1.5-only),
+integer durations 1-15s, reports `usage.unitsBilled` seconds and exact `usage.cost`), `byteplusVideo(...)` (Seedance —
 aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family,
 4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`),
 `openRouterVideo(...)` (OpenRouter's dedicated `POST /api/v1/videos` gateway),
@@ -996,7 +1010,7 @@ generateImage({
 })
 
 generateImage({
-  adapter: geminiImage('gemini-3.1-flash-image-preview'), // native multimodal
+  adapter: geminiImage('gemini-3.1-flash-image'), // native multimodal
   prompt: [
     { type: 'text', content: 'Edit this' },
     { type: 'image', source: { type: 'url', value: url } },

package/skills/ai-core/structured-outputs/SKILL.md

@@ -20,6 +20,7 @@ sources:
   - 'TanStack/ai:docs/structured-outputs/streaming.md'
   - 'TanStack/ai:docs/structured-outputs/multi-turn.md'
   - 'TanStack/ai:docs/structured-outputs/with-tools.md'
+  - 'TanStack/ai:docs/structured-outputs/harnesses.md'
 ---
 
 # Structured Outputs
@@ -48,7 +49,7 @@ person.age // number
 
 When `outputSchema` is provided, `chat()` returns `Promise<InferSchemaType<TSchema>>` instead of `AsyncIterable<StreamChunk>`. The result is fully typed.
 
-Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below for direct iteration, **Pattern 4** for the `useChat` shape on the client, and **Pattern 5** for multi-turn structured chats.
+Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below for direct iteration, **Pattern 4** for the `useChat` shape on the client, **Pattern 5** for multi-turn structured chats, and **Pattern 6** for harness adapters.
 
 ## Decision: which pattern fits
 
@@ -59,6 +60,7 @@ Adding `stream: true` switches the return to `StructuredOutputStream<InferSchema
 | Direct iteration of the stream in Node or tests                                                | Pattern 3 — async iterable                                       |
 | Users iterate on a structured object across multiple turns (recipe builder, ticket refinement) | Pattern 5 — multi-turn structured chat                           |
 | Tools that gather info, then return a typed object                                             | Combine any of the above with `tools` — see ai-core/tool-calling |
+| A coding agent in a sandbox inspects files, then returns a typed object                        | Pattern 6 — harness `outputSchema`                               |
 
 ## Core Patterns
 
@@ -189,6 +191,13 @@ The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-out
 | `@tanstack/ai-grok` (Grok 4 family only)                        | **Native combined mode (#605)** — `response_format: json_schema` + `tools`. Grok 2 / 3 fall back                                                      |
 | `@tanstack/ai-openrouter`                                       | Native single-request stream (legacy `structuredOutputStream` path; per-call combined-mode lookup is a follow-up)                                     |
 | `@tanstack/ai-groq`                                             | Legacy `structuredOutputStream` only (no tools — Groq's API rejects schema + tools + stream)                                                          |
+| `@tanstack/ai-bedrock`                                          | Separate native `structuredOutputStream` finalization through Converse or an OpenAI-compatible API                                                    |
+| `@tanstack/ai-byteplus`                                         | Native combined mode on supported models; unsupported models emit `RUN_ERROR`                                                                         |
+| `@tanstack/ai-claude-code`                                      | Combined + event source — `--json-schema` on the same harness turn. Read `useChat().final`. See Pattern 6.                                            |
+| `@tanstack/ai-codex`                                            | Combined + event source — `--output-schema` on the same harness turn. Read `useChat().final`. See Pattern 6.                                          |
+| `@tanstack/ai-opencode`                                         | Combined + event source — prompt-and-parse. Read `useChat().final`. See Pattern 6.                                                                    |
+| `@tanstack/ai-grok-build`                                       | Combined + event source — prompt-and-parse (ACP and streaming-json). Read `useChat().final` or the `structured-output` part. See Pattern 6.           |
+| `@tanstack/ai-acp` (`acpCompatible`)                            | Combined + event source — prompt-and-parse. Read `useChat().final` or the `structured-output` part. See Pattern 6.                                    |
 | All other adapters (ollama, older Claude, Gemini 2.x, Grok 2/3) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event                                                         |
 
 **Native combined mode vs fallback** is signaled by the adapter's
@@ -341,6 +350,68 @@ Key behaviors:
 - **`partial` / `final` are derived.** The hook-level `partial` and `final` are NOT singleton state — they're derived from the latest assistant message's part (the one after the most recent user message). Between `sendMessage()` and the first chunk, `partial` reads `{}` and `final` reads `null` because no new assistant turn exists yet.
 - **Round-trip preserves history.** When the client sends turn N+1, each prior assistant turn's `structured-output` part is serialized back as `{ role: 'assistant', content: <part.raw> }` so the model sees its own prior structured response. Streaming / errored parts are dropped from the round-trip.
 
+### Pattern 6: Harness adapters (Claude Code, Codex, OpenCode, Grok Build, ACP)
+
+Dedicated harness adapters honor `chat({ outputSchema })` on the same turn. Native harness tools still run. Read the object from `await chat()`, from `useChat().final`, or from the assistant `structured-output` part on `messages[].parts`. Do not parse assistant prose.
+
+A UI endpoint must pass `stream: true`. Without it, `chat()` returns a `Promise`, not SSE.
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { withSandbox } from '@tanstack/ai-sandbox'
+import { z } from 'zod'
+import { sandbox } from './sandbox'
+
+const ReportSchema = z.object({
+  name: z.string(),
+  oneLiner: z.string(),
+})
+
+export async function POST(request: Request) {
+  const body: unknown = await request.json()
+  const messages =
+    typeof body === 'object' &&
+    body !== null &&
+    'messages' in body &&
+    Array.isArray(body.messages)
+      ? body.messages
+      : []
+
+  const stream = chat({
+    adapter: claudeCodeText('claude-opus-4-8'),
+    messages,
+    outputSchema: ReportSchema,
+    stream: true,
+    middleware: [withSandbox(sandbox)],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+```tsx
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+import { z } from 'zod'
+
+const ReportSchema = z.object({
+  name: z.string(),
+  oneLiner: z.string(),
+})
+
+const { final } = useChat({
+  connection: fetchServerSentEvents('/api/repo-report'),
+  outputSchema: ReportSchema,
+})
+
+final?.name
+```
+
+- Claude Code: `--json-schema`. Codex: `--output-schema`. OpenCode, Grok Build, and `acpCompatible`: prompt-and-parse.
+- `partial` stays empty until `structured-output.complete`.
+- Client tools and `needsApproval` fail fast. The harness cannot pause for a browser round-trip.
+- Render live work from `messages[].parts` (`thinking`, `tool-call`, `text`, `structured-output`). `final` is only the latest turn.
+- See [docs/structured-outputs/harnesses.md](https://github.com/TanStack/ai/blob/main/docs/structured-outputs/harnesses.md).
+
 ## Common Mistakes
 
 ### HIGH: Filtering `TextPart`s out of `useChat` renderers when using `outputSchema`
@@ -509,4 +580,5 @@ provider call, stripping system prompts), use the dedicated
 - See also: **ai-core/chat-experience/SKILL.md** — Base `useChat` surface; the structured-output additions documented here layer on top.
 - See also: **ai-core/adapter-configuration/SKILL.md** — Adapter handles structured-output strategy transparently.
 - See also: **ai-core/tool-calling/SKILL.md** — Combine `tools` with `outputSchema` for an agent loop that runs tools first and returns a typed object. Tool-approval and client-tool flows compose with structured runs without extra wiring; see [docs/structured-outputs/with-tools.md](https://github.com/TanStack/ai/blob/main/docs/structured-outputs/with-tools.md).
+- See also: [docs/structured-outputs/harnesses.md](https://github.com/TanStack/ai/blob/main/docs/structured-outputs/harnesses.md) — dedicated harness adapters and `useChat().final`.
 - See also: **ai-core/middleware/SKILL.md** — `onStructuredOutputConfig` hook and the `structuredOutput` phase for observing/transforming the final structured-output call.

package/skills/ai-core/tool-calling/SKILL.md

@@ -623,7 +623,7 @@ export const Route = createFileRoute('/api/chat')({
 
 ## Provider Skills
 
-> **Not to be confused with `@tanstack/ai-code-mode-skills`**, which are locally-generated TypeScript functions executed client-side. Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.
+> **Not to be confused with `@tanstack/ai-code-mode-snippets`**, whose snippets are TypeScript functions your application generates and runs in its own Code Mode sandbox (a local JS isolate). Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.
 
 Provider Skills are inert without an execution tool. The execution tool is what activates the sandbox; skills are additional capability bundles that run inside it:
 

package/src/activities/chat/adapter.ts

@@ -131,7 +131,8 @@ export interface TextAdapter<
    * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,
    * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final
    * `CUSTOM` event named `structured-output.complete` whose `value` is
-   * `{ object, raw, reasoning? }`.
+   * `{ object, raw, reasoning? }`. Events must be timestamped when emitted so
+   * their timestamps follow stream order.
    */
   structuredOutputStream?: (
     options: StructuredOutputOptions<TProviderOptions>,
@@ -159,6 +160,20 @@ export interface TextAdapter<
   supportsCombinedToolsAndSchema?: (
     modelOptions?: TProviderOptions | undefined,
   ) => boolean
+
+  /**
+   * Where native-combined structured output is taken from.
+   *
+   * - `'text'` (default when omitted): the agent loop's accumulated
+   *   assistant text is schema JSON. The engine parses it after the loop.
+   *   HTTP adapters use this.
+   * - `'event'`: the adapter emits `structured-output.complete` during
+   *   `chatStream`. The engine must not parse accumulated prose. Harness
+   *   adapters use this.
+   */
+  combinedStructuredOutputSource?: (
+    modelOptions?: TProviderOptions | undefined,
+  ) => 'text' | 'event'
 }
 
 /**

package/src/activities/chat/index.ts

@@ -655,11 +655,12 @@ interface TextEngineConfig<
    * - nativeCombined: when true, the adapter declared
    *   `supportsCombinedToolsAndSchema()` and the engine wires `jsonSchema`
    *   into the regular `chatStream` call instead of running a separate
-   *   finalization round-trip. The agent loop's final-turn text is the
-   *   schema-constrained JSON; the engine parses it from accumulated
-   *   content. The `'structuredOutput'` middleware phase does NOT fire on
-   *   this path — middleware sees the run through `beforeModel` /
-   *   `modelStream` as usual.
+   *   finalization round-trip. The `'structuredOutput'` middleware phase
+   *   does NOT fire on this path — middleware sees the run through
+   *   `beforeModel` / `modelStream` as usual.
+   * - source: how to take the combined object. `'text'` (default) parses
+   *   accumulated assistant text. `'event'` reads an adapter-emitted
+   *   `structured-output.complete` and does not parse prose.
    */
   finalStructuredOutput?: {
     jsonSchema: JSONSchema
@@ -667,6 +668,7 @@ interface TextEngineConfig<
     normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
+    source?: 'text' | 'event'
   }
 }
 
@@ -801,12 +803,14 @@ class TextEngine<
     code?: string
     cause?: unknown
   } | null = null
+  private combinedCompleteEmitted = false
   private readonly finalStructuredOutput?: {
     jsonSchema: JSONSchema
     yieldChunks: boolean
     normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
+    source?: 'text' | 'event'
   }
 
   constructor(
@@ -1110,7 +1114,8 @@ class TextEngine<
         this.finalStructuredOutput &&
         this.toolPhase !== 'wait' &&
         !this.isCancelled() &&
-        !this.finalizationError
+        !this.finalizationError &&
+        !this.earlyTermination
       ) {
         if (this.finalStructuredOutput.nativeCombined === true) {
           yield* this.harvestCombinedStructuredOutput()
@@ -1374,9 +1379,46 @@ class TextEngine<
       // text starting — intermediate tool-call iterations don't need it,
       // and emitting at run-start would wrap tool-call commentary into a
       // structured-output part too.
+      if (
+        chunk.type === EventType.CUSTOM &&
+        chunk.name === 'structured-output.start'
+      ) {
+        this.combinedStartEmitted = true
+        const startValue = chunk.value
+        if (
+          startValue &&
+          typeof startValue === 'object' &&
+          'messageId' in startValue &&
+          typeof startValue.messageId === 'string'
+        ) {
+          this.combinedStructuredMessageId = startValue.messageId
+        }
+      }
+
+      let outboundChunk: StreamChunk = chunk
+      if (
+        this.finalStructuredOutput?.source === 'event' &&
+        chunk.type === EventType.CUSTOM &&
+        chunk.name === 'structured-output.complete'
+      ) {
+        const parsed = readStructuredOutputCompleteValue(chunk.value)
+        if (parsed) {
+          const object = this.finalStructuredOutput.normalize
+            ? this.finalStructuredOutput.normalize(parsed.object)
+            : parsed.object
+          this.structuredOutputResult = { data: object, rawText: parsed.raw }
+          this.combinedCompleteEmitted = true
+          const value = chunk.value
+          if (object !== parsed.object && value && typeof value === 'object') {
+            outboundChunk = { ...chunk, value: { ...value, object } }
+          }
+        }
+      }
+
       if (
         this.finalStructuredOutput?.nativeCombined === true &&
         this.finalStructuredOutput.yieldChunks &&
+        this.finalStructuredOutput.source !== 'event' &&
         !this.combinedStartEmitted &&
         chunk.type === EventType.TEXT_MESSAGE_START
       ) {
@@ -1408,7 +1450,7 @@ class TextEngine<
       // Pipe chunk through middleware (devtools middleware observes; strip-to-spec cleans)
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
-        chunk,
+        outboundChunk,
       )
       // When a streaming structured-output finalization step will run after
       // the agent loop, suppress the agent-loop's RUN_STARTED/RUN_FINISHED
@@ -1554,9 +1596,23 @@ class TextEngine<
   }
 
   private handleRunErrorEvent(
-    _chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+    chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
   ): void {
     this.earlyTermination = true
+    if (this.finalStructuredOutput && this.finalizationError === null) {
+      const message =
+        chunk.message ||
+        chunk.error?.message ||
+        'Run failed before structured output completed'
+      this.finalizationError = {
+        message,
+        ...(chunk.code !== undefined
+          ? { code: chunk.code }
+          : chunk.error?.code !== undefined
+            ? { code: chunk.error.code }
+            : {}),
+      }
+    }
   }
 
   private finalizeCurrentThinkingStep(): void {
@@ -2177,7 +2233,9 @@ class TextEngine<
               ? undefined
               : JSON.stringify(message.content)
         return {
-          id: `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
+          id:
+            message.id ||
+            `snapshot_${this.runIdOverride ?? this.requestId}_${index}`,
           role: message.role,
           ...(content !== undefined ? { content } : {}),
           ...('toolCalls' in message && message.toolCalls
@@ -2855,7 +2913,9 @@ class TextEngine<
       return null
     }
 
-    const buildSynthesizedStart = (): StreamChunk => {
+    // The synthetic event is inserted before its trigger, so share that
+    // trigger's timestamp rather than making the earlier event sort later.
+    const buildSynthesizedStart = (timestamp = Date.now()): StreamChunk => {
       const idForStart = structuredMessageId ?? generateMessageId()
       structuredMessageId = idForStart
       return {
@@ -2863,7 +2923,7 @@ class TextEngine<
         name: 'structured-output.start',
         value: { messageId: idForStart },
         model: this.params.model,
-        timestamp: Date.now(),
+        timestamp,
         threadId: this.threadId,
         ...(this.runIdOverride ? { runId: this.runIdOverride } : {}),
       }
@@ -2913,7 +2973,7 @@ class TextEngine<
             chunk.type === EventType.TEXT_MESSAGE_END)
         ) {
           startEmitted = true
-          const synthStart = buildSynthesizedStart()
+          const synthStart = buildSynthesizedStart(chunk.timestamp)
           const synthOutputs = await pipeThroughMiddleware(synthStart)
           for (const outputChunk of synthOutputs) {
             yield outputChunk
@@ -2926,7 +2986,7 @@ class TextEngine<
         // of a silent UI.
         if (!startEmitted && chunk.type === EventType.RUN_ERROR) {
           startEmitted = true
-          const synthStart = buildSynthesizedStart()
+          const synthStart = buildSynthesizedStart(chunk.timestamp)
           const synthOutputs = await pipeThroughMiddleware(synthStart)
           for (const outputChunk of synthOutputs) {
             yield outputChunk
@@ -3139,35 +3199,46 @@ class TextEngine<
     }
 
     const yieldChunks = this.finalStructuredOutput.yieldChunks
-    const rawText = this.accumulatedContent
+    const source = this.finalStructuredOutput.source ?? 'text'
 
-    // Empty final-turn text means the agent loop terminated without the
-    // model emitting any assistant content (e.g. early termination after
-    // tool calls). Mirror the fallback path's "missing structured result"
-    // error rather than silently returning undefined.
-    if (rawText.length === 0) {
-      this.finalizationError = {
-        message: 'missing structured result',
-        code: 'structured-output-missing-result',
+    if (source === 'event') {
+      if (!this.structuredOutputResult) {
+        this.finalizationError = {
+          message: 'missing structured result',
+          code: 'structured-output-missing-result',
+        }
       }
     } else {
-      try {
-        const parsed: unknown = JSON.parse(rawText)
-        // Normalize (un-widen) before storing so the synthesized
-        // structured-output.complete chunk and the Promise<T> result both
-        // carry the cleaned payload. JSON.parse preserves provider nulls, so
-        // this is where native-combined output gets its widening undone.
-        const data = this.finalStructuredOutput.normalize
-          ? this.finalStructuredOutput.normalize(parsed)
-          : parsed
-        this.structuredOutputResult = { data, rawText }
-      } catch (err: unknown) {
-        const detail =
-          rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
+      const rawText = this.accumulatedContent
+
+      // Empty final-turn text means the agent loop terminated without the
+      // model emitting any assistant content (e.g. early termination after
+      // tool calls). Mirror the fallback path's "missing structured result"
+      // error rather than silently returning undefined.
+      if (rawText.length === 0) {
         this.finalizationError = {
-          message: `Failed to parse structured output as JSON. Content: ${detail}`,
-          code: 'structured-output-parse-failed',
-          cause: err,
+          message: 'missing structured result',
+          code: 'structured-output-missing-result',
+        }
+      } else {
+        try {
+          const parsed: unknown = JSON.parse(rawText)
+          // Normalize (un-widen) before storing so the synthesized
+          // structured-output.complete chunk and the Promise<T> result both
+          // carry the cleaned payload. JSON.parse preserves provider nulls, so
+          // this is where native-combined output gets its widening undone.
+          const data = this.finalStructuredOutput.normalize
+            ? this.finalStructuredOutput.normalize(parsed)
+            : parsed
+          this.structuredOutputResult = { data, rawText }
+        } catch (err: unknown) {
+          const detail =
+            rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
+          this.finalizationError = {
+            message: `Failed to parse structured output as JSON. Content: ${detail}`,
+            code: 'structured-output-parse-failed',
+            cause: err,
+          }
         }
       }
     }
@@ -3237,7 +3308,11 @@ class TextEngine<
     // complete event yields AFTER the loop ends, by which point
     // `getActiveAssistantMessageId()` returns null and would otherwise drop
     // the event silently).
-    if (this.structuredOutputResult && !this.finalizationError) {
+    if (
+      this.structuredOutputResult &&
+      !this.finalizationError &&
+      !this.combinedCompleteEmitted
+    ) {
       const completeChunk: StreamChunk = {
         type: EventType.CUSTOM,
         name: 'structured-output.complete',
@@ -3890,6 +3965,8 @@ async function runAgenticStructuredOutput<
   // agent loop's accumulated final-turn text.
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+  const source =
+    adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text'
 
   const mcpManager = MCPManager.from(mcp)
   const mcpTools = await mcpManager.discover()
@@ -3913,6 +3990,7 @@ async function runAgenticStructuredOutput<
         normalize,
         ...(validate ? { validate } : {}),
         ...(nativeCombined ? { nativeCombined: true } : {}),
+        source,
       },
     },
     logger,
@@ -4008,14 +4086,14 @@ async function* fallbackStructuredOutputStream(
     chatOptions.threadId ?? `fallback-${Date.now()}-${fallbackRand}`
   const messageId = `fallback-${Date.now()}-${fallbackRand}`
   const model = chatOptions.model
-  const timestamp = Date.now()
+  const startedAt = Date.now()
 
   yield {
     type: EventType.RUN_STARTED,
     runId,
     threadId,
     model,
-    timestamp,
+    timestamp: startedAt,
   }
 
   let result: StructuredOutputResult<unknown>
@@ -4029,7 +4107,7 @@ async function* fallbackStructuredOutputStream(
       runId,
       threadId,
       model,
-      timestamp,
+      timestamp: Date.now(),
       message,
       error: { message },
     }
@@ -4041,7 +4119,7 @@ async function* fallbackStructuredOutputStream(
     messageId,
     role: 'assistant',
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4049,14 +4127,14 @@ async function* fallbackStructuredOutputStream(
     messageId,
     delta: result.rawText,
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
     type: EventType.TEXT_MESSAGE_END,
     messageId,
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4064,7 +4142,7 @@ async function* fallbackStructuredOutputStream(
     name: 'structured-output.complete',
     value: { object: result.data, raw: result.rawText },
     model,
-    timestamp,
+    timestamp: Date.now(),
   }
 
   yield {
@@ -4072,7 +4150,7 @@ async function* fallbackStructuredOutputStream(
     runId,
     threadId,
     model,
-    timestamp,
+    timestamp: Date.now(),
     finishReason: 'stop',
     // Forward adapter-reported token usage so consumers reading
     // `RUN_FINISHED.usage` (and the engine's `runOnUsage` middleware hook) see
@@ -4205,6 +4283,8 @@ async function* runStreamingStructuredOutputImpl<
   // does not fire.
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+  const source =
+    adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? 'text'
 
   const mcpManager = MCPManager.from(mcp)
   const mcpTools = await mcpManager.discover()
@@ -4229,6 +4309,7 @@ async function* runStreamingStructuredOutputImpl<
         yieldChunks: true,
         normalize,
         ...(nativeCombined ? { nativeCombined: true } : {}),
+        source,
       },
     },
     logger,