@tanstack/ai 0.44.1 → 0.45.1

package/README.md

@@ -36,6 +36,14 @@
   </a>
 </div>
 
+<br />
+
+<div align="center">
+  <a href="https://tanstack.com/blog/tanstack-open-source-awards-2026">
+    <img src="https://raw.githubusercontent.com/TanStack/ai/16826d81cade868956df240d6239a671e689193c/media/js-open-source-award-2026-ai-project-of-the-year.svg" alt="Winner of the 2026 JavaScript Open Source Award for AI Project of the Year" width="250" />
+  </a>
+</div>
+
 # TanStack AI
 
 Type-safe, provider-agnostic TypeScript SDK for building streaming chat,
@@ -191,7 +199,7 @@ Learn more in the
   build low-latency realtime voice experiences.
 - [Code Mode](https://tanstack.com/ai/latest/docs/code-mode/code-mode) - let
   models write and execute TypeScript inside a secure isolate.
-- [Code Mode with Skills](https://tanstack.com/ai/latest/docs/code-mode/code-mode-with-skills) -
+- [Code Mode with Snippets](https://tanstack.com/ai/latest/docs/code-mode/code-mode-with-snippets) -
   give Code Mode reusable runtime capabilities.
 
 ## Providers
@@ -208,6 +216,7 @@ Official adapters include:
 | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok)             | xAI Grok chat, images, and realtime                                            |
 | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq)             | Groq low-latency inference                                                     |
 | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects     |
+| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus)     | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR    |
 | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal)               | fal.ai image, video, audio, speech, and transcription models                   |
 
 The adapter system is tree-shakeable by activity. Import `openaiText` for chat,

package/dist/esm/activities/chat/adapter.d.ts

