@tanstack/ai-client 0.33.2 → 0.34.0

package/src/chat-client.ts

@@ -1,4 +1,5 @@
 import {
+  EventType,
   StreamProcessor,
   convertSchemaToJsonSchema,
   generateMessageId,
@@ -72,6 +73,7 @@ import type {
   QueueStrategy,
   QueuedMessage,
   SendMessageOptions,
+  SubagentHandle,
   ToolCallPart,
   UIMessage,
   WhenBusy,
@@ -330,11 +332,54 @@ const REJOIN_REBUILD_TRIGGERS = new Set<string>([
   'TEXT_MESSAGE_CONTENT',
   'TOOL_CALL_START',
   'MESSAGES_SNAPSHOT',
+  // Drop the hydrated card before this chunk creates it again. A subagent
+  // turn may have no parent text, so the text triggers arrive too late.
+  'SUBAGENT_STARTED',
 ])
 
+type SubagentCard = Extract<UIMessage['parts'][number], { type: 'subagent' }>
+
+/** Every subagent card in the messages, nested cards included. */
+function collectSubagentParts(
+  messages: ReadonlyArray<UIMessage>,
+): Array<SubagentCard> {
+  const cards: Array<SubagentCard> = []
+  for (const message of messages) {
+    for (const part of message.parts) {
+      if (part.type !== 'subagent') continue
+      cards.push(part)
+      cards.push(...collectSubagentParts(part.subagent.messages))
+    }
+  }
+  return cards
+}
+
+function readSubagentRunId(chunk: StreamChunk) {
+  if ('subagentRunId' in chunk && typeof chunk.subagentRunId === 'string') {
+    return chunk.subagentRunId
+  }
+  return undefined
+}
+
 // Cap parent-chain walks so a cyclic replayed parentRunId cannot loop.
 const MAX_RUN_LINEAGE_DEPTH = 64
 
+/**
+ * A deep copy of plain data. Dates stay Dates. Function-valued properties are
+ * dropped.
+ */
+function copyForDevtools<T>(value: T): T
+function copyForDevtools(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(copyForDevtools)
+  if (value instanceof Date) return new Date(value.getTime())
+  if (value === null || typeof value !== 'object') return value
+  const out: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== 'function') out[key] = copyForDevtools(item)
+  }
+  return out
+}
+
 export class ChatClient<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = unknown,
@@ -342,6 +387,8 @@ export class ChatClient<
     any,
 > {
   private readonly processor: StreamProcessor
+  private readonly subagentHandles = new Map<string, SubagentHandle>()
+  private readonly stoppedSubagentIds = new Set<string>()
   private connection: SubscribeConnectionAdapter
   private uniqueId: string
   private threadId: string
@@ -669,9 +716,16 @@ export class ChatClient<
         : {}),
       ...(initialMessages ? { initialMessages } : {}),
       events: {
-        onMessagesChange: (messages: Array<UIMessage>) => {
+        onMessagesChange: (messages) => {
+          // Restored or replaced messages bring their own cards. Give each one
+          // its live handle before anyone reads the messages.
+          this.syncSubagentHandles()
           this.persistor?.notifyMessagesChanged(messages)
           this.callbacksRef.current.onMessagesChange(messages)
+          // The bridge only snapshots on status changes, and the panel draws a
+          // child card from the snapshot, so without this the card would update
+          // only when the parent run ends.
+          this.queueDevtoolsSnapshot()
         },
         onStreamStart: () => {
           this.setStatus('streaming')
@@ -887,6 +941,8 @@ export class ChatClient<
         },
       },
     })
+    // `initialMessages` do not fire a change event. Give their cards handles.
+    this.syncSubagentHandles()
 
     this.persistor?.hydrateAsync(persistedState)
 
