@tanstack/ai 0.21.3 → 0.22.1

package/src/activities/chat/index.ts

@@ -312,11 +312,20 @@ interface TextEngineConfig<
    *   as the validated result and retrievable via
    *   `getValidatedStructuredOutput()`. Used by `runAgenticStructuredOutput`
    *   to perform Standard Schema validation inside the engine.
+   * - nativeCombined: when true, the adapter declared
+   *   `supportsCombinedToolsAndSchema()` and the engine wires `jsonSchema`
+   *   into the regular `chatStream` call instead of running a separate
+   *   finalization round-trip. The agent loop's final-turn text is the
+   *   schema-constrained JSON; the engine parses it from accumulated
+   *   content. The `'structuredOutput'` middleware phase does NOT fire on
+   *   this path — middleware sees the run through `beforeModel` /
+   *   `modelStream` as usual.
    */
   finalStructuredOutput?: {
     jsonSchema: JSONSchema
     yieldChunks: boolean
     validate?: (data: unknown) => unknown
+    nativeCombined?: boolean
   }
 }
 
@@ -379,6 +388,16 @@ class TextEngine<
   // Structured-output finalization state (populated by runStructuredFinalization)
   private structuredOutputResult: { data: unknown; rawText: string } | null =
     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.
+  private 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.
+  private combinedStructuredMessageId: string | null = 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).
@@ -393,6 +412,7 @@ class TextEngine<
     jsonSchema: JSONSchema
     yieldChunks: boolean
     validate?: (data: unknown) => unknown
+    nativeCombined?: boolean
   }
 
   constructor(
@@ -461,6 +481,7 @@ class TextEngine<
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
+      runId: this.runIdOverride ?? this.requestId,
       threadId: this.threadId,
       // Legacy alias kept on the ctx so middleware that reads
       // `ctx.conversationId` keeps working. Always equals `threadId`.
@@ -560,12 +581,19 @@ class TextEngine<
         return
       }
 
-      // Skip the agent loop entirely when there are no tools AND a structured-
-      // output finalization will run. Without tools the model has nothing to
-      // do in the loop, so executing one iteration would burn an extra
-      // provider call before the finalization request.
+      // Skip the agent loop entirely when there are no tools AND a separate
+      // structured-output finalization will run. Without tools the model has
+      // nothing to do in the loop, so executing one iteration would burn an
+      // extra provider call before the finalization request.
+      //
+      // Native combined mode does NOT skip — the agent loop itself produces
+      // the schema-constrained final answer in one pass (model emits the
+      // schema-constrained text on its natural final turn). Even with zero
+      // tools, the single chatStream call IS the structured-output call.
       const skipAgentLoop =
-        !!this.finalStructuredOutput && this.tools.length === 0
+        !!this.finalStructuredOutput &&
+        this.tools.length === 0 &&
+        this.finalStructuredOutput.nativeCombined !== true
 
       if (!skipAgentLoop) {
         do {
@@ -584,11 +612,12 @@ class TextEngine<
             this.middlewareCtx.phase = 'beforeModel'
             this.middlewareCtx.iteration = this.iterationCount
             const iterConfig = this.buildMiddlewareConfig()
-            const transformedConfig = await this.middlewareRunner.runOnConfig(
-              this.middlewareCtx,
-              iterConfig,
-            )
-            this.applyMiddlewareConfig(transformedConfig)
+            const iterTransformedConfig =
+              await this.middlewareRunner.runOnConfig(
+                this.middlewareCtx,
+                iterConfig,
+              )
+            this.applyMiddlewareConfig(iterTransformedConfig)
 
             yield* this.streamModelResponse()
           } else {
@@ -607,12 +636,20 @@ class TextEngine<
       // requested AND the run hasn't already errored/aborted, run it through
       // the middleware pipeline. The terminal hook fires once at the very
       // end (after finalization), not after the agent loop.
+      //
+      // Native combined mode takes a different path: the agent loop's final-
+      // turn text IS the schema-constrained JSON, so we harvest it from
+      // `accumulatedContent` instead of issuing a second provider call.
       if (
         this.finalStructuredOutput &&
         !this.isCancelled() &&
         !this.finalizationError
       ) {
-        yield* this.runStructuredFinalization()
+        if (this.finalStructuredOutput.nativeCombined === true) {
+          yield* this.harvestCombinedStructuredOutput()
+        } else {
+          yield* this.runStructuredFinalization()
+        }
       }
 
       // Call terminal hook (skip when waiting for client — stream is paused, not finished).
@@ -777,6 +814,18 @@ class TextEngine<
       },
     )
 
