@tanstack/ai 0.20.0 → 0.21.0

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
     }
 
@@ -463,12 +463,13 @@ export function modelMessagesToUIMessages(
     if (msg.role === 'tool') {
       // Tool result - merge into the last assistant message if possible
       if (
+        msg.toolCallId !== undefined &&
         currentAssistantMessage &&
         currentAssistantMessage.role === 'assistant'
       ) {
         currentAssistantMessage.parts.push({
           type: 'tool-result',
-          toolCallId: msg.toolCallId!,
+          toolCallId: msg.toolCallId,
           content: getTextContent(msg.content),
           state: 'complete',
         })

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.
@@ -79,9 +88,9 @@ export interface ChatMiddlewareContext {
   /** Names of configured tools, if any */
   toolNames?: Array<string>
   /** Flattened generation options (temperature, topP, maxTokens, metadata) */
-  options?: Record<string, unknown>
+  options?: Record<string, unknown> | undefined
   /** Provider-specific model options */
-  modelOptions?: Record<string, unknown>
+  modelOptions?: Record<string, unknown> | undefined
 
   // --- Computed info ---
 
@@ -121,8 +130,26 @@ export interface ChatMiddlewareConfig {
   temperature?: number
   topP?: number
   maxTokens?: number
-  metadata?: Record<string, unknown>
-  modelOptions?: Record<string, unknown>
+  metadata?: Record<string, unknown> | undefined
+  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
 }
 
 // ===========================
@@ -257,11 +284,13 @@ export interface FinishInfo {
   /** Final accumulated text content */
   content: string
   /** Final usage totals, if available */
-  usage?: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
+  usage?:
+    | {
+        promptTokens: number
+        completionTokens: number
+        totalTokens: number
+      }
+    | undefined
 }
 
 /**
@@ -335,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

@@ -133,25 +133,25 @@ export interface StreamProcessorOptions {
  * @see docs/chat-architecture.md#adapter-contract — What this class expects from adapters
  */
 export class StreamProcessor {
-  private chunkStrategy: ChunkStrategy
-  private events: StreamProcessorEvents
-  private jsonParser: { parse: (jsonString: string) => any }
+  private readonly chunkStrategy: ChunkStrategy
+  private readonly events: StreamProcessorEvents
+  private readonly jsonParser: { parse: (jsonString: string) => any }
   private recordingEnabled: boolean
 
   // Message state
   private messages: Array<UIMessage> = []
 
   // Per-message stream state
-  private messageStates: Map<string, MessageStreamState> = new Map()
-  private activeMessageIds: Set<string> = new Set()
-  private toolCallToMessage: Map<string, string> = new Map()
+  private readonly messageStates: Map<string, MessageStreamState> = new Map()
+  private readonly activeMessageIds: Set<string> = new Set()
+  private readonly toolCallToMessage: Map<string, string> = new Map()
   private pendingManualMessageId: string | null = null
   private pendingThinkingStepId: string | null = null
 
-  private structuredMessageIds: Set<string> = new Set()
+  private readonly structuredMessageIds: Set<string> = new Set()
 
   // Run tracking (for concurrent run safety)
-  private activeRuns = new Set<string>()
+  private readonly activeRuns = new Set<string>()
 
   // Shared stream state
   private finishReason: string | null = null
@@ -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,8 @@ 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
       case 'TEXT_MESSAGE_START':
@@ -645,10 +646,9 @@ export class StreamProcessor {
    * Used as fallback for events that don't include a messageId.
    */
   private getActiveAssistantMessageId(): string | null {
-    // Set iteration is insertion-order; convert to array and search from the end
-    const ids = Array.from(this.activeMessageIds)
-    for (let i = ids.length - 1; i >= 0; i--) {
-      const id = ids[i]!
+    // Set iteration is insertion-order; reverse-iterate to search from the end
+    const ids = Array.from(this.activeMessageIds).reverse()
+    for (const id of ids) {
       const state = this.messageStates.get(id)
       if (state && state.role === 'assistant') {
         return id
@@ -679,8 +679,8 @@ export class StreamProcessor {
     // Try active assistant message
     const activeId = this.getActiveAssistantMessageId()
     if (activeId) {
-      const state = this.getMessageState(activeId)!
-      return { messageId: activeId, state }
+      const state = this.getMessageState(activeId)
+      if (state) return { messageId: activeId, state }
     }
 
     // Check if a message with preferredId already exists (reconnect/resume case).
@@ -781,10 +781,10 @@ export class StreamProcessor {
     const existingMsg = this.messages.find((m) => m.id === messageId)
     if (existingMsg) {
       this.activeMessageIds.add(messageId)
-      if (!this.messageStates.has(messageId)) {
+      const existingState = this.messageStates.get(messageId)
+      if (!existingState) {
         this.createMessageState(messageId, uiRole)
       } else {
-        const existingState = this.messageStates.get(messageId)!
         // If tool calls happened since last text, this TEXT_MESSAGE_START
         // signals a new text segment — reset segment accumulation
         if (existingState.hasToolCallsSinceTextStart) {
@@ -845,7 +845,7 @@ export class StreamProcessor {
   ): void {
     this.resetStreamState()
     // AG-UI Message[] is compatible with UIMessage[] at runtime
-    this.messages = [...chunk.messages] as unknown as Array<UIMessage>
+    this.messages = [...chunk.messages] as Array<UIMessage>
     this.emitMessagesChange()
   }
 
@@ -1365,7 +1365,7 @@ export class StreamProcessor {
       state.currentThinkingStepId = stepId
     }
 
-    const previous = state.thinkingSteps.get(stepId)!
+    const previous = state.thinkingSteps.get(stepId) ?? ''
     let nextThinking = previous
 
     // Prefer delta over content
@@ -1900,7 +1900,7 @@ export function createReplayStream(
   recording: ChunkRecording,
 ): AsyncIterable<StreamChunk> {
   return {
-    // eslint-disable-next-line @typescript-eslint/require-await
+    // eslint-disable-next-line @typescript-eslint/require-await -- async generator required by AsyncIterable contract; body has no await
     async *[Symbol.asyncIterator]() {
       for (const { chunk } of recording.chunks) {
         yield chunk

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

@@ -20,7 +20,7 @@ export class ImmediateStrategy implements ChunkStrategy {
  * Useful for natural text flow in UI
  */
 export class PunctuationStrategy implements ChunkStrategy {
-  private punctuation = /[.,!?;:\n]/
+  private readonly punctuation = /[.,!?;:\n]/
 
   shouldEmit(chunk: string, _accumulated: string): boolean {
     return this.punctuation.test(chunk)
@@ -34,7 +34,7 @@ export class PunctuationStrategy implements ChunkStrategy {
 export class BatchStrategy implements ChunkStrategy {
   private chunkCount = 0
 
-  constructor(private batchSize: number = 5) {}
+  constructor(private readonly batchSize: number = 5) {}
 
   shouldEmit(_chunk: string, _accumulated: string): boolean {
     this.chunkCount++
@@ -66,7 +66,7 @@ export class WordBoundaryStrategy implements ChunkStrategy {
  * Emits if ANY strategy says to emit
  */
 export class CompositeStrategy implements ChunkStrategy {
-  constructor(private strategies: Array<ChunkStrategy>) {}
+  constructor(private readonly strategies: Array<ChunkStrategy>) {}
 
   shouldEmit(chunk: string, accumulated: string): boolean {
     return this.strategies.some((s) => s.shouldEmit(chunk, accumulated))

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,7 +56,6 @@ 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'] &&
     schema['~standard'].version === 1 &&
@@ -58,19 +76,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 +102,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 +137,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 +235,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 +281,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
+  }
+
+  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 as JSONSchema
+  return schema
 }
 
 /**
@@ -293,7 +314,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
@@ -315,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.
@@ -323,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)) {
@@ -344,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)
 }