@tanstack/ai 0.20.1 → 0.21.1

package/src/activities/chat/messages.ts

@@ -114,7 +114,7 @@ export function convertMessagesToModelMessages(
       modelMessages.push({
         role: 'system' as ModelMessage['role'],
         content: (msg as { content: string }).content,
-      } as ModelMessage)
+      })
       continue
     }
 

package/src/activities/chat/middleware/compose.ts

@@ -11,6 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
+  StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
   UsageInfo,
@@ -71,7 +72,7 @@ export class MiddlewareRunner {
           current = { ...current, ...result }
           if (!skip) {
             this.logger.config(
-              `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result as object).join(',')}`,
+              `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,
               {
                 middleware: mw.name ?? 'unnamed',
                 changes: result,
@@ -94,7 +95,66 @@ export class MiddlewareRunner {
               ...base,
               middlewareName: mw.name || 'unnamed',
               iteration: ctx.iteration,
-              changes: result as Record<string, unknown>,
+              changes: result,
+            })
+          }
+        }
+      }
+    }
+    return current
+  }
+
+  /**
+   * Pipe config through all middleware onStructuredOutputConfig hooks in order.
+   * Each middleware receives the merged config from previous middleware.
+   * Partial returns are shallow-merged with the current config.
+   *
+   * Called once at the structured-output boundary, before runOnConfig at the
+   * same boundary (which receives a ChatMiddlewareConfig view, no outputSchema).
+   */
+  async runOnStructuredOutputConfig(
+    ctx: ChatMiddlewareContext,
+    config: StructuredOutputMiddlewareConfig,
+  ): Promise<StructuredOutputMiddlewareConfig> {
+    let current = config
+    for (const mw of this.middlewares) {
+      if (mw.onStructuredOutputConfig) {
+        const skip = shouldSkipInstrumentation(mw)
+        const start = Date.now()
+        const result = await mw.onStructuredOutputConfig(ctx, current)
+        const hasTransform = result !== undefined && result !== null
+        if (hasTransform) {
+          current = { ...current, ...result }
+          if (!skip) {
+            this.logger.config(
+              `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,
+              {
+                middleware: mw.name ?? 'unnamed',
+                changes: result,
+              },
+            )
+          }
+        }
+        if (!skip) {
+          const base = instrumentCtx(ctx)
+          aiEventClient.emit('middleware:hook:executed', {
+            ...base,
+            middlewareName: mw.name || 'unnamed',
+            hookName: 'onStructuredOutputConfig',
+            iteration: ctx.iteration,
+            duration: Date.now() - start,
+            hasTransform,
+          })
+          if (hasTransform) {
+            aiEventClient.emit('middleware:config:transformed', {
+              ...base,
+              middlewareName: mw.name || 'unnamed',
+              iteration: ctx.iteration,
+              // `result` is `Partial<StructuredOutputMiddlewareConfig>` —
+              // Object.fromEntries(Object.entries(result)) yields the
+              // structural `Record<string, unknown>` the event emitter wants
+              // without an `as` cast.
+              changes: Object.fromEntries(Object.entries(result)),
             })
           }
         }