@@ -103,7 +103,8 @@ export interface TextAdapter<TModel extends string, TProviderOptions extends Rec
      * 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>) => AsyncIterable<StreamChunk>;
     /**
@@ -126,6 +127,17 @@ export interface TextAdapter<TModel extends string, TProviderOptions extends Rec
      * answer per-request. Most adapters can return a constant.
      */
     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';
 }
 /**
  * A TextAdapter with any/unknown type parameters.

package/dist/esm/activities/chat/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA+KA,IAAsB,kBAAtB,MAgBE;CACA,OAAgB;CAEhB;CACA,WAAsD,KAAA;CAYtD;CAEA,YAAY,SAA4B,CAAC,GAAG,OAAe;EACzD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAcA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n  TokenUsage,\n} from '../../types'\nimport type { CapabilityHandle } from './middleware/capabilities'\n\n/**\n * Configuration for adapter instances\n */\nexport interface TextAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Options for structured output generation.\n *\n * The internal logger is threaded through `chatOptions.logger` (inherited from\n * `TextOptions`). Adapter implementations must call `logger.request()` before\n * SDK calls, `logger.provider()` for each chunk received, and `logger.errors()`\n * in catch blocks.\n */\nexport interface StructuredOutputOptions<TProviderOptions extends object> {\n  /** Text options for the request */\n  chatOptions: TextOptions<TProviderOptions>\n  /** JSON Schema for structured output - already converted from Zod in the ai layer */\n  outputSchema: JSONSchema\n}\n\n/**\n * Result from structured output generation\n */\nexport interface StructuredOutputResult<T = unknown> {\n  /** The parsed data conforming to the schema */\n  data: T\n  /** The raw text response from the model before parsing */\n  rawText: string\n  /** Token usage information (if provided by the adapter) */\n  usage?: TokenUsage\n}\n\n/**\n * Text adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'gpt-4o')\n * - TProviderOptions: Provider-specific options for this model (already resolved)\n * - TInputModalities: Supported input modalities for this model (already resolved)\n * - TMessageMetadata: Metadata types for content parts (already resolved)\n * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`\n * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)\n * - TSystemPromptMetadata: Provider-typed metadata accepted on each\n *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to\n *   `never` — adapters without per-prompt metadata reject the `metadata`\n *   field at the call site.\n */\nexport interface TextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> {\n  /** Discriminator for adapter kind */\n  readonly kind: 'text'\n  /** Provider name identifier (e.g., 'openai', 'anthropic') */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * Capabilities this adapter requires at runtime. `chat()` validates that the\n   * configured middleware provides each one. Model adapters omit this; harness\n   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.\n   * Runtime access to capabilities from inside the adapter is not yet wired —\n   * this is the declaration/validation surface only.\n   */\n  readonly requires?: ReadonlyArray<CapabilityHandle>\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  /**\n   * Stream text completions from the model\n   */\n  chatStream: (\n    options: TextOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * This method uses stream: false and sends the JSON schema to the provider\n   * to ensure the response conforms to the expected structure.\n   *\n   * @param options - Structured output options containing chat options and JSON schema\n   * @returns Promise with the raw data (validation is done in the chat function)\n   */\n  structuredOutput: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => Promise<StructuredOutputResult<unknown>>\n\n  /**\n   * Stream structured output using the provider's native streaming structured\n   * output API (stream + response_format json_schema in a single request).\n   *\n   * Optional — adapters without native streaming JSON omit this method and the\n   * activity layer synthesizes a stream around the non-streaming\n   * `structuredOutput` call.\n   *\n   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,\n   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final\n   * `CUSTOM` event named `structured-output.complete` whose `value` is\n   * `{ object, raw, reasoning? }`. Events must be timestamped when emitted so\n   * their timestamps follow stream order.\n   */\n  structuredOutputStream?: (\n    options: StructuredOutputOptions<TProviderOptions>,\n  ) => AsyncIterable<StreamChunk>\n\n  /**\n   * Declares whether the adapter supports combining `tools` and a\n   * schema-constrained final answer in a single streaming request.\n   *\n   * When `true`, the engine wires `outputSchema` into the regular\n   * `chatStream()` call and skips the separate `runStructuredFinalization`\n   * round-trip. The model's natural final turn carries the\n   * schema-constrained JSON text and the engine harvests it from the agent\n   * loop's accumulated content.\n   *\n   * When `false`, `undefined`, or the method is omitted, the engine runs\n   * the agent loop without `outputSchema` and then issues a separate\n   * `structuredOutput` / `structuredOutputStream` call against the JSON\n   * schema for finalization (the legacy path).\n   *\n   * The method receives the per-call `modelOptions` so providers whose\n   * support depends on the resolved upstream model (e.g. OpenRouter) can\n   * answer per-request. Most adapters can return a constant.\n   */\n  supportsCombinedToolsAndSchema?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => boolean\n\n  /**\n   * Where native-combined structured output is taken from.\n   *\n   * - `'text'` (default when omitted): the agent loop's accumulated\n   *   assistant text is schema JSON. The engine parses it after the loop.\n   *   HTTP adapters use this.\n   * - `'event'`: the adapter emits `structured-output.complete` during\n   *   `chatStream`. The engine must not parse accumulated prose. Harness\n   *   adapters use this.\n   */\n  combinedStructuredOutputSource?: (\n    modelOptions?: TProviderOptions | undefined,\n  ) => 'text' | 'event'\n}\n\n/**\n * A TextAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>\n\n/**\n * Abstract base class for text adapters.\n * Extend this class to implement a text adapter for a specific provider.\n *\n * Generic parameters match TextAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTextAdapter<\n  TModel extends string,\n  TProviderOptions extends Record<string, any>,\n  TInputModalities extends ReadonlyArray<Modality>,\n  TMessageMetadataByModality extends DefaultMessageMetadataByModality,\n  TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TToolCallMetadata = unknown,\n  TSystemPromptMetadata = never,\n> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata,\n  TSystemPromptMetadata\n> {\n  readonly kind = 'text' as const\n  abstract readonly name: string\n  readonly model: TModel\n  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n    inputModalities: TInputModalities\n    messageMetadataByModality: TMessageMetadataByModality\n    toolCapabilities: TToolCapabilities\n    toolCallMetadata: TToolCallMetadata\n    systemPromptMetadata: TSystemPromptMetadata\n  }\n\n  protected config: TextAdapterConfig\n\n  constructor(config: TextAdapterConfig = {}, model: TModel) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract chatStream(\n    options: TextOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk>\n\n  /**\n   * Generate structured output using the provider's native structured output API.\n   * Concrete implementations should override this to use provider-specific structured output.\n   */\n  abstract structuredOutput(\n    options: StructuredOutputOptions<TProviderOptions>,\n  ): Promise<StructuredOutputResult<unknown>>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"mappings":";;;;;;;AA8LA,IAAsB,kBAAtB,MAgBE;CACA,OAAgB;CAEhB;CACA,WAAsD,KAAA;CAYtD;CAEA,YAAY,SAA4B,CAAC,GAAG,OAAe;EACzD,KAAK,SAAS;EACd,KAAK,QAAQ;CACf;CAcA,aAA+B;EAC7B,OAAO,GAAG,KAAK,KAAK,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;CAC7E;AACF"}

