@tanstack/ai 0.15.0 → 0.17.0

package/dist/esm/activities/summarize/chat-stream-summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-stream-summarize.js","sources":["../../../../src/activities/summarize/chat-stream-summarize.ts"],"sourcesContent":["import { EventType } from '@ag-ui/core'\nimport { toRunErrorPayload } from '../error-payload'\nimport { BaseSummarizeAdapter } from './adapter'\nimport type {\n  StreamChunk,\n  SummarizationOptions,\n  SummarizationResult,\n  TextOptions,\n} from '../../types'\n\n/**\n * Minimal contract for a text adapter that supports `chatStream`. Lets\n * `ChatStreamSummarizeAdapter` work with any text adapter without coupling\n * to a specific implementation.\n *\n * The provider-options shape is intentionally `any` here — the wrapper only\n * forwards `modelOptions` straight through, so a text adapter with a richer\n * per-model options type (e.g. `ResolveProviderOptions<TModel>`) is still\n * acceptable. Summarize-level type safety is enforced via\n * `SummarizationOptions<TProviderOptions>` on the wrapper itself.\n */\nexport interface ChatStreamCapable {\n  chatStream: (options: TextOptions<any>) => AsyncIterable<StreamChunk>\n}\n\n/**\n * Extract the per-model `modelOptions` type a text adapter accepts. Used by\n * provider summarize factories so their `modelOptions` IntelliSense matches\n * what the underlying text adapter actually understands.\n */\nexport type InferTextProviderOptions<TAdapter> = TAdapter extends {\n  '~types': { providerOptions: infer P }\n}\n  ? P extends object\n    ? P\n    : object\n  : object\n\n/**\n * Summarize adapter that wraps any `ChatStreamCapable` text adapter and\n * prompts it for summarization. Not tied to any wire format.\n */\nexport class ChatStreamSummarizeAdapter<\n  TModel extends string,\n  TProviderOptions extends object = Record<string, unknown>,\n> extends BaseSummarizeAdapter<TModel, TProviderOptions> {\n  readonly name: string\n\n  private textAdapter: ChatStreamCapable\n\n  constructor(\n    textAdapter: ChatStreamCapable,\n    model: TModel,\n    name: string = 'chat-stream-summarize',\n  ) {\n    super({}, model)\n    this.name = name\n    this.textAdapter = textAdapter\n  }\n\n  async summarize(\n    options: SummarizationOptions<TProviderOptions>,\n  ): Promise<SummarizationResult> {\n    const systemPrompt = this.buildSummarizationPrompt(options)\n\n    let summary = ''\n    const id = this.generateId()\n    let model = options.model\n    let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }\n\n    options.logger.request(\n      `activity=summarize provider=${this.name} model=${options.model} text-length=${options.text.length} maxLength=${options.maxLength ?? 'unset'}`,\n      { provider: this.name, model: options.model },\n    )\n\n    try {\n      for await (const chunk of this.textAdapter.chatStream(\n        this.buildTextOptions(options, systemPrompt),\n      )) {\n        if (chunk.type === 'TEXT_MESSAGE_CONTENT') {\n          if (chunk.content) {\n            summary = chunk.content\n          } else if (chunk.delta) {\n            // Append delta only when present — a content-less chunk with no\n            // delta would otherwise concat literal `'undefined'`.\n            summary += chunk.delta\n          }\n          model = chunk.model || model\n        }\n        if (chunk.type === 'RUN_FINISHED') {\n          if (chunk.usage) {\n            usage = chunk.usage\n          }\n        }\n        // Surface failures: the underlying chatStream emits RUN_ERROR instead\n        // of throwing, so without this branch summarize() would return an\n        // empty summary and pretend a failed run succeeded.\n        if (chunk.type === 'RUN_ERROR') {\n          const message =\n            (chunk.error && typeof chunk.error.message === 'string'\n              ? chunk.error.message\n              : null) ?? 'Summarization failed'\n          const code =\n            chunk.error && typeof chunk.error.code === 'string'\n              ? chunk.error.code\n              : undefined\n          const err = new Error(message)\n          if (code) {\n            ;(err as Error & { code?: string }).code = code\n          }\n          throw err\n        }\n      }\n    } catch (error: unknown) {\n      // Narrow before logging: raw SDK errors can carry request metadata\n      // (including auth headers) which we must never surface to user loggers.\n      options.logger.errors(`${this.name}.summarize fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.summarize failed`),\n        source: `${this.name}.summarize`,\n      })\n      throw error\n    }\n\n    return { id, model, summary, usage }\n  }\n\n  async *summarizeStream(\n    options: SummarizationOptions<TProviderOptions>,\n  ): AsyncIterable<StreamChunk> {\n    const systemPrompt = this.buildSummarizationPrompt(options)\n\n    options.logger.request(\n      `activity=summarizeStream provider=${this.name} model=${options.model} text-length=${options.text.length} maxLength=${options.maxLength ?? 'unset'}`,\n      { provider: this.name, model: options.model },\n    )\n\n    const id = this.generateId()\n    let summary = ''\n    let model = options.model\n    let usage: SummarizationResult['usage'] = {\n      promptTokens: 0,\n      completionTokens: 0,\n      totalTokens: 0,\n    }\n\n    try {\n      for await (const chunk of this.textAdapter.chatStream(\n        this.buildTextOptions(options, systemPrompt),\n      )) {\n        // Accumulate the same way `summarize()` does so consumers see deltas\n        // AND the terminal `generation:result` event below carries the same\n        // final summary that non-streaming returns.\n        if (chunk.type === 'TEXT_MESSAGE_CONTENT') {\n          if (chunk.content) {\n            summary = chunk.content\n          } else if (chunk.delta) {\n            summary += chunk.delta\n          }\n          if (chunk.model) model = chunk.model\n        }\n\n        // Emit the GenerationClient-shaped result event just before the\n        // terminal RUN_FINISHED so subscribers (useSummarize) populate\n        // `result` before flipping `status` to success.\n        if (chunk.type === 'RUN_FINISHED') {\n          if (chunk.usage) usage = chunk.usage\n          if (chunk.model) model = chunk.model\n          yield {\n            type: EventType.CUSTOM,\n            name: 'generation:result',\n            value: { id, model, summary, usage } satisfies SummarizationResult,\n            model,\n            timestamp: Date.now(),\n          }\n        }\n\n        yield chunk\n      }\n    } catch (error: unknown) {\n      options.logger.errors(`${this.name}.summarizeStream fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.summarizeStream failed`),\n        source: `${this.name}.summarizeStream`,\n      })\n      throw error\n    }\n  }\n\n  /**\n   * Build the TextOptions passed to the underlying chatStream. Provider\n   * `modelOptions` from the summarize call are forwarded as-is so knobs like\n   * Anthropic cache headers, Gemini safety settings, or Ollama tuning params\n   * still reach the wire layer.\n   */\n  protected buildTextOptions(\n    options: SummarizationOptions<TProviderOptions>,\n    systemPrompt: string,\n  ): TextOptions<TProviderOptions> {\n    return {\n      model: options.model,\n      messages: [{ role: 'user', content: options.text }],\n      systemPrompts: [systemPrompt],\n      maxTokens: options.maxLength,\n      temperature: 0.3,\n      modelOptions: options.modelOptions,\n      logger: options.logger,\n    }\n  }\n\n  protected buildSummarizationPrompt(\n    options: SummarizationOptions<TProviderOptions>,\n  ): string {\n    let prompt = 'You are a professional summarizer. '\n\n    switch (options.style) {\n      case 'bullet-points':\n        prompt += 'Provide a summary in bullet point format. '\n        break\n      case 'paragraph':\n        prompt += 'Provide a summary in paragraph format. '\n        break\n      case 'concise':\n        prompt += 'Provide a very concise summary in 1-2 sentences. '\n        break\n      default:\n        prompt += 'Provide a clear and concise summary. '\n    }\n\n    if (options.focus && options.focus.length > 0) {\n      prompt += `Focus on the following aspects: ${options.focus.join(', ')}. `\n    }\n\n    if (options.maxLength) {\n      prompt += `Keep the summary under ${options.maxLength} tokens. `\n    }\n\n    return prompt\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/activities/summarize/index.d.ts

@@ -105,3 +105,4 @@ export declare function summarize<TAdapter extends SummarizeAdapter<string, obje
 export declare function createSummarizeOptions<TAdapter extends SummarizeAdapter<string, object>, TStream extends boolean = false>(options: SummarizeActivityOptions<TAdapter, TStream>): SummarizeActivityOptions<TAdapter, TStream>;
 export type { SummarizeAdapter, SummarizeAdapterConfig, AnySummarizeAdapter, } from './adapter.js';
 export { BaseSummarizeAdapter } from './adapter.js';
+export { ChatStreamSummarizeAdapter, type ChatStreamCapable, type InferTextProviderOptions, } from './chat-stream-summarize.js';

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

@@ -17,7 +17,7 @@ function summarize(options) {
   );
 }
 async function runSummarize(options) {
-  const { adapter, text, maxLength, style, focus } = options;
+  const { adapter, text, maxLength, style, focus, modelOptions } = options;
   const model = adapter.model;
   const requestId = createId("summarize");
   const inputLength = text.length;
@@ -41,6 +41,7 @@ async function runSummarize(options) {
     maxLength,
     style,
     focus,
+    modelOptions,
     logger
   };
   try {
@@ -70,7 +71,7 @@ async function runSummarize(options) {
   }
 }
 async function* runStreamingSummarize(options) {
-  const { adapter, text, maxLength, style, focus } = options;
+  const { adapter, text, maxLength, style, focus, modelOptions } = options;
   const model = adapter.model;
   const logger = resolveDebugOption(options.debug);
   logger.request(`activity=summarize provider=${adapter.name}`, {
@@ -84,6 +85,7 @@ async function* runStreamingSummarize(options) {
     maxLength,
     style,
     focus,
+    modelOptions,
     logger
   };
   try {

package/dist/esm/activities/summarize/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/summarize/index.ts"],"sourcesContent":["/**\n * Summarize Activity\n *\n * Generates summaries from text input.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { SummarizeAdapter } from './adapter'\nimport type {\n  StreamChunk,\n  SummarizationOptions,\n  SummarizationResult,\n} from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'summarize' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/** Extract provider options from a SummarizeAdapter via ~types */\nexport type SummarizeProviderOptions<TAdapter> =\n  TAdapter extends SummarizeAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the summarize activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The summarize adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface SummarizeActivityOptions<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n> {\n  /** The summarize adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary (in words or characters, provider-dependent) */\n  maxLength?: number\n  /** Style of summary to generate */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics or aspects to focus on in the summary */\n  focus?: Array<string>\n  /** Provider-specific options */\n  modelOptions?: SummarizeProviderOptions<TAdapter>\n  /**\n   * Whether to stream the summarization result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming output.\n   * When false or not provided, returns a Promise<SummarizationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the summarize activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<SummarizationResult>\n */\nexport type SummarizeActivityResult<TStream extends boolean> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<SummarizationResult>\n\n// ===========================\n// Helper Functions\n// ===========================\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Summarize activity - generates summaries from text.\n *\n * Supports both streaming and non-streaming modes.\n *\n * @example Basic summarization\n * ```ts\n * import { summarize } from '@tanstack/ai'\n * import { openaiSummarize } from '@tanstack/ai-openai'\n *\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...'\n * })\n *\n * console.log(result.summary)\n * ```\n *\n * @example Summarization with style\n * ```ts\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...',\n *   style: 'bullet-points',\n *   maxLength: 100\n * })\n * ```\n *\n * @example Focused summarization\n * ```ts\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long technical document...',\n *   focus: ['key findings', 'methodology']\n * })\n * ```\n *\n * @example Streaming summarization\n * ```ts\n * for await (const chunk of summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...',\n *   stream: true\n * })) {\n *   if (chunk.type === 'content') {\n *     process.stdout.write(chunk.delta)\n *   }\n * }\n * ```\n */\nexport function summarize<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: SummarizeActivityOptions<TAdapter, TStream>,\n): SummarizeActivityResult<TStream> {\n  const { stream } = options\n\n  if (stream) {\n    return runStreamingSummarize(\n      options as unknown as SummarizeActivityOptions<\n        SummarizeAdapter<string, object>,\n        true\n      >,\n    ) as SummarizeActivityResult<TStream>\n  }\n\n  return runSummarize(\n    options as unknown as SummarizeActivityOptions<\n      SummarizeAdapter<string, object>,\n      false\n    >,\n  ) as SummarizeActivityResult<TStream>\n}\n\n/**\n * Run non-streaming summarization\n */\nasync function runSummarize(\n  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, false>,\n): Promise<SummarizationResult> {\n  const { adapter, text, maxLength, style, focus } = options\n  const model = adapter.model\n  const requestId = createId('summarize')\n  const inputLength = text.length\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  aiEventClient.emit('summarize:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    inputLength,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=summarize provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n    inputLength,\n  })\n\n  const summarizeOptions: SummarizationOptions = {\n    model,\n    text,\n    maxLength,\n    style,\n    focus,\n    logger,\n  }\n\n  try {\n    const result = await adapter.summarize(summarizeOptions)\n\n    const duration = Date.now() - startTime\n    const outputLength = result.summary.length\n\n    aiEventClient.emit('summarize:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      inputLength,\n      outputLength,\n      duration,\n      timestamp: Date.now(),\n    })\n\n    logger.output(`activity=summarize length=${outputLength}`, {\n      hasSummary: !!result.summary,\n      outputLength,\n    })\n\n    return result\n  } catch (error) {\n    logger.errors('summarize activity failed', {\n      error,\n      source: 'summarize',\n    })\n    throw error\n  }\n}\n\n/**\n * Run streaming summarization\n * Uses the adapter's native streaming if available, otherwise falls back\n * to non-streaming and yields the result as a single chunk.\n */\nasync function* runStreamingSummarize(\n  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,\n): AsyncIterable<StreamChunk> {\n  const { adapter, text, maxLength, style, focus } = options\n  const model = adapter.model\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  logger.request(`activity=summarize provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n    stream: true,\n  })\n\n  const summarizeOptions: SummarizationOptions = {\n    model,\n    text,\n    maxLength,\n    style,\n    focus,\n    logger,\n  }\n\n  try {\n    // Use real streaming if the adapter supports it\n    if (adapter.summarizeStream) {\n      yield* adapter.summarizeStream(summarizeOptions)\n      return\n    }\n\n    // Fall back to non-streaming — wrap result with streamGenerationResult\n    yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))\n  } catch (error) {\n    logger.errors('summarize activity failed', {\n      error,\n      source: 'summarize',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the summarize() function without executing.\n */\nexport function createSummarizeOptions<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: SummarizeActivityOptions<TAdapter, TStream>,\n): SummarizeActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  SummarizeAdapter,\n  SummarizeAdapterConfig,\n  AnySummarizeAdapter,\n} from './adapter'\nexport { BaseSummarizeAdapter } from './adapter'\n"],"names":[],"mappings":";;;AAwBO,MAAM,OAAO;AAyEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAwDO,SAAS,UAId,SACkC;AAClC,QAAM,EAAE,WAAW;AAEnB,MAAI,QAAQ;AACV,WAAO;AAAA,MACL;AAAA,IAAA;AAAA,EAKJ;AAEA,SAAO;AAAA,IACL;AAAA,EAAA;AAKJ;AAKA,eAAe,aACb,SAC8B;AAC9B,QAAM,EAAE,SAAS,MAAM,WAAW,OAAO,UAAU;AACnD,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,WAAW;AACtC,QAAM,cAAc,KAAK;AACzB,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAE/D,gBAAc,KAAK,6BAA6B;AAAA,IAC9C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,+BAA+B,QAAQ,IAAI,IAAI;AAAA,IAC5D,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA;AAAA,EAAA,CACD;AAED,QAAM,mBAAyC;AAAA,IAC7C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAGF,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,UAAU,gBAAgB;AAEvD,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,eAAe,OAAO,QAAQ;AAEpC,kBAAc,KAAK,+BAA+B;AAAA,MAChD;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO,OAAO,6BAA6B,YAAY,IAAI;AAAA,MACzD,YAAY,CAAC,CAAC,OAAO;AAAA,MACrB;AAAA,IAAA,CACD;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,WAAO,OAAO,6BAA6B;AAAA,MACzC;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AAOA,gBAAgB,sBACd,SAC4B;AAC5B,QAAM,EAAE,SAAS,MAAM,WAAW,OAAO,UAAU;AACnD,QAAM,QAAQ,QAAQ;AACtB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAE/D,SAAO,QAAQ,+BAA+B,QAAQ,IAAI,IAAI;AAAA,IAC5D,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ;AAAA,EAAA,CACT;AAED,QAAM,mBAAyC;AAAA,IAC7C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAGF,MAAI;AAEF,QAAI,QAAQ,iBAAiB;AAC3B,aAAO,QAAQ,gBAAgB,gBAAgB;AAC/C;AAAA,IACF;AAGA,WAAO,uBAAuB,MAAM,QAAQ,UAAU,gBAAgB,CAAC;AAAA,EACzE,SAAS,OAAO;AACd,WAAO,OAAO,6BAA6B;AAAA,MACzC;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,uBAId,SAC6C;AAC7C,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/summarize/index.ts"],"sourcesContent":["/**\n * Summarize Activity\n *\n * Generates summaries from text input.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { SummarizeAdapter } from './adapter'\nimport type { StreamChunk, SummarizationResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'summarize' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/** Extract provider options from a SummarizeAdapter via ~types */\nexport type SummarizeProviderOptions<TAdapter> =\n  TAdapter extends SummarizeAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the summarize activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The summarize adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface SummarizeActivityOptions<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n> {\n  /** The summarize adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary (in words or characters, provider-dependent) */\n  maxLength?: number\n  /** Style of summary to generate */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics or aspects to focus on in the summary */\n  focus?: Array<string>\n  /** Provider-specific options */\n  modelOptions?: SummarizeProviderOptions<TAdapter>\n  /**\n   * Whether to stream the summarization result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming output.\n   * When false or not provided, returns a Promise<SummarizationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the summarize activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<SummarizationResult>\n */\nexport type SummarizeActivityResult<TStream extends boolean> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<SummarizationResult>\n\n// ===========================\n// Helper Functions\n// ===========================\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Summarize activity - generates summaries from text.\n *\n * Supports both streaming and non-streaming modes.\n *\n * @example Basic summarization\n * ```ts\n * import { summarize } from '@tanstack/ai'\n * import { openaiSummarize } from '@tanstack/ai-openai'\n *\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...'\n * })\n *\n * console.log(result.summary)\n * ```\n *\n * @example Summarization with style\n * ```ts\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...',\n *   style: 'bullet-points',\n *   maxLength: 100\n * })\n * ```\n *\n * @example Focused summarization\n * ```ts\n * const result = await summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long technical document...',\n *   focus: ['key findings', 'methodology']\n * })\n * ```\n *\n * @example Streaming summarization\n * ```ts\n * for await (const chunk of summarize({\n *   adapter: openaiSummarize('gpt-4o-mini'),\n *   text: 'Long article text here...',\n *   stream: true\n * })) {\n *   if (chunk.type === 'content') {\n *     process.stdout.write(chunk.delta)\n *   }\n * }\n * ```\n */\nexport function summarize<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: SummarizeActivityOptions<TAdapter, TStream>,\n): SummarizeActivityResult<TStream> {\n  const { stream } = options\n\n  if (stream) {\n    return runStreamingSummarize(\n      options as unknown as SummarizeActivityOptions<\n        SummarizeAdapter<string, object>,\n        true\n      >,\n    ) as SummarizeActivityResult<TStream>\n  }\n\n  return runSummarize(\n    options as unknown as SummarizeActivityOptions<\n      SummarizeAdapter<string, object>,\n      false\n    >,\n  ) as SummarizeActivityResult<TStream>\n}\n\n/**\n * Run non-streaming summarization\n */\nasync function runSummarize(\n  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, false>,\n): Promise<SummarizationResult> {\n  const { adapter, text, maxLength, style, focus, modelOptions } = options\n  const model = adapter.model\n  const requestId = createId('summarize')\n  const inputLength = text.length\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  aiEventClient.emit('summarize:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    inputLength,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=summarize provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n    inputLength,\n  })\n\n  const summarizeOptions = {\n    model,\n    text,\n    maxLength,\n    style,\n    focus,\n    modelOptions,\n    logger,\n  }\n\n  try {\n    const result = await adapter.summarize(summarizeOptions)\n\n    const duration = Date.now() - startTime\n    const outputLength = result.summary.length\n\n    aiEventClient.emit('summarize:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      inputLength,\n      outputLength,\n      duration,\n      timestamp: Date.now(),\n    })\n\n    logger.output(`activity=summarize length=${outputLength}`, {\n      hasSummary: !!result.summary,\n      outputLength,\n    })\n\n    return result\n  } catch (error) {\n    logger.errors('summarize activity failed', {\n      error,\n      source: 'summarize',\n    })\n    throw error\n  }\n}\n\n/**\n * Run streaming summarization\n * Uses the adapter's native streaming if available, otherwise falls back\n * to non-streaming and yields the result as a single chunk.\n */\nasync function* runStreamingSummarize(\n  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,\n): AsyncIterable<StreamChunk> {\n  const { adapter, text, maxLength, style, focus, modelOptions } = options\n  const model = adapter.model\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n\n  logger.request(`activity=summarize provider=${adapter.name}`, {\n    provider: adapter.name,\n    model,\n    stream: true,\n  })\n\n  const summarizeOptions = {\n    model,\n    text,\n    maxLength,\n    style,\n    focus,\n    modelOptions,\n    logger,\n  }\n\n  try {\n    // Use real streaming if the adapter supports it\n    if (adapter.summarizeStream) {\n      yield* adapter.summarizeStream(summarizeOptions)\n      return\n    }\n\n    // Fall back to non-streaming — wrap result with streamGenerationResult\n    yield* streamGenerationResult(() => adapter.summarize(summarizeOptions))\n  } catch (error) {\n    logger.errors('summarize activity failed', {\n      error,\n      source: 'summarize',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the summarize() function without executing.\n */\nexport function createSummarizeOptions<\n  TAdapter extends SummarizeAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: SummarizeActivityOptions<TAdapter, TStream>,\n): SummarizeActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  SummarizeAdapter,\n  SummarizeAdapterConfig,\n  AnySummarizeAdapter,\n} from './adapter'\nexport { BaseSummarizeAdapter } from './adapter'\nexport {\n  ChatStreamSummarizeAdapter,\n  type ChatStreamCapable,\n  type InferTextProviderOptions,\n} from './chat-stream-summarize'\n"],"names":[],"mappings":";;;AAoBO,MAAM,OAAO;AAyEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAwDO,SAAS,UAId,SACkC;AAClC,QAAM,EAAE,WAAW;AAEnB,MAAI,QAAQ;AACV,WAAO;AAAA,MACL;AAAA,IAAA;AAAA,EAKJ;AAEA,SAAO;AAAA,IACL;AAAA,EAAA;AAKJ;AAKA,eAAe,aACb,SAC8B;AAC9B,QAAM,EAAE,SAAS,MAAM,WAAW,OAAO,OAAO,iBAAiB;AACjE,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,WAAW;AACtC,QAAM,cAAc,KAAK;AACzB,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAE/D,gBAAc,KAAK,6BAA6B;AAAA,IAC9C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,+BAA+B,QAAQ,IAAI,IAAI;AAAA,IAC5D,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA;AAAA,EAAA,CACD;AAED,QAAM,mBAAmB;AAAA,IACvB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAGF,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,UAAU,gBAAgB;AAEvD,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,eAAe,OAAO,QAAQ;AAEpC,kBAAc,KAAK,+BAA+B;AAAA,MAChD;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO,OAAO,6BAA6B,YAAY,IAAI;AAAA,MACzD,YAAY,CAAC,CAAC,OAAO;AAAA,MACrB;AAAA,IAAA,CACD;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,WAAO,OAAO,6BAA6B;AAAA,MACzC;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AAOA,gBAAgB,sBACd,SAC4B;AAC5B,QAAM,EAAE,SAAS,MAAM,WAAW,OAAO,OAAO,iBAAiB;AACjE,QAAM,QAAQ,QAAQ;AACtB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAE/D,SAAO,QAAQ,+BAA+B,QAAQ,IAAI,IAAI;AAAA,IAC5D,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ;AAAA,EAAA,CACT;AAED,QAAM,mBAAmB;AAAA,IACvB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAGF,MAAI;AAEF,QAAI,QAAQ,iBAAiB;AAC3B,aAAO,QAAQ,gBAAgB,gBAAgB;AAC/C;AAAA,IACF;AAGA,WAAO,uBAAuB,MAAM,QAAQ,UAAU,gBAAgB,CAAC;AAAA,EACzE,SAAS,OAAO;AACd,WAAO,OAAO,6BAA6B;AAAA,MACzC;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,uBAId,SAC6C;AAC7C,SAAO;AACT;"}

package/dist/esm/types.d.ts

@@ -70,15 +70,17 @@ export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema;
  * For plain JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
  */
 export type InferSchemaType<T> = T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown;
-export interface ToolCall {
+export interface ToolCall<TMetadata = unknown> {
     id: string;
     type: 'function';
     function: {
         name: string;
         arguments: string;
     };
-    /** Provider-specific metadata to carry through the tool call lifecycle */
-    providerMetadata?: Record<string, unknown>;
+    /** Provider-specific metadata to carry through the tool call lifecycle.
+     * Typed per-adapter via `TToolCallMetadata`. For example,
+     * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
+    metadata?: TMetadata;
 }
 /**
  * Supported input modality types for multimodal content.
@@ -221,7 +223,7 @@ export interface TextPart<TMetadata = unknown> {
     content: string;
     metadata?: TMetadata;
 }
-export interface ToolCallPart {
+export interface ToolCallPart<TMetadata = unknown> {
     type: 'tool-call';
     id: string;
     name: string;
@@ -235,6 +237,9 @@ export interface ToolCallPart {
     };
     /** Tool execution output (for client tools or after approval) */
     output?: any;
+    /** Provider-specific metadata that round-trips with the tool call.
+     * Typed per-adapter via `TToolCallMetadata`. */
+    metadata?: TMetadata;
 }
 export interface ToolResultPart {
     type: 'tool-result';
@@ -740,7 +745,7 @@ export interface TextMessageEndEvent extends AGUITextMessageEndEvent {
  * Emitted when a tool call starts.
  *
  * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
- * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `providerMetadata?`
+ * TanStack AI adds: `model?`, `toolName` (deprecated alias), `index?`, `metadata?`
  */
 export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
     /** Model identifier for multi-model support */
@@ -752,8 +757,11 @@ export interface ToolCallStartEvent extends AGUIToolCallStartEvent {
     toolName: string;
     /** Index for parallel tool calls */
     index?: number;
-    /** Provider-specific metadata to carry into the ToolCall */
-    providerMetadata?: Record<string, unknown>;
+    /** Provider-specific metadata to carry into the ToolCall.
+     * Untyped at the event layer because events flow through a discriminated
+     * union that does not survive generics; adapters cast it to their typed
+     * `TToolCallMetadata` shape when emitting. */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Emitted when tool call arguments are streaming.
@@ -887,6 +895,95 @@ export interface CustomEvent extends AGUICustomEvent {
     /** Model identifier for multi-model support */
     model?: string;
 }
+/**
+ * Final event of a streaming structured-output run. Carries the validated
+ * `object` (typed as `T` after the orchestrator runs Standard Schema parsing),
+ * the `raw` JSON text that produced it, and — for thinking/reasoning models —
+ * the accumulated reasoning text. Adapters emit this with `T = unknown`; the
+ * chat orchestrator narrows to the schema's inferred type after validation.
+ *
+ * `reasoning` is `undefined` when the model produced none (most non-thinking
+ * models) and when the underlying adapter doesn't expose reasoning streams.
+ *
+ * `name` is a string literal so consumers can narrow directly:
+ *
+ * ```ts
+ * if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
+ *   chunk.value.object // typed as T
+ * }
+ * ```
+ */
+export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<CustomEvent, 'name' | 'value'> {
+    name: 'structured-output.complete';
+    value: {
+        object: T;
+        raw: string;
+        reasoning?: string;
+    };
+}
+/**
+ * Emitted when a server tool requires approval before execution. The agent
+ * loop yields this and pauses — `structured-output.complete` will not fire
+ * for that run. The shape is fixed by the orchestrator's tool-approval flow
+ * (see `buildApprovalChunks` in `activities/chat/index.ts`).
+ */
+export interface ApprovalRequestedEvent extends Omit<CustomEvent, 'name' | 'value'> {
+    name: 'approval-requested';
+    value: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+        approval: {
+            id: string;
+            needsApproval: true;
+        };
+    };
+}
+/**
+ * Emitted when a client tool is invoked. The agent loop yields this and
+ * pauses to let the caller run the tool client-side — `structured-output.complete`
+ * will not fire for that run. Shape fixed by `buildClientToolChunks` in
+ * `activities/chat/index.ts`.
+ */
+export interface ToolInputAvailableEvent extends Omit<CustomEvent, 'name' | 'value'> {
+    name: 'tool-input-available';
+    value: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    };
+}
+/**
+ * Public type for streams returned by `chat({ outputSchema, stream: true })`.
+ *
+ * Yields all standard `StreamChunk` lifecycle events plus the three tagged
+ * `CUSTOM` events the orchestrator can emit through this path:
+ * - `structured-output.complete` — terminal event with typed `value.object: T`
+ * - `approval-requested` — server tool needs approval (pauses the run)
+ * - `tool-input-available` — client tool invocation (pauses the run)
+ *
+ * Each variant has a literal `name`, so a single discriminated narrow gives
+ * you a typed `value` with no helper or cast:
+ *
+ * ```ts
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
+ *     chunk.value.object // typed as T
+ *   } else if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') {
+ *     chunk.value.toolCallId // typed as string
+ *   }
+ * }
+ * ```
+ *
+ * Caveat: tools can emit arbitrary user-defined custom events via the
+ * `emitCustomEvent(name, value)` context API. Those flow through this stream
+ * at runtime but are intentionally absent from this type — including a bare
+ * `CustomEvent` (whose `value: any` would poison the union) would collapse
+ * `chunk.value` back to `any` after the narrow. If you rely on
+ * `emitCustomEvent` plus `outputSchema + stream: true`, branch on `CUSTOM`
+ * outside the literal-`name` narrows or cast explicitly.
+ */
+export type StructuredOutputStream<T = unknown> = AsyncIterable<Exclude<StreamChunk, CustomEvent> | StructuredOutputCompleteEvent<T> | ApprovalRequestedEvent | ToolInputAvailableEvent>;
 /**
  * Emitted when reasoning starts for a message.
  *
@@ -968,12 +1065,14 @@ export interface TextCompletionChunk {
         totalTokens: number;
     };
 }
-export interface SummarizationOptions {
+export interface SummarizationOptions<TProviderOptions extends object = Record<string, unknown>> {
     model: string;
     text: string;
     maxLength?: number;
     style?: 'bullet-points' | 'paragraph' | 'concise';
     focus?: Array<string>;
+    /** Provider-specific options forwarded by the summarize() activity. */
+    modelOptions?: TProviderOptions;
     /**
      * Internal logger threaded from the summarize() entry point. Adapters must
      * call logger.request() before the SDK call and logger.errors() in catch blocks.
@@ -994,7 +1093,7 @@ export interface SummarizationResult {
  * Options for image generation.
  * These are the common options supported across providers.
  */
-export interface ImageGenerationOptions<TProviderOptions extends object = object, TSize extends string = string> {
+export interface ImageGenerationOptions<TProviderOptions extends object = object, TSize extends string | undefined = string> {
     /** The model to use for image generation */
     model: string;
     /** Text description of the desired image(s) */
@@ -1102,7 +1201,7 @@ export interface AudioGenerationResult {
  *
  * @experimental Video generation is an experimental feature and may change.
  */
-export interface VideoGenerationOptions<TProviderOptions extends object = object, TSize extends string = string> {
+export interface VideoGenerationOptions<TProviderOptions extends object = object, TSize extends string | undefined = string> {
     /** The model to use for video generation */
     model: string;
     /** Text description of the desired video */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@ag-ui/core": "0.0.49",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.2.9"
+    "@tanstack/ai-event-client": "0.3.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/structured-outputs/SKILL.md

@@ -4,7 +4,9 @@ description: >
   Type-safe JSON schema responses from LLMs using outputSchema on chat().
   Supports Zod, ArkType, and Valibot schemas. The adapter handles
   provider-specific strategies transparently — never configure structured
-  output at the provider level. convertSchemaToJsonSchema() for manual
+  output at the provider level. Pass stream:true alongside outputSchema for
+  incremental JSON deltas + a terminal validated object via the
+  `structured-output.complete` event. convertSchemaToJsonSchema() for manual
   schema conversion.
 type: sub-skill
 library: tanstack-ai
@@ -46,6 +48,8 @@ const stream = chat({
 
 When `outputSchema` is provided, `chat()` returns `Promise<InferSchemaType<TSchema>>` instead of `AsyncIterable<StreamChunk>`. The result is fully typed based on the schema.
 
+Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below.
+
 ## Core Patterns
 
 ### Pattern 1: Basic structured output with Zod
@@ -128,8 +132,94 @@ console.log(company.employees[0].role)
 console.log(company.financials?.revenue)
 ```
 
+### Pattern 3: Streaming structured output
+
+Pass `stream: true` alongside `outputSchema` to receive incremental JSON deltas while the model generates, plus a final validated typed object. Useful for streaming partial UI (progress views, typewriter previews, partially-filled forms).
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages: [
+    { role: 'user', content: 'Extract: John Doe is 30, john@example.com' },
+  ],
+  outputSchema: PersonSchema,
+  stream: true,
+})
+
+let raw = ''
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    // Partial JSON text — drive progress UI only. Do NOT JSON.parse.
+    raw += chunk.delta
+  } else if (
+    chunk.type === 'CUSTOM' &&
+    chunk.name === 'structured-output.complete'
+  ) {
+    // Terminal event. `chunk.value.object` is fully validated and typed
+    // against the schema you passed in — no helper or cast required.
+    chunk.value.object.name // string
+    chunk.value.object.age // number
+    chunk.value.reasoning // string | undefined (thinking models only)
+  }
+}
+```
+
+The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-output.complete', value: { object: T, raw: string, reasoning?: string } }`. The return type of `chat({ outputSchema, stream: true })` carries `T` through to the terminal event, so a plain discriminated narrow (`chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete'`) is enough — no type guard helper needed.
+
+**Adapter coverage for streaming:**
+
+| Adapter                                           | `outputSchema` + `stream: true`                                                               |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@tanstack/ai-openai`                             | Native single-request stream (Responses API)                                                  |
+| `@tanstack/ai-openrouter`                         | Native single-request stream                                                                  |
+| `@tanstack/ai-grok`                               | Native single-request stream (Chat Completions)                                               |
+| `@tanstack/ai-groq`                               | Native single-request stream (Chat Completions)                                               |
+| All other adapters (anthropic, gemini, ollama, …) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event |
+
+The consumer code is identical across providers — always read the final object off `structured-output.complete`. You only see incremental deltas when the adapter implements `structuredOutputStream` natively.
+
 ## Common Mistakes
 
+### HIGH: Parsing streaming JSON deltas yourself
+
+When using `chat({ outputSchema, stream: true })`, the `TEXT_MESSAGE_CONTENT` chunks contain _partial_ JSON fragments — they are not valid JSON until the stream completes. Always read the validated object from the terminal `structured-output.complete` event. Validation runs once, on the complete payload.
+
+```typescript
+// WRONG -- partial JSON, throws SyntaxError mid-stream, no schema validation
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    const obj = JSON.parse(chunk.delta) // ❌ partial, invalid
+  }
+}
+
+// CORRECT -- accumulate deltas only for UX progress; trust the terminal event
+let raw = ''
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    raw += chunk.delta // optional: render a "streaming JSON" preview
+  } else if (
+    chunk.type === 'CUSTOM' &&
+    chunk.name === 'structured-output.complete'
+  ) {
+    const result = chunk.value.object // ✅ typed and validated
+  }
+}
+```
+
+If you need progressive _parsed_ state (e.g. show fields as they arrive), use a partial-JSON parser on the accumulated `raw` string at render time — but do NOT treat the result as schema-validated; only the terminal event is.
+
+Source: maintainer interview
+
 ### HIGH: Trying to implement provider-specific structured output strategies
 
 The adapter already handles provider differences (OpenAI uses `response_format`, Anthropic uses tool-based extraction, Gemini uses `responseSchema`). Never configure this yourself.
@@ -201,3 +291,4 @@ Source: maintainer interview
 ## Cross-References
 
 - See also: ai-core/adapter-configuration/SKILL.md -- Adapter handles structured output strategy transparently
+- See also: ai-core/chat-experience/SKILL.md -- Consuming `StreamChunk` events on the client (the streaming variant uses the same chunk model plus the terminal `structured-output.complete` custom event)

package/src/activities/chat/adapter.ts

@@ -54,6 +54,7 @@ export interface StructuredOutputResult<T = unknown> {
  * - TInputModalities: Supported input modalities for this model (already resolved)
  * - TMessageMetadata: Metadata types for content parts (already resolved)
  * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`
+ * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)
  */
 export interface TextAdapter<
   TModel extends string,
@@ -61,6 +62,7 @@ export interface TextAdapter<
   TInputModalities extends ReadonlyArray<Modality>,
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TToolCallMetadata = unknown,
 > {
   /** Discriminator for adapter kind */
   readonly kind: 'text'
@@ -77,6 +79,7 @@ export interface TextAdapter<
     inputModalities: TInputModalities
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
+    toolCallMetadata: TToolCallMetadata
   }
 
   /**
@@ -97,13 +100,30 @@ export interface TextAdapter<
   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.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyTextAdapter = TextAdapter<any, any, any, any, any>
+export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any>
 
 /**
  * Abstract base class for text adapters.
@@ -117,12 +137,14 @@ export abstract class BaseTextAdapter<
   TInputModalities extends ReadonlyArray<Modality>,
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TToolCallMetadata = unknown,
 > implements TextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   TMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  TToolCallMetadata
 > {
   readonly kind = 'text' as const
   abstract readonly name: string
@@ -134,6 +156,7 @@ export abstract class BaseTextAdapter<
     inputModalities: TInputModalities
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
+    toolCallMetadata: TToolCallMetadata
   }
 
   protected config: TextAdapterConfig