@tanstack/ai 0.58.0 → 0.59.0

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

@@ -12,6 +12,7 @@ import type {
   MessagePart,
   ModelMessage,
   StructuredOutputPart,
+  SubagentPart,
   TanStackMessageMetadata,
   UIMessage,
   UIResourcePart,
@@ -19,6 +20,8 @@ import type {
 import type { MetadataRecord } from './merge-metadata'
 import { tanstackMetadata } from './merge-metadata'
 import { normalizeToolResult } from './tool-result'
+import { wireSubagentInfo, wireSubagentRunId } from './subagent-wire'
+import type { SubagentWireInfo } from './subagent-wire'
 import {
   coerceCreatedAt,
   modelMessageToUIMessage,
@@ -263,6 +266,10 @@ export function uiMessagesToWire(
         })
       }
     }
+
+    for (const part of parts) {
+      if (part.type === 'subagent') wire.push(...subagentToWire(part, options))
+    }
   }
 
   return wire
@@ -332,6 +339,8 @@ function messageMetadata(
   const tanstack: TanStackMessageMetadata = {}
   if (previousTanstack?.model !== undefined)
     tanstack.model = previousTanstack.model
+  if (previousTanstack?.runId !== undefined)
+    tanstack.runId = previousTanstack.runId
   if (previousTanstack?.signature !== undefined)
     tanstack.signature = previousTanstack.signature
   const createdAt = coerceCreatedAt(msg.createdAt)
@@ -424,6 +433,71 @@ function collectText(parts: ReadonlyArray<MessagePart>): string {
   return out.join('')
 }
 
+/**
+ * A child's messages, tagged with its AG-UI `subagentRunId`. The card data
+ * rides in `metadata.tanstack.subagent`, so the other side can rebuild the
+ * card and continue a suspended child.
+ */
+function subagentToWire(
+  part: SubagentPart,
+  options?: { includeSnapshotStructuredOutput: boolean },
+): Array<WireMessage> {
+  const { subagent } = part
+  const info: SubagentWireInfo = {
+    name: subagent.name,
+    status: subagent.status,
+    ...(subagent.description !== undefined && {
+      description: subagent.description,
+    }),
+    ...(subagent.error !== undefined && { error: subagent.error }),
+    ...(subagent.interruptIds !== undefined && {
+      interruptIds: subagent.interruptIds,
+    }),
+    ...(subagent.parentSubagentRunId !== undefined && {
+      parentSubagentRunId: subagent.parentSubagentRunId,
+    }),
+    ...(subagent.parentToolCallId !== undefined && {
+      parentToolCallId: subagent.parentToolCallId,
+    }),
+    ...(subagent.metadata !== undefined && { metadata: subagent.metadata }),
+  }
+  const child = uiMessagesToWire(subagent.messages, options)
+  const own = child.some((message) => wireSubagentRunId(message) === undefined)
+  const messages: Array<WireMessage> = own
+    ? child
+    : [{ id: `subagent:${subagent.id}`, role: 'assistant' }, ...child]
+  return messages.map((message, index) => {
+    const nestedId = wireSubagentRunId(message)
+    if (nestedId !== undefined) {
+      const nested = wireSubagentInfo(message)
+      if (!nested || nested.parentSubagentRunId !== undefined) return message
+      return withSubagentInfo(message, nestedId, {
+        ...nested,
+        parentSubagentRunId: subagent.id,
+      })
+    }
+    return withSubagentInfo(
+      message,
+      subagent.id,
+      !own && index === 0 ? { ...info, placeholder: true } : info,
+    )
+  })
+}
+
+function withSubagentInfo(
+  message: WireMessage,
+  subagentRunId: string,
+  info: SubagentWireInfo,
+): WireMessage {
+  const metadata = isRecord(message.metadata) ? message.metadata : {}
+  const tanstack = isRecord(metadata.tanstack) ? metadata.tanstack : {}
+  return {
+    ...message,
+    subagentRunId,
+    metadata: { ...metadata, tanstack: { ...tanstack, subagent: info } },
+  }
+}
+
 function collectUserContent(
   parts: ReadonlyArray<MessagePart>,
 ): string | Array<InputContent> {

package/src/utilities/normalize-stream-chunk.ts

@@ -11,6 +11,14 @@ function stringField(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
 
+function chunkFields(chunk: object) {
+  const fields: Record<string, unknown> = {}
+  for (const key of Object.keys(chunk)) {
+    fields[key] = Reflect.get(chunk, key)
+  }
+  return fields
+}
+
 function encryptedValueExtras(chunk: AdapterYieldChunk): Array<StreamChunk> {
   const extras: Array<StreamChunk> = []
   const timestamp =
@@ -19,7 +27,7 @@ function encryptedValueExtras(chunk: AdapterYieldChunk): Array<StreamChunk> {
       : undefined
 
   if (typeof chunk.signature === 'string' && chunk.signature !== '') {
-    const source = chunk as Record<string, unknown>
+    const source = chunkFields(chunk)
     const toolCallId = stringField(source.toolCallId)
     const entityId =
       stringField(chunk.stepId) ??
@@ -62,7 +70,7 @@ export function normalizeStreamChunk(
   chunk: AdapterYieldChunk,
 ): Array<StreamChunk> {
   const specKeys = specKeysFor(chunk.type)
-  const source = chunk as Record<string, unknown>
+  const source = chunkFields(chunk)
   const specChunk: Record<string, unknown> & {
     metadata?: MetadataRecord | null
   } = {}

package/src/utilities/spec-event-keys.ts

@@ -30,11 +30,6 @@ const SPEC_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
     EventType.TOOL_CALL_RESULT,
     keys('messageId', 'toolCallId', 'content', 'role'),
   ],
-  [EventType.THINKING_START, keys('title')],
-  [EventType.THINKING_END, SHARED],
-  [EventType.THINKING_TEXT_MESSAGE_START, SHARED],
-  [EventType.THINKING_TEXT_MESSAGE_CONTENT, keys('delta')],
-  [EventType.THINKING_TEXT_MESSAGE_END, SHARED],
   [EventType.STATE_SNAPSHOT, keys('snapshot')],
   [EventType.STATE_DELTA, keys('delta')],
   [EventType.MESSAGES_SNAPSHOT, keys('messages')],
@@ -45,7 +40,10 @@ const SPEC_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
   [EventType.ACTIVITY_DELTA, keys('messageId', 'activityType', 'patch')],
   [EventType.RAW, keys('event', 'source')],
   [EventType.CUSTOM, keys('name', 'value')],
-  [EventType.RUN_STARTED, keys('threadId', 'runId', 'parentRunId', 'input')],
+  [
+    EventType.RUN_STARTED,
+    keys('threadId', 'runId', 'protocolVersion', 'parentRunId', 'input'),
+  ],
   [
     EventType.RUN_FINISHED,
     keys('threadId', 'runId', 'result', 'outcome', 'usage'),
@@ -63,10 +61,39 @@ const SPEC_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
     EventType.REASONING_ENCRYPTED_VALUE,
     keys('subtype', 'entityId', 'encryptedValue'),
   ],
+  [
+    EventType.SUBAGENT_STARTED,
+    keys(
+      'subagentRunId',
+      'name',
+      'description',
+      'parentSubagentRunId',
+      'parentToolCallId',
+      'parentMessageId',
+    ),
+  ],
+  [EventType.SUBAGENT_FINISHED, keys('subagentRunId', 'result', 'outcome')],
+  [EventType.SUBAGENT_ERROR, keys('subagentRunId', 'message', 'code')],
 ])
 
+const RUN_SCOPED = new Set<string>([
+  EventType.RUN_STARTED,
+  EventType.RUN_FINISHED,
+  EventType.RUN_ERROR,
+  EventType.MESSAGES_SNAPSHOT,
+])
+
+const ATTRIBUTABLE_KEYS = new Map(
+  [...SPEC_KEYS]
+    .filter(([type]) => !RUN_SCOPED.has(type))
+    .map(
+      ([type, fields]) =>
+        [type, new Set([...fields, 'subagentRunId'])] as const,
+    ),
+)
+
 export function specKeysFor(type: string): ReadonlySet<string> {
-  return SPEC_KEYS.get(type) ?? SHARED
+  return ATTRIBUTABLE_KEYS.get(type) ?? SPEC_KEYS.get(type) ?? SHARED
 }
 
 export function isSpecTopLevelKey(type: string, key: string): boolean {

package/src/utilities/subagent-wire.ts

@@ -0,0 +1,184 @@
+import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
+import type { SubagentHandleData } from '../types'
+
+/**
+ * Card data that travels on each child wire message, in
+ * `metadata.tanstack.subagent`. The messages carry the AG-UI `subagentRunId`.
+ */
+export interface SubagentWireInfo
+  extends
+    AGUISubagentInfo,
+    Pick<
+      SubagentHandleData,
+      | 'status'
+      | 'error'
+      | 'interruptIds'
+      | 'parentSubagentRunId'
+      | 'parentToolCallId'
+      | 'metadata'
+    > {
+  /** The child has no messages yet. This wire message only holds the card. */
+  placeholder?: true
+}
+
+export interface SubagentWireGroup<T> {
+  id: string
+  info: SubagentWireInfo
+  /** The child's messages without its own tag. Nested children keep theirs. */
+  messages: Array<T>
+  /** Index in `top` of the last message before this child, or -1. */
+  hostIndex: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function wireSubagentRunId(message: unknown): string | undefined {
+  if (!isRecord(message) || 'parts' in message) return undefined
+  const id = message.subagentRunId
+  return typeof id === 'string' && id !== '' ? id : undefined
+}
+
+export function wireSubagentInfo(
+  message: unknown,
+): SubagentWireInfo | undefined {
+  if (!isRecord(message) || !isRecord(message.metadata)) return undefined
+  const tanstack = message.metadata.tanstack
+  if (!isRecord(tanstack) || !isRecord(tanstack.subagent)) return undefined
+  // Wire data comes from the client. Keep only well-formed fields.
+  const { name, status, error, interruptIds } = tanstack.subagent
+  if (typeof name !== 'string' || !isStatus(status)) return undefined
+  const {
+    description,
+    parentSubagentRunId,
+    parentToolCallId,
+    metadata,
+    placeholder,
+  } = tanstack.subagent
+  return {
+    name,
+    status,
+    ...(typeof description === 'string' && { description }),
+    ...(isRecord(error) &&
+      typeof error.message === 'string' && {
+        error: {
+          message: error.message,
+          ...(typeof error.code === 'string' && { code: error.code }),
+        },
+      }),
+    ...(Array.isArray(interruptIds) && {
+      interruptIds: interruptIds.filter(
+        (id): id is string => typeof id === 'string',
+      ),
+    }),
+    ...(typeof parentSubagentRunId === 'string' && { parentSubagentRunId }),
+    ...(typeof parentToolCallId === 'string' && { parentToolCallId }),
+    ...(isRecord(metadata) && { metadata }),
+    ...(placeholder === true && { placeholder: true as const }),
+  }
+}
+
+function isStatus(value: unknown): value is SubagentWireInfo['status'] {
+  return (
+    value === 'running' ||
+    value === 'finished' ||
+    value === 'error' ||
+    value === 'suspended'
+  )
+}
+
+function untag<T>(message: T): T {
+  if (!isRecord(message)) return message
+  const { subagentRunId: _id, ...rest } = message
+  void _id
+  const metadata = isRecord(rest.metadata) ? rest.metadata : undefined
+  const tanstack = isRecord(metadata?.tanstack) ? metadata.tanstack : undefined
+  if (!metadata || !tanstack || !('subagent' in tanstack)) return rest as T
+  const { subagent: _info, ...tanstackRest } = tanstack
+  void _info
+  return { ...rest, metadata: { ...metadata, tanstack: tanstackRest } } as T
+}
+
+/**
+ * Split wire messages into the parent's own messages and one group per direct
+ * child. A nested child's messages stay inside its parent's group.
+ */
+export function splitSubagentWire<T>(messages: ReadonlyArray<T>): {
+  top: Array<T>
+  groups: Array<SubagentWireGroup<T>>
+} {
+  const parentOf = new Map<string, string | undefined>()
+  for (const message of messages) {
+    const id = wireSubagentRunId(message)
+    if (id !== undefined && !parentOf.has(id)) {
+      parentOf.set(id, wireSubagentInfo(message)?.parentSubagentRunId)
+    }
+  }
+  const rootOf = (id: string) => {
+    let current = id
+    for (let depth = 0; depth < 64; depth++) {
+      const parent = parentOf.get(current)
+      if (parent === undefined || !parentOf.has(parent)) return current
+      current = parent
+    }
+    return current
+  }
+
+  const top: Array<T> = []
+  const groups = new Map<string, SubagentWireGroup<T>>()
+  for (const message of messages) {
+    const id = wireSubagentRunId(message)
+    if (id === undefined) {
+      top.push(message)
+      continue
+    }
+    const root = rootOf(id)
+    let group = groups.get(root)
+    if (!group) {
+      group = {
+        id: root,
+        info: { name: 'subagent', status: 'finished' },
+        messages: [],
+        hostIndex: top.length - 1,
+      }
+      groups.set(root, group)
+    }
+    if (id !== root) {
+      group.messages.push(message)
+      continue
+    }
+    const info = wireSubagentInfo(message)
+    if (info) group.info = info
+    if (!info?.placeholder) group.messages.push(untag(message))
+  }
+  return { top, groups: [...groups.values()] }
+}
+
+/** Text a child wrote, for the parent model and for a later child. */
+export function subagentWireText(messages: ReadonlyArray<unknown>): string {
+  const blocks: Array<string> = []
+  for (const message of messages) {
+    if (!isRecord(message) || message.role !== 'assistant') continue
+    if (wireSubagentRunId(message) !== undefined) continue
+    const content = message.content
+    if (typeof content === 'string' && content.trim() !== '') {
+      blocks.push(content.trim())
+    }
+  }
+  const nested = splitSubagentWire(messages).groups
+  for (const group of nested) {
+    const text = subagentWireText(group.messages)
+    if (text !== '') blocks.push(`${group.info.name}:\n${text}`)
+  }
+  return blocks.join('\n\n')
+}
+
+/**
+ * The id of the parent assistant message that hosts a routed turn's cards.
+ * The persistence recorder writes that message, and a handoff run passes the
+ * same id so the stored thread keeps one copy.
+ */
+export function subagentHostMessageId(runId: string) {
+  return `assistant:${runId}`
+}