@@ -1693,7 +1749,9 @@ export class ChatClient<
 
   private getDevtoolsSnapshot(): AIDevtoolsChatSnapshot {
     return {
-      messages: this.processor.getMessages(),
+      // The devtools store keeps the objects it gets, and a subagent handle
+      // changes in place. A copy lets the panel see each new status and part.
+      messages: copyForDevtools(this.processor.getMessages()),
       status: this.status,
       isLoading: this.isLoading,
       isSubscribed: this.isSubscribed,
@@ -1970,7 +2028,18 @@ export class ChatClient<
     }
     this.callbacksRef.current.onChunk(chunk)
     this.devtoolsBridge.observeChunk(chunk)
+    const attributedId = readSubagentRunId(chunk)
+    // A resumed child starts again under the same id, so its start lifts the stop.
+    if (attributedId && chunk.type === EventType.SUBAGENT_STARTED) {
+      this.stoppedSubagentIds.delete(attributedId)
+    }
+    if (attributedId && this.stoppedSubagentIds.has(attributedId)) {
+      this.updateRunLifecycle(chunk)
+      this.resolveJoinedRun(chunk)
+      return
+    }
     this.processor.processChunk(chunk)
+    this.syncSubagentHandles()
     this.updateRunLifecycle(chunk)
     this.observeInterruptState(chunk)
     // Live path: yield a macrotask so the UI can paint. Skip when the page is
@@ -2678,6 +2747,7 @@ export class ChatClient<
    */
   stop(): void {
     // Invalidate deferred work from the stopped continuation.
+    // This aborts the local request. A durable server run keeps going.
     this.continuationGeneration++
     const hadLocalStream = this.abortController !== null
     this.cancelInFlightStream({ setReadyStatus: true })
@@ -2715,6 +2785,7 @@ export class ChatClient<
     this.resetHistoryPaging()
     this.discardPendingSends()
     this.persistor?.remove()
+    this.stoppedSubagentIds.clear()
     this.lastResume = null
     this.interruptManager.reset()
     this.pendingResumeThreadId = null
@@ -2974,6 +3045,72 @@ export class ChatClient<
     return this.processor.getMessages() as Array<UIMessage<TTools>>
   }
 
+  getSubagents() {
+    return [...this.subagentHandles.values()]
+  }
+
+  private devtoolsSnapshotQueued = false
+
+  /** One devtools snapshot per microtask, however many chunks arrive. */
+  private queueDevtoolsSnapshot(): void {
+    if (this.devtoolsSnapshotQueued) return
+    this.devtoolsSnapshotQueued = true
+    queueMicrotask(() => {
+      this.devtoolsSnapshotQueued = false
+      this.devtoolsBridge.emitSnapshot()
+    })
+  }
+
+  private syncSubagentHandles(): void {
+    // Every card, nested ones included, gets a handle.
+    const cards = collectSubagentParts(this.processor.getMessages())
+    const present = new Set(cards.map((part) => part.subagent.id))
+    // A card that left the messages (clear, reload) loses its handle.
+    for (const id of this.subagentHandles.keys()) {
+      if (!present.has(id)) this.subagentHandles.delete(id)
+    }
+    for (const part of cards) {
+      const id = part.subagent.id
+      const existing = this.subagentHandles.get(id)
+      if (existing) {
+        if (part.subagent === existing) continue
+        // Keep the same live object, with exactly the card's fields. The
+        // wire reads this object, so a field the card dropped goes too.
+        const { stop } = existing
+        for (const key of Object.keys(existing)) {
+          Reflect.deleteProperty(existing, key)
+        }
+        Object.assign(existing, part.subagent, { stop })
+        part.subagent = existing
+        continue
+      }
+      const handle: SubagentHandle = {
+        ...part.subagent,
+        stop: () => {
+          this.stopSubagent(id)
+        },
+      }
+      this.subagentHandles.set(id, handle)
+      part.subagent = handle
+    }
+  }
+
+  private stopSubagent(id: string): void {
+    const handle = this.subagentHandles.get(id)
+    if (!handle || handle.status !== 'running') return
+    this.stoppedSubagentIds.add(id)
+    this.processor.processChunk({
+      type: EventType.SUBAGENT_ERROR,
+      subagentRunId: id,
+      message: 'Stopped',
+      timestamp: Date.now(),
+    })
+    this.syncSubagentHandles()
+    handle.status = 'error'
+    handle.error = { message: 'Stopped' }
+    this.abortController?.abort()
+  }
+
   /**
    * True when the last hydrate or older-page response said more messages exist.
    */

package/src/index.ts

@@ -33,6 +33,13 @@ export type {
   ToolResultPart,
   ThinkingPart,
   StructuredOutputPart,
+  SubagentPart,
+  SubagentPartOf,
+  SubagentHandle,
+  SubagentHandleOf,
+  SubagentHandles,
+  SubagentClientAgent,
+  SubagentStatus,
   // Client configuration types
   ChatClientPersistence,
   ChatPersistedState,

package/src/types.ts

@@ -22,6 +22,8 @@ import type {
   SchemaInput,
   StreamChunk,
   StructuredOutputPart,
+  SubagentHandleData,
+  SubagentStatus,
   UIResourcePart,
   VideoPart,
 } from '@tanstack/ai/client'
@@ -514,6 +516,20 @@ export interface TextPart {
   content: string
 }
 
+/**
+ * Tool-call part for a bare `{ name }` tool, such as a server tool
+ * definition a subagent carries. No `approval` field.
+ */
+type ToolCallPartForNamedTool<T extends { name: string }> = {
+  type: 'tool-call'
+  id: string
+  name: T['name']
+  arguments: string
+  input?: InferToolInput<T>
+  state: ToolCallState
+  output?: InferToolOutput<T>
+}
+
 /**
  * Helper type that creates a tool-call part for a specific tool.
  * This is a conditional type to enable proper distribution over union types,
@@ -549,7 +565,9 @@ type ToolCallPartForTool<T> = T extends AnyClientTool
       : // Tools without `needsApproval: true` never carry an approval field.
         // `& unknown` is a no-op intersection (adds nothing).
         unknown)
-  : never
+  : T extends { name: string }
+    ? ToolCallPartForNamedTool<T>
+    : never
 
 /**
  * Fallback tool-call part type when tools are not typed
@@ -581,14 +599,14 @@ type UntypedToolCallPart = {
  * }
  * ```
  */
-export type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =
+export type ToolCallPart<TTools extends ReadonlyArray<{ name: string }> = any> =
   // Check if we have a concrete tools array (not 'any' or 'never')
   [TTools] extends [never]
     ? UntypedToolCallPart
     : unknown extends TTools
       ? UntypedToolCallPart
       : TTools extends ReadonlyArray<infer Tool>
-        ? Tool extends AnyClientTool
+        ? Tool extends { name: string }
           ? ToolCallPartForTool<Tool>
           : UntypedToolCallPart
         : UntypedToolCallPart
@@ -610,9 +628,97 @@ export interface ThinkingPart {
   content: string
 }
 
+export type { SubagentStatus }
+
+export interface SubagentHandle extends SubagentHandleData {
+  /**
+   * Set by ChatClient on every card it holds, streamed, restored, or initial,
+   * nested cards included. Calling it marks the card `error` (`Stopped`),
+   * ignores that child's later chunks until the same child starts again, and
+   * aborts the local request, parent stream included. A durable server run
+   * keeps going.
+   */
+  stop?: () => void
+}
+
+export interface SubagentPart {
+  type: 'subagent'
+  subagent: SubagentHandle
+}
+
+/**
+ * The slice of a server `defineAgent` result that the client reads for types.
+ * The client does not call `run`. Put tool definitions (from
+ * `toolDefinition`) in `tools` to type the child's tool calls and approvals.
+ */
+export type SubagentClientAgent = {
+  name: string
+  description?: string
+  tools?: ReadonlyArray<{ name: string }>
+  interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
+  outputSchema?: SchemaInput
+}
+
+type AgentToolList<TAgent> = TAgent extends { tools?: infer TTools }
+  ? [undefined] extends [TTools]
+    ? [TTools] extends [undefined]
+      ? any
+      : Exclude<TTools, undefined> extends ReadonlyArray<infer TTool>
+        ? [TTool] extends [never]
+          ? any
+          : Exclude<TTools, undefined>
+        : any
+    : TTools extends ReadonlyArray<infer TTool>
+      ? [TTool] extends [never]
+        ? any
+        : TTools
+      : any
+  : any
+
+type AgentOutputData<TAgent> = TAgent extends { outputSchema?: infer TSchema }
+  ? Exclude<TSchema, undefined> extends SchemaInput
+    ? [Exclude<TSchema, undefined>] extends [never]
+      ? unknown
+      : InferSchemaType<Exclude<TSchema, undefined>>
+    : unknown
+  : unknown
+
+/** One child handle. `name` is the discriminant. */
+export type SubagentHandleOf<TAgent extends SubagentClientAgent> = Omit<
+  SubagentHandle,
+  'name' | 'messages'
+> & {
+  name: TAgent['name']
+  messages: Array<UIMessage<AgentToolList<TAgent>, AgentOutputData<TAgent>>>
+}
+
+export type SubagentHandles<
+  TAgents extends ReadonlyArray<SubagentClientAgent> | undefined,
+> = [TAgents] extends [undefined]
+  ? SubagentHandle
+  : unknown extends TAgents
+    ? SubagentHandle
+    : TAgents extends ReadonlyArray<infer TAgent>
+      ? TAgent extends SubagentClientAgent
+        ? SubagentHandleOf<TAgent>
+        : SubagentHandle
+      : SubagentHandle
+
+export type SubagentPartOf<
+  TAgents extends ReadonlyArray<SubagentClientAgent> | undefined,
+> = [TAgents] extends [undefined]
+  ? SubagentPart
+  : unknown extends TAgents
+    ? SubagentPart
+    : {
+        type: 'subagent'
+        subagent: SubagentHandles<TAgents>
+      }
+
 export type MessagePart<
-  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TTools extends ReadonlyArray<{ name: string }> = any,
   TData = unknown,
+  TSubagents extends ReadonlyArray<SubagentClientAgent> | undefined = undefined,
 > =
   | TextPart
   | ImagePart
@@ -624,6 +730,7 @@ export type MessagePart<
   | ThinkingPart
   | StructuredOutputPart<TData>
   | UIResourcePart
+  | SubagentPartOf<TSubagents>
 
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
@@ -638,13 +745,14 @@ export type MessagePart<
  * is typed without manual casts.
  */
 export interface UIMessage<
-  TTools extends ReadonlyArray<AnyClientTool> = any,
+  TTools extends ReadonlyArray<{ name: string }> = any,
   TData = unknown,
+  TSubagents extends ReadonlyArray<SubagentClientAgent> | undefined = undefined,
 > {
   id: string
   role: 'system' | 'user' | 'assistant'
   name?: string
-  parts: Array<MessagePart<TTools, TData>>
+  parts: Array<MessagePart<TTools, TData, TSubagents>>
   createdAt?: Date
   /**
    * Optional AG-UI metadata bag. TanStack writes the `tanstack` key.
@@ -895,6 +1003,14 @@ export interface ChatClientBaseOptions<
    */
   byok?: ByokClient
 
+  /**
+   * The agents you pass to `chat({ subagents: { agents } })`, for types only.
+   * The client does not call `run`. `createChatHook` from
+   * `@tanstack/ai-react/ui` requires a `subagentsComponents` entry for every
+   * agent name.
+   */
+  subagents?: ReadonlyArray<SubagentClientAgent>
+
   /**
    * Optional provider id for this chat. If it returns a provider slug,
    * only that key is prepared and sent. Otherwise the merged `provider`

package/src/ui/selectors.ts

@@ -25,6 +25,7 @@ const PART_KEY_BY_TYPE: Record<string, ChatUIPartKey> = {
   'tool-result': 'toolResult',
   'structured-output': 'structuredOutput',
   'ui-resource': 'uiResource',
+  subagent: 'subagent',
 }
 
 export function partTypeToKey(type: string): ChatUIPartKey | string {

package/src/ui/types.ts

@@ -10,6 +10,7 @@ import type {
   ChatInterrupt,
   MessagePart,
   RegisteredGenericInterrupt,
+  SubagentClientAgent,
   StructuredOutputPart,
   ToolApprovalInterrupt,
   ToolCallPart,
@@ -28,6 +29,7 @@ export type ChatUIPartKey =
   | 'toolResult'
   | 'structuredOutput'
   | 'uiResource'
+  | 'subagent'
 
 export type ChatUIPartTypeByKey = {
   text: 'text'
@@ -40,6 +42,7 @@ export type ChatUIPartTypeByKey = {
   toolResult: 'tool-result'
   structuredOutput: 'structured-output'
   uiResource: 'ui-resource'
+  subagent: 'subagent'
 }
 
 export type ChatUIPartOf<
@@ -60,7 +63,7 @@ export type ChatUIToolsOf<TOptions> = TOptions extends {
     : any
   : any
 
-export type ChatUIInterruptsOf<TOptions> = TOptions extends {
+type RootInterruptsOf<TOptions> = TOptions extends {
   interrupts: infer TInterrupts
 }
   ? TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>
@@ -68,6 +71,23 @@ export type ChatUIInterruptsOf<TOptions> = TOptions extends {
     : readonly []
   : readonly []
 
+type AgentInterrupts<TOptions> = ConcreteItems<
+  AgentField<ChatUISubagentsOf<TOptions>[number], 'interrupts', readonly []>
+>
+
+/** The root `interrupts` plus every child agent's `interrupts`. */
+export type ChatUIInterruptsOf<TOptions> = [AgentInterrupts<TOptions>] extends [
+  never,
+]
+  ? RootInterruptsOf<TOptions>
+  : ReadonlyArray<
+      | RootInterruptsOf<TOptions>[number]
+      | Extract<
+          AgentInterrupts<TOptions>,
+          InterruptDefinition<any, any, any, any>
+        >
+    >
+
 export type ChatUISchemaOf<TOptions> = TOptions extends {
   outputSchema: infer TSchema
 }
@@ -114,14 +134,105 @@ export type ChatUIHasNamedInterrupts<TOptions> = [
     ? false
     : true
 
+/** The agents in `options.subagents`, or an empty list. */
+export type ChatUISubagentsOf<TOptions> = TOptions extends {
+  subagents?: infer TAgents
+}
+  ? Exclude<TAgents, undefined> extends ReadonlyArray<SubagentClientAgent>
+    ? Exclude<TAgents, undefined>
+    : readonly []
+  : readonly []
+
+export type ChatUISubagentName<TOptions> =
+  ChatUISubagentsOf<TOptions>[number]['name']
+
+/** The agent in `options.subagents` with this name. */
+export type ChatUISubagentOf<TOptions, TName> = Extract<
+  ChatUISubagentsOf<TOptions>[number],
+  { name: TName }
+>
+
+type AgentField<TAgent, TKey extends string, TFallback> = TAgent extends {
+  [K in TKey]?: infer TValue
+}
+  ? [Exclude<TValue, undefined>] extends [never]
+    ? TFallback
+    : Exclude<TValue, undefined>
+  : TFallback
+
+/**
+ * One child agent seen as chat options, so the part, tool, and interrupt
+ * types read that agent's `tools`, `interrupts`, and `outputSchema`. An
+ * unknown name gives untyped options.
+ */
+export type ChatUISubagentOptions<TOptions, TName> = [
+  ChatUISubagentOf<TOptions, TName>,
+] extends [never]
+  ? {}
+  : ChatUISubagentOf<TOptions, TName> extends infer TAgent
+    ? {
+        tools: AgentField<TAgent, 'tools', readonly []>
+        interrupts: AgentField<TAgent, 'interrupts', readonly []>
+        outputSchema: AgentField<TAgent, 'outputSchema', undefined>
+      }
+    : {}
+
+type ConcreteItems<TList> = unknown extends TList
+  ? never
+  : TList extends ReadonlyArray<infer TItem>
+    ? TItem
+    : never
+
+type AgentTools<TOptions> = ConcreteItems<
+  AgentField<ChatUISubagentsOf<TOptions>[number], 'tools', readonly []>
+>
+
+/**
+ * The tools whose approvals can reach this chat: the root `tools` plus every
+ * child agent's `tools`.
+ */
+export type ChatUIApprovalToolsOf<TOptions> = [
+  ConcreteItems<ChatUIToolsOf<TOptions>> | AgentTools<TOptions>,
+] extends [never]
+  ? ChatUIToolsOf<TOptions>
+  : ReadonlyArray<
+      Extract<
+        ConcreteItems<ChatUIToolsOf<TOptions>> | AgentTools<TOptions>,
+        AnyClientTool
+      >
+    >
+
+export type ChatUIApprovalToolName<TOptions> =
+  ChatUIApprovalToolsOf<TOptions>[number] extends infer TTool
+    ? TTool extends AnyClientTool
+      ? TTool['name']
+      : string
+    : string
+
+export type ChatUIHasNamedSubagents<TOptions> = [
+  ChatUISubagentName<TOptions>,
+] extends [never]
+  ? false
+  : [string] extends [ChatUISubagentName<TOptions>]
+    ? false
+    : true
+
 export type ChatUINamedInterruptId<TOptions> = Exclude<
   ChatUIRegisteredInterruptId<TOptions>,
   'fallback'
 >
 
+type ChatUIHasNamedApprovalTools<TOptions> = [
+  ChatUIApprovalToolName<TOptions>,
+] extends [never]
+  ? false
+  : [string] extends [ChatUIApprovalToolName<TOptions>]
+    ? false
+    : true
+
 export type ChatUIInterruptName<TOptions> =
-  | (ChatUIHasNamedTools<TOptions> extends true
-      ? ChatUIToolName<TOptions>
+  | (ChatUIHasNamedApprovalTools<TOptions> extends true
+      ? ChatUIApprovalToolName<TOptions>
       : never)
   | (ChatUIHasNamedInterrupts<TOptions> extends true
       ? ChatUINamedInterruptId<TOptions>
@@ -136,9 +247,9 @@ export type ChatUIInterrupt = ChatInterrupt | ToolApprovalInterrupt
 
 export type ChatUIToolApproval<
   TOptions,
-  TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
+  TName extends string = ChatUIApprovalToolName<TOptions>,
 > = Extract<
-  ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>,
+  ChatInterrupt<ChatUIApprovalToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>,
   { kind: 'tool-approval'; toolName: TName }
 >
 
@@ -149,10 +260,7 @@ export type ChatUIToolPart<
   key: 'toolCall'
   part: Extract<ToolCallPart<ChatUIToolsOf<TOptions>>, { name: TName }>
   result?: ToolResultPart
-  interrupt?: Extract<
-    ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>,
-    { kind: 'tool-approval'; toolName: TName }
-  >
+  interrupt?: ChatUIToolApproval<TOptions, TName>
   input?: InferToolInput<ToolByName<TOptions, TName>>
   output?: InferToolOutput<ToolByName<TOptions, TName>>
 }
@@ -172,8 +280,8 @@ export type ChatUIInterruptOf<
 > = [TName] extends [never]
   ? ChatUIInterrupt
   : TName extends (
-        ChatUIHasNamedTools<TOptions> extends true
-          ? ChatUIToolName<TOptions>
+        ChatUIHasNamedApprovalTools<TOptions> extends true
+          ? ChatUIApprovalToolName<TOptions>
           : never
       )
     ? ChatUIToolApproval<TOptions, TName>

package/src/ui.ts

@@ -6,8 +6,11 @@ export {
   selectMessageUI,
 } from './ui/selectors'
 export type {
+  ChatUIApprovalToolName,
+  ChatUIApprovalToolsOf,
   ChatUIData,
   ChatUIHasNamedInterrupts,
+  ChatUIHasNamedSubagents,
   ChatUIHasNamedTools,
   ChatUIInterrupt,
   ChatUIInterruptName,
@@ -28,6 +31,10 @@ export type {
   ChatUISelectedResultPart,
   ChatUISelectedToolPart,
   ChatUISelection,
+  ChatUISubagentName,
+  ChatUISubagentOf,
+  ChatUISubagentOptions,
+  ChatUISubagentsOf,
   ChatUIStructuredPart,
   ChatUIToolApproval,
   ChatUIToolName,