package/dist/esm/activities/chat/index.js

@@ -151,6 +151,7 @@ var TextEngine = class {
 	eventOptions;
 	eventToolNames;
 	finishedEvent = null;
+	streamedToolErrorResults = /* @__PURE__ */ new Map();
 	deferredToolCallRunFinishedChunks = [];
 	earlyTermination = false;
 	toolPhase = "continue";
@@ -187,6 +188,7 @@ var TextEngine = class {
 	validatedStructuredOutput = void 0;
 	hasValidatedStructuredOutput = false;
 	finalizationError = null;
+	combinedCompleteEmitted = false;
 	finalStructuredOutput;
 	constructor(config, logger) {
 		this.logger = logger;
@@ -336,27 +338,31 @@ var TextEngine = class {
 				this.endCycle();
 			} while (await this.shouldContinue());
 			this.logger.agentLoop("run finished", { finishReason: this.lastFinishReason });
-			if (this.finalStructuredOutput && this.toolPhase !== "wait" && !this.isCancelled() && !this.finalizationError) if (this.finalStructuredOutput.nativeCombined === true) yield* this.harvestCombinedStructuredOutput();
-			else yield* this.runStructuredFinalization();
-			if (!this.terminalHookCalled && this.toolPhase !== "wait" && !this.isCancelled()) if (this.finalizationError) {
-				this.terminalHookCalled = true;
-				const errForHook = new Error(this.finalizationError.message, this.finalizationError.cause !== void 0 ? { cause: this.finalizationError.cause } : void 0);
-				if (this.finalizationError.code !== void 0) 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.terminalHookCalled = true;
-				await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
-					finishReason: this.lastFinishReason,
-					duration: Date.now() - this.streamStartTime,
-					content: this.accumulatedContent,
-					usage: this.finishedEvent?.usage
-				});
+			if (this.finalStructuredOutput && this.toolPhase !== "wait" && !this.isCancelled() && !this.finalizationError && !this.earlyTermination) {
+				if (this.finalStructuredOutput.nativeCombined === true) yield* this.harvestCombinedStructuredOutput();
+				else yield* this.runStructuredFinalization();
+			}
+			if (!this.terminalHookCalled && this.toolPhase !== "wait" && !this.isCancelled()) {
+				if (this.finalizationError) {
+					this.terminalHookCalled = true;
+					const errForHook = new Error(this.finalizationError.message, this.finalizationError.cause !== void 0 ? { cause: this.finalizationError.cause } : void 0);
+					if (this.finalizationError.code !== void 0) 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.terminalHookCalled = true;
+					await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
+						finishReason: this.lastFinishReason,
+						duration: Date.now() - this.streamStartTime,
+						content: this.accumulatedContent,
+						usage: this.finishedEvent?.usage
+					});
+				}
 			}
 		} catch (error) {
 			if (error instanceof Error && error.name === "InterruptReplaySignal" && "continuationRunId" in error && typeof error.continuationRunId === "string") {
@@ -453,6 +459,7 @@ var TextEngine = class {
 		this.currentThinkingContent = "";
 		this.currentThinkingSignature = "";
 		this.finishedEvent = null;
+		this.streamedToolErrorResults.clear();
 		this.middlewareCtx.currentMessageId = this.currentMessageId;
 		this.middlewareCtx.accumulatedContent = "";
 		await this.middlewareRunner.runOnIteration(this.middlewareCtx, {
@@ -498,7 +505,32 @@ var TextEngine = class {
 			if (this.isCancelled()) break;
 			this.totalChunkCount++;
 			this.handleStreamChunk(chunk);
-			if (this.finalStructuredOutput?.nativeCombined === true && this.finalStructuredOutput.yieldChunks && !this.combinedStartEmitted && chunk.type === EventType.TEXT_MESSAGE_START) {
+			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 = 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) {
 				this.combinedStartEmitted = true;
 				const messageId = typeof chunk.messageId === "string" && chunk.messageId !== "" ? chunk.messageId : generateMessageId();
 				this.combinedStructuredMessageId = messageId;
@@ -517,7 +549,7 @@ var TextEngine = class {
 					this.middlewareCtx.chunkIndex++;
 				}
 			}
-			const outputChunks = await this.middlewareRunner.runOnChunk(this.middlewareCtx, chunk);
+			const outputChunks = await this.middlewareRunner.runOnChunk(this.middlewareCtx, outboundChunk);
 			const suppressAgentLifecycle = !!this.finalStructuredOutput && this.finalStructuredOutput.yieldChunks && this.finalStructuredOutput.nativeCombined !== true;
 			for (const outputChunk of outputChunks) {
 				if (suppressAgentLifecycle && (outputChunk.type === EventType.RUN_STARTED || outputChunk.type === EventType.RUN_FINISHED)) continue;
@@ -561,16 +593,7 @@ var TextEngine = class {
 			case "STEP_STARTED":
 				this.handleStepStartedEvent();
 				break;
-			case "STEP_FINISHED":
-				this.handleStepFinishedEvent(chunk);
-				break;
-			case "TOOL_CALL_RESULT": break;
-			case "REASONING_START":
-			case "REASONING_MESSAGE_START":
-			case "REASONING_MESSAGE_CONTENT":
-			case "REASONING_MESSAGE_END":
-			case "REASONING_END": break;
-			default: break;
+			case "STEP_FINISHED": this.handleStepFinishedEvent(chunk);
 		}
 	}
 	handleTextMessageContentEvent(chunk) {
@@ -595,13 +618,30 @@ var TextEngine = class {
 	}
 	handleToolCallEndEvent(chunk) {
 		this.toolCallManager.completeToolCall(chunk);
+		if (chunk.state !== "output-error" || chunk.result === void 0) return;
+		const toolCall = this.toolCallManager.getToolCalls().find((candidate) => candidate.id === chunk.toolCallId);
+		if (!toolCall) return;
+		this.streamedToolErrorResults.set(chunk.toolCallId, {
+			toolCallId: chunk.toolCallId,
+			toolName: toolCall.function.name,
+			result: chunk.result,
+			...chunk.input !== void 0 && { input: chunk.input },
+			state: "output-error"
+		});
 	}
 	handleRunFinishedEvent(chunk) {
 		this.finishedEvent = chunk;
 		this.lastFinishReason = chunk.finishReason ?? null;
 	}
-	handleRunErrorEvent(_chunk) {
+	handleRunErrorEvent(chunk) {
 		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 !== void 0 ? { code: chunk.code } : chunk.error?.code !== void 0 ? { code: chunk.error.code } : {}
+			};
+		}
 	}
 	finalizeCurrentThinkingStep() {
 		if (this.currentThinkingContent) {
@@ -723,6 +763,7 @@ var TextEngine = class {
 		this.addAssistantToolCallMessage(toolCalls);
 		const undiscoveredLazyResults = [];
 		const executableToolCalls = toolCalls.filter((tc) => {
+			if (this.streamedToolErrorResults.has(tc.id)) return false;
 			if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
 				undiscoveredLazyResults.push({
 					toolCallId: tc.id,
@@ -734,7 +775,7 @@ var TextEngine = class {
 			}
 			return true;
 		});
-		const deferredErrorResults = [...undiscoveredLazyResults];
+		const deferredErrorResults = [...this.streamedToolErrorResults.values(), ...undiscoveredLazyResults];
 		if (executableToolCalls.length === 0) {
 			yield* this.flushDeferredToolCallRunFinishedChunks();
 			if (deferredErrorResults.length > 0) for (const chunk of this.buildToolResultChunks(deferredErrorResults, finishEvent)) yield* this.pipeThroughMiddleware(chunk);
@@ -940,7 +981,7 @@ var TextEngine = class {
 		const messages = this.messages.map((message, index) => {
 			const content = typeof message.content === "string" ? message.content : message.content === null ? void 0 : 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 !== void 0 ? { content } : {},
 				..."toolCalls" in message && message.toolCalls ? { toolCalls: message.toolCalls } : {},
@@ -1372,7 +1413,7 @@ var TextEngine = class {
 			if (c.type === EventType.TEXT_MESSAGE_START || c.type === EventType.TEXT_MESSAGE_CONTENT || c.type === EventType.TEXT_MESSAGE_END) return typeof c.messageId === "string" && c.messageId !== "" ? c.messageId : null;
 			return null;
 		};
-		const buildSynthesizedStart = () => {
+		const buildSynthesizedStart = (timestamp = Date.now()) => {
 			const idForStart = structuredMessageId ?? generateMessageId();
 			structuredMessageId = idForStart;
 			return {
@@ -1380,7 +1421,7 @@ var TextEngine = class {
 				name: "structured-output.start",
 				value: { messageId: idForStart },
 				model: this.params.model,
-				timestamp: Date.now(),
+				timestamp,
 				threadId: this.threadId,
 				...this.runIdOverride ? { runId: this.runIdOverride } : {}
 			};
@@ -1397,7 +1438,7 @@ var TextEngine = class {
 			if (this.finalStructuredOutput.yieldChunks) {
 				if (!startEmitted && (chunk.type === EventType.TEXT_MESSAGE_START || chunk.type === EventType.TEXT_MESSAGE_CONTENT || chunk.type === EventType.TEXT_MESSAGE_END)) {
 					startEmitted = true;
-					const synthOutputs = await pipeThroughMiddleware(buildSynthesizedStart());
+					const synthOutputs = await pipeThroughMiddleware(buildSynthesizedStart(chunk.timestamp));
 					for (const outputChunk of synthOutputs) {
 						yield outputChunk;
 						this.middlewareCtx.chunkIndex++;
@@ -1405,7 +1446,7 @@ var TextEngine = class {
 				}
 				if (!startEmitted && chunk.type === EventType.RUN_ERROR) {
 					startEmitted = true;
-					const synthOutputs = await pipeThroughMiddleware(buildSynthesizedStart());
+					const synthOutputs = await pipeThroughMiddleware(buildSynthesizedStart(chunk.timestamp));
 					for (const outputChunk of synthOutputs) {
 						yield outputChunk;
 						this.middlewareCtx.chunkIndex++;
@@ -1511,25 +1552,32 @@ var TextEngine = class {
 	async *harvestCombinedStructuredOutput() {
 		if (!this.finalStructuredOutput) throw new Error("harvestCombinedStructuredOutput called without finalStructuredOutput config");
 		const yieldChunks = this.finalStructuredOutput.yieldChunks;
-		const rawText = this.accumulatedContent;
-		if (rawText.length === 0) this.finalizationError = {
-			message: "missing structured result",
-			code: "structured-output-missing-result"
-		};
-		else try {
-			const parsed = JSON.parse(rawText);
-			const data = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed) : parsed;
-			this.structuredOutputResult = {
-				data,
-				rawText
+		if ((this.finalStructuredOutput.source ?? "text") === "event") {
+			if (!this.structuredOutputResult) this.finalizationError = {
+				message: "missing structured result",
+				code: "structured-output-missing-result"
 			};
-		} catch (err) {
-			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
+		} else {
+			const rawText = this.accumulatedContent;
+			if (rawText.length === 0) this.finalizationError = {
+				message: "missing structured result",
+				code: "structured-output-missing-result"
 			};
+			else try {
+				const parsed = JSON.parse(rawText);
+				const data = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed) : parsed;
+				this.structuredOutputResult = {
+					data,
+					rawText
+				};
+			} catch (err) {
+				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
+				};
+			}
 		}
 		if (this.structuredOutputResult && !this.finalizationError && this.finalStructuredOutput.validate) try {
 			const validated = this.finalStructuredOutput.validate(this.structuredOutputResult.data);
@@ -1563,7 +1611,7 @@ var TextEngine = class {
 				this.middlewareCtx.chunkIndex++;
 			}
 		}
-		if (this.structuredOutputResult && !this.finalizationError) {
+		if (this.structuredOutputResult && !this.finalizationError && !this.combinedCompleteEmitted) {
 			const completeChunk = {
 				type: EventType.CUSTOM,
 				name: "structured-output.complete",
@@ -1911,7 +1959,8 @@ async function* streamTextChunks(options, engineRef) {
 * Runs the full agentic loop (if tools are provided) but returns collected text.
 */
 function runNonStreamingText(options) {
-	return streamToText(runStreamingText(options));
+	const stream = runStreamingText(options);
+	return streamToText(stream);
 }
 /**
 * Run agentic structured output:
@@ -1929,6 +1978,7 @@ async function runAgenticStructuredOutput(options) {
 	const normalize = (data) => undoNullWidening(data, nullWideningMap);
 	const validate = isStandardSchema(outputSchema) ? (data) => parseWithStandardSchema(outputSchema, data) : void 0;
 	const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true;
+	const source = adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? "text";
 	const mcpManager = MCPManager.from(mcp);
 	const mcpTools = await mcpManager.discover();
 	if (mcpTools.length > 0) textOptions.tools = [...textOptions.tools ?? [], ...mcpTools];
@@ -1946,7 +1996,8 @@ async function runAgenticStructuredOutput(options) {
 			yieldChunks: false,
 			normalize,
 			...validate ? { validate } : {},
-			...nativeCombined ? { nativeCombined: true } : {}
+			...nativeCombined ? { nativeCombined: true } : {},
+			source
 		}
 	}, logger);
 	try {
@@ -2007,13 +2058,13 @@ async function* fallbackStructuredOutputStream(adapter, options, onAdapterError)
 	const threadId = 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;
 	try {
@@ -2026,7 +2077,7 @@ async function* fallbackStructuredOutputStream(adapter, options, onAdapterError)
 			runId,
 			threadId,
 			model,
-			timestamp,
+			timestamp: Date.now(),
 			message,
 			error: { message }
 		};
@@ -2037,20 +2088,20 @@ async function* fallbackStructuredOutputStream(adapter, options, onAdapterError)
 		messageId,
 		role: "assistant",
 		model,
-		timestamp
+		timestamp: Date.now()
 	};
 	yield {
 		type: EventType.TEXT_MESSAGE_CONTENT,
 		messageId,
 		delta: result.rawText,
 		model,
-		timestamp
+		timestamp: Date.now()
 	};
 	yield {
 		type: EventType.TEXT_MESSAGE_END,
 		messageId,
 		model,
-		timestamp
+		timestamp: Date.now()
 	};
 	yield {
 		type: EventType.CUSTOM,
@@ -2060,14 +2111,14 @@ async function* fallbackStructuredOutputStream(adapter, options, onAdapterError)
 			raw: result.rawText
 		},
 		model,
-		timestamp
+		timestamp: Date.now()
 	};
 	yield {
 		type: EventType.RUN_FINISHED,
 		runId,
 		threadId,
 		model,
-		timestamp,
+		timestamp: Date.now(),
 		finishReason: "stop",
 		...result.usage ? { usage: result.usage } : {}
 	};
@@ -2115,6 +2166,7 @@ async function* runStreamingStructuredOutputImpl(options, jsonSchema, normalize,
 	const model = adapter.model;
 	const logger = resolveDebugOption(debug);
 	const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true;
+	const source = adapter.combinedStructuredOutputSource?.(options.modelOptions) ?? "text";
 	const mcpManager = MCPManager.from(mcp);
 	const mcpTools = await mcpManager.discover();
 	if (mcpTools.length > 0) textOptions.tools = [...textOptions.tools ?? [], ...mcpTools];
@@ -2131,7 +2183,8 @@ async function* runStreamingStructuredOutputImpl(options, jsonSchema, normalize,
 			jsonSchema,
 			yieldChunks: true,
 			normalize,
-			...nativeCombined ? { nativeCombined: true } : {}
+			...nativeCombined ? { nativeCombined: true } : {},
+			source
 		}
 	}, logger);
 	engineRef.current = engine;