@tanstack/ai 0.17.0 → 0.19.0

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

@@ -20,6 +20,9 @@
 import { generateMessageId, uiMessageToModelMessages } from '../messages.js'
 import { defaultJSONParser } from './json-parser'
 import {
+  appendStructuredOutputDelta,
+  completeStructuredOutputPart,
+  errorStructuredOutputPart,
   updateTextPart,
   updateThinkingPart,
   updateToolCallApproval,
@@ -145,6 +148,8 @@ export class StreamProcessor {
   private pendingManualMessageId: string | null = null
   private pendingThinkingStepId: string | null = null
 
+  private structuredMessageIds: Set<string> = new Set()
+
   // Run tracking (for concurrent run safety)
   private activeRuns = new Set<string>()
 
@@ -383,6 +388,27 @@ export class StreamProcessor {
    * Remove messages after a certain index (for reload/retry)
    */
   removeMessagesAfter(index: number): void {
+    const keptIds = new Set(this.messages.slice(0, index + 1).map((m) => m.id))
+    // Drop routing state for messages that no longer exist; otherwise a
+    // resumed stream (`reload()` or a server that reuses messageIds across
+    // runs) could land deltas / tool args on stale map entries and corrupt
+    // the new assistant message's parts. Mirror the four routing maps that
+    // key on messageId: structuredMessageIds (custom-event routing),
+    // messageStates (per-message stream state), toolCallToMessage (tool
+    // args → message), and activeMessageIds (finalize / completeAllToolCalls
+    // iteration targets — must not include phantoms).
+    for (const id of this.structuredMessageIds) {
+      if (!keptIds.has(id)) this.structuredMessageIds.delete(id)
+    }
+    for (const id of this.messageStates.keys()) {
+      if (!keptIds.has(id)) this.messageStates.delete(id)
+    }
+    for (const [toolCallId, msgId] of this.toolCallToMessage) {
+      if (!keptIds.has(msgId)) this.toolCallToMessage.delete(toolCallId)
+    }
+    for (const id of this.activeMessageIds) {
+      if (!keptIds.has(id)) this.activeMessageIds.delete(id)
+    }
     this.messages = this.messages.slice(0, index + 1)
     this.emitMessagesChange()
   }
@@ -395,6 +421,7 @@ export class StreamProcessor {
     this.messageStates.clear()
     this.activeMessageIds.clear()
     this.toolCallToMessage.clear()
+    this.structuredMessageIds.clear()
     this.pendingManualMessageId = null
     this.emitMessagesChange()
   }
@@ -841,6 +868,41 @@ export class StreamProcessor {
     // Content arriving means all current tool calls for this message are complete
     this.completeAllToolCallsForMessage(messageId)
 
+    if (this.structuredMessageIds.has(messageId)) {
+      // `chunk.delta` is incremental; `chunk.content` is sometimes cumulative
+      // (mirrors what the plain-text branch handles below). Reconcile against
+      // the existing raw buffer so adapters that emit cumulative content
+      // don't duplicate the JSON.
+      let delta = chunk.delta || ''
+      if (delta === '' && chunk.content !== undefined && chunk.content !== '') {
+        const existingRaw = (
+          this.messages
+            .find((m) => m.id === messageId)
+            ?.parts.find(
+              (p): p is Extract<MessagePart, { type: 'structured-output' }> =>
+                p.type === 'structured-output',
+            ) ?? { raw: '' }
+        ).raw
+        if (chunk.content.startsWith(existingRaw)) {
+          delta = chunk.content.slice(existingRaw.length)
+        } else if (existingRaw.startsWith(chunk.content)) {
+          delta = ''
+        } else {
+          delta = chunk.content
+        }
+      }
+      if (delta !== '') {
+        this.messages = appendStructuredOutputDelta(
+          this.messages,
+          messageId,
+          delta,
+        )
+        state.totalTextContent += delta
+        this.emitMessagesChange()
+      }
+      return
+    }
+
     const previousSegment = state.currentSegmentText
 
     // Detect if this is a NEW text segment (after tool calls) vs continuation
@@ -1192,10 +1254,29 @@ export class StreamProcessor {
     } else {
       this.activeRuns.clear()
     }
-    this.ensureAssistantMessage()
-    // Prefer spec field `message`; fall back to deprecated `error.message`
+    const { messageId } = this.ensureAssistantMessage()
+    // Prefer spec field `message`; fall back to deprecated `error.message`.
+    // If neither is set, the chunk still carries debug context (provider
+    // error codes, request ids, etc.) — log it so the failure isn't silent.
     const errorMessage =
       chunk.message || chunk.error?.message || 'An error occurred'
+    if (!chunk.message && !chunk.error?.message) {
+      console.error(
+        '[StreamProcessor] RUN_ERROR with no message; original chunk:',
+        chunk,
+      )
+    }
+
+    if (this.structuredMessageIds.has(messageId)) {
+      this.messages = errorStructuredOutputPart(
+        this.messages,
+        messageId,
+        errorMessage,
+      )
+      this.structuredMessageIds.delete(messageId)
+      this.emitMessagesChange()
+    }
+
     this.events.onError?.(new Error(errorMessage))
   }
 
@@ -1375,6 +1456,38 @@ export class StreamProcessor {
   ): void {
     const messageId = this.getActiveAssistantMessageId()
 
+    if (chunk.name === 'structured-output.start' && chunk.value) {
+      const v = chunk.value as { messageId?: string }
+      const targetId = v.messageId ?? messageId
+      if (targetId) {
+        this.ensureAssistantMessage(targetId)
+        this.structuredMessageIds.add(targetId)
+      }
+      return
+    }
+
+    if (chunk.name === 'structured-output.complete' && chunk.value) {
+      const v = chunk.value as {
+        object: unknown
+        raw?: string
+        reasoning?: string
+        messageId?: string
+      }
+      const targetId = v.messageId ?? messageId
+      if (targetId) {
+        this.messages = completeStructuredOutputPart(
+          this.messages,
+          targetId,
+          v.object,
+          v.raw ?? '',
+          v.reasoning,
+        )
+        this.structuredMessageIds.delete(targetId)
+        this.emitMessagesChange()
+      }
+      // Fall through so user `onCustomEvent` callbacks still observe the event.
+    }
+
     // Handle client tool input availability - trigger client-side execution
     if (chunk.name === 'tool-input-available' && chunk.value) {
       const { toolCallId, toolName, input } = chunk.value as {
@@ -1591,6 +1704,27 @@ export class StreamProcessor {
       }
     }
 
+    // The stream closed but one or more structured-output runs never sent
+    // their terminal `structured-output.complete`. Snap each lingering
+    // streaming part to error so the UI doesn't appear to stream forever,
+    // and drop the routing entries so a subsequent run on the same
+    // processor instance (long-lived `subscribe()` mode) doesn't reuse
+    // the stale ids.
+    //
+    // The iteration is unconditional w.r.t. `this.hasError` — RUN_ERROR
+    // already removed its target messageId from `structuredMessageIds`
+    // before reaching finalize, so anything still in the set is by
+    // definition a non-errored, never-completed run (the multi-run case:
+    // run-A errors, run-B is still streaming when finalize fires).
+    for (const messageId of this.structuredMessageIds) {
+      this.messages = errorStructuredOutputPart(
+        this.messages,
+        messageId,
+        'Stream ended without structured-output.complete',
+      )
+    }
+    this.structuredMessageIds.clear()
+
     this.activeMessageIds.clear()
 
     // Remove whitespace-only assistant messages (handles models like Gemini
@@ -1719,6 +1853,7 @@ export class StreamProcessor {
     this.activeMessageIds.clear()
     this.activeRuns.clear()
     this.toolCallToMessage.clear()
+    this.structuredMessageIds.clear()
     this.pendingManualMessageId = null
     this.pendingThinkingStepId = null
     this.finishReason = null

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

@@ -254,6 +254,20 @@ export function convertSchemaToJsonSchema(
     return result as JSONSchema
   }
 
+  // Detect Standard Schema validators (Zod, ArkType, Valibot, …) that don't
+  // expose a `~standard.jsonSchema` converter. These would otherwise fall
+  // through to the JSONSchema pass-through below and ship `{ '~standard': … }`
+  // straight to the LLM provider, producing an opaque downstream error. Fail
+  // fast with actionable guidance instead.
+  if (isStandardSchema(schema)) {
+    throw new Error(
+      'Schema is a Standard Schema validator but does not expose a JSON Schema ' +
+        'converter on `~standard.jsonSchema`. Use Zod v4.2+, ArkType v2.1.28+, ' +
+        'or wrap a Valibot schema with `toStandardJsonSchema()` from ' +
+        '`@valibot/to-json-schema` before passing it as `outputSchema`.',
+    )
+  }
+
   // If it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through
   // Still apply structured output transformation if requested
 

package/src/adapter-internals.ts

@@ -4,5 +4,6 @@
 
 export type { ResolvedCategories } from './logger/internal-logger'
 export { InternalLogger } from './logger/internal-logger'
+export type { Logger } from './logger/types'
 export { resolveDebugOption } from './logger/resolve'
 export { toRunErrorPayload } from './activities/error-payload'

package/src/index.ts

@@ -168,6 +168,17 @@ export type {
   JSONParser,
 } from './activities/chat/stream/index'
 
+// Chat utilities
+export {
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  mergeAgentTools,
+} from './utilities/chat-params'
+
+// AG-UI wire serialization (used internally by @tanstack/ai-client)
+export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { WireMessage } from './utilities/ag-ui-wire'
+
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef } from './extend-adapter'

package/src/types.ts

@@ -1,4 +1,7 @@
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
 import type {
   BaseEvent as AGUIBaseEvent,
@@ -91,25 +94,42 @@ export interface JSONSchema {
 }
 
 /**
- * Union type for schema input - can be any Standard JSON Schema compliant schema or a plain JSONSchema object.
+ * Union type for schema input - can be any Standard Schema compliant validator,
+ * any Standard JSON Schema compliant schema, or a plain JSONSchema object.
  *
- * Standard JSON Schema compliant libraries include:
+ * Standard JSON Schema compliant libraries (carry the JSON-schema converter):
  * - Zod v4.2+ (natively supports StandardJSONSchemaV1)
  * - ArkType v2.1.28+ (natively supports StandardJSONSchemaV1)
  * - Valibot v1.2+ (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
  *
+ * StandardSchemaV1 covers libraries whose published types only expose the
+ * validator surface — Zod's core `$ZodType['~standard']` is currently typed
+ * as `StandardSchemaV1.Props` even though the runtime attaches the
+ * `jsonSchema` converter, so this branch is what makes `InferSchemaType`
+ * recover the inferred type for callers using `z.ZodType<T>`.
+ *
  * @see https://standardschema.dev/json-schema
  */
 
-export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema
+export type SchemaInput =
+  | StandardJSONSchemaV1<any, any>
+  | StandardSchemaV1<any, any>
+  | JSONSchema
 
 /**
  * Infer the TypeScript type from a schema.
  * For Standard JSON Schema compliant schemas, extracts the input type.
- * For plain JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
+ * For Standard Schema validators (e.g. Zod's `~standard` surface), extracts
+ * the input type from the `StandardSchemaV1` shape.
+ * For plain JSONSchema, returns `unknown` since we can't infer types from
+ * JSON Schema at compile time.
  */
 export type InferSchemaType<T> =
-  T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown
+  T extends StandardJSONSchemaV1<infer TInput, unknown>
+    ? TInput
+    : T extends StandardSchemaV1<infer TInput, unknown>
+      ? TInput
+      : unknown
 
 export interface ToolCall<TMetadata = unknown> {
   id: string
@@ -345,7 +365,43 @@ export interface ThinkingPart {
   signature?: string
 }
 
-export type MessagePart =
+/**
+ * Recursive `Partial` — every nested field becomes optional. Used as the
+ * `partial` type on a streaming structured-output part since the progressive
+ * JSON parse hands back objects whose fields are only filled in as bytes
+ * arrive. Defaulted in `DeepPartial<unknown>` → `unknown` so untyped parts
+ * keep their existing shape.
+ */
+export type DeepPartial<T> =
+  T extends ReadonlyArray<infer U>
+    ? Array<DeepPartial<U>>
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T
+
+/**
+ * StructuredOutputPart — a typed structured response attached to the assistant
+ * message that produced it. Generic over the schema-inferred data type so
+ * consumers can thread `useChat({ outputSchema })`'s schema all the way down
+ * to `messages[i].parts[j].data`. Defaults to `unknown` so untyped consumers
+ * (e.g. internal codepaths that don't know about TSchema) keep working.
+ */
+export interface StructuredOutputPart<TData = unknown> {
+  type: 'structured-output'
+  status: 'streaming' | 'complete' | 'error'
+  /** Progressive parse of `raw` via parsePartialJSON — populated while streaming and after complete. */
+  partial?: DeepPartial<TData>
+  /** Validated final object — only set when `status === 'complete'`. */
+  data?: TData
+  /** Accumulating JSON buffer. Source of truth for wire round-trip. */
+  raw: string
+  /** Optional chain-of-thought surfaced by reasoning models alongside the structured output. */
+  reasoning?: string
+  /** Populated when `status === 'error'`. */
+  errorMessage?: string
+}
+
+export type MessagePart<TData = unknown> =
   | TextPart
   | ImagePart
   | AudioPart
@@ -354,15 +410,19 @@ export type MessagePart =
   | ToolCallPart
   | ToolResultPart
   | ThinkingPart
+  | StructuredOutputPart<TData>
 
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
- * Contains parts that can be text, tool calls, or tool results
+ * Contains parts that can be text, tool calls, or tool results. Generic over
+ * the structured-output data type so `useChat({ outputSchema })`'s schema
+ * narrows `parts.find(p => p.type === 'structured-output').data` on the
+ * consumer side without manual casts.
  */
-export interface UIMessage {
+export interface UIMessage<TData = unknown> {
   id: string
   role: 'system' | 'user' | 'assistant'
-  parts: Array<MessagePart>
+  parts: Array<MessagePart<TData>>
   createdAt?: Date
 }
 
@@ -729,8 +789,14 @@ export interface TextOptions<
    */
   outputSchema?: SchemaInput
   /**
-   * Conversation ID for correlating client and server-side devtools events.
-   * When provided, server-side events will be linked to the client conversation in devtools.
+   * @deprecated Use `threadId` instead. `conversationId` is the legacy
+   * pre-AG-UI name for the same concept (a stable per-conversation
+   * identifier used to correlate client/server devtools events). When
+   * `conversationId` is omitted, the runtime falls back to `threadId`
+   * automatically, so most callers can simply pass `threadId` (or rely
+   * on `chatParamsFromRequest`, which surfaces it on `params`).
+   *
+   * Will be removed in a future major release.
    */
   conversationId?: string
   /**
@@ -766,6 +832,11 @@ export interface TextOptions<
    * If not provided, a unique ID will be generated.
    */
   runId?: string
+  /**
+   * Parent run ID for AG-UI protocol nested run correlation.
+   * Surfaced for observability/middleware; not consumed by the LLM call.
+   */
+  parentRunId?: string
 }
 
 // ============================================================================
@@ -1083,11 +1154,28 @@ export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<
   value: { object: T; raw: string; reasoning?: string }
 }
 
+/**
+ * Emitted at the start of a streaming structured-output run, before the JSON
+ * deltas. Tells consumers that the upcoming `TEXT_MESSAGE_CONTENT` deltas
+ * belong to a structured response so they can route those bytes into a
+ * `StructuredOutputPart` instead of building a `TextPart`. Carries the
+ * `messageId` the deltas will be tagged with so the routing decision can be
+ * made per-message rather than globally.
+ */
+export interface StructuredOutputStartEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'structured-output.start'
+  value: { messageId: string }
+}
+
 /**
  * Emitted when a server tool requires approval before execution. The agent
  * loop yields this and pauses — `structured-output.complete` will not fire
  * for that run. The shape is fixed by the orchestrator's tool-approval flow
- * (see `buildApprovalChunks` in `activities/chat/index.ts`).
+ * (the agent-loop branch of `runStreamingStructuredOutputImpl` in
+ * `activities/chat/index.ts` forwards CUSTOM events from `TextEngine.run()`).
  */
 export interface ApprovalRequestedEvent extends Omit<
   CustomEvent,
@@ -1105,8 +1193,8 @@ export interface ApprovalRequestedEvent extends Omit<
 /**
  * Emitted when a client tool is invoked. The agent loop yields this and
  * pauses to let the caller run the tool client-side — `structured-output.complete`
- * will not fire for that run. Shape fixed by `buildClientToolChunks` in
- * `activities/chat/index.ts`.
+ * will not fire for that run. Shape fixed by the agent-loop forwarding in
+ * `runStreamingStructuredOutputImpl` in `activities/chat/index.ts`.
  */
 export interface ToolInputAvailableEvent extends Omit<
   CustomEvent,
@@ -1152,6 +1240,7 @@ export interface ToolInputAvailableEvent extends Omit<
  */
 export type StructuredOutputStream<T = unknown> = AsyncIterable<
   | Exclude<StreamChunk, CustomEvent>
+  | StructuredOutputStartEvent
   | StructuredOutputCompleteEvent<T>
   | ApprovalRequestedEvent
   | ToolInputAvailableEvent

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

@@ -0,0 +1,201 @@
+import type { ContentPart, MessagePart, UIMessage } from '../types'
+
+type AGUITextInputContent = { type: 'text'; text: string }
+type AGUIInputContent =
+  | AGUITextInputContent
+  | (ContentPart & { type: 'image' | 'audio' | 'video' | 'document' })
+
+type AGUIToolCallMirror = {
+  id: string
+  type: 'function'
+  function: { name: string; arguments: string }
+}
+
+type AGUIToolMessage = {
+  role: 'tool'
+  id: string
+  toolCallId: string
+  content: string
+  error?: string
+}
+
+type AGUIReasoningMessage = {
+  role: 'reasoning'
+  id: string
+  content: string
+}
+
+type WireAnchorMessage = UIMessage & {
+  content?: string | Array<AGUIInputContent>
+  toolCalls?: Array<AGUIToolCallMirror>
+}
+
+export type WireMessage =
+  | WireAnchorMessage
+  | AGUIToolMessage
+  | AGUIReasoningMessage
+
+/**
+ * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`
+ * wire shape. Each anchor (system/user/assistant) carries the canonical
+ * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)
+ * so AG-UI Zod parsing succeeds. Tool results and thinking parts on
+ * assistant messages are additionally emitted as fan-out
+ * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict
+ * AG-UI server consumers.
+ */
+export function uiMessagesToWire(
+  messages: Array<UIMessage>,
+): Array<WireMessage> {
+  const wire: Array<WireMessage> = []
+
+  for (const msg of messages) {
+    // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.
+    // UIMessage always has parts; ModelMessage uses content directly.
+    const parts: ReadonlyArray<MessagePart> =
+      (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []
+
+    if (msg.role === 'system') {
+      wire.push({
+        ...msg,
+        content:
+          parts.length > 0
+            ? collectText(parts)
+            : ((msg as unknown as { content?: string }).content ?? ''),
+      })
+      continue
+    }
+
+    if (msg.role === 'user') {
+      wire.push({
+        ...msg,
+        content:
+          parts.length > 0
+            ? collectUserContent(parts)
+            : ((msg as unknown as { content?: string }).content ?? ''),
+      })
+      continue
+    }
+
+    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs
+    for (const part of parts) {
+      if (part.type === 'thinking') {
+        wire.push({
+          role: 'reasoning',
+          id: deriveReasoningId(msg.id, part),
+          content: part.content,
+        })
+      }
+    }
+
+    const text = collectText(parts)
+    const toolCalls = collectToolCalls(parts)
+    wire.push({
+      ...msg,
+      ...(text !== '' && { content: text }),
+      ...(toolCalls && { toolCalls }),
+    })
+
+    for (const part of parts) {
+      if (part.type === 'tool-result') {
+        wire.push({
+          role: 'tool',
+          id: deriveToolMessageId(part.toolCallId),
+          toolCallId: part.toolCallId,
+          content: part.content,
+          ...(part.error !== undefined && { error: part.error }),
+        })
+      }
+    }
+  }
+
+  return wire
+}
+
+function collectText(parts: ReadonlyArray<MessagePart>): string {
+  // The streamed JSON of a completed structured-output part is the source of
+  // truth for multi-turn coherence — emitting it back as assistant content
+  // lets the LLM see its own prior structured response. Streaming/errored
+  // parts are skipped: they'd ship malformed JSON fragments and confuse the
+  // model. `completeStructuredOutputPart` tries hard to populate `raw`
+  // (caller → existing buffer → `JSON.stringify(data)`), but the stringify
+  // fallback can leave it empty when `data` is unserializable (BigInt,
+  // circular). The `p.raw !== ''` guard below is what enforces "no malformed
+  // round-trip" in that case — without it we'd ship `''` and the model would
+  // see an empty assistant turn.
+  const out: Array<string> = []
+  for (const p of parts) {
+    if (p.type === 'text') {
+      out.push(p.content)
+    } else if (
+      p.type === 'structured-output' &&
+      p.status === 'complete' &&
+      p.raw !== ''
+    ) {
+      out.push(p.raw)
+    }
+  }
+  return out.join('')
+}
+
+function collectUserContent(
+  parts: ReadonlyArray<MessagePart>,
+): string | Array<AGUIInputContent> {
+  const hasMultimodal = parts.some(
+    (p) =>
+      p.type === 'image' ||
+      p.type === 'audio' ||
+      p.type === 'video' ||
+      p.type === 'document',
+  )
+  if (!hasMultimodal) {
+    return collectText(parts)
+  }
+  const out: Array<AGUIInputContent> = []
+  for (const p of parts) {
+    if (p.type === 'text') {
+      out.push({ type: 'text', text: p.content })
+    } else if (
+      p.type === 'image' ||
+      p.type === 'audio' ||
+      p.type === 'video' ||
+      p.type === 'document'
+    ) {
+      out.push(p as AGUIInputContent)
+    }
+  }
+  return out
+}
+
+function collectToolCalls(
+  parts: ReadonlyArray<MessagePart>,
+): Array<AGUIToolCallMirror> | undefined {
+  const calls: Array<AGUIToolCallMirror> = []
+  for (const p of parts) {
+    if (p.type === 'tool-call') {
+      calls.push({
+        id: p.id,
+        type: 'function',
+        function: { name: p.name, arguments: p.arguments },
+      })
+    }
+  }
+  return calls.length > 0 ? calls : undefined
+}
+
+function deriveReasoningId(messageId: string, part: MessagePart): string {
+  return `${messageId}-reasoning-${(part as { id?: string }).id ?? hashContent((part as { content: string }).content)}`
+}
+
+function deriveToolMessageId(toolCallId: string): string {
+  return `tool-${toolCallId}`
+}
+
+function hashContent(s: string): string {
+  // Cheap deterministic id suffix; collisions are tolerable since
+  // reasoning ids only matter for AG-UI server consumers, not for our
+  // own server's dedup logic (which keys on toolCallId, not reasoning id).
+  let h = 0
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0
+  return Math.abs(h).toString(36)
+}