@tanstack/ai 0.15.0 → 0.17.0

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

@@ -111,15 +111,17 @@ export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema
 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 // JSON 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
 }
 
 // ============================================================================
@@ -309,7 +311,7 @@ export interface TextPart<TMetadata = unknown> {
   metadata?: TMetadata
 }
 
-export interface ToolCallPart {
+export interface ToolCallPart<TMetadata = unknown> {
   type: 'tool-call'
   id: string
   name: string
@@ -323,6 +325,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 {
@@ -892,7 +897,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 */
@@ -904,8 +909,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>
 }
 
 /**
@@ -1049,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
 // ============================================================================
@@ -1171,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.
@@ -1205,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
@@ -1335,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