@tanstack/ai 0.20.0 → 0.20.1

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

@@ -55,12 +55,21 @@ export async function* streamGenerationResult<TResult>(
     }
   } catch (error: unknown) {
     const payload = toRunErrorPayload(error, 'Generation failed')
+    // `code` is omitted entirely when undefined so the event matches the
+    // AG-UI `code?: string` shape under `exactOptionalPropertyTypes`. The
+    // deprecated nested `error` form preserves the same conditional
+    // structure for backward compatibility.
+    const codeFields =
+      payload.code !== undefined ? { code: payload.code } : undefined
     yield {
       type: EventType.RUN_ERROR,
       message: payload.message,
-      code: payload.code,
+      ...codeFields,
       // Deprecated nested form for backward compatibility
-      error: payload,
+      error: {
+        message: payload.message,
+        ...codeFields,
+      },
       timestamp: Date.now(),
     }
   }

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

@@ -46,7 +46,7 @@ export class ChatStreamSummarizeAdapter<
 > extends BaseSummarizeAdapter<TModel, TProviderOptions> {
   readonly name: string
 
-  private textAdapter: ChatStreamCapable
+  private readonly textAdapter: ChatStreamCapable
 
   constructor(
     textAdapter: ChatStreamCapable,
@@ -124,7 +124,7 @@ export class ChatStreamSummarizeAdapter<
     return { id, model, summary, usage }
   }
 
-  async *summarizeStream(
+  override async *summarizeStream(
     options: SummarizationOptions<TProviderOptions>,
   ): AsyncIterable<StreamChunk> {
     const systemPrompt = this.buildSummarizationPrompt(options)
@@ -221,6 +221,9 @@ export class ChatStreamSummarizeAdapter<
       case 'concise':
         prompt += 'Provide a very concise summary in 1-2 sentences. '
         break
+      case undefined:
+        prompt += 'Provide a clear and concise summary. '
+        break
       default:
         prompt += 'Provide a clear and concise summary. '
     }

package/src/activities/summarize/index.ts

@@ -159,7 +159,7 @@ export function summarize<
 
   if (stream) {
     return runStreamingSummarize(
-      options as unknown as SummarizeActivityOptions<
+      options as SummarizeActivityOptions<
         SummarizeAdapter<string, object>,
         true
       >,
@@ -167,7 +167,7 @@ export function summarize<
   }
 
   return runSummarize(
-    options as unknown as SummarizeActivityOptions<
+    options as SummarizeActivityOptions<
       SummarizeAdapter<string, object>,
       false
     >,

package/src/index.ts

@@ -69,6 +69,7 @@ export { ToolCallManager } from './activities/chat/tools/tool-calls'
 
 // Provider tool type
 export type { ProviderTool } from './tools/provider-tool'
+export { brandProviderTool } from './tools/provider-tool'
 
 // Agent loop strategies
 export {

package/src/middlewares/content-guard.ts

@@ -142,10 +142,15 @@ function createDeltaStrategy(
 
       if (blockOnMatch) return null // drop chunk
 
+      // Strip out the previous `content` field by destructuring it away — with
+      // `exactOptionalPropertyTypes` we can't assign `content: undefined`
+      // against `content?: string`. The replacement event carries only the
+      // filtered delta.
+      const { content: _strippedContent, ...rest } = chunk
+      void _strippedContent
       return {
-        ...chunk,
+        ...rest,
         delta: filtered,
-        content: undefined,
       } as StreamChunk
     },
   }
@@ -278,8 +283,11 @@ function createBufferedStrategy(
         content: filtered.slice(0, safeFilteredEnd),
       } as StreamChunk
 
+      // `pending` was empty before this push iff `emitChunk` is now the only
+      // entry — return it directly without re-indexing through `pending[0]`.
+      const wasEmpty = pending.length === 0
       pending.push(emitChunk)
-      return pending.length === 1 ? pending[0]! : pending
+      return wasEmpty ? emitChunk : pending
     },
   }
 }

package/src/middlewares/otel.ts

@@ -137,8 +137,11 @@ function serializeContent(content: unknown): string {
       case 'document':
         parts.push('[document]')
         break
+      case undefined:
+        parts.push('[unknown]')
+        break
       default:
-        parts.push(`[${type ?? 'unknown'}]`)
+        parts.push(`[${type}]`)
     }
   }
   return parts.join(' ')
@@ -630,9 +633,10 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
 
         if (!info.ok && info.error !== undefined) {
           toolSpan.recordException(info.error as Exception)
+          const msg = errorMessage(info.error)
           toolSpan.setStatus({
             code: SpanStatusCode.ERROR,
-            message: errorMessage(info.error),
+            ...(msg !== undefined && { message: msg }),
           })
         }
 
@@ -688,13 +692,16 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
 
         const errType = errorTypeName(info.error)
         const message = errorMessage(info.error)
+        const statusMessage =
+          message !== undefined ? { message } : ({} as const)
         const exception = info.error as Exception
 
