@tanstack/ai 0.49.1 → 0.50.0

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

@@ -19,6 +19,7 @@
  */
 import {
   aguiSnapshotMessageToUIMessage,
+  coerceCreatedAt,
   generateMessageId,
   uiMessageToModelMessages,
 } from '../messages.js'
@@ -835,11 +836,10 @@ export class StreamProcessor {
           }
         : incomingRecord
     const metadata = mergeMetadata(message.metadata, toMerge)
-    const createdAtRaw = tanstackMetadata(incomingRecord)?.createdAt
-    const createdAt =
-      typeof createdAtRaw === 'string' ? new Date(createdAtRaw) : undefined
-    const createdAtValid =
-      createdAt !== undefined && !Number.isNaN(createdAt.getTime())
+    const createdAt = coerceCreatedAt(
+      tanstackMetadata(incomingRecord)?.createdAt,
+    )
+    const createdAtValid = createdAt !== undefined
     this.messages = this.messages.map((msg) =>
       msg.id === messageId
         ? {
@@ -1050,8 +1050,10 @@ export class StreamProcessor {
       msg.parts.every((part) => part.type === 'thinking')
     const isToolResultOnly = (msg: UIMessage) =>
       msg.role === 'assistant' &&
-      msg.parts.length === 1 &&
-      msg.parts[0]?.type === 'tool-result'
+      msg.parts.some((part) => part.type === 'tool-result') &&
+      msg.parts.every(
+        (part) => part.type === 'tool-result' || part.type === 'ui-resource',
+      )
     const flushPending = () => {
       out.push(...pending)
       pending = []
@@ -1109,9 +1111,16 @@ export class StreamProcessor {
 
     const reconciled: Array<UIMessage> = []
     for (const msg of snapshot) {
+      const toolResultParts = msg.parts.filter(
+        (part): part is ToolResultPart => part.type === 'tool-result',
+      )
       const toolResultPart =
-        msg.role === 'assistant' && msg.parts.length === 1
-          ? msg.parts.find((p): p is ToolResultPart => p.type === 'tool-result')
+        msg.role === 'assistant' &&
+        toolResultParts.length === 1 &&
+        msg.parts.every(
+          (part) => part.type === 'tool-result' || part.type === 'ui-resource',
+        )
+          ? toolResultParts[0]
           : undefined
 
       if (!toolResultPart) {
@@ -1170,7 +1179,7 @@ export class StreamProcessor {
           )
         }
       }
-      parts.push(toolResultPart)
+      parts.push(...msg.parts)
       // Replace rather than push into `target.parts`: a snapshot message that
       // arrived already carrying `parts` (TanStack server echoing UIMessages)
       // shares its array with the incoming chunk, and mutating it in place

package/src/types.ts

@@ -372,6 +372,10 @@ export interface ModelMessage<
   toolCalls?: Array<ToolCall>
   toolCallId?: string
   thinking?: Array<{ content: string; signature?: string }>
+  /** Error reported by an AG-UI tool message. */
+  error?: string
+  /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
+  metadata?: Record<string, any>
   /**
    * Completed structured output represented by this assistant message.
    * `content` remains the provider-facing JSON text; this field preserves the
@@ -435,10 +439,14 @@ export interface ToolCallPart<TMetadata = unknown> {
 
 export interface ToolResultPart {
   type: 'tool-result'
+  id?: string
+  name?: string
   toolCallId: string
   content: string | Array<ContentPart>
   state: ToolResultState
   error?: string // Error message if state is "error"
+  metadata?: Record<string, unknown>
+  createdAt?: Date
 }
 
 export interface ThinkingPart {
@@ -524,9 +532,17 @@ export interface TanStackMessageMetadata {
   signature?: string
   /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
   toolCallMetadata?: Record<string, unknown>
+  toolResult?: {
+    id?: string
+    createdAt?: string
+    content?: Array<ContentPart>
+  }
   structuredOutput?: {
     status?: 'streaming' | 'complete' | 'error'
+    partial?: unknown
+    data?: unknown
     raw?: string
+    reasoning?: string
     errorMessage?: string
   }
   uiResources?: Array<UIResourcePart>
@@ -562,6 +578,8 @@ export interface UIMessage<TData = unknown> {
   role: 'system' | 'user' | 'assistant'
   parts: Array<MessagePart<TData>>
   createdAt?: Date
+  /** Optional AG-UI sender name. Converters preserve it across wire and persist. */
+  name?: string
   /**
    * Optional AG-UI metadata bag. TanStack writes the `tanstack` key.
    * User keys stay at the top.

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

@@ -1,6 +1,16 @@
+import type {
+  AssistantMessage,
+  InputContent,
+  ReasoningMessage,
+  SystemMessage,
+  ToolCall,
+  ToolMessage,
+  UserMessage,
+} from '@ag-ui/core'
 import type {
   ContentPart,
   MessagePart,
+  ModelMessage,
   StructuredOutputPart,
   TanStackMessageMetadata,
   UIMessage,
@@ -8,72 +18,125 @@ import type {
 } from '../types'
 import type { MetadataRecord } from './merge-metadata'
 import { tanstackMetadata } from './merge-metadata'
+import { normalizeToolResult } from './tool-result'
+import {
+  coerceCreatedAt,
+  modelMessageToUIMessage,
+} from '../activities/chat/messages'
 
-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 }
-  encryptedValue?: string
-}
-
-type AGUIToolMessage = {
-  role: 'tool'
-  id: string
-  toolCallId: string
-  content: string
-  error?: string
-}
+type WithMetadata<T> = T & { metadata?: MetadataRecord }
+type WireSystemMessage = WithMetadata<SystemMessage>
+type WireUserMessage = WithMetadata<UserMessage>
+type WireAssistantMessage = WithMetadata<AssistantMessage>
+type WireToolMessage = WithMetadata<
+  ToolMessage & {
+    name?: string
+  }
+>
+type WireReasoningMessage = WithMetadata<ReasoningMessage>
 
-type AGUIReasoningMessage = {
-  role: 'reasoning'
-  id: string
-  content: string
-  encryptedValue?: string
-  metadata?: MetadataRecord
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-/** Spec AG-UI message. No `parts`, no `createdAt` Date. */
-type WireAnchorMessage = {
-  id: string
-  role: UIMessage['role']
-  name?: string
-  content?: string | Array<AGUIInputContent>
-  toolCalls?: Array<AGUIToolCallMirror>
-  metadata?: MetadataRecord
+function rebuiltToolMetadata(
+  metadata: unknown,
+  createdAt: unknown,
+  id: string | undefined,
+  content: string | null | Array<ContentPart>,
+  anchorOwnsUiResources = false,
+): MetadataRecord | undefined {
+  const source: MetadataRecord = isRecord(metadata) ? metadata : {}
+  const tanstack = isRecord(source.tanstack) ? { ...source.tanstack } : {}
+  if (anchorOwnsUiResources) delete tanstack.uiResources
+  const date = coerceCreatedAt(createdAt)
+  const toolResult: NonNullable<TanStackMessageMetadata['toolResult']> = {
+    ...(id !== undefined ? { id } : {}),
+    ...(date && { createdAt: date.toISOString() }),
+    ...(Array.isArray(content) && { content }),
+  }
+  const result = {
+    ...source,
+    tanstack: { ...tanstack, toolResult },
+  }
+  return Object.keys(result).length ? result : undefined
 }
 
 export type WireMessage =
-  | WireAnchorMessage
-  | AGUIToolMessage
-  | AGUIReasoningMessage
+  | WireSystemMessage
+  | WireUserMessage
+  | WireAssistantMessage
+  | WireToolMessage
+  | WireReasoningMessage
 
 /**
- * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`
- * wire shape. Anchors are spec-only (`id`, `role`, `name`, `content`,
- * `toolCalls`, `metadata`). 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.
+ * Serialize TanStack `UIMessage`s and `ModelMessage`s into the AG-UI
+ * `RunAgentInput.messages` wire shape. Anchors are spec-only (`id`, `role`,
+ * `name`, `content`, `toolCalls`, `metadata`). 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. Set `includeSnapshotStructuredOutput` to retain complete
+ * structured-output metadata for UI snapshots.
  */
 export function uiMessagesToWire(
-  messages: Array<UIMessage>,
+  messages: Array<UIMessage | ModelMessage>,
+  options?: { includeSnapshotStructuredOutput: boolean },
 ): Array<WireMessage> {
   const wire: Array<WireMessage> = []
+  const usedWireIds = new Set<string>(
+    messages.flatMap((message) =>
+      'id' in message && message.id && message.role !== 'tool'
+        ? [message.id]
+        : [],
+    ),
+  )
+  const includeSnapshotStructuredOutput =
+    options?.includeSnapshotStructuredOutput ?? false
+
+  const assistantIds = new Set<string>()
+  for (const msg of messages) {
+    if (msg.role === 'assistant' && msg.id !== undefined) {
+      assistantIds.add(msg.id)
+    }
+  }
 
   for (const msg of messages) {
-    // Defensive: ModelMessage-shaped input has no `parts`; fall back to `content`.
-    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 (!('parts' in msg) && msg.role === 'tool' && msg.toolCallId) {
+      const id = uniqueToolWireId(
+        toolWireId(msg.id, msg.toolCallId, assistantIds),
+        usedWireIds,
+      )
+      const metadata = rebuiltToolMetadata(
+        msg.metadata,
+        msg.createdAt,
+        msg.id,
+        msg.content,
+      )
+      wire.push({
+        role: 'tool',
+        id,
+        ...(msg.name !== undefined && { name: msg.name }),
+        toolCallId: msg.toolCallId,
+        content:
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content),
+        ...(msg.error !== undefined && { error: msg.error }),
+        ...(metadata !== undefined && { metadata }),
+      })
+      continue
+    }
+
+    const uiMessage: UIMessage =
+      'parts' in msg ? msg : modelMessageToUIMessage(msg, msg.id)
+    const parts: ReadonlyArray<MessagePart> = uiMessage.parts
+    usedWireIds.add(uiMessage.id)
 
     if (msg.role === 'system') {
       wire.push(
         toAnchor(
-          msg,
+          uiMessage,
+          'system',
           {
             content:
               parts.length > 0
@@ -81,6 +144,7 @@ export function uiMessagesToWire(
                 : ((msg as { content?: string }).content ?? ''),
           },
           parts,
+          includeSnapshotStructuredOutput,
         ),
       )
       continue
@@ -89,7 +153,8 @@ export function uiMessagesToWire(
     if (msg.role === 'user') {
       wire.push(
         toAnchor(
-          msg,
+          uiMessage,
+          'user',
           {
             content:
               parts.length > 0
@@ -97,6 +162,7 @@ export function uiMessagesToWire(
                 : ((msg as { content?: string }).content ?? ''),
           },
           parts,
+          includeSnapshotStructuredOutput,
         ),
       )
       continue
@@ -105,9 +171,9 @@ export function uiMessagesToWire(
     // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs
     for (const part of parts) {
       if (part.type === 'thinking') {
-        const reasoning: AGUIReasoningMessage = {
+        const reasoning: WireReasoningMessage = {
           role: 'reasoning',
-          id: deriveReasoningId(msg.id, part),
+          id: uniqueWireId(deriveReasoningId(uiMessage.id, part), usedWireIds),
           content: part.content,
         }
         if (part.signature) {
@@ -121,26 +187,79 @@ export function uiMessagesToWire(
     const toolCalls = collectToolCalls(parts)
     wire.push(
       toAnchor(
-        msg,
+        uiMessage,
+        'assistant',
         {
           ...(text !== '' && { content: text }),
           ...(toolCalls && { toolCalls }),
         },
         parts,
+        includeSnapshotStructuredOutput,
       ),
     )
 
+    const explicitToolResults = new Set(
+      parts.flatMap((part) =>
+        part.type === 'tool-result' ? [part.toolCallId] : [],
+      ),
+    )
     for (const part of parts) {
       if (part.type === 'tool-result') {
+        const id = uniqueToolWireId(
+          part.id ?? deriveToolMessageId(part.toolCallId),
+          usedWireIds,
+        )
+        const metadata = rebuiltToolMetadata(
+          part.metadata,
+          part.createdAt,
+          part.id,
+          part.content,
+          true,
+        )
         wire.push({
           role: 'tool',
-          id: deriveToolMessageId(part.toolCallId),
+          id,
           toolCallId: part.toolCallId,
+          ...(part.name !== undefined && { name: part.name }),
           content:
             typeof part.content === 'string'
               ? part.content
               : JSON.stringify(part.content),
           ...(part.error !== undefined && { error: part.error }),
+          ...(metadata !== undefined && { metadata }),
+        })
+      } else if (part.type === 'tool-call') {
+        const approved = part.approval?.approved
+        if (
+          explicitToolResults.has(part.id) ||
+          (part.output === undefined &&
+            (part.state !== 'approval-responded' || approved === undefined))
+        ) {
+          continue
+        }
+        const result =
+          part.output !== undefined
+            ? normalizeToolResult(part.output)
+            : JSON.stringify({
+                approved,
+                ...(approved && { pendingExecution: true }),
+                message: approved
+                  ? 'User approved this action'
+                  : 'User denied this action',
+              })
+        const content =
+          typeof result === 'string' ? result : JSON.stringify(result)
+        wire.push({
+          role: 'tool',
+          id: uniqueToolWireId(deriveToolMessageId(part.id), usedWireIds),
+          toolCallId: part.id,
+          content,
+          metadata: rebuiltToolMetadata(
+            undefined,
+            undefined,
+            undefined,
+            result,
+          ),
         })
       }
     }
@@ -151,33 +270,78 @@ export function uiMessagesToWire(
 
 function toAnchor(
   msg: UIMessage,
+  role: 'system',
+  extras: { content: string },
+  parts: ReadonlyArray<MessagePart>,
+  includeSnapshotStructuredOutput: boolean,
+): WireSystemMessage
+function toAnchor(
+  msg: UIMessage,
+  role: 'user',
+  extras: { content: string | Array<InputContent> },
+  parts: ReadonlyArray<MessagePart>,
+  includeSnapshotStructuredOutput: boolean,
+): WireUserMessage
+function toAnchor(
+  msg: UIMessage,
+  role: 'assistant',
   extras: {
-    content?: string | Array<AGUIInputContent>
-    toolCalls?: Array<AGUIToolCallMirror>
+    content?: string
+    toolCalls?: Array<ToolCall>
   },
   parts: ReadonlyArray<MessagePart>,
-): WireAnchorMessage {
-  const metadata = messageMetadata(msg, parts)
-  const name = (msg as { name?: string }).name
-  return {
+  includeSnapshotStructuredOutput: boolean,
+): WireAssistantMessage
+function toAnchor(
+  msg: UIMessage,
+  role: UIMessage['role'],
+  extras: {
+    content?: string | Array<InputContent>
+    toolCalls?: Array<ToolCall>
+  },
+  parts: ReadonlyArray<MessagePart>,
+  includeSnapshotStructuredOutput: boolean,
+): WireSystemMessage | WireUserMessage | WireAssistantMessage {
+  const metadata = messageMetadata(msg, parts, includeSnapshotStructuredOutput)
+  const base = {
     id: msg.id,
-    role: msg.role,
-    ...(name !== undefined && { name }),
-    ...extras,
+    ...(msg.name !== undefined && { name: msg.name }),
     ...(metadata !== undefined && { metadata }),
   }
+  if (role === 'system') {
+    return { ...base, role, content: String(extras.content ?? '') }
+  }
+  if (role === 'user') {
+    return { ...base, role, content: extras.content ?? '' }
+  }
+  return {
+    ...base,
+    role,
+    ...(typeof extras.content === 'string' && { content: extras.content }),
+    ...(extras.toolCalls !== undefined && { toolCalls: extras.toolCalls }),
+  }
 }
 
 function messageMetadata(
   msg: UIMessage,
   parts: ReadonlyArray<MessagePart>,
+  includeSnapshotStructuredOutput: boolean,
 ): MetadataRecord | undefined {
   const base: MetadataRecord = { ...(msg.metadata ?? {}) }
-  const tanstack: MetadataRecord = { ...(tanstackMetadata(msg) ?? {}) }
-  if (msg.createdAt) tanstack.createdAt = msg.createdAt.toISOString()
+  const previousTanstack = tanstackMetadata(msg)
+  const tanstack: TanStackMessageMetadata = {}
+  if (previousTanstack?.model !== undefined)
+    tanstack.model = previousTanstack.model
+  if (previousTanstack?.signature !== undefined)
+    tanstack.signature = previousTanstack.signature
+  const createdAt = coerceCreatedAt(msg.createdAt)
+  if (createdAt !== undefined) tanstack.createdAt = createdAt.toISOString()
 
-  const leftover = unfinishedStructuredOutput(parts)
-  if (leftover) tanstack.structuredOutput = leftover
+  const structuredOutput = serializedStructuredOutput(
+    parts,
+    includeSnapshotStructuredOutput,
+  )
+  if (structuredOutput) tanstack.structuredOutput = structuredOutput
 
   const toolCallMetadata: Record<string, unknown> = {}
   for (const part of parts) {
@@ -195,26 +359,41 @@ function messageMetadata(
   if (uiResources.length > 0) tanstack.uiResources = uiResources
 
   if (Object.keys(tanstack).length > 0) base.tanstack = tanstack
+  else delete base.tanstack
   return Object.keys(base).length > 0 ? base : undefined
 }
 
-function unfinishedStructuredOutput(
+function serializedStructuredOutput(
   parts: ReadonlyArray<MessagePart>,
+  includeSnapshotStructuredOutput: boolean,
 ): TanStackMessageMetadata['structuredOutput'] | undefined {
   for (const p of parts) {
-    if (p.type === 'structured-output' && p.status !== 'complete') {
-      return structuredOutputLeftover(p)
+    if (
+      p.type === 'structured-output' &&
+      (includeSnapshotStructuredOutput || p.status !== 'complete')
+    ) {
+      return structuredOutputMetadata(p, includeSnapshotStructuredOutput)
     }
   }
   return undefined
 }
 
-function structuredOutputLeftover(
+function structuredOutputMetadata(
   part: StructuredOutputPart,
+  includeSnapshotStructuredOutput: boolean,
 ): NonNullable<TanStackMessageMetadata['structuredOutput']> {
   return {
     status: part.status,
     raw: part.raw,
+    ...(includeSnapshotStructuredOutput && part.partial !== undefined
+      ? { partial: part.partial }
+      : {}),
+    ...(includeSnapshotStructuredOutput && part.data !== undefined
+      ? { data: part.data }
+      : {}),
+    ...(includeSnapshotStructuredOutput && part.reasoning
+      ? { reasoning: part.reasoning }
+      : {}),
     ...(part.errorMessage !== undefined && { errorMessage: part.errorMessage }),
   }
 }
@@ -247,7 +426,7 @@ function collectText(parts: ReadonlyArray<MessagePart>): string {
 
 function collectUserContent(
   parts: ReadonlyArray<MessagePart>,
-): string | Array<AGUIInputContent> {
+): string | Array<InputContent> {
   const hasMultimodal = parts.some(
     (p) =>
       p.type === 'image' ||
@@ -258,7 +437,7 @@ function collectUserContent(
   if (!hasMultimodal) {
     return collectText(parts)
   }
-  const out: Array<AGUIInputContent> = []
+  const out: Array<InputContent> = []
   for (const p of parts) {
     if (p.type === 'text') {
       out.push({ type: 'text', text: p.content })
@@ -289,8 +468,8 @@ function thoughtSignatureFromMetadata(metadata: unknown): string | undefined {
 
 function collectToolCalls(
   parts: ReadonlyArray<MessagePart>,
-): Array<AGUIToolCallMirror> | undefined {
-  const calls: Array<AGUIToolCallMirror> = []
+): Array<ToolCall> | undefined {
+  const calls: Array<ToolCall> = []
   for (const p of parts) {
     if (p.type === 'tool-call') {
       const encryptedValue = thoughtSignatureFromMetadata(p.metadata)
@@ -313,6 +492,32 @@ function deriveToolMessageId(toolCallId: string): string {
   return `tool-${toolCallId}`
 }
 
+function uniqueToolWireId(id: string, used: Set<string>): string {
+  return uniqueWireId(id, used)
+}
+
+function uniqueWireId(id: string, used: Set<string>): string {
+  if (!used.has(id)) {
+    used.add(id)
+    return id
+  }
+  let suffix = 2
+  while (used.has(`${id}-${suffix}`)) suffix++
+  const unique = `${id}-${suffix}`
+  used.add(unique)
+  return unique
+}
+
+function toolWireId(
+  id: string | undefined,
+  toolCallId: string,
+  assistantIds: ReadonlySet<string>,
+): string {
+  const derived = deriveToolMessageId(toolCallId)
+  if (id === undefined || assistantIds.has(id)) return derived
+  return id
+}
+
 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