@@ -152,7 +212,7 @@ export class MiddlewareRunner {
       const nextChunks: Array<StreamChunk> = []
       for (const c of chunks) {
         // Cast: @ag-ui/core Zod passthrough types prevent direct `.type` access
-        const chunkType = (c as StreamChunk & { type: string }).type
+        const chunkType = c.type
         if (!skip) {
           this.logger.middleware(
             `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType}`,
@@ -188,7 +248,7 @@ export class MiddlewareRunner {
           nextChunks.push(...result)
           if (!skip) {
             this.logger.middleware(
-              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=[${result.map((r: StreamChunk) => (r as StreamChunk & { type: string }).type).join(',')}]`,
+              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=[${result.map((r: StreamChunk) => r.type).join(',')}]`,
               {
                 middleware: mw.name ?? 'unnamed',
                 hook: 'onChunk',
@@ -209,7 +269,7 @@ export class MiddlewareRunner {
           nextChunks.push(result)
           if (!skip) {
             this.logger.middleware(
-              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=${(result as StreamChunk & { type: string }).type}`,
+              `hook=onChunk middleware=${mw.name ?? 'unnamed'} in=${chunkType} out=${result.type}`,
               {
                 middleware: mw.name ?? 'unnamed',
                 hook: 'onChunk',

package/src/activities/chat/middleware/index.ts

@@ -3,6 +3,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
   AfterToolCallInfo,

package/src/activities/chat/middleware/types.ts

@@ -1,4 +1,10 @@
-import type { ModelMessage, StreamChunk, Tool, ToolCall } from '../../../types'
+import type {
+  JSONSchema,
+  ModelMessage,
+  StreamChunk,
+  Tool,
+  ToolCall,
+} from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 
 // ===========================
@@ -12,6 +18,8 @@ import type { SystemPrompt } from '../../../system-prompts'
  * - 'modelStream': During model streaming
  * - 'beforeTools': Before tool execution phase
  * - 'afterTools': After tool execution phase
+ * - 'structuredOutput': During the final structured-output adapter call (set
+ *   for chunks from adapter.structuredOutputStream or the synthesized fallback)
  */
 export type ChatMiddlewarePhase =
   | 'init'
@@ -19,6 +27,7 @@ export type ChatMiddlewarePhase =
   | 'modelStream'
   | 'beforeTools'
   | 'afterTools'
+  | 'structuredOutput'
 
 /**
  * Stable context object passed to all middleware hooks.
@@ -125,6 +134,24 @@ export interface ChatMiddlewareConfig {
   modelOptions?: Record<string, unknown> | undefined
 }
 
+/**
+ * Config passed to onStructuredOutputConfig.
+ *
+ * Mirrors ChatMiddlewareConfig minus `tools` (the final structured-output call
+ * is a single typed-response request, not an agentic loop — tools cannot be
+ * forwarded to it), plus the `outputSchema` being sent to the provider.
+ * Middleware may transform the schema (e.g., inject $defs, strip
+ * vendor-incompatible keywords) by returning a partial that includes
+ * `outputSchema`.
+ */
+export interface StructuredOutputMiddlewareConfig extends Omit<
+  ChatMiddlewareConfig,
+  'tools'
+> {
+  /** JSON Schema being sent to the provider for structured output. */
+  outputSchema: JSONSchema
+}
+
 // ===========================
 // Tool Call Hook Context
 // ===========================
@@ -337,7 +364,31 @@ export interface ChatMiddleware {
     | void
     | null
     | Partial<ChatMiddlewareConfig>
-    | Promise<void | Partial<ChatMiddlewareConfig>>
+    | Promise<void | null | Partial<ChatMiddlewareConfig>>
+
+  /**
+   * Called at the start of the final structured-output call (when the chat
+   * was invoked with outputSchema). Pipes through middleware in order, like
+   * onConfig, but with access to the JSON Schema being sent to the provider.
+   *
+   * Return a partial to shallow-merge into the current config, or void to
+   * pass through.
+   *
+   * Fires BEFORE onConfig at the structured-output boundary. onConfig also
+   * re-fires at the same boundary with ctx.phase === 'structuredOutput',
+   * receiving the post-onStructuredOutputConfig view of the config (minus
+   * outputSchema). Use onConfig for general-purpose transforms that apply
+   * to every adapter call; use this hook when you need to transform the
+   * outputSchema or apply structured-output-specific behavior.
+   */
+  onStructuredOutputConfig?: (
+    ctx: ChatMiddlewareContext,
+    config: StructuredOutputMiddlewareConfig,
+  ) =>
+    | void
+    | null
+    | Partial<StructuredOutputMiddlewareConfig>
+    | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>
 
   /**
    * Called when the chat run starts (after initial onConfig).

package/src/activities/chat/stream/processor.ts

@@ -216,7 +216,7 @@ export class StreamProcessor {
         ? [{ type: 'text', content }]
         : content.map((part) => {
             // ContentPart types (text, image, audio, video, document) are compatible with MessagePart
-            return part as MessagePart
+            return part
           })
 
     const userMessage: UIMessage = {
@@ -479,7 +479,7 @@ export class StreamProcessor {
 
     // Cast needed: @ag-ui/core Zod passthrough types add `& { [k: string]: unknown }`
     // which prevents TypeScript from narrowing the `type` discriminant in switch.
-    const c = chunk as StreamChunk & { type: string }
+    const c = chunk
     // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events.
     switch (c.type) {
       // AG-UI Events

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

@@ -58,7 +58,6 @@ export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
     typeof schema['~standard'] === 'object' &&
     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'
@@ -340,6 +339,25 @@ export async function validateWithStandardSchema<T>(
   }
 }
 
+/**
+ * Error thrown when Standard Schema validation fails. Carries the original
+ * `issues` array so consumers (middleware `onError`, callers catching from
+ * `chat({ outputSchema })`) can programmatically inspect each failure.
+ */
+export class StandardSchemaValidationError extends Error {
+  override readonly name = 'StandardSchemaValidationError'
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
+
+  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>) {
+    super(
+      `Validation failed: ${issues
+        .map((i) => i.message || 'Validation failed')
+        .join(', ')}`,
+    )
+    this.issues = issues
+  }
+}
+
 /**
  * Synchronously validates data against a Standard Schema compliant schema.
  * Note: Some Standard Schema implementations may only support async validation.
@@ -348,7 +366,8 @@ export async function validateWithStandardSchema<T>(
  * @param schema - Standard Schema compliant schema
  * @param data - Data to validate
  * @returns Parsed/validated data
- * @throws Error if validation fails or if the schema only supports async validation
+ * @throws StandardSchemaValidationError if validation fails; Error if the
+ *         schema only supports async validation.
  */
 export function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {
   if (!isStandardSchema(schema)) {
@@ -369,9 +388,5 @@ export function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {
     return result.value as T
   }
 
-  // invalid validation, throw error with all issues
-  const errorMessages = result.issues
-    .map((issue) => issue.message || 'Validation failed')
-    .join(', ')
-  throw new Error(`Validation failed: ${errorMessages}`)
+  throw new StandardSchemaValidationError(result.issues)
 }

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,
   })
 
@@ -237,7 +237,7 @@ async function runGenerateImage<
         b64Json: image.b64Json,
       })),
       duration,
-      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+      modelOptions: rest.modelOptions,
       timestamp: Date.now(),
     })
 
@@ -246,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/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 {
@@ -91,6 +94,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
   AfterToolCallInfo,

package/src/middlewares/content-guard.ts

@@ -151,7 +151,7 @@ function createDeltaStrategy(
       return {
         ...rest,
         delta: filtered,
-      } as StreamChunk
+      }
     },
   }
 }

package/src/middlewares/otel.ts

@@ -256,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
@@ -676,7 +673,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
               toolName: info.toolName,
               toolCallId: info.toolCallId,
               iteration: state.iterationCount - 1,
-            } as OtelSpanInfo<'tool'>,
+            },
             toolSpan,
           ),
         )
@@ -709,7 +706,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 kind: 'iteration',
                 ctx,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'iteration'>,
+              },
               iterationSpan,
             ),
           )
@@ -729,7 +726,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )
@@ -782,7 +779,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 kind: 'iteration',
                 ctx,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'iteration'>,
+              },
               iterationSpan,
             ),
           )
@@ -800,7 +797,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )
@@ -845,7 +842,7 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
                 toolCallId: id,
                 toolName,
                 iteration: state.iterationCount - 1,
-              } as OtelSpanInfo<'tool'>,
+              },
               span,
             ),
           )

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/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') {
@@ -161,7 +162,7 @@ function collectUserContent(
       p.type === 'video' ||
       p.type === 'document'
     ) {
-      out.push(p as AGUIInputContent)
+      out.push(p)
     }
   }
   return out