@tanstack/ai 0.44.1 → 0.45.0

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

@@ -187,6 +187,7 @@ var TextEngine = class {
 	validatedStructuredOutput = void 0;
 	hasValidatedStructuredOutput = false;
 	finalizationError = null;
+	combinedCompleteEmitted = false;
 	finalStructuredOutput;
 	constructor(config, logger) {
 		this.logger = logger;
@@ -336,27 +337,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") {
@@ -498,7 +503,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 +547,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 +591,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) {
@@ -600,8 +621,15 @@ var TextEngine = class {
 		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) {
@@ -940,7 +968,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 +1400,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 +1408,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 +1425,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 +1433,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 +1539,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 +1598,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 +1946,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 +1965,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 +1983,8 @@ async function runAgenticStructuredOutput(options) {
 			yieldChunks: false,
 			normalize,
 			...validate ? { validate } : {},
-			...nativeCombined ? { nativeCombined: true } : {}
+			...nativeCombined ? { nativeCombined: true } : {},
+			source
 		}
 	}, logger);
 	try {
@@ -2007,13 +2045,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 +2064,7 @@ async function* fallbackStructuredOutputStream(adapter, options, onAdapterError)
 			runId,
 			threadId,
 			model,
-			timestamp,
+			timestamp: Date.now(),
 			message,
 			error: { message }
 		};
@@ -2037,20 +2075,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 +2098,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 +2153,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 +2170,8 @@ async function* runStreamingStructuredOutputImpl(options, jsonSchema, normalize,
 			jsonSchema,
 			yieldChunks: true,
 			normalize,
-			...nativeCombined ? { nativeCombined: true } : {}
+			...nativeCombined ? { nativeCombined: true } : {},
+			source
 		}
 	}, logger);
 	engineRef.current = engine;