@tanstack/ai 0.57.0 → 0.59.0

package/src/activities/chat/messages.ts

@@ -4,6 +4,10 @@ import {
   normalizeToolResult,
 } from '../../utilities/tool-result'
 import { tanstackMetadata } from '../../utilities/merge-metadata'
+import {
+  splitSubagentWire,
+  subagentWireText,
+} from '../../utilities/subagent-wire'
 import type { Message as AGUIMessage } from '@ag-ui/core'
 import type {
   ContentPart,
@@ -14,6 +18,7 @@ import type {
   TextPart,
   ToolCall,
   ToolCallPart,
+  SubagentPart,
   UIMessage,
   UIResourcePart,
 } from '../../types'
@@ -124,6 +129,37 @@ function getTextContent(
     .join('')
 }
 
+function historyTextFromParts(parts: ReadonlyArray<MessagePart>): string {
+  const blocks: Array<string> = []
+  for (const part of parts) {
+    if (part.type === 'text' && part.content !== '') {
+      blocks.push(part.content)
+    } else if (
+      part.type === 'structured-output' &&
+      part.status === 'complete' &&
+      part.raw !== ''
+    ) {
+      blocks.push(part.raw)
+    } else if (part.type === 'subagent') {
+      const nested = subagentHistoryText(part)
+      if (nested !== '') blocks.push(nested)
+    }
+  }
+  return blocks.join('\n\n')
+}
+
+/** Child text for a later turn. The name stays so the next agent can tell the notes apart. */
+export function subagentHistoryText(part: SubagentPart): string {
+  const blocks: Array<string> = []
+  for (const message of part.subagent.messages) {
+    if (!('parts' in message)) continue
+    const text = historyTextFromParts(message.parts).trim()
+    if (text !== '') blocks.push(text)
+  }
+  if (blocks.length === 0) return ''
+  return `${part.subagent.name}:\n${blocks.join('\n\n')}`
+}
+
 function toolResultContent(
   content: string | null | undefined | Array<ContentPart>,
 ): string | Array<ContentPart> {
@@ -135,6 +171,57 @@ function toolResultContent(
  */
 export function convertMessagesToModelMessages(
   messages: Array<UIMessage | ModelMessage>,
+): Array<ModelMessage> {
+  const { top, groups } = splitSubagentWire(messages)
+  if (groups.length === 0) return convertOwnMessages(messages)
+
+  // Child wire messages leave the parent history. The parent model reads each
+  // child's text on the assistant message before it, the same as for a UI
+  // subagent part. A child that a tool call started reports through the tool
+  // result instead.
+  const blocks = new Map<string | undefined, Array<string>>()
+  for (const group of groups) {
+    if (group.info.parentToolCallId !== undefined) continue
+    const text = subagentWireText(group.messages)
+    if (text === '') continue
+    const host = top
+      .slice(0, group.hostIndex + 1)
+      .findLast((message) => message.role === 'assistant')
+    const hostId = host && 'id' in host ? host.id : undefined
+    blocks.set(hostId, [
+      ...(blocks.get(hostId) ?? []),
+      `${group.info.name}:\n${text}`,
+    ])
+  }
+  const converted = convertOwnMessages(top)
+  for (const [hostId, texts] of blocks) {
+    const block = texts.join('\n\n')
+    const index =
+      hostId === undefined
+        ? -1
+        : converted.findIndex(
+            (message) => message.role === 'assistant' && message.id === hostId,
+          )
+    const host = converted[index]
+    if (!host) {
+      converted.push({ role: 'assistant', content: block })
+      continue
+    }
+    converted[index] = {
+      ...host,
+      content:
+        typeof host.content === 'string' && host.content !== ''
+          ? `${host.content}\n\n${block}`
+          : Array.isArray(host.content)
+            ? [...host.content, { type: 'text', content: block }]
+            : block,
+    }
+  }
+  return converted
+}
+
+function convertOwnMessages(
+  messages: Array<UIMessage | ModelMessage>,
 ): Array<ModelMessage> {
   // Pre-pass: collect toolCallIds already represented in anchor UIMessage parts.
   // Fan-out tool messages whose toolCallId matches an anchored ToolResultPart
@@ -455,6 +542,7 @@ function assistantMetadata(
   const previous = tanstackMetadata(uiMessage)
   const tanstack: TanStackMessageMetadata = {}
   if (previous?.model !== undefined) tanstack.model = previous.model
+  if (previous?.runId !== undefined) tanstack.runId = previous.runId
   if (previous?.signature !== undefined) tanstack.signature = previous.signature
   if (fromParts.length > 0) tanstack.uiResources = fromParts
   const result = { ...current }
@@ -690,6 +778,22 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         // model input, so it is intentionally dropped from the model message.
         break
 
+      case 'subagent': {
+        // A child that a tool call started reports through the tool result.
+        const block =
+          part.subagent.parentToolCallId === undefined
+            ? subagentHistoryText(part)
+            : ''
+        if (block !== '') {
+          const prefix = current.contentParts.length > 0 ? '\n\n' : ''
+          current.contentParts.push({
+            type: 'text',
+            content: `${prefix}${block}`,
+          })
+        }
+        break
+      }
+
       default:
         break
     }
@@ -947,7 +1051,9 @@ export function aguiSnapshotMessageToUIMessage(
         modelMessageToUIMessage(
           {
             role: 'tool',
-            content: message.content,
+            content: isContentPartArray(message.content)
+              ? message.content
+              : aguiContentToContentParts(message.content),
             toolCallId: message.toolCallId,
             ...('name' in message && typeof message.name === 'string'
               ? { name: message.name }
@@ -1071,25 +1177,29 @@ function snapshotStructuredOutput(
  * AG-UI user content is either a plain string or a multimodal array whose text
  * entries use `{ type: 'text', text }` (vs. TanStack's `{ type: 'text', content }`).
  * Text entries are rewritten to the TanStack shape; image/audio/video/document
- * entries already match `ContentPart` and pass through. `binary` entries have no
- * TanStack equivalent and are dropped.
+ * entries already match `ContentPart` and pass through.
  */
 function aguiUserContentToParts(
   content: Extract<AGUIMessage, { role: 'user' }>['content'],
 ): Array<MessagePart> {
-  if (typeof content === 'string') {
-    return content ? [{ type: 'text', content }] : []
-  }
+  const converted = aguiContentToContentParts(content)
+  return typeof converted === 'string'
+    ? converted
+      ? [{ type: 'text', content: converted }]
+      : []
+    : converted
+}
 
-  const parts: Array<MessagePart> = []
-  for (const part of content) {
-    if (part.type === 'text') {
-      parts.push({ type: 'text', content: part.text })
-    } else if (part.type !== 'binary') {
-      parts.push(part)
-    }
-  }
-  return parts
+/** Convert wire content parts. Data, url, and file sources pass through. */
+export function aguiContentToContentParts(
+  content: Extract<AGUIMessage, { role: 'user' }>['content'],
+): string | Array<ContentPart> {
+  if (typeof content === 'string') return content
+  return content.map((part) => {
+    if (part.type !== 'text') return part
+    const { text, ...rest } = part
+    return { ...rest, content: text }
+  })
 }
 
 /**

package/src/activities/chat/middleware/run-store.ts

@@ -112,8 +112,25 @@ export interface RunRecord {
    * reuse this record by faking `threadId = requestId`; they need a separate
    * job store. `withGenerationPersistence` currently does exactly that and
    * labels itself a stopgap — do not copy it.
+   *
+   * A subagent child record stores `subagent:<subagentRunId>` here, the key of
+   * its own transcript, so `findActiveRun` and `listByThread` on the
+   * conversation never return children. Use `listByParentRun`.
    */
   threadId: string
+  /**
+   * Parent chat run that started this child, when this record is a subagent.
+   * Absent on the parent run itself.
+   */
+  parentRunId?: string
+  /**
+   * The child's AG-UI subagentRunId, the id on its `SUBAGENT_*` chunks and on
+   * every chunk it streams. On a child record this equals `runId`. Absent on
+   * the parent run.
+   */
+  subagentRunId?: string
+  /** Agent name (`researcher`, `writer`) when this record is a subagent. */
+  name?: string
   status: RunStatus
   startedAt: number
   finishedAt?: number
@@ -172,9 +189,10 @@ export interface RunRecord {
  * instead of failing at build time. It was optional for exactly one release
  * cycle and cost precisely that.
  *
- * OPTIONAL: `listByThread`, `listReclaimable`. Each serves one higher-level
- * feature (thread history, reclaim reaping) and callers feature-detect them,
- * degrading gracefully when a backend omits them.
+ * OPTIONAL: `listByThread`, `listByParentRun`, `listReclaimable`. Each serves
+ * one higher-level feature (thread history, subagent card reload, reclaim
+ * reaping) and callers feature-detect them, degrading when a backend omits
+ * them.
  */
 export interface RunStore {
   /**
@@ -182,12 +200,17 @@ export interface RunStore {
    * already present.
    *
    * INVARIANT (idempotency): an existing record is returned **unchanged** and
-   * the passed `threadId`/`startedAt`/`status` are ignored. This is what makes
-   * resuming a run safe. `status` defaults to `'running'` on first creation.
+   * the passed `threadId`, `startedAt`, `status`, `parentRunId`,
+   * `subagentRunId`, and `name` are ignored. This is what makes resuming a
+   * run safe. `status` defaults to `'running'` on first creation. The three
+   * link fields are copied only on the first insert.
    */
   createOrResume: (
     input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
       status?: RunStatus
+      parentRunId?: string
+      subagentRunId?: string
+      name?: string
     },
   ) => Promise<RunRecord>
   /**
@@ -215,10 +238,19 @@ export interface RunStore {
   /** Current record, or null when unknown. */
   get: (runId: string) => Promise<RunRecord | null>
   /**
-   * Every run in a conversation, ascending by `startedAt`. OPTIONAL: only
-   * needed to render a thread's past agent activity. Consumers feature-detect.
+   * Every run in a conversation, ascending by `startedAt`. OPTIONAL.
+   * `reconstructChat` calls it to find the parent runs of children that a
+   * tool call started. Without it those cards stay absent on reload.
+   * Consumers feature-detect.
    */
   listByThread?: (threadId: string) => Promise<Array<RunRecord>>
+  /**
+   * Child runs started by `parentRunId`, ascending by `startedAt`.
+   * OPTIONAL. `reconstructChat` uses this to put subagent cards back
+   * on the parent assistant message. A store that omits it reloads the
+   * text and not the cards.
+   */
+  listByParentRun?: (parentRunId: string) => Promise<Array<RunRecord>>
   /**
    * Runs that may be reclaimed: ALL THREE of `status === 'running'`,
    * `detachedSince` is set, and `detachedSince <= now - ttlMs`. The cutoff is
@@ -341,6 +373,9 @@ export class InMemoryRunStore implements RunStore {
   createOrResume(
     input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
       status?: RunStatus
+      parentRunId?: string
+      subagentRunId?: string
+      name?: string
     },
   ): Promise<RunRecord> {
     const existing = this.runs.get(input.runId)
@@ -350,6 +385,13 @@ export class InMemoryRunStore implements RunStore {
       threadId: input.threadId,
       status: input.status ?? 'running',
       startedAt: input.startedAt,
+      ...(input.parentRunId !== undefined
+        ? { parentRunId: input.parentRunId }
+        : {}),
+      ...(input.subagentRunId !== undefined
+        ? { subagentRunId: input.subagentRunId }
+        : {}),
+      ...(input.name !== undefined ? { name: input.name } : {}),
     }
     this.runs.set(record.runId, record)
     return Promise.resolve(record)
@@ -387,6 +429,13 @@ export class InMemoryRunStore implements RunStore {
     return Promise.resolve(matching)
   }
 
+  listByParentRun(parentRunId: string): Promise<Array<RunRecord>> {
+    const matching = [...this.runs.values()]
+      .filter((run) => run.parentRunId === parentRunId)
+      .sort((a, b) => a.startedAt - b.startedAt)
+    return Promise.resolve(matching)
+  }
+
   listReclaimable(opts: {
     now: number
     ttlMs: number

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

@@ -4,8 +4,11 @@ import type {
 } from '@standard-schema/spec'
 import type {
   AgentLoopState,
+  EmitCustomEventOptions,
+  Interrupt,
   JSONSchema,
   ModelMessage,
+  UIMessage,
   RunAgentResumeItem,
   StreamChunk,
   TokenUsage,
@@ -190,6 +193,11 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   runId: string
   /** Interrupted or parent run correlated with this continuation. */
   parentRunId?: string
+  /**
+   * Set when this run is a subagent. The id on the child's `SUBAGENT_STARTED`
+   * and on every chunk it streams. Absent on a top-level run.
+   */
+  subagentRunId?: string
   /**
    * AG-UI thread identifier — a stable per-conversation ID used to
    * correlate client and server devtools events. Resolves to the
@@ -216,9 +224,14 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   /**
    * Push a `CUSTOM` chunk onto the chat stream immediately.
    * The engine yields it as soon as it can (including while `onConfig`
-   * is still awaiting work such as a summarize call).
+   * is still awaiting work such as a summarize call). Durability then
+   * flushes the event on its own, unless you pass `{ batch: true }`.
    */
-  emitCustomEvent: (name: string, value: Record<string, any>) => void
+  emitCustomEvent: (
+    name: string,
+    value: Record<string, any>,
+    options?: EmitCustomEventOptions,
+  ) => void
   /** Runtime context provided by chat() options */
   context: TContext
   /**
@@ -538,6 +551,40 @@ export interface ErrorInfo {
   duration: number
 }
 
+/**
+ * Saves subagent runs while a router owns the turn.
+ * `withPersistence` sets this. `chat()` calls it. Apps do not.
+ */
+export interface RoutedSubagentPersistence {
+  start: (input: {
+    threadId: string
+    runId: string
+    messages: ReadonlyArray<UIMessage | ModelMessage>
+    /**
+     * The run's resume entries: answers to earlier child interrupts, plus any
+     * the parent answers itself.
+     */
+    resume?: ReadonlyArray<RunAgentResumeItem>
+  }) => Promise<void>
+  chunk: (input: {
+    threadId: string
+    runId: string
+    chunk: StreamChunk
+  }) => Promise<void>
+  finish: (input: { threadId: string; runId: string }) => Promise<void>
+  /** The run stopped because a child waits for outside input. */
+  suspend?: (input: {
+    threadId: string
+    runId: string
+    interrupts: ReadonlyArray<Interrupt>
+  }) => Promise<void>
+  abort: (input: {
+    threadId: string
+    runId: string
+    error?: unknown
+  }) => Promise<void>
+}
+
 // ===========================
 // Middleware Interface
 // ===========================
@@ -578,6 +625,12 @@ export interface ChatMiddleware<
   /** Optional name for debugging and identification */
   name?: string
 
+  /**
+   * Present when this middleware stores subagent runs.
+   * The router calls it. An app does not set it.
+   */
+  routedSubagentPersistence?: RoutedSubagentPersistence
+
   /**
    * Called at a lifecycle boundary. Return interrupt requests to pause the run.
    * Requests from every middleware in the same boundary form one batch.