+    // When the adapter declared `supportsCombinedToolsAndSchema()`, the
+    // activity layer set `nativeCombined: true` and we forward the
+    // pre-converted JSON Schema into the regular chatStream call. The
+    // adapter wires it into the upstream request (e.g. `response_format`,
+    // `text.format`, `output_format`) so the model's final-turn text is
+    // schema-constrained and the engine can harvest it from the agent loop
+    // without a separate finalization round-trip.
+    const combinedSchema =
+      this.finalStructuredOutput?.nativeCombined === true
+        ? this.finalStructuredOutput.jsonSchema
+        : undefined
+
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
       messages: this.messages,
@@ -792,6 +841,7 @@ class TextEngine<
       threadId: this.threadId,
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
+      ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
         break
@@ -803,6 +853,44 @@ class TextEngine<
       // BEFORE middleware, so fields like finishReason, delta, etc. are available
       this.handleStreamChunk(chunk)
 
+      // Native combined mode: synthesize `structured-output.start` BEFORE
+      // the first TEXT_MESSAGE_START so the client-side StreamProcessor
+      // routes the schema-constrained JSON deltas into a
+      // StructuredOutputPart. We delay synthesis until we actually see
+      // text starting — intermediate tool-call iterations don't need it,
+      // and emitting at run-start would wrap tool-call commentary into a
+      // structured-output part too.
+      if (
+        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: StreamChunk = {
+          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++
+        }
+      }
+
       // Pipe chunk through middleware (devtools middleware observes; strip-to-spec cleans)
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
@@ -812,8 +900,13 @@ class TextEngine<
       // the agent loop, suppress the agent-loop's RUN_STARTED/RUN_FINISHED
       // here — the finalization step emits the single outer lifecycle pair
       // that reaches the consumer.
+      //
+      // Native combined mode does NOT issue a second adapter stream — the
+      // agent loop's lifecycle IS the outer pair the consumer sees.
       const suppressAgentLifecycle =
