@tanstack/ai 0.16.0 → 0.18.0

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

@@ -76,6 +76,20 @@ export interface TextAdapter<TModel extends string, TProviderOptions extends Rec
      * @returns Promise with the raw data (validation is done in the chat function)
      */
     structuredOutput: (options: StructuredOutputOptions<TProviderOptions>) => Promise<StructuredOutputResult<unknown>>;
+    /**
+     * Stream structured output using the provider's native streaming structured
+     * output API (stream + response_format json_schema in a single request).
+     *
+     * Optional — adapters without native streaming JSON omit this method and the
+     * activity layer synthesizes a stream around the non-streaming
+     * `structuredOutput` call.
+     *
+     * 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? }`.
+     */
+    structuredOutputStream?: (options: StructuredOutputOptions<TProviderOptions>) => AsyncIterable<StreamChunk>;
 }
 /**
  * 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 */\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> {\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  }\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/**\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>\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> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata\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  }\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":"AAoHO,MAAe,gBAcpB;AAAA,EAgBA,YAAY,SAA4B,CAAA,GAAI,OAAe;AAf3D,SAAS,OAAO;AAgBd,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 */\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> {\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  }\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>\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> implements TextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  TMessageMetadataByModality,\n  TToolCapabilities,\n  TToolCallMetadata\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  }\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":"AAqIO,MAAe,gBAcpB;AAAA,EAgBA,YAAY,SAA4B,CAAA,GAAI,OAAe;AAf3D,SAAS,OAAO;AAgBd,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.d.ts

@@ -1,5 +1,5 @@
 import { AnyTextAdapter } from './adapter.js';
-import { ConstrainedModelMessage, InferSchemaType, SchemaInput, StreamChunk, TextOptions, Tool } from '../../types.js';
+import { ConstrainedModelMessage, InferSchemaType, ModelMessage, SchemaInput, StreamChunk, StructuredOutputStream, TextOptions, Tool, UIMessage } from '../../types.js';
 import { ChatMiddleware } from './middleware/types.js';
 import { DebugOption } from '../../logger/types.js';
 import { ProviderTool } from '../../tools/provider-tool.js';
