@tanstack/ai 0.16.0 → 0.18.0

package/src/activities/error-payload.ts

@@ -5,16 +5,45 @@
  * Accepts Error instances, objects with string-ish `message`/`code`, or bare
  * strings; always returns a shape safe to serialize. Never leaks the full
  * error object (which may carry request/response state from an SDK).
+ *
+ * Abort-shaped errors (DOM `AbortError`, OpenAI `APIUserAbortError`,
+ * OpenRouter `RequestAbortedError`) are normalized to a stable
+ * `{ message: 'Request aborted', code: 'aborted' }` shape so callers can
+ * discriminate user-initiated cancellation from other failures without
+ * matching on provider-specific message strings.
  */
+const ABORT_ERROR_NAMES = new Set([
+  'AbortError',
+  'APIUserAbortError',
+  'RequestAbortedError',
+])
+
+// HTTP status codes carried as numbers (e.g. `error.status = 429`) are a
+// common variant on SDK error classes; coerce so the resulting `code` field
+// is stable as a string for downstream consumers.
+function normalizeCode(codeField: unknown): string | undefined {
+  if (typeof codeField === 'string') return codeField
+  if (typeof codeField === 'number' && Number.isFinite(codeField)) {
+    return String(codeField)
+  }
+  return undefined
+}
+
 export function toRunErrorPayload(
   error: unknown,
   fallbackMessage = 'Unknown error occurred',
 ): { message: string; code: string | undefined } {
+  if (error && typeof error === 'object') {
+    const name = (error as { name?: unknown }).name
+    if (typeof name === 'string' && ABORT_ERROR_NAMES.has(name)) {
+      return { message: 'Request aborted', code: 'aborted' }
+    }
+  }
   if (error instanceof Error) {
     const codeField = (error as Error & { code?: unknown }).code
     return {
       message: error.message || fallbackMessage,
-      code: typeof codeField === 'string' ? codeField : undefined,
+      code: normalizeCode(codeField),
     }
   }
   if (typeof error === 'object' && error !== null) {
@@ -25,7 +54,7 @@ export function toRunErrorPayload(
         typeof messageField === 'string' && messageField.length > 0
           ? messageField
           : fallbackMessage,
-      code: typeof codeField === 'string' ? codeField : undefined,
+      code: normalizeCode(codeField),
     }
   }
   if (typeof error === 'string' && error.length > 0) {

package/src/activities/generateImage/adapter.ts

@@ -34,7 +34,10 @@ export interface ImageAdapter<
   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 by generate() to determine API shape */
   readonly kind: 'image'
@@ -76,7 +79,10 @@ export abstract class BaseImageAdapter<
   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 ImageAdapter<
   TModel,
   TProviderOptions,

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/index.ts

@@ -168,6 +168,17 @@ export type {
   JSONParser,
 } from './activities/chat/stream/index'
 
+// Chat utilities
+export {
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  mergeAgentTools,
+} from './utilities/chat-params'
+
+// AG-UI wire serialization (used internally by @tanstack/ai-client)
+export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { WireMessage } from './utilities/ag-ui-wire'
+
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef } from './extend-adapter'