@tanstack/ai 0.57.0 → 0.59.0

package/src/activities/chat/index.ts

@@ -38,6 +38,8 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from '../../utilities/merge-metadata'
+import { subagentHostMessageId } from '../../utilities/subagent-wire'
+import { withDurabilityBatchHint } from '../../utilities/durability-batch'
 import { normalizeStreamChunk } from '../../utilities/normalize-stream-chunk'
 import { restorePublicUsage } from '../../utilities/restore-inbound-chunk'
 import type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'
@@ -45,6 +47,25 @@ import { normalizeToolResult } from '../../utilities/tool-result'
 import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import { assertUniqueToolNames } from './tools/unique-tool-names'
+import type { DefinedAgent } from './agents/define-agent'
+import {
+  collectNamedText,
+  createSubagentSink,
+  createSyntheticSubagentTools,
+  normalizeRouterPick,
+  rebindInterrupts,
+  spawnNamedAgents,
+  subagentCallMessages,
+  withChildUsage,
+} from './agents/spawn'
+import type {
+  SpawnEntry,
+  SubagentSink,
+  SubagentStep,
+  SubagentStepsPlan,
+  SubagentsBag,
+} from './agents/spawn'
+import { SUBAGENT_PLAN_KEY, readSubagentTurn } from './agents/turn'
 import {
   MiddlewareAbortError,
   ToolCallManager,
@@ -101,6 +122,7 @@ import type {
   ChatStream,
   ConstrainedModelMessage,
   CustomEvent,
+  EmitCustomEventOptions,
   InferSchemaType,
   Interrupt,
   JSONSchema,
@@ -161,6 +183,28 @@ type RuntimeToolWithApproval = AnyRuntimeTool & {
 }
 const interruptBindingMetadataKey = INTERRUPT_BINDING_METADATA_KEY
 
+/** Resume entries a subagent tool call owns. The parent run skips them. */
+const CHILD_RESUME_IDS = Symbol('tanstack.ai.childResumeIds')
+
+// ponytail: no adapter maps `{ type: 'file' }` yet, so every one fails closed
+// instead of reading the handle as a URL or base64. The Files API work
+// replaces this with a per-adapter capability check.
+function assertNoFileSources(
+  adapterName: string,
+  messages: ReadonlyArray<ModelMessage>,
+): void {
+  for (const message of messages) {
+    if (!Array.isArray(message.content)) continue
+    for (const part of message.content) {
+      if ('source' in part && part.source.type === 'file') {
+        throw new Error(
+          `${adapterName} does not support provider file-handle sources ({ type: 'file' }). Pass a data or url source.`,
+        )
+      }
+    }
+  }
+}
+
 interface StructuralInterruptFailure {
   error: Error
   errors: ReadonlyArray<InterruptSubmissionError>
@@ -393,8 +437,9 @@ type TextActivityOptionsWithContext<
     [],
   TContext = unknown,
   TMiddleware extends Array<unknown> | undefined = undefined,
+  TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>,
 > = Omit<
-  TextActivityOptions<TAdapter, TSchema, TStream, any>,
+  TextActivityOptions<TAdapter, TSchema, TStream, any, TAgents>,
   'tools' | 'middleware' | 'context' | 'interrupts'
 > & {
   tools?: TTools
@@ -420,6 +465,7 @@ export interface TextActivityOptions<
   TSchema extends SchemaInput | undefined,
   TStream extends boolean,
   TContext = unknown,
+  TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>,
 > {
   /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */
   adapter: TAdapter
@@ -497,6 +543,8 @@ export interface TextActivityOptions<
   runId?: TextOptions['runId']
   /** Parent run ID for AG-UI protocol nested run correlation. */
   parentRunId?: TextOptions['parentRunId']
+  /** Subagent run id when this chat runs as a child. See `defineAgent`. */
+  subagentRunId?: TextOptions['subagentRunId']
   /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
   state?: TextOptions['state']
   /**
@@ -504,6 +552,12 @@ export interface TextActivityOptions<
    * before accepting new input on a thread with pending interrupts.
    */
   resume?: TextOptions['resume']
+  /**
+   * Named child agents. When `router` is set, the library spawns that agent
+   * directly. When `router` is omitted, the main model gets one synthetic
+   * server tool per agent and picks the child.
+   */
+  subagents?: SubagentsBag<TAgents>
   /**
    * Optional Standard Schema for structured output.
    * When provided, the activity will:
@@ -840,6 +894,7 @@ class TextEngine<
   private readonly threadId: string
   private readonly runIdOverride?: string
   private readonly parentRunIdOverride?: string
+  private readonly subagentRunIdOverride?: string
 
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner<
@@ -970,6 +1025,7 @@ class TextEngine<
       this.createId('thread')
     this.runIdOverride = config.params.runId
     this.parentRunIdOverride = config.params.parentRunId
+    this.subagentRunIdOverride = config.params.subagentRunId
 
     // Initialize middleware — devtools first. Spec stripping for the AG-UI
     // wire happens in toServerSentEventsStream, so in-process chat()
@@ -988,6 +1044,7 @@ class TextEngine<
       streamId: this.streamId,
       runId: this.runIdOverride ?? this.requestId,
       parentRunId: this.parentRunIdOverride,
+      subagentRunId: this.subagentRunIdOverride,
       threadId: this.threadId,
       // Legacy alias kept on the ctx so middleware that reads
       // `ctx.conversationId` keeps working. Always equals `threadId`.
@@ -1000,9 +1057,9 @@ class TextEngine<
         this.abortReason = reason
         this.middlewareAbortController?.abort(reason)
       },
-      emitCustomEvent: (name, value) => {
+      emitCustomEvent: (name, value, options) => {
         this.middlewareCustomQueue.push(
-          this.createCustomEventChunk(name, value),
+          this.createCustomEventChunk(name, value, options),
         )
         const waiters = this.middlewareCustomWaiters
         this.middlewareCustomWaiters = []
@@ -1514,6 +1571,8 @@ class TextEngine<
       )
     }
 
+    assertNoFileSources(this.adapter.name, this.messages)
+
     for await (const raw of this.adapter.chatStream({
       model: this.params.model,
       messages: this.providerMessages,
@@ -2019,7 +2078,8 @@ class TextEngine<
       this.resolveExecutableTools(executablePendingCalls),
       approvals,
       clientToolResults,
-      (eventName, data) => this.createCustomEventChunk(eventName, data),
+      (eventName, data, options) =>
+        this.createCustomEventChunk(eventName, data, options),
       {
         onBeforeToolCall: async (toolCall, tool, args) => {
           this.logger.tools(`phase=before name=${toolCall.function.name}`, {
@@ -2080,7 +2140,8 @@ class TextEngine<
 
     if (
       executionResult.needsApproval.length > 0 ||
-      executionResult.needsClientExecution.length > 0
+      executionResult.needsClientExecution.length > 0 ||
+      executionResult.subagentInterrupts.length > 0
     ) {
       this.discardDeferredToolCallRunFinishedChunks()
 
@@ -2097,6 +2158,8 @@ class TextEngine<
         finishEvent,
         executionResult.needsApproval,
         executionResult.needsClientExecution,
+        [],
+        executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
       return emitted ? 'wait' : 'stop'
@@ -2199,7 +2262,8 @@ class TextEngine<
       this.resolveExecutableTools(executableToolCalls),
       approvals,
       clientToolResults,
-      (eventName, data) => this.createCustomEventChunk(eventName, data),
+      (eventName, data, options) =>
+        this.createCustomEventChunk(eventName, data, options),
       {
         onBeforeToolCall: async (toolCall, tool, args) => {
           this.logger.tools(`phase=before name=${toolCall.function.name}`, {
@@ -2288,7 +2352,8 @@ class TextEngine<
 
     if (
       executionResult.needsApproval.length > 0 ||
-      executionResult.needsClientExecution.length > 0
+      executionResult.needsClientExecution.length > 0 ||
+      executionResult.subagentInterrupts.length > 0
     ) {
       if (allResults.length > 0) {
         for (const chunk of afterToolBoundaryChunks) {
@@ -2300,6 +2365,8 @@ class TextEngine<
         finishEvent,
         executionResult.needsApproval,
         executionResult.needsClientExecution,
+        [],
+        executionResult.subagentInterrupts,
       )
       this.setToolPhase(emitted ? 'wait' : 'stop')
       return
@@ -2618,6 +2685,7 @@ class TextEngine<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
     genericInterruptIds: ReadonlyArray<string> = [],
+    childInterrupts: ReadonlyArray<Interrupt> = [],
   ): Array<Interrupt> {
     const interrupts: Array<Interrupt> = []
 
@@ -2735,6 +2803,9 @@ class TextEngine<
       })
     }
 
+    // A subagent tool call raised these. They keep their `subagentRunId`.
+    interrupts.push(...childInterrupts)
+
     const ids = new Set<string>()
     for (const interrupt of interrupts) {
       if (ids.has(interrupt.id)) {
@@ -2756,6 +2827,7 @@ class TextEngine<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
     genericInterruptIds?: ReadonlyArray<string>,
+    childInterrupts?: ReadonlyArray<Interrupt>,
   ): StreamChunk {
     return {
       ...finishEvent,
@@ -2767,6 +2839,7 @@ class TextEngine<
           clientRequests,
           genericRequests,
           genericInterruptIds,
+          childInterrupts,
         ),
       },
     }
@@ -2916,11 +2989,13 @@ class TextEngine<
     genericRequests: ReadonlyArray<
       GenericInterruptRequest<InterruptDefinition<any, any, any, any>>
     > = [],
+    childInterrupts: ReadonlyArray<Interrupt> = [],
   ): AsyncGenerator<StreamChunk, boolean, void> {
     yield* this.emitSyntheticRunStarted(finishEvent)
     const genericInterruptIds = genericRequests.map(() =>
       this.genericInterruptId(),
     )
+    // Binding completion also binds child interrupts to this run.
     const terminal = this.completeEphemeralInterruptBindings(
       this.buildInterruptFinishedChunk(
         finishEvent,
@@ -2928,6 +3003,7 @@ class TextEngine<
         clientRequests,
         genericRequests,
         genericInterruptIds,
+        childInterrupts,
       ),
     )
     let terminalOutputs: Array<StreamChunk>
@@ -3513,6 +3589,8 @@ class TextEngine<
     // Apply merged config back to engine state
     this.applyMiddlewareConfig(postOnConfig)
 
+    assertNoFileSources(this.adapter.name, this.messages)
+
     // Build the StructuredOutputOptions the adapter expects.
     // `this.adapter` is already `TAdapter extends AnyTextAdapter` per the
     // class generics — no cast needed.
@@ -4009,9 +4087,25 @@ class TextEngine<
     }
   }
 
+  /** Resume entries this run answers itself. A subagent tool owns the rest. */
+  private ownResume(
+    resume: ChatMiddlewareConfig['resume'],
+  ): ChatMiddlewareConfig['resume'] {
+    const childIds = (
+      this.params as { [CHILD_RESUME_IDS]?: ReadonlySet<string> }
+    )[CHILD_RESUME_IDS]
+    return childIds
+      ? resume?.filter((entry) => !childIds.has(entry.interruptId))
+      : resume
+  }
+
   private async applyEphemeralInterruptResume(
-    config: ChatMiddlewareConfig,
+    middlewareConfig: ChatMiddlewareConfig,
   ): Promise<void> {
+    const config = {
+      ...middlewareConfig,
+      resume: this.ownResume(middlewareConfig.resume),
+    }
     if ((config.resume?.length ?? 0) === 0) {
       return
     }
@@ -4244,7 +4338,7 @@ class TextEngine<
     }> = []
     const ids = new Set<string>()
     const batchIndexes = new Set<number>()
-    for (const resumeItem of this.params.resume ?? []) {
+    for (const resumeItem of this.ownResume(this.params.resume) ?? []) {
       const parsed = readGenericInterruptContinuation(resumeItem.metadata)
       if (parsed.status === 'absent') continue
       if (parsed.status === 'invalid') {
@@ -4554,11 +4648,12 @@ class TextEngine<
    */
   private async *drainToolCallGenerator(
     generator: AsyncGenerator<
-      CustomEvent,
+      CustomEvent | StreamChunk,
       {
         results: Array<ToolResult>
         needsApproval: Array<ApprovalRequest>
         needsClientExecution: Array<ClientToolRequest>
+        subagentInterrupts: Array<Interrupt>
       },
       void
     >,
@@ -4568,6 +4663,7 @@ class TextEngine<
       results: Array<ToolResult>
       needsApproval: Array<ApprovalRequest>
       needsClientExecution: Array<ClientToolRequest>
+      subagentInterrupts: Array<Interrupt>
     },
     void
   > {
@@ -4583,13 +4679,15 @@ class TextEngine<
   private createCustomEventChunk(
     eventName: string,
     value: Record<string, unknown>,
+    options?: EmitCustomEventOptions,
   ): CustomEvent {
-    return {
+    const chunk: CustomEvent = {
       type: EventType.CUSTOM,
       timestamp: Date.now(),
       name: eventName,
       value,
     }
+    return options?.batch ? withDurabilityBatchHint(chunk) : chunk
   }
 
   private createId(prefix: string): string {
@@ -4677,6 +4775,8 @@ export function chat<
   > = [],
   TContext = unknown,
   const TMiddleware extends Array<unknown> | undefined = undefined,
+  const TAgents extends ReadonlyArray<DefinedAgent> =
+    ReadonlyArray<DefinedAgent>,
 >(
   options: TextActivityOptionsWithContext<
     TAdapter,
@@ -4685,7 +4785,8 @@ export function chat<
     TTools,
     TInterrupts,
     TContext,
-    TMiddleware
+    TMiddleware,
+    TAgents
   >,
 ): TextActivityResult<TSchema, TStream, TTools> {
   validateInterruptDefinitions(options.interrupts)
@@ -4699,6 +4800,12 @@ export function chat<
 
   const { outputSchema, stream } = options
 
+  if (outputSchema && (options.subagents?.agents.length ?? 0) > 0) {
+    throw new Error(
+      'chat() does not support subagents together with outputSchema. Put outputSchema on a child chat() instead.',
+    )
+  }
+
   if (outputSchema && stream === true) {
     return runStreamingStructuredOutput(
       toRuntimeTextActivityOptions(options, {
@@ -4738,7 +4845,10 @@ type RuntimeTextActivityOptions<
   TAdapter extends AnyTextAdapter,
   TSchema extends SchemaInput | undefined,
   TStream extends boolean,
-> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any>, 'middleware'> & {
+> = Omit<
+  TextActivityOptions<TAdapter, TSchema, TStream, any, any>,
+  'middleware'
+> & {
   middleware?: Array<AnyChatMiddleware>
 }
 
@@ -4767,6 +4877,7 @@ function toRuntimeTextActivityOptions<
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
   TContext,
   TMiddleware extends Array<unknown> | undefined,
+  TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>,
 >(
   options: TextActivityOptionsWithContext<
     TAdapter,
@@ -4775,7 +4886,8 @@ function toRuntimeTextActivityOptions<
     TTools,
     TInterrupts,
     TContext,
-    TMiddleware
+    TMiddleware,
+    TAgents
   >,
   overrides: { outputSchema: TOutputSchema; stream: TOutputStream },
 ): RuntimeTextActivityOptions<TAdapter, TOutputSchema, TOutputStream> {
@@ -4862,11 +4974,19 @@ function runStreamingText(
   return stream
 }
 
-async function* streamTextChunks(
+async function* runChatEngine(
   options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
   engineRef: DeliveryEngineRef,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, middleware, context, debug, mcp, ...textOptions } = options
+  const {
+    adapter,
+    middleware,
+    context,
+    debug,
+    mcp,
+    subagents: _subagents,
+    ...textOptions
+  } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
@@ -4900,6 +5020,410 @@ async function* streamTextChunks(
   }
 }
 
+async function* streamTextChunks(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
+  engineRef: DeliveryEngineRef,
+): AsyncIterable<StreamChunk> {
+  const bag = options.subagents
+  const agents = bag?.agents ?? []
+  if (bag && agents.length > 0 && bag.router) {
+    yield* runRoutedSubagents(options, engineRef)
+    return
+  }
+  if (bag && agents.length > 0) {
+    const threadId = options.threadId ?? `thread-${Date.now()}`
+    const runId = options.runId ?? `run-${Date.now()}`
+    const messages = options.messages ?? []
+    // A resume can answer a child's interrupts. Those entries go to the child
+    // tool call. The parent run validates only its own entries.
+    const turn = readSubagentTurn(messages, options.resume)
+    const sink = createSubagentSink()
+    const calls = subagentCallMessages(
+      new Set(bag.agents.map((agent: DefinedAgent) => agent.name)),
+    )
+    const synthetic = createSyntheticSubagentTools(bag, {
+      messages: turn?.before ?? messages,
+      messagesFor: calls.messagesFor,
+      threadId,
+      runId,
+      ...(options.parentRunId !== undefined && {
+        interruptedRunId: options.parentRunId,
+      }),
+      ...(options.abortController && {
+        abortSignal: options.abortController.signal,
+      }),
+      ...(turn && { turn }),
+      sink,
+    })
+    yield* streamWithChildUsage(
+      runChatEngine(
+        {
+          ...options,
+          threadId,
+          runId,
+          ...(turn && {
+            [CHILD_RESUME_IDS]: new Set(
+              turn.children.flatMap((child) =>
+                child.resume.map((entry) => entry.interruptId),
+              ),
+            ),
+          }),
+          tools: [...(options.tools ?? []), ...synthetic],
+          middleware: [...(options.middleware ?? []), calls.middleware],
+        },
+        engineRef,
+      ),
+      sink,
+    )
+    return
+  }
+  yield* runChatEngine(options, engineRef)
+}
+
+/** Add child usage to the next RUN_FINISHED of the parent. */
+async function* streamWithChildUsage(
+  stream: AsyncIterable<StreamChunk>,
+  sink: SubagentSink,
+): AsyncIterable<StreamChunk> {
+  for await (const chunk of stream) {
+    yield chunk.type === EventType.RUN_FINISHED
+      ? withChildUsage(chunk, sink)
+      : chunk
+  }
+}
+
+async function* runRoutedSubagents(
+  options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
+  engineRef: DeliveryEngineRef,
+): AsyncIterable<StreamChunk> {
+  const bag = options.subagents
+  if (!bag?.router) {
+    yield* runChatEngine(options, engineRef)
+    return
+  }
+  const threadId = options.threadId ?? `thread-${Date.now()}`
+  const runId = options.runId ?? `run-${Date.now()}`
+  const messages = options.messages ?? []
+  const turn = readSubagentTurn(messages, options.resume)
+  if (!turn && (options.resume?.length ?? 0) > 0) {
+    // No child owns these answers. Main raised them, after a main pick or a
+    // handoff. Run main alone.
+    yield* runChatEngine(
+      { ...options, threadId, runId, subagents: undefined },
+      engineRef,
+    )
+    return
+  }
+  const abortSignal = options.abortController?.signal
+  const turnMessages = turn?.before ?? messages
+  const subagentPersistence = readRoutedSubagentPersistence(options.middleware)
+  await subagentPersistence?.start({
+    threadId,
+    runId,
+    messages,
+    ...(options.resume && { resume: options.resume }),
+  })
+  try {
+    // A resume reuses the plan that the first run put on each child's
+    // SUBAGENT_STARTED metadata. Children that finished keep their result.
+    // Suspended children continue.
+    const plan =
+      savedPlan(turn?.plan, bag.agents, {
+        threadId,
+        interruptedRunId: options.parentRunId ?? runId,
+        interruptIds: options.resume?.map((entry) => entry.interruptId) ?? [],
+      }) ??
+      normalizeRouterPick(
+        await bag.router({
+          messages: turnMessages,
+          agents: bag.agents,
+          ...(abortSignal && { abortSignal }),
+        }),
+        bag.agents,
+      )
+    // The run was stopped while the router decided. Start nothing. No
+    // RUN_STARTED went out, so the stream ends without a terminal, but the
+    // record start() opened still has to settle. Otherwise it stays `running`
+    // and reconstructChat hands the client a run to tail that never emits.
+    if (abortSignal?.aborted) {
+      const error = new Error('Aborted')
+      error.name = 'AbortError'
+      await subagentPersistence?.abort({ threadId, runId, error })
+      return
+    }
+    const onlyStep = plan.steps.length === 1 ? plan.steps[0] : undefined
+    if (onlyStep?.names.length === 1 && onlyStep.names[0] === 'main') {
+      // Earlier children own answers in this resume. Commit them first.
+      if (turn) await subagentPersistence?.finish({ threadId, runId })
+      yield* runChatEngine(
+        {
+          ...options,
+          threadId,
+          runId,
+          subagents: undefined,
+          ...(turn && { resume: turn.rest }),
+        },
+        engineRef,
+      )
+      return
+    }
+
+    yield {
+      type: EventType.RUN_STARTED,
+      threadId,
+      runId,
+      timestamp: Date.now(),
+    }
+
+    const earlier = [...(turn?.children ?? [])]
+    const takeEarlier = (name: string) => {
+      const index = earlier.findIndex((child) => child.name === name)
+      return index === -1 ? undefined : earlier.splice(index, 1)[0]
+    }
+    const sink = createSubagentSink()
+    const stepTexts: Array<string> = []
+    let stepMessages = turnMessages
+    let failure:
+      | Extract<StreamChunk, { type: EventType.SUBAGENT_ERROR }>
+      | undefined
+    for (const step of plan.steps) {
+      const entries: Array<SpawnEntry> = []
+      const textByName = new Map<string, string>()
+      for (const name of step.names) {
+        const prior = takeEarlier(name)
+        if (prior?.status === 'finished') {
+          textByName.set(name, prior.text)
+          continue
+        }
+        entries.push(
+          prior?.status === 'suspended'
+            ? {
+                name,
+                resume: {
+                  subagentRunId: prior.subagentRunId,
+                  messages: prior.messages,
+                  entries: prior.resume,
+                  text: prior.text,
+                },
+              }
+            : { name },
+        )
+      }
+      const stepChunks: Array<StreamChunk> = []
+      if (entries.length > 0) {
+        for await (const chunk of spawnNamedAgents(
+          entries,
+          { ...bag, order: step.order ?? bag.order },
+          {
+            messages: stepMessages,
+            ...(abortSignal && { abortSignal }),
+            threadId,
+            parentRunId: runId,
+            ...(options.parentRunId !== undefined && {
+              interruptedRunId: options.parentRunId,
+            }),
+          },
+          sink,
+        )) {
+          const tagged = withPlan(chunk, plan)
+          stepChunks.push(tagged)
+          await subagentPersistence?.chunk({ threadId, runId, chunk: tagged })
+          yield tagged
+        }
+      }
+      failure = stepChunks.find(
+        (chunk) => chunk.type === EventType.SUBAGENT_ERROR,
+      )
+      if (failure) break
+      if (sink.interrupts.length > 0) break
+      for (const entry of entries) {
+        const text = collectNamedText(stepChunks, [entry.name])
+        textByName.set(
+          entry.name,
+          [entry.resume?.text, text].filter(Boolean).join('\n\n'),
+        )
+      }
+      const text = step.names
+        .map((name) => textByName.get(name)?.trim() ?? '')
+        .filter((block) => block !== '')
+        .join('\n\n')
+      if (text) {
+        stepTexts.push(text)
+        stepMessages = [...stepMessages, { role: 'assistant', content: text }]
+      }
+    }
+
+    if (abortSignal?.aborted) {
+      const error = new Error('Aborted')
+      error.name = 'AbortError'
+      await subagentPersistence?.abort({ threadId, runId, error })
+      yield withChildUsage(
+        {
+          type: EventType.RUN_FINISHED,
+          threadId,
+          runId,
+          outcome: { type: 'cancelled' },
+          timestamp: Date.now(),
+        },
+        sink,
+      )
+      return
+    }
+
+    if (failure) {
+      // Carry the child's own cause, not a generic label, and keep the usage
+      // the children already spent: the run failed, but the tokens were real.
+      const message = failure.message || 'A subagent failed'
+      await subagentPersistence?.abort({
+        threadId,
+        runId,
+        error: new Error(message),
+      })
+      yield withChildUsage(
+        {
+          type: EventType.RUN_ERROR,
+          threadId,
+          runId,
+          message,
+          ...(failure.code !== undefined ? { code: failure.code } : {}),
+          timestamp: Date.now(),
+        },
+        sink,
+      )
+      return
+    }
+
+    if (sink.interrupts.length > 0) {
+      const interrupts = rebindInterrupts(sink.interrupts, runId)
+      await subagentPersistence?.suspend?.({ threadId, runId, interrupts })
+      yield withChildUsage(
+        {
+          type: EventType.RUN_FINISHED,
+          threadId,
+          runId,
+          outcome: { type: 'interrupt', interrupts },
+          timestamp: Date.now(),
+        },
+        sink,
+      )
+      return
+    }
+
+    const strategy = bag.strategy ?? 'exclusive'
+    if (strategy === 'handoff') {
+      const childText = stepTexts.join('\n\n')
+      // The children are done. Commit their answers and settle their records
+      // before main runs. Main's own persistence takes over from here.
+      await subagentPersistence?.finish({ threadId, runId })
+      yield* streamWithChildUsage(
+        runChatEngine(
+          {
+            ...options,
+            threadId,
+            runId,
+            subagents: undefined,
+            ...(turn && { resume: turn.rest }),
+            messages: [
+              ...turnMessages,
+              {
+                // Same id as the recorder's parent row, so the stored thread
+                // keeps one host message for the cards.
+                id: subagentHostMessageId(runId),
+                role: 'assistant',
+                content: childText || 'Subagent finished.',
+                metadata: { tanstack: { runId } },
+              },
+            ],
+          },
+          engineRef,
+        ),
+        sink,
+      )
+      return
+    }
+
+    await subagentPersistence?.finish({ threadId, runId })
+    yield withChildUsage(
+      {
+        type: EventType.RUN_FINISHED,
+        threadId,
+        runId,
+        timestamp: Date.now(),
+      },
+      sink,
+    )
+  } catch (error) {
+    await subagentPersistence?.abort({ threadId, runId, error })
+    throw error
+  }
+}
+
+/**
+ * The plan from a resumed turn, or undefined when it is absent. A plan that
+ * names agents this chat does not have is stale: re-routing would strand the
+ * suspended child that owns the answers, so fail the resume instead.
+ */
+function savedPlan(
+  plan: unknown,
+  agents: ReadonlyArray<DefinedAgent>,
+  run: {
+    threadId: string
+    interruptedRunId: string
+    interruptIds: ReadonlyArray<string>
+  },
+): { steps: ReadonlyArray<SubagentStep> } | undefined {
+  if (typeof plan !== 'object' || plan === null || !('steps' in plan)) {
+    return undefined
+  }
+  try {
+    // The plan comes back from the client. Check it like a router pick.
+    return normalizeRouterPick(plan as SubagentStepsPlan, agents)
+  } catch (error) {
+    throw new InterruptResumeValidationError([
+      {
+        scope: 'batch',
+        threadId: run.threadId,
+        interruptedRunId: run.interruptedRunId,
+        generation: 0,
+        interruptIds: run.interruptIds,
+        code: 'stale',
+        message: `The saved subagent plan does not match the agents of this chat. ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        source: 'server',
+        retryable: false,
+      },
+    ])
+  }
+}
+
+/** Put the router plan on a direct child's SUBAGENT_STARTED metadata. */
+function withPlan(
+  chunk: StreamChunk,
+  plan: { steps: ReadonlyArray<SubagentStep> },
+): StreamChunk {
+  if (
+    chunk.type !== EventType.SUBAGENT_STARTED ||
+    chunk.parentSubagentRunId !== undefined
+  ) {
+    return chunk
+  }
+  return withTanstackMetadata(chunk, { [SUBAGENT_PLAN_KEY]: plan })
+}
+
+function readRoutedSubagentPersistence(
+  middleware:
+    | ReadonlyArray<{
+        routedSubagentPersistence?: ChatMiddleware['routedSubagentPersistence']
+      }>
+    | undefined,
+) {
+  for (const item of middleware ?? []) {
+    if (item.routedSubagentPersistence) return item.routedSubagentPersistence
+  }
+  return undefined
+}
+
 /**
  * Run non-streaming text - collects all content and returns as a string.
  * Runs the full agentic loop (if tools are provided) but returns collected text.