@tanstack/ai 0.16.0 → 0.17.0

package/src/activities/generateVideo/adapter.ts

@@ -36,7 +36,10 @@ export interface VideoAdapter<
   TModel extends string = string,
   TProviderOptions extends object = Record<string, unknown>,
   TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
-  TModelSizeByName extends Record<string, string> = Record<string, string>,
+  TModelSizeByName extends Record<string, string | undefined> = Record<
+    string,
+    string
+  >,
 > {
   /** Discriminator for adapter kind - used to determine API shape */
   readonly kind: 'video'
@@ -92,7 +95,10 @@ export abstract class BaseVideoAdapter<
   TModel extends string = string,
   TProviderOptions extends object = Record<string, unknown>,
   TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
-  TModelSizeByName extends Record<string, string> = Record<string, string>,
+  TModelSizeByName extends Record<string, string | undefined> = Record<
+    string,
+    string
+  >,
 > implements VideoAdapter<
   TModel,
   TProviderOptions,

package/src/activities/index.ts

@@ -60,6 +60,11 @@ export {
   type SummarizeAdapterConfig,
   type AnySummarizeAdapter,
 } from './summarize/adapter'
+export {
+  ChatStreamSummarizeAdapter,
+  type ChatStreamCapable,
+  type InferTextProviderOptions,
+} from './summarize/chat-stream-summarize'
 
 // ===========================
 // Image Activity

package/src/activities/stream-generation-result.ts

@@ -34,7 +34,7 @@ export async function* streamGenerationResult<TResult>(
     runId,
     threadId,
     timestamp: Date.now(),
-  } as StreamChunk
+  }
 
   try {
     const result = await generator()
@@ -44,7 +44,7 @@ export async function* streamGenerationResult<TResult>(
       name: 'generation:result',
       value: result as unknown,
       timestamp: Date.now(),
-    } as StreamChunk
+    }
 
     yield {
       type: EventType.RUN_FINISHED,
@@ -52,18 +52,16 @@ export async function* streamGenerationResult<TResult>(
       threadId,
       finishReason: 'stop',
       timestamp: Date.now(),
-    } as StreamChunk
+    }
   } catch (error: unknown) {
     const payload = toRunErrorPayload(error, 'Generation failed')
     yield {
       type: EventType.RUN_ERROR,
-      runId,
-      threadId,
       message: payload.message,
       code: payload.code,
       // Deprecated nested form for backward compatibility
       error: payload,
       timestamp: Date.now(),
-    } as StreamChunk
+    }
   }
 }

package/src/activities/summarize/adapter.ts

@@ -46,7 +46,9 @@ export interface SummarizeAdapter<
   /**
    * Summarize the given text
    */
-  summarize: (options: SummarizationOptions) => Promise<SummarizationResult>
+  summarize: (
+    options: SummarizationOptions<TProviderOptions>,
+  ) => Promise<SummarizationResult>
 
   /**
    * Stream summarization of the given text.
@@ -54,7 +56,7 @@ export interface SummarizeAdapter<
    * non-streaming summarize and yield the result as a single chunk.
    */
   summarizeStream?: (
-    options: SummarizationOptions,
+    options: SummarizationOptions<TProviderOptions>,
   ) => AsyncIterable<StreamChunk>
 }
 
@@ -91,7 +93,7 @@ export abstract class BaseSummarizeAdapter<
   }
 
   abstract summarize(
-    options: SummarizationOptions,
+    options: SummarizationOptions<TProviderOptions>,
   ): Promise<SummarizationResult>
 
   /**
@@ -99,7 +101,9 @@ export abstract class BaseSummarizeAdapter<
    * Override this method in concrete implementations to enable streaming.
    * If not overridden, the activity layer will fall back to non-streaming.
    */
-  summarizeStream?(options: SummarizationOptions): AsyncIterable<StreamChunk>
+  summarizeStream?(
+    options: SummarizationOptions<TProviderOptions>,
+  ): AsyncIterable<StreamChunk>
 
   protected generateId(): string {
     return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`

package/src/activities/summarize/chat-stream-summarize.ts

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

package/src/activities/summarize/index.ts

@@ -11,11 +11,7 @@ import { resolveDebugOption } from '../../logger/resolve'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { SummarizeAdapter } from './adapter'
-import type {
-  StreamChunk,
-  SummarizationOptions,
-  SummarizationResult,
-} from '../../types'
+import type { StreamChunk, SummarizationResult } from '../../types'
 
 // ===========================
 // Activity Kind
@@ -184,7 +180,7 @@ export function summarize<
 async function runSummarize(
   options: SummarizeActivityOptions<SummarizeAdapter<string, object>, false>,
 ): Promise<SummarizationResult> {
-  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
@@ -205,12 +201,13 @@ async function runSummarize(
     inputLength,
   })
 
-  const summarizeOptions: SummarizationOptions = {
+  const summarizeOptions = {
     model,
     text,
     maxLength,
     style,
     focus,
+    modelOptions,
     logger,
   }
 
@@ -253,7 +250,7 @@ async function runSummarize(
 async function* runStreamingSummarize(
   options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, text, maxLength, style, focus } = options
+  const { adapter, text, maxLength, style, focus, modelOptions } = options
   const model = adapter.model
   const logger: InternalLogger = resolveDebugOption(options.debug)
 
@@ -263,12 +260,13 @@ async function* runStreamingSummarize(
     stream: true,
   })
 
-  const summarizeOptions: SummarizationOptions = {
+  const summarizeOptions = {
     model,
     text,
     maxLength,
     style,
     focus,
+    modelOptions,
     logger,
   }
 
@@ -313,3 +311,8 @@ export type {
   AnySummarizeAdapter,
 } from './adapter'
 export { BaseSummarizeAdapter } from './adapter'
+export {
+  ChatStreamSummarizeAdapter,
+  type ChatStreamCapable,
+  type InferTextProviderOptions,
+} from './chat-stream-summarize'

package/src/types.ts

@@ -1057,6 +1057,106 @@ export interface CustomEvent extends AGUICustomEvent {
   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
+>
+
 // ============================================================================
 // AG-UI Reasoning Event Interfaces
 // ============================================================================
@@ -1179,12 +1279,16 @@ export interface TextCompletionChunk {
   }
 }
 
-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.
@@ -1213,7 +1317,7 @@ export interface SummarizationResult {
  */
 export interface ImageGenerationOptions<
   TProviderOptions extends object = object,
-  TSize extends string = string,
+  TSize extends string | undefined = string,
 > {
   /** The model to use for image generation */
   model: string
@@ -1343,7 +1447,7 @@ export interface AudioGenerationResult {
  */
 export interface VideoGenerationOptions<
   TProviderOptions extends object = object,
-  TSize extends string = string,
+  TSize extends string | undefined = string,
 > {
   /** The model to use for video generation */
   model: string