@tanstack/ai 0.21.3 → 0.22.0

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

@@ -95,6 +95,26 @@ export interface TextAdapter<TModel extends string, TProviderOptions extends Rec
      * `{ object, raw, reasoning? }`.
      */
     structuredOutputStream?: (options: StructuredOutputOptions<TProviderOptions>) => AsyncIterable<StreamChunk>;
+    /**
+     * Declares whether the adapter supports combining `tools` and a
+     * schema-constrained final answer in a single streaming request.
+     *
+     * When `true`, the engine wires `outputSchema` into the regular
+     * `chatStream()` call and skips the separate `runStructuredFinalization`
+     * round-trip. The model's natural final turn carries the
+     * schema-constrained JSON text and the engine harvests it from the agent
+     * loop's accumulated content.
+     *
+     * When `false`, `undefined`, or the method is omitted, the engine runs
+     * the agent loop without `outputSchema` and then issues a separate
+     * `structuredOutput` / `structuredOutputStream` call against the JSON
+     * schema for finalization (the legacy path).
+     *
+     * The method receives the per-call `modelOptions` so providers whose
+     * support depends on the resolved upstream model (e.g. OpenRouter) can
+     * answer per-request. Most adapters can return a constant.
+     */
+    supportsCombinedToolsAndSchema?: (modelOptions?: TProviderOptions | undefined) => boolean;
 }
 /**
  * A TextAdapter with any/unknown type parameters.

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n} from '../../types'\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}\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   * @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/**\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\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"],"names":[],"mappings":"AA2IO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;AAAA,EAEV,YAAY,SAA4B,CAAA,GAAI,OAAe;AACzD,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAcU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}
+{"version":3,"file":"adapter.js","sources":["../../../../src/activities/chat/adapter.ts"],"sourcesContent":["import type {\n  DefaultMessageMetadataByModality,\n  JSONSchema,\n  Modality,\n  StreamChunk,\n  TextOptions,\n} from '../../types'\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}\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   * @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\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"],"names":[],"mappings":"AAkKO,MAAe,gBAgBpB;AAAA,EACS,OAAO;AAAA,EAEP;AAAA,EAYC;AAAA,EAEV,YAAY,SAA4B,CAAA,GAAI,OAAe;AACzD,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAcU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}

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

@@ -59,6 +59,16 @@ class TextEngine {
   logger;
   // Structured-output finalization state (populated by runStructuredFinalization)
   structuredOutputResult = null;
+  // Native combined mode: tracks whether we've already emitted the synthetic
+  // `structured-output.start` event before the schema-constrained final-turn
+  // text begins streaming. The event must precede the first
+  // TEXT_MESSAGE_START so the client-side StreamProcessor routes the JSON
+  // deltas into a StructuredOutputPart instead of a plain TextPart.
+  combinedStartEmitted = false;
+  // Native combined mode: messageId we want the synthetic
+  // `structured-output.start` (and any error emitted before deltas arrive)
+  // to carry, so the client matches it to the streaming text deltas.
+  combinedStructuredMessageId = null;
   // Holds the validated value when `finalStructuredOutput.validate` is provided
   // and succeeds. Distinct from `structuredOutputResult.data` (the raw,
   // unvalidated payload from the structured-output.complete chunk).
@@ -184,7 +194,7 @@ class TextEngine {
       if (pendingPhase === "wait") {
         return;
       }
-      const skipAgentLoop = !!this.finalStructuredOutput && this.tools.length === 0;
+      const skipAgentLoop = !!this.finalStructuredOutput && this.tools.length === 0 && this.finalStructuredOutput.nativeCombined !== true;
       if (!skipAgentLoop) {
         do {
           if (this.earlyTermination || this.isCancelled()) {
@@ -198,11 +208,11 @@ class TextEngine {
             this.middlewareCtx.phase = "beforeModel";
             this.middlewareCtx.iteration = this.iterationCount;
             const iterConfig = this.buildMiddlewareConfig();
-            const transformedConfig2 = await this.middlewareRunner.runOnConfig(
+            const iterTransformedConfig = await this.middlewareRunner.runOnConfig(
               this.middlewareCtx,
               iterConfig
             );
-            this.applyMiddlewareConfig(transformedConfig2);
+            this.applyMiddlewareConfig(iterTransformedConfig);
             yield* this.streamModelResponse();
           } else {
             yield* this.processToolCalls();
@@ -214,7 +224,11 @@ class TextEngine {
         finishReason: this.lastFinishReason
       });
       if (this.finalStructuredOutput && !this.isCancelled() && !this.finalizationError) {
-        yield* this.runStructuredFinalization();
+        if (this.finalStructuredOutput.nativeCombined === true) {
+          yield* this.harvestCombinedStructuredOutput();
+        } else {
+          yield* this.runStructuredFinalization();
+        }
       }
       if (!this.terminalHookCalled && this.toolPhase !== "wait" && !this.isCancelled()) {
         if (this.finalizationError) {
@@ -338,6 +352,7 @@ class TextEngine {
         toolCount: this.tools.length
       }
     );
+    const combinedSchema = this.finalStructuredOutput?.nativeCombined === true ? this.finalStructuredOutput.jsonSchema : void 0;
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
       messages: this.messages,
@@ -352,18 +367,41 @@ class TextEngine {
       logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
-      parentRunId: this.parentRunIdOverride
+      parentRunId: this.parentRunIdOverride,
+      ...combinedSchema ? { outputSchema: combinedSchema } : {}
     })) {
       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) {
+        this.combinedStartEmitted = true;
+        const messageId = typeof chunk.messageId === "string" && chunk.messageId !== "" ? chunk.messageId : generateMessageId();
+        this.combinedStructuredMessageId = messageId;
+        const synthStart = {
+          type: EventType.CUSTOM,
+          name: "structured-output.start",
+          value: { messageId },
+          model: this.params.model,
+          timestamp: Date.now(),
+          threadId: this.threadId,
+          ...this.runIdOverride ? { runId: this.runIdOverride } : {}
+        };
+        const synthOutputs = await this.middlewareRunner.runOnChunk(
+          this.middlewareCtx,
+          synthStart
+        );
+        for (const outputChunk of synthOutputs) {
+          yield outputChunk;
+          this.middlewareCtx.chunkIndex++;
+        }
+      }
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
         chunk
       );
-      const suppressAgentLifecycle = !!this.finalStructuredOutput && this.finalStructuredOutput.yieldChunks;
+      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;
@@ -1145,6 +1183,137 @@ class TextEngine {
       }
     }
   }
+  /**
+   * Native combined mode: harvest the structured output from the agent
+   * loop's accumulated final-turn text (no separate provider call).
+   *
+   * The adapter wired `outputSchema` into the regular `chatStream` request,
+   * so the model's final-turn text is the schema-constrained JSON. We parse
+   * `this.accumulatedContent`, populate `this.structuredOutputResult`, emit
+   * a synthetic `structured-output.complete` (and a `structured-output.start`
+   * if one wasn't emitted earlier — only happens on the streaming path when
+   * the model returned no text at all), and run the validate callback when
+   * present. Failures populate `this.finalizationError` so the engine's
+   * terminal-hook chooser routes to `onError` (per spec §7.3).
+   *
+   * The `'structuredOutput'` middleware phase intentionally does NOT fire on
+   * this path — middleware sees the run through `beforeModel` / `modelStream`
+   * as usual. See PR #605 / issue #605 for the design rationale.
+   */
+  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);
+        this.structuredOutputResult = { data: parsed, 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
+        );
+        this.validatedStructuredOutput = validated;
+        this.hasValidatedStructuredOutput = true;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.finalizationError = {
+          message,
+          code: "structured-output-validation-failed",
+          cause: err
+        };
+      }
+    }
+    if (!yieldChunks) {
+      return;
+    }
+    if (!this.combinedStartEmitted) {
+      this.combinedStartEmitted = true;
+      const messageId = this.combinedStructuredMessageId ?? generateMessageId();
+      this.combinedStructuredMessageId = messageId;
+      const synthStart = {
+        type: EventType.CUSTOM,
+        name: "structured-output.start",
+        value: { messageId },
+        model: this.params.model,
+        timestamp: Date.now(),
+        threadId: this.threadId,
+        ...this.runIdOverride ? { runId: this.runIdOverride } : {}
+      };
+      const startOutputs = await this.middlewareRunner.runOnChunk(
+        this.middlewareCtx,
+        synthStart
+      );
+      for (const outputChunk of startOutputs) {
+        yield outputChunk;
+        this.middlewareCtx.chunkIndex++;
+      }
+    }
+    if (this.structuredOutputResult && !this.finalizationError) {
+      const completeChunk = {
+        type: EventType.CUSTOM,
+        name: "structured-output.complete",
+        value: {
+          object: this.structuredOutputResult.data,
+          raw: this.structuredOutputResult.rawText,
+          ...this.combinedStructuredMessageId ? { messageId: this.combinedStructuredMessageId } : {}
+        },
+        model: this.params.model,
+        timestamp: Date.now(),
+        threadId: this.threadId,
+        ...this.runIdOverride ? { runId: this.runIdOverride } : {}
+      };
+      const completeOutputs = await this.middlewareRunner.runOnChunk(
+        this.middlewareCtx,
+        completeChunk
+      );
+      for (const outputChunk of completeOutputs) {
+        yield outputChunk;
+        this.middlewareCtx.chunkIndex++;
+      }
+    }
+    if (this.finalizationError) {
+      const errChunk = {
+        type: EventType.RUN_ERROR,
+        runId: this.runIdOverride ?? this.requestId,
+        model: this.params.model,
+        timestamp: Date.now(),
+        threadId: this.threadId,
+        message: this.finalizationError.message,
+        ...this.finalizationError.code ? { code: this.finalizationError.code } : {},
+        error: {
+          message: this.finalizationError.message,
+          ...this.finalizationError.code ? { code: this.finalizationError.code } : {}
+        }
+      };
+      const errOutputs = await this.middlewareRunner.runOnChunk(
+        this.middlewareCtx,
+        errChunk
+      );
+      for (const outputChunk of errOutputs) {
+        yield outputChunk;
+        this.middlewareCtx.chunkIndex++;
+      }
+    }
+  }
   buildMiddlewareConfig() {
     return {
       messages: this.messages,
@@ -1283,6 +1452,7 @@ async function runAgenticStructuredOutput(options) {
     throw new Error("Failed to convert output schema to JSON Schema");
   }
   const validate = isStandardSchema(outputSchema) ? (data) => parseWithStandardSchema(outputSchema, data) : void 0;
+  const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true;
   const engine = new TextEngine(
     {
       adapter,
@@ -1292,7 +1462,8 @@ async function runAgenticStructuredOutput(options) {
       finalStructuredOutput: {
         jsonSchema,
         yieldChunks: false,
-        ...validate ? { validate } : {}
+        ...validate ? { validate } : {},
+        ...nativeCombined ? { nativeCombined: true } : {}
       }
     },
     logger
@@ -1424,13 +1595,18 @@ async function* runStreamingStructuredOutputImpl(options, jsonSchema) {
   const { adapter, outputSchema, middleware, context, debug, ...textOptions } = options;
   const model = adapter.model;
   const logger = resolveDebugOption(debug);
+  const nativeCombined = adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true;
   const engine = new TextEngine(
     {
       adapter,
       params: { ...textOptions, model, logger },
       middleware,
       context,
-      finalStructuredOutput: { jsonSchema, yieldChunks: true }
+      finalStructuredOutput: {
+        jsonSchema,
+        yieldChunks: true,
+        ...nativeCombined ? { nativeCombined: true } : {}
+      }
     },
     logger
   );