-        if (state.currentIterationSpan) {
-          state.currentIterationSpan.recordException(exception)
-          state.currentIterationSpan.setStatus({
+        const iterationSpan = state.currentIterationSpan
+        if (iterationSpan) {
+          iterationSpan.recordException(exception)
+          iterationSpan.setStatus({
             code: SpanStatusCode.ERROR,
-            message,
+            ...statusMessage,
           })
           safeCall('otel.onSpanEnd', () =>
             onSpanEnd?.(
@@ -703,17 +710,17 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 ctx,
                 iteration: state.iterationCount - 1,
               } as OtelSpanInfo<'iteration'>,
-              state.currentIterationSpan!,
+              iterationSpan,
             ),
           )
-          state.currentIterationSpan.end()
+          iterationSpan.end()
           state.currentIterationSpan = null
         }
 
         for (const [id, entry] of state.toolSpans) {
           const { span, toolName } = entry
           span.recordException(exception)
-          span.setStatus({ code: SpanStatusCode.ERROR, message })
+          span.setStatus({ code: SpanStatusCode.ERROR, ...statusMessage })
           safeCall('otel.onSpanEnd', () =>
             onSpanEnd?.(
               {
@@ -731,7 +738,10 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         }
 
         state.rootSpan.recordException(exception)
-        state.rootSpan.setStatus({ code: SpanStatusCode.ERROR, message })
+        state.rootSpan.setStatus({
+          code: SpanStatusCode.ERROR,
+          ...statusMessage,
+        })
 
         if (durationHistogram) {
           durationHistogram.record(info.duration / 1000, {
@@ -763,8 +773,9 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
           span.setStatus({ code: SpanStatusCode.ERROR, message: 'cancelled' })
         }
 
-        if (state.currentIterationSpan) {
-          closeCancelled(state.currentIterationSpan)
+        const iterationSpan = state.currentIterationSpan
+        if (iterationSpan) {
+          closeCancelled(iterationSpan)
           safeCall('otel.onSpanEnd', () =>
             onSpanEnd?.(
               {
@@ -772,10 +783,10 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 ctx,
                 iteration: state.iterationCount - 1,
               } as OtelSpanInfo<'iteration'>,
-              state.currentIterationSpan!,
+              iterationSpan,
             ),
           )
-          state.currentIterationSpan.end()
+          iterationSpan.end()
           state.currentIterationSpan = null
         }
         for (const [id, entry] of state.toolSpans) {

package/src/realtime/index.ts

@@ -1,7 +1,7 @@
 import type { RealtimeToken, RealtimeTokenOptions } from './types'
 
 // Re-export all types
-export * from './types'
+export type * from './types'
 
 /**
  * Generate a realtime token using the provided adapter.

package/src/tools/provider-tool.ts

@@ -23,3 +23,17 @@ export interface ProviderTool<
   readonly '~provider': TProvider
   readonly '~toolKind': TKind
 }
+
+/**
+ * Attach the `ProviderTool` phantom brand to a plain `Tool`-shaped object.
+ *
+ * The brand fields (`'~provider'`, `'~toolKind'`) exist only in the type
+ * system and are never assigned at runtime, so this is a single audited
+ * type-only assertion. Use it inside adapter `xxxTool()` factories instead
+ * of `as unknown as` — the cast collapses to one named site.
+ */
+export function brandProviderTool<T extends ProviderTool<string, string>>(
+  tool: Omit<T, '~provider' | '~toolKind'>,
+): T {
+  return tool as T
+}

package/src/types.ts

@@ -586,7 +586,9 @@ export interface Tool<
    *   return weather; // Can return object or string
    * }
    */
-  execute?: (args: any, context?: ToolExecutionContext) => Promise<any> | any
+  execute?:
+    | ((args: any, context?: ToolExecutionContext) => Promise<any> | any)
+    | undefined
 
   /** If true, tool execution requires user approval before running. Works with both server and client tools. */
   needsApproval?: boolean
@@ -595,7 +597,7 @@ export interface Tool<
   lazy?: boolean
 
   /** Additional metadata for adapters or custom extensions */
-  metadata?: Record<string, any>
+  metadata?: Record<string, any> | undefined
 }
 
 export interface ToolConfig {
@@ -729,7 +731,7 @@ export interface TextOptions<
 > {
   model: string
   messages: Array<ModelMessage>
-  tools?: Array<Tool<any, any, any>>
+  tools?: Array<Tool<any, any, any>> | undefined
   /**
    * System prompts to include with the request.
    *
@@ -791,7 +793,7 @@ export interface TextOptions<
    * - Anthropic: `metadata` (Record<string, any>) - includes optional user_id (max 256 chars)
    * - Gemini: Not directly available in TextProviderOptions
    */
-  metadata?: Record<string, any>
+  metadata?: Record<string, any> | undefined
   modelOptions?: TProviderOptionsForModel
   request?: Request | RequestInit
 
@@ -938,10 +940,12 @@ export interface RunErrorEvent extends AGUIRunErrorEvent {
    * @deprecated Use top-level `message` and `code` fields instead.
    * Kept for backward compatibility.
    */
-  error?: {
-    message: string
-    code?: string
-  }
+  error?:
+    | {
+        message: string
+        code?: string | undefined
+      }
+    | undefined
 }
 
 /**

package/src/utilities/ag-ui-wire.ts

@@ -61,7 +61,7 @@ export function uiMessagesToWire(
         content:
           parts.length > 0
             ? collectText(parts)
-            : ((msg as unknown as { content?: string }).content ?? ''),
+            : ((msg as { content?: string }).content ?? ''),
       })
       continue
     }
@@ -72,7 +72,7 @@ export function uiMessagesToWire(
         content:
           parts.length > 0
             ? collectUserContent(parts)
-            : ((msg as unknown as { content?: string }).content ?? ''),
+            : ((msg as { content?: string }).content ?? ''),
       })
       continue
     }

package/src/utilities/chat-params.ts

@@ -131,7 +131,7 @@ export async function chatParamsFromRequest(
       'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
       { status: 400 },
     )
-    ;(res as unknown as { cause?: unknown }).cause = cause
+    ;(res as { cause?: unknown }).cause = cause
     throw res
   }
   try {
@@ -145,7 +145,7 @@ export async function chatParamsFromRequest(
       'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
       { status: 400 },
     )
-    ;(res as unknown as { cause?: unknown }).cause = cause
+    ;(res as { cause?: unknown }).cause = cause
     throw res
   }
 }