-        !!this.finalStructuredOutput && this.finalStructuredOutput.yieldChunks
+        !!this.finalStructuredOutput &&
+        this.finalStructuredOutput.yieldChunks &&
+        this.finalStructuredOutput.nativeCombined !== true
       for (const outputChunk of outputChunks) {
         if (
           suppressAgentLifecycle &&
@@ -1948,6 +2041,179 @@ 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.
+   */
+  private async *harvestCombinedStructuredOutput(): AsyncGenerator<StreamChunk> {
+    if (!this.finalStructuredOutput) {
+      throw new Error(
+        'harvestCombinedStructuredOutput called without finalStructuredOutput config',
+      )
+    }
+
+    const yieldChunks = this.finalStructuredOutput.yieldChunks
+    const rawText = this.accumulatedContent
+
+    // Empty final-turn text means the agent loop terminated without the
+    // model emitting any assistant content (e.g. early termination after
+    // tool calls). Mirror the fallback path's "missing structured result"
+    // error rather than silently returning undefined.
+    if (rawText.length === 0) {
+      this.finalizationError = {
+        message: 'missing structured result',
+        code: 'structured-output-missing-result',
+      }
+    } else {
+      try {
+        const parsed: unknown = JSON.parse(rawText)
+        this.structuredOutputResult = { data: parsed, rawText }
+      } catch (err: unknown) {
+        const detail =
+          rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
+        this.finalizationError = {
+          message: `Failed to parse structured output as JSON. Content: ${detail}`,
+          code: 'structured-output-parse-failed',
+          cause: err,
+        }
+      }
+    }
+
+    // Validate against the Standard Schema (when supplied). Validation
+    // failures route through onError just like the fallback path.
+    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: unknown) {
+        const message = err instanceof Error ? err.message : String(err)
+        this.finalizationError = {
+          message,
+          code: 'structured-output-validation-failed',
+          cause: err,
+        }
+      }
+    }
+
+    if (!yieldChunks) {
+      // Promise<T> path: state is populated, nothing to yield. The
+      // activity-layer caller pulls `structuredOutputResult` /
+      // `validatedStructuredOutput` directly.
+      return
+    }
+
+    // Streaming path: emit a synthetic `structured-output.start` if the
+    // model produced no text at all (so the client snaps an errored
+    // StructuredOutputPart rather than nothing). The normal path already
+    // emitted start before the first TEXT_MESSAGE_START in
+    // `streamModelResponse`.
+    if (!this.combinedStartEmitted) {
+      this.combinedStartEmitted = true
+      const messageId = this.combinedStructuredMessageId ?? generateMessageId()
+      this.combinedStructuredMessageId = messageId
+      const synthStart: StreamChunk = {
+        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++
+      }
+    }
+
+    // On success, emit the synthetic `structured-output.complete` carrying
+    // the parsed object + raw text. Pin the messageId so the client-side
+    // handler can target the right UIMessage even when the agent loop's
+    // terminal RUN_FINISHED has already cleared `activeMessageIds` (the
+    // complete event yields AFTER the loop ends, by which point
+    // `getActiveAssistantMessageId()` returns null and would otherwise drop
+    // the event silently).
+    if (this.structuredOutputResult && !this.finalizationError) {
+      const completeChunk: StreamChunk = {
+        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++
+      }
+    }
+
+    // On failure, emit a synthetic RUN_ERROR so the streaming consumer's
+    // `for await` doesn't end silently. Mirrors the fallback path.
+    if (this.finalizationError) {
+      const errChunk: StreamChunk = {
+        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++
+      }
+    }
+  }
+
   private buildMiddlewareConfig(): ChatMiddlewareConfig {
     return {
       messages: this.messages,
@@ -2243,6 +2509,13 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
         parseWithStandardSchema<InferSchemaType<TSchema>>(outputSchema, data)
     : undefined
 
+  // Per issue #605: same capability check as the streaming path. When the
+  // adapter handles tools + schema natively, the engine skips the separate
+  // structured-output finalization call and harvests the JSON from the
+  // agent loop's accumulated final-turn text.
+  const nativeCombined =
+    adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+
   const engine = new TextEngine(
     {
       adapter,
@@ -2256,6 +2529,7 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
         jsonSchema,
         yieldChunks: false,
         ...(validate ? { validate } : {}),
+        ...(nativeCombined ? { nativeCombined: true } : {}),
       },
     },
     logger,
@@ -2493,6 +2767,16 @@ async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
+  // Per issue #605: adapters that natively combine tools + schema-constrained
+  // output in one streaming call (modern OpenAI, Anthropic 4.5+, Gemini 3+,
+  // Grok 4+) opt in via `supportsCombinedToolsAndSchema()`. The engine then
+  // forwards the schema into the regular `chatStream` call and harvests the
+  // structured result from the agent loop's accumulated text — no separate
+  // finalization round-trip, and the `'structuredOutput'` middleware phase
+  // does not fire.
+  const nativeCombined =
+    adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
+
   // Inputs may be UIMessages (from useChat) or ModelMessages (from server-side
   // callers). TextEngine handles the conversion uniformly.
   const engine = new TextEngine(
@@ -2504,7 +2788,11 @@ async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
       >,
       middleware,
       context,
-      finalStructuredOutput: { jsonSchema, yieldChunks: true },
+      finalStructuredOutput: {
+        jsonSchema,
+        yieldChunks: true,
+        ...(nativeCombined ? { nativeCombined: true } : {}),
+      },
     },
     logger,
   )

package/src/activities/chat/middleware/types.ts

@@ -38,6 +38,8 @@ export interface ChatMiddlewareContext {
   requestId: string
   /** Unique identifier for this stream */
   streamId: string
+  /** AG-UI run identifier for correlating client and server events */
+  runId: string
   /**
    * AG-UI thread identifier — a stable per-conversation ID used to
    * correlate client and server devtools events. Resolves to the

package/src/activities/chat/stream/processor.ts

@@ -98,6 +98,17 @@ export interface StreamProcessorEvents {
     stepId: string,
     content: string,
   ) => void
+  onStructuredOutputChange?: (args: {
+    phase: 'start' | 'update' | 'complete' | 'error'
+    messageId: string
+    status: 'streaming' | 'complete' | 'error'
+    raw: string
+    partial?: unknown
+    data?: unknown
+    reasoning?: string
+    errorMessage?: string
+    delta?: string
+  }) => void
 }
 
 /**
@@ -116,6 +127,8 @@ export interface StreamProcessorOptions {
   initialMessages?: Array<UIMessage>
 }
 
+const STRUCTURED_OUTPUT_UPDATE_BATCH_SIZE = 12
+
 /**
  * StreamProcessor - State machine for processing AI response streams
  *
@@ -149,6 +162,13 @@ export class StreamProcessor {
   private pendingThinkingStepId: string | null = null
 
   private readonly structuredMessageIds: Set<string> = new Set()
+  private readonly structuredOutputUpdateBatches = new Map<
+    string,
+    {
+      delta: string
+      chunkCount: number
+    }
+  >()
 
   // Run tracking (for concurrent run safety)
   private readonly activeRuns = new Set<string>()
@@ -401,6 +421,9 @@ export class StreamProcessor {
     for (const id of this.structuredMessageIds) {
       if (!keptIds.has(id)) this.structuredMessageIds.delete(id)
     }
+    for (const id of this.structuredOutputUpdateBatches.keys()) {
+      if (!keptIds.has(id)) this.structuredOutputUpdateBatches.delete(id)
+    }
     for (const id of this.messageStates.keys()) {
       if (!keptIds.has(id)) this.messageStates.delete(id)
     }
@@ -423,6 +446,7 @@ export class StreamProcessor {
     this.activeMessageIds.clear()
     this.toolCallToMessage.clear()
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
     this.pendingManualMessageId = null
     this.emitMessagesChange()
   }
@@ -899,6 +923,7 @@ export class StreamProcessor {
           delta,
         )
         state.totalTextContent += delta
+        this.queueStructuredOutputUpdate(messageId, delta)
         this.emitMessagesChange()
       }
       return
@@ -1269,12 +1294,14 @@ export class StreamProcessor {
     }
 
     if (this.structuredMessageIds.has(messageId)) {
+      this.flushStructuredOutputUpdate(messageId)
       this.messages = errorStructuredOutputPart(
         this.messages,
         messageId,
         errorMessage,
       )
       this.structuredMessageIds.delete(messageId)
+      this.emitStructuredOutputChange(messageId, 'error')
       this.emitMessagesChange()
     }
 
@@ -1463,6 +1490,13 @@ export class StreamProcessor {
       if (targetId) {
         this.ensureAssistantMessage(targetId)
         this.structuredMessageIds.add(targetId)
+        this.structuredOutputUpdateBatches.delete(targetId)
+        this.events.onStructuredOutputChange?.({
+          phase: 'start',
+          messageId: targetId,
+          status: 'streaming',
+          raw: '',
+        })
       }
       return
     }
@@ -1476,6 +1510,7 @@ export class StreamProcessor {
       }
       const targetId = v.messageId ?? messageId
       if (targetId) {
+        this.flushStructuredOutputUpdate(targetId)
         this.messages = completeStructuredOutputPart(
           this.messages,
           targetId,
@@ -1484,6 +1519,7 @@ export class StreamProcessor {
           v.reasoning,
         )
         this.structuredMessageIds.delete(targetId)
+        this.emitStructuredOutputChange(targetId, 'complete')
         this.emitMessagesChange()
       }
       // Fall through so user `onCustomEvent` callbacks still observe the event.
@@ -1665,6 +1701,58 @@ export class StreamProcessor {
     this.events.onTextUpdate?.(messageId, state.currentSegmentText)
   }
 
+  private queueStructuredOutputUpdate(messageId: string, delta: string): void {
+    const existing = this.structuredOutputUpdateBatches.get(messageId)
+    const next = {
+      delta: `${existing?.delta ?? ''}${delta}`,
+      chunkCount: (existing?.chunkCount ?? 0) + 1,
+    }
+
+    this.structuredOutputUpdateBatches.set(messageId, next)
+
+    if (next.chunkCount >= STRUCTURED_OUTPUT_UPDATE_BATCH_SIZE) {
+      this.flushStructuredOutputUpdate(messageId)
+    }
+  }
+
+  private flushStructuredOutputUpdate(messageId: string): void {
+    const batch = this.structuredOutputUpdateBatches.get(messageId)
+    if (!batch || batch.chunkCount === 0) return
+
+    this.structuredOutputUpdateBatches.delete(messageId)
+    this.emitStructuredOutputChange(messageId, 'update', batch.delta)
+  }
+
+  private emitStructuredOutputChange(
+    messageId: string,
+    phase: 'update' | 'complete' | 'error',
+    delta?: string,
+  ): void {
+    const part = this.messages
+      .find((message) => message.id === messageId)
+      ?.parts.find(
+        (
+          messagePart,
+        ): messagePart is Extract<MessagePart, { type: 'structured-output' }> =>
+          messagePart.type === 'structured-output',
+      )
+    if (!part) return
+
+    this.events.onStructuredOutputChange?.({
+      phase,
+      messageId,
+      status: part.status,
+      raw: part.raw,
+      ...(part.partial !== undefined ? { partial: part.partial } : {}),
+      ...(part.data !== undefined ? { data: part.data } : {}),
+      ...(part.reasoning !== undefined ? { reasoning: part.reasoning } : {}),
+      ...(part.errorMessage !== undefined
+        ? { errorMessage: part.errorMessage }
+        : {}),
+      ...(delta !== undefined ? { delta } : {}),
+    })
+  }
+
   /**
    * Emit messages change event
    */
@@ -1718,13 +1806,16 @@ export class StreamProcessor {
     // definition a non-errored, never-completed run (the multi-run case:
     // run-A errors, run-B is still streaming when finalize fires).
     for (const messageId of this.structuredMessageIds) {
+      this.flushStructuredOutputUpdate(messageId)
       this.messages = errorStructuredOutputPart(
         this.messages,
         messageId,
         'Stream ended without structured-output.complete',
       )
+      this.emitStructuredOutputChange(messageId, 'error')
     }
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
 
     this.activeMessageIds.clear()
 
@@ -1855,6 +1946,7 @@ export class StreamProcessor {
     this.activeRuns.clear()
     this.toolCallToMessage.clear()
     this.structuredMessageIds.clear()
+    this.structuredOutputUpdateBatches.clear()
     this.pendingManualMessageId = null
     this.pendingThinkingStepId = null
     this.finishReason = null

package/src/activities/generateSpeech/index.ts

@@ -103,10 +103,10 @@ function createId(prefix: string): string {
  * @example Generate speech from text
  * ```ts
  * import { generateSpeech } from '@tanstack/ai'
- * import { openaiTTS } from '@tanstack/ai-openai'
+ * import { openaiSpeech } from '@tanstack/ai-openai'
  *
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1-hd'),
+ *   adapter: openaiSpeech('tts-1-hd'),
  *   text: 'Hello, welcome to TanStack AI!',
  *   voice: 'nova'
  * })
@@ -117,7 +117,7 @@ function createId(prefix: string): string {
  * @example With format and speed options
  * ```ts
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1'),
+ *   adapter: openaiSpeech('tts-1'),
  *   text: 'This is slower speech.',
  *   voice: 'alloy',
  *   format: 'wav',

package/src/types.ts

@@ -800,10 +800,26 @@ export interface TextOptions<
 
   /**
    * Schema for structured output.
-   * When provided, the adapter should use the provider's native structured output API
-   * to ensure the response conforms to this schema.
-   * The schema will be converted to JSON Schema format before being sent to the provider.
-   * Supports any Standard JSON Schema compliant library (Zod, ArkType, Valibot, etc.).
+   *
+   * **Two distinct use sites:**
+   *
+   * 1. **User-facing (activity layer):** accepts any
+   *    {@link SchemaInput} — Zod, ArkType, Valibot, or a raw JSON Schema.
+   *    The activity layer converts to JSON Schema before handing off.
+   *
+   * 2. **Adapter-facing (`chatStream` call):** the engine populates this with
+   *    a pre-converted JSON Schema **only** when the adapter declared
+   *    `supportsCombinedToolsAndSchema(modelOptions) === true`. The adapter
+   *    should then wire the schema into the upstream request (e.g.
+   *    `response_format: { type: 'json_schema', ... }`, `text.format`,
+   *    `output_format`) alongside any `tools`. The model's natural final
+   *    turn carries the schema-constrained JSON text and the engine
+   *    harvests it from the agent loop without a separate finalization
+   *    round-trip.
+   *
+   *    Adapters that did NOT declare the capability never see this field
+   *    populated — the engine instead invokes `structuredOutput` /
+   *    `structuredOutputStream` after the agent loop.
    */
   outputSchema?: SchemaInput
   /**