@tanstack/ai 0.19.1 → 0.20.1

package/src/activities/chat/tools/schema-converter.ts

@@ -1,11 +1,29 @@
-/* eslint-disable @typescript-eslint/no-unnecessary-condition */
-
 import type {
   StandardJSONSchemaV1,
   StandardSchemaV1,
 } from '@standard-schema/spec'
 import type { JSONSchema, SchemaInput } from '../../../types'
 
+/**
+ * Build a JSONSchema object from any plain key/value source. The `JSONSchema`
+ * interface's `[key: string]: any` index signature makes every property
+ * assignable through bracket access without a type cast — copying keys here
+ * lets us narrow either `Record<string, unknown>` (returned by
+ * `~standard.jsonSchema.input()`) or a `JSONSchema` (from the SchemaInput
+ * pass-through arm) into the typed view used by the rest of this module.
+ *
+ * Accepts `object` so callers don't need a cast when narrowing from union
+ * types like `SchemaInput`.
+ */
+function toJsonSchema(obj: object): JSONSchema {
+  const result: JSONSchema = {}
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === '$schema') continue // not needed by LLM providers
+    result[key] = value
+  }
+  return result
+}
+
 /**
  * Check if a value is a Standard JSON Schema compliant schema.
  * Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)
@@ -19,6 +37,7 @@ export function isStandardJSONSchema(
     schema !== null &&
     '~standard' in schema &&
     typeof (schema as StandardJSONSchemaV1)['~standard'] === 'object' &&
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for caller-provided unknown; type assertion narrows but doesn't validate the wire payload
     (schema as StandardJSONSchemaV1)['~standard'].version === 1 &&
     typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema ===
       'object' &&
@@ -37,9 +56,9 @@ export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
     schema !== null &&
     '~standard' in schema &&
     typeof schema['~standard'] === 'object' &&
-    schema !== null &&
     schema['~standard'] !== null &&
     'version' in schema['~standard'] &&
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for caller-provided unknown; in-operator narrows but doesn't validate the wire payload
     schema['~standard'].version === 1 &&
     'validate' in schema['~standard'] &&
     typeof schema['~standard'].validate === 'function'
@@ -58,19 +77,20 @@ export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
  * @returns Transformed schema compatible with OpenAI structured output
  */
 function makeStructuredOutputCompatible(
-  schema: Record<string, any>,
+  schema: JSONSchema,
   originalRequired: Array<string> = [],
-): Record<string, any> {
-  const result = { ...schema }
+): JSONSchema {
+  const result: JSONSchema = { ...schema }
 
   // Handle object types
   if (result.type === 'object' && result.properties) {
-    const properties = { ...result.properties }
+    const properties: Record<string, JSONSchema> = { ...result.properties }
     const allPropertyNames = Object.keys(properties)
 
     // Transform each property
     for (const propName of allPropertyNames) {
       const prop = properties[propName]
+      if (!prop) continue
       const wasOptional = !originalRequired.includes(propName)
 
       // Recursively transform nested objects/arrays
@@ -83,12 +103,12 @@ function makeStructuredOutputCompatible(
           ? { ...transformed, type: ['object', 'null'] }
           : transformed
       } else if (prop.type === 'array' && prop.items) {
-        const transformed = {
+        const items = Array.isArray(prop.items) ? prop.items[0] : prop.items
+        const transformed: JSONSchema = {
           ...prop,
-          items: makeStructuredOutputCompatible(
-            prop.items,
-            prop.items.required || [],
-          ),
+          items: items
+            ? makeStructuredOutputCompatible(items, items.required || [])
+            : prop.items,
         }
         properties[propName] = wasOptional
           ? { ...transformed, type: ['array', 'null'] }
@@ -118,10 +138,10 @@ function makeStructuredOutputCompatible(
 
   // Handle array types with object items
   if (result.type === 'array' && result.items) {
-    result.items = makeStructuredOutputCompatible(
-      result.items,
-      result.items.required || [],
-    )
+    const items = Array.isArray(result.items) ? result.items[0] : result.items
+    if (items) {
+      result.items = makeStructuredOutputCompatible(items, items.required || [])
+    }
   }
 
   return result
@@ -216,42 +236,33 @@ export function convertSchemaToJsonSchema(
       target: 'draft-07',
     })
 
-    let result = jsonSchema
-
-    if (typeof result === 'object' && '$schema' in result) {
-      // Remove $schema property as it's not needed for LLM providers
-      const { $schema, ...rest } = result
-      result = rest
-    }
+    // Rebuild structurally so the typed JSONSchema view is acquired without
+    // a `Record<string, unknown> as JSONSchema` cast; `toJsonSchema()` also
+    // drops the `$schema` key which LLM providers don't need.
+    let result: JSONSchema = toJsonSchema(jsonSchema)
 
     // Ensure object schemas always have type: "object"
+    // If it has properties (even empty), it should be an object type
+    if ('properties' in result && !result.type) {
+      result.type = 'object'
+    }
 
-    if (typeof result === 'object') {
-      // If it has properties (even empty), it should be an object type
-      if ('properties' in result && !result.type) {
-        result.type = 'object'
-      }
-
-      // Ensure properties exists for object types (even if empty)
-      if (result.type === 'object' && !('properties' in result)) {
-        result.properties = {}
-      }
+    // Ensure properties exists for object types (even if empty)
+    if (result.type === 'object' && !('properties' in result)) {
+      result.properties = {}
+    }
 
-      // Ensure required exists for object types (even if empty array)
-      if (result.type === 'object' && !('required' in result)) {
-        result.required = []
-      }
+    // Ensure required exists for object types (even if empty array)
+    if (result.type === 'object' && !('required' in result)) {
+      result.required = []
+    }
 
-      // Apply structured output transformation if requested
-      if (forStructuredOutput) {
-        result = makeStructuredOutputCompatible(
-          result,
-          (result.required as Array<string>) || [],
-        )
-      }
+    // Apply structured output transformation if requested
+    if (forStructuredOutput) {
+      result = makeStructuredOutputCompatible(result, result.required || [])
     }
 
-    return result as JSONSchema
+    return result
   }
 
   // Detect Standard Schema validators (Zod, ArkType, Valibot, …) that don't
@@ -271,14 +282,25 @@ export function convertSchemaToJsonSchema(
   // If it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through
   // Still apply structured output transformation if requested
 
-  if (forStructuredOutput && typeof schema === 'object') {
-    return makeStructuredOutputCompatible(
-      schema as Record<string, any>,
-      ((schema as JSONSchema).required as Array<string>) || [],
-    ) as JSONSchema
+  // At this branch, `schema` is the plain `JSONSchema` arm of `SchemaInput`
+  // (the two `~standard` arms were handled above). When no transformation
+  // is requested we pass the schema through by reference to preserve
+  // identity for callers that compare via `===`.
+  if (typeof schema !== 'object') {
+    // The SchemaInput union is object-shaped on every arm; if we ever hit a
+    // non-object here, propagate it untouched and let the downstream
+    // provider error loudly rather than silently widen.
+    return schema
   }
 
-  return schema as JSONSchema
+  if (forStructuredOutput) {
+    // Build a typed view structurally so we don't need a SchemaInput→JSONSchema
+    // cast on the transformation path.
+    const typedView = toJsonSchema(schema)
+    return makeStructuredOutputCompatible(typedView, typedView.required || [])
+  }
+
+  return schema
 }
 
 /**
@@ -293,7 +315,10 @@ export async function validateWithStandardSchema<T>(
   data: unknown,
 ): Promise<
   | { success: true; data: T }
-  | { success: false; issues: Array<{ message: string; path?: Array<string> }> }
+  | {
+      success: false
+      issues: Array<{ message: string; path?: Array<string> | undefined }>
+    }
 > {
   if (!isStandardSchema(schema)) {
     // If it's not a Standard Schema, just return the data as-is

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

@@ -227,6 +227,11 @@ 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,

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 {
@@ -104,6 +105,10 @@ export type {
 // All types
 export * from './types'
 
+// System prompts (type + normaliser used by adapters)
+export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts'
+export { normalizeSystemPrompts } from './system-prompts'
+
 // Utility functions
 export { detectImageMimeType } from './utils'
 

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(' ')
@@ -372,9 +375,29 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
         state.assistantTextBufferTruncated = false
 
         if (captureContent) {
+          const systemPromptContents = config.systemPrompts.map((p) =>
+            typeof p === 'string' ? p : p.content,
+          )
+          // Anthropic prompt-caching users need to know which prompt carried
+          // `cache_control`: it's the one attribute that explains cache
+          // hit/miss in observability. Serialise per-prompt metadata as a
+          // single JSON span attribute so backends that don't understand
+          // GenAI events can still surface it. Kept off span events to
+          // avoid breaking the one-event-per-message GenAI semconv contract.
+          const systemPromptMetadata = config.systemPrompts.map((p) =>
+            typeof p === 'string' || p.metadata === undefined
+              ? null
+              : p.metadata,
+          )
+          if (systemPromptMetadata.some((m) => m !== null)) {
+            iterSpan.setAttribute(
+              'tanstack.ai.system_prompt.metadata',
+              JSON.stringify(systemPromptMetadata),
+            )
+          }
           // Span events follow the original GenAI semconv (one event per
           // message). Backends that read events get content this way.
-          for (const sys of config.systemPrompts) {
+          for (const sys of systemPromptContents) {
             iterSpan.addEvent('gen_ai.system.message', {
               content: redactContent(sys),
             })
@@ -391,7 +414,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
           // (`gen_ai.input.messages`) — backends like PostHog read prompt
           // content from this attribute, not from span events.
           const inputMessages: Array<{ role: string; content: string }> = []
-          for (const sys of config.systemPrompts) {
+          for (const sys of systemPromptContents) {
             inputMessages.push({
               role: 'system',
               content: redactContent(sys),
@@ -610,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 }),
           })
         }
 
@@ -668,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?.(
@@ -683,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?.(
               {
@@ -711,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, {
@@ -743,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?.(
               {
@@ -752,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.