@@ -16,8 +16,15 @@ export declare const kind: "text";
 export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean> {
     /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
     adapter: TAdapter;
-    /** Conversation messages - content types are constrained by the adapter's input modalities and metadata */
-    messages?: Array<ConstrainedModelMessage<{
+    /**
+     * Conversation messages. Accepts:
+     * - `ConstrainedModelMessage` — content types constrained by the adapter's input modalities.
+     * - `ModelMessage` — unconstrained model message (e.g., forwarded from an AG-UI wire payload).
+     * - `UIMessage` — parts-based UI representation; converted internally via `convertMessagesToModelMessages`.
+     *
+     * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages).
+     */
+    messages?: Array<UIMessage | ModelMessage | ConstrainedModelMessage<{
         inputModalities: TAdapter['~types']['inputModalities'];
         messageMetadataByModality: TAdapter['~types']['messageMetadataByModality'];
     }>>;
@@ -56,6 +63,8 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     threadId?: TextOptions['threadId'];
     /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
     runId?: TextOptions['runId'];
+    /** Parent run ID for AG-UI protocol nested run correlation. */
+    parentRunId?: TextOptions['parentRunId'];
     /**
      * Optional Standard Schema for structured output.
      * When provided, the activity will:
@@ -139,11 +148,21 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
 export declare function createChatOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = true>(options: TextActivityOptions<TAdapter, TSchema, TStream>): TextActivityOptions<TAdapter, TSchema, TStream>;
 /**
  * Result type for the text activity.
- * - If outputSchema is provided: Promise<InferSchemaType<TSchema>>
- * - If stream is false: Promise<string>
- * - Otherwise (stream is true, default): AsyncIterable<StreamChunk>
+ * - If outputSchema is provided AND stream is explicitly true:
+ *   StructuredOutputStream<InferSchemaType<TSchema>> — yields raw JSON deltas
+ *   via TEXT_MESSAGE_CONTENT plus a terminal StructuredOutputCompleteEvent
+ *   carrying the validated object.
+ * - If outputSchema is provided without explicit stream:true:
+ *   Promise<InferSchemaType<TSchema>>.
+ * - If stream is explicitly false (no schema): Promise<string>.
+ * - Otherwise (default): AsyncIterable<StreamChunk>.
+ *
+ * `[TStream] extends [true]` is used (not `TStream extends true`) so that the
+ * default `boolean` value of `TStream` does *not* match the streaming branch.
+ * Without this, plain `chat({ outputSchema })` would type as a stream while
+ * the runtime returns a Promise — see issue #526.
  */
-export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream extends boolean = true> = TSchema extends SchemaInput ? Promise<InferSchemaType<TSchema>> : TStream extends false ? Promise<string> : AsyncIterable<StreamChunk>;
+export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream extends boolean = boolean> = TSchema extends SchemaInput ? [TStream] extends [true] ? StructuredOutputStream<InferSchemaType<TSchema>> : Promise<InferSchemaType<TSchema>> : [TStream] extends [false] ? Promise<string> : AsyncIterable<StreamChunk>;
 /**
  * Text activity - handles agentic text generation, one-shot text generation, and agentic structured output.
  *
@@ -205,6 +224,6 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * // result is { summary: string, keyPoints: string[] }
  * ```
  */
-export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = true>(options: TextActivityOptions<TAdapter, TSchema, TStream>): TextActivityResult<TSchema, TStream>;
+export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean>(options: TextActivityOptions<TAdapter, TSchema, TStream>): TextActivityResult<TSchema, TStream>;
 export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
 export { BaseTextAdapter } from './adapter.js';

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

@@ -8,6 +8,7 @@ import { convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema }
 import { maxIterations } from "./agent-loop-strategies.js";
 import { convertMessagesToModelMessages } from "./messages.js";
 import { MiddlewareRunner } from "./middleware/compose.js";
+import { EventType } from "@ag-ui/core";
 const kind = "text";
 function createChatOptions(options) {
   return options;
@@ -53,8 +54,9 @@ class TextEngine {
     this.streamId = this.createId("stream");
     this.effectiveRequest = config.params.abortController ? { signal: config.params.abortController.signal } : void 0;
     this.effectiveSignal = config.params.abortController?.signal;
-    this.threadId = config.params.threadId || this.createId("thread");
+    this.threadId = config.params.threadId || config.params.conversationId || this.createId("thread");
     this.runIdOverride = config.params.runId;
+    this.parentRunIdOverride = config.params.parentRunId;
     const allMiddleware = [
       devtoolsMiddleware(),
       ...config.middleware || [],
@@ -65,7 +67,10 @@ class TextEngine {
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
-      conversationId: config.params.conversationId,
+      threadId: this.threadId,
+      // Legacy alias kept on the ctx so middleware that reads
+      // `ctx.conversationId` keeps working. Always equals `threadId`.
+      conversationId: this.threadId,
       phase: "init",
       iteration: 0,
       chunkIndex: 0,
@@ -110,7 +115,7 @@ class TextEngine {
   async *run() {
     this.beforeRun();
     this.logger.agentLoop("run started", {
-      conversationId: this.middlewareCtx.conversationId
+      threadId: this.middlewareCtx.threadId
     });
     try {
       this.middlewareCtx.phase = "init";
@@ -172,7 +177,7 @@ class TextEngine {
         } else {
           this.logger.errors("chat run failed", {
             error,
-            conversationId: this.middlewareCtx.conversationId
+            threadId: this.middlewareCtx.threadId
           });
           await this.middlewareRunner.runOnError(this.middlewareCtx, {
             error,
@@ -268,7 +273,8 @@ class TextEngine {
       systemPrompts: this.systemPrompts,
       logger: this.logger,
       threadId: this.threadId,
-      runId: this.runIdOverride
+      runId: this.runIdOverride,
+      parentRunId: this.parentRunIdOverride
     })) {
       if (this.isCancelled()) {
         break;
@@ -926,19 +932,31 @@ class TextEngine {
 }
 function chat(options) {
   const { outputSchema, stream } = options;
+  if (outputSchema && stream === true) {
+    return runStreamingStructuredOutput({
+      ...options,
+      outputSchema,
+      stream
+    });
+  }
   if (outputSchema) {
-    return runAgenticStructuredOutput(
-      options
-    );
+    return runAgenticStructuredOutput({
+      ...options,
+      outputSchema
+    });
   }
   if (stream === false) {
-    return runNonStreamingText(
-      options
-    );
+    return runNonStreamingText({
+      ...options,
+      outputSchema: void 0,
+      stream
+    });
   }
-  return runStreamingText(
-    options
-  );
+  return runStreamingText({
+    ...options,
+    outputSchema: void 0,
+    stream
+  });
 }
 async function* runStreamingText(options) {
   const { adapter, middleware, context, debug, ...textOptions } = options;
@@ -1017,6 +1035,219 @@ async function runAgenticStructuredOutput(options) {
   }
   return result.data;
 }
+async function* fallbackStructuredOutputStream(adapter, options) {
+  const { chatOptions } = options;
+  const runId = chatOptions.runId ?? `mock-${Date.now()}`;
+  const threadId = chatOptions.threadId ?? `mock-${Date.now()}`;
+  const messageId = `mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const model = chatOptions.model;
+  const timestamp = Date.now();
+  yield {
+    type: EventType.RUN_STARTED,
+    runId,
+    threadId,
+    model,
+    timestamp
+  };
+  let result;
+  try {
+    result = await adapter.structuredOutput(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    yield {
+      type: EventType.RUN_ERROR,
+      runId,
+      model,
+      timestamp,
+      message,
+      error: { message }
+    };
+    return;
+  }
+  yield {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId,
+    role: "assistant",
+    model,
+    timestamp
+  };
+  yield {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId,
+    delta: result.rawText,
+    model,
+    timestamp
+  };
+  yield {
+    type: EventType.TEXT_MESSAGE_END,
+    messageId,
+    model,
+    timestamp
+  };
+  yield {
+    type: EventType.CUSTOM,
+    name: "structured-output.complete",
+    value: { object: result.data, raw: result.rawText },
+    model,
+    timestamp
+  };
+  yield {
+    type: EventType.RUN_FINISHED,
+    runId,
+    threadId,
+    model,
+    timestamp,
+    finishReason: "stop"
+  };
+}
+function runStreamingStructuredOutput(options) {
+  const { outputSchema } = options;
+  if (!outputSchema) {
+    throw new Error("outputSchema is required for streaming structured output");
+  }
+  const jsonSchema = convertSchemaToJsonSchema(outputSchema, {
+    forStructuredOutput: true
+  });
+  if (!jsonSchema) {
+    throw new Error("Failed to convert output schema to JSON Schema");
+  }
+  return runStreamingStructuredOutputImpl(
+    options,
+    jsonSchema
+  );
+}
+async function* runStreamingStructuredOutputImpl(options, jsonSchema) {
+  const { adapter, outputSchema, middleware, context, debug, ...textOptions } = options;
+  const model = adapter.model;
+  const logger = resolveDebugOption(debug);
+  const runId = textOptions.runId;
+  let finalMessages = convertMessagesToModelMessages(textOptions.messages ?? []);
+  if (textOptions.tools?.length) {
+    const engine = new TextEngine(
+      {
+        adapter,
+        params: { ...textOptions, model, logger, messages: finalMessages },
+        middleware,
+        context
+      },
+      logger
+    );
+    let agentLoopErrored = false;
+    try {
+      for await (const chunk of engine.run()) {
+        if (chunk.type === "RUN_STARTED" || chunk.type === "RUN_FINISHED") {
+          continue;
+        }
+        if (chunk.type === "RUN_ERROR") {
+          agentLoopErrored = true;
+          yield chunk;
+          continue;
+        }
+        yield chunk;
+      }
+    } catch (engineError) {
+      const message = engineError.message || "Agent loop failed";
+      logger.errors("runStreamingStructuredOutput agent loop failed", {
+        error: engineError,
+        source: "runStreamingStructuredOutput"
+      });
+      yield {
+        type: EventType.RUN_ERROR,
+        runId,
+        model,
+        timestamp: Date.now(),
+        message,
+        code: "agent-loop-failed",
+        error: { message, code: "agent-loop-failed" }
+      };
+      return;
+    }
+    if (agentLoopErrored) {
+      return;
+    }
+    finalMessages = engine.getMessages();
+  }
+  const {
+    tools: _tools,
+    agentLoopStrategy: _als,
+    ...structuredTextOptions
+  } = textOptions;
+  logger.request(
+    `activity=chat-structured-stream provider=${adapter.name} model=${model} messages=${finalMessages.length}`,
+    {
+      provider: adapter.name,
+      model,
+      messageCount: finalMessages.length
+    }
+  );
+  const structuredChatOptions = {
+    ...structuredTextOptions,
+    model,
+    messages: finalMessages,
+    logger,
+    request: textOptions.abortController ? { signal: textOptions.abortController.signal } : void 0
+  };
+  const stream = adapter.structuredOutputStream ? adapter.structuredOutputStream({
+    chatOptions: structuredChatOptions,
+    outputSchema: jsonSchema
+  }) : fallbackStructuredOutputStream(adapter, {
+    chatOptions: structuredChatOptions,
+    outputSchema: jsonSchema
+  });
+  for await (const chunk of stream) {
+    if (chunk.type === EventType.CUSTOM && chunk.name === "structured-output.complete") {
+      const value = chunk.value;
+      if (isStandardSchema(outputSchema)) {
+        try {
+          const validated = parseWithStandardSchema(
+            outputSchema,
+            value.object
+          );
+          yield {
+            ...chunk,
+            // Forward `reasoning` through schema validation so consumers that
+            // only listen for the terminal event don't lose chain-of-thought.
+            value: {
+              object: validated,
+              raw: value.raw,
+              ...value.reasoning ? { reasoning: value.reasoning } : {}
+            }
+          };
+          continue;
+        } catch (err) {
+          const message = err.message || "Schema validation failed";
+          logger.errors(
+            "runStreamingStructuredOutput schema validation failed",
+            {
+              error: err,
+              source: "runStreamingStructuredOutput",
+              // Include reasoning in error meta so post-mortems can recover
+              // what the model thought through before producing invalid JSON.
+              ...value.reasoning ? { reasoning: value.reasoning } : {}
+            }
+          );
+          yield {
+            type: EventType.RUN_ERROR,
+            runId,
+            model: chunk.model ?? model,
+            timestamp: chunk.timestamp ?? Date.now(),
+            message,
+            code: "schema-validation",
+            error: {
+              message,
+              code: "schema-validation",
+              ...value.reasoning ? { reasoning: value.reasoning } : {}
+            }
+          };
+          return;
+        }
+      }
+      yield chunk;
+      continue;
+    }
+    yield chunk;
+  }
+}
 export {
   chat,
   createChatOptions,