@tanstack/ai 0.20.0 → 0.21.0

package/src/activities/chat/tools/tool-calls.ts

@@ -81,8 +81,8 @@ export class MiddlewareAbortError extends Error {
  * ```
  */
 export class ToolCallManager {
-  private toolCallsMap = new Map<number, ToolCall>()
-  private tools: ReadonlyArray<Tool>
+  private readonly toolCallsMap = new Map<number, ToolCall>()
+  private readonly tools: ReadonlyArray<Tool>
 
   constructor(tools: ReadonlyArray<Tool>) {
     this.tools = tools
@@ -320,14 +320,16 @@ async function* executeWithEventPolling<T>(
     ])
 
     // Flush any pending events
-    while (pendingEvents.length > 0) {
-      yield pendingEvents.shift()!
+    let event: CustomEvent | undefined
+    while ((event = pendingEvents.shift()) !== undefined) {
+      yield event
     }
   }
 
   // Final flush in case events were emitted right at completion
-  while (pendingEvents.length > 0) {
-    yield pendingEvents.shift()!
+  let event: CustomEvent | undefined
+  while ((event = pendingEvents.shift()) !== undefined) {
+    yield event
   }
 
   return state.result
@@ -404,13 +406,17 @@ async function* executeServerTool(
 ): AsyncGenerator<CustomEvent, void, void> {
   const startTime = Date.now()
   try {
-    const executionPromise = Promise.resolve(tool.execute!(input, context))
+    if (!tool.execute) {
+      throw new Error(`Tool ${toolName} has no execute() implementation`)
+    }
+    const executionPromise = Promise.resolve(tool.execute(input, context))
     let result = yield* executeWithEventPolling(executionPromise, pendingEvents)
     const duration = Date.now() - startTime
 
     // Flush remaining events
-    while (pendingEvents.length > 0) {
-      yield pendingEvents.shift()!
+    let pendingEvent: CustomEvent | undefined
+    while ((pendingEvent = pendingEvents.shift()) !== undefined) {
+      yield pendingEvent
     }
 
     // Validate output against outputSchema if provided
@@ -448,8 +454,9 @@ async function* executeServerTool(
     const duration = Date.now() - startTime
 
     // Flush remaining events
-    while (pendingEvents.length > 0) {
-      yield pendingEvents.shift()!
+    let pendingEvent: CustomEvent | undefined
+    while ((pendingEvent = pendingEvents.shift()) !== undefined) {
+      yield pendingEvent
     }
 
     if (error instanceof MiddlewareAbortError) {

package/src/activities/chat/tools/tool-definition.ts

@@ -29,6 +29,11 @@ export interface ClientTool<
   __toolSide: 'client'
   name: TName
   description: string
+  // Note: `inputSchema` / `outputSchema` stay as bare optionals (not
+  // widened to `| undefined`). They participate in inference via
+  // `InferToolInput` / `InferToolOutput` — widening with `| undefined`
+  // breaks the `infer TInput extends StandardJSONSchemaV1<...>` chain
+  // because `undefined` doesn't extend the schema constraint.
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
@@ -215,7 +220,7 @@ export function toolDefinition<
       return {
         __toolSide: 'client',
         ...config,
-        execute,
+        ...(execute !== undefined && { execute }),
       }
     },
   }

package/src/activities/generateAudio/index.ts

@@ -27,10 +27,11 @@ export const kind = 'audio' as const
 /**
  * Extract provider options from an AudioAdapter via ~types.
  */
-export type AudioProviderOptions<TAdapter> =
-  TAdapter extends AudioAdapter<any, any>
-    ? TAdapter['~types']['providerOptions']
-    : object
+export type AudioProviderOptions<TAdapter> = TAdapter extends {
+  '~types': { providerOptions: infer P extends object }
+}
+  ? P
+  : object
 
 // ===========================
 // Activity Options Type

package/src/activities/generateImage/index.ts

@@ -210,7 +210,7 @@ async function runGenerateImage<
     prompt: rest.prompt,
     numberOfImages: rest.numberOfImages,
     size: rest.size,
-    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+    modelOptions: rest.modelOptions,
     timestamp: startTime,
   })
 
@@ -227,12 +227,17 @@ async function runGenerateImage<
       requestId,
       provider: adapter.name,
       model,
+      // GeneratedImage is a discriminated `{ url } | { b64Json }` union, but the
+      // wire shape on the devtools event is a plain optional pair. Use
+      // conditional spreads so the emitted record only sets the field actually
+      // present — `exactOptionalPropertyTypes` rejects `field: undefined`
+      // against `field?: string` targets.
       images: result.images.map((image) => ({
         url: image.url,
         b64Json: image.b64Json,
       })),
       duration,
-      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      modelOptions: rest.modelOptions,
       timestamp: Date.now(),
     })
 
@@ -241,7 +246,7 @@ async function runGenerateImage<
         requestId,
         model,
         usage: result.usage,
-        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+        modelOptions: rest.modelOptions,
         timestamp: Date.now(),
       })
     }

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/extend-adapter.ts

@@ -65,7 +65,7 @@ export function createModel<
   return {
     name,
     input,
-    modelOptions: {} as unknown,
+    modelOptions: {},
   }
 }
 

package/src/index.ts

@@ -53,7 +53,10 @@ export {
 } from './activities/chat/tools/tool-definition'
 
 // Schema conversion (Standard JSON Schema compliant)
-export { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter'
+export {
+  convertSchemaToJsonSchema,
+  StandardSchemaValidationError,
+} from './activities/chat/tools/schema-converter'
 
 // Stream utilities
 export {
@@ -69,6 +72,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 {
@@ -90,6 +94,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
   AfterToolCallInfo,

package/src/middlewares/content-guard.ts

@@ -142,11 +142,16 @@ 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(' ')
@@ -253,10 +256,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
     const span = state.currentIterationSpan
     const iteration = state.iterationCount - 1
     safeCall('otel.onSpanEnd', () =>
-      onSpanEnd?.(
-        { kind: 'iteration', ctx, iteration } as OtelSpanInfo<'iteration'>,
-        span,
-      ),
+      onSpanEnd?.({ kind: 'iteration', ctx, iteration }, span),
     )
     span.end()
     state.currentIterationSpan = null
@@ -630,9 +630,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 }),
           })
         }
 
@@ -672,7 +673,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
               toolName: info.toolName,
               toolCallId: info.toolCallId,
               iteration: state.iterationCount - 1,
-            } as OtelSpanInfo<'tool'>,
+            },
             toolSpan,
           ),
         )
@@ -688,13 +689,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?.(
@@ -702,18 +706,18 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 kind: 'iteration',
                 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?.(
               {
@@ -722,7 +726,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )
@@ -731,7 +735,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,19 +770,20 @@ 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?.(
               {
                 kind: 'iteration',
                 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) {
@@ -789,7 +797,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )
@@ -834,7 +842,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )

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/strip-to-spec-middleware.ts

@@ -12,10 +12,7 @@ import type { StreamChunk } from './types'
  */
 export function stripToSpec(chunk: StreamChunk): StreamChunk {
   // Only strip the deprecated nested error object from RUN_ERROR
-  if (
-    (chunk as StreamChunk & { type: string }).type === 'RUN_ERROR' &&
-    'error' in chunk
-  ) {
+  if (chunk.type === 'RUN_ERROR' && 'error' in chunk) {
     const { error: _deprecated, ...rest } = chunk as Record<string, unknown>
     return rest as StreamChunk
   }

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

@@ -53,6 +53,7 @@ export function uiMessagesToWire(
     // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.
     // UIMessage always has parts; ModelMessage uses content directly.
     const parts: ReadonlyArray<MessagePart> =
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- runtime input may be ModelMessage-shaped (no `parts`); cast forces the optional-chain fallback below to remain in scope
       (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []
 
     if (msg.role === 'system') {
@@ -61,7 +62,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 +73,7 @@ export function uiMessagesToWire(
         content:
           parts.length > 0
             ? collectUserContent(parts)
-            : ((msg as unknown as { content?: string }).content ?? ''),
+            : ((msg as { content?: string }).content ?? ''),
       })
       continue
     }
@@ -161,7 +162,7 @@ function collectUserContent(
       p.type === 'video' ||
       p.type === 'document'
     ) {
-      out.push(p as AGUIInputContent)
+      out.push(p)
     }
   }
   return out

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
   }
 }