@tanstack/ai-react 0.27.3 → 0.28.0

package/src/types.ts

@@ -27,6 +27,8 @@ import type {
   SendMessageOptions,
   UIMessage,
   WhenBusy,
+  SubagentClientAgent,
+  SubagentHandles,
 } from '@tanstack/ai-client'
 
 // Re-export types from ai-client
@@ -86,6 +88,7 @@ export type UseChatOptions<
   TContext = InferredClientContext<TTools>,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     readonly [],
+  TSubagents extends ReadonlyArray<SubagentClientAgent> | undefined = undefined,
 > = DistributedOmit<
   ChatClientOptions<TTools, TContext, TInterrupts>,
   | 'onMessagesChange'
@@ -100,6 +103,7 @@ export type UseChatOptions<
   | 'onRunIdChange'
   | 'context'
   | 'devtools'
+  | 'subagents'
 > & {
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
@@ -115,6 +119,12 @@ export type UseChatOptions<
    * against the schema passed to `chat({ outputSchema })` on the server route.
    */
   outputSchema?: TSchema
+  /**
+   * Agents from `defineAgent`. This types `messages` parts and `subagents`.
+   * The hook does not call `run` and does not send the agents to the server.
+   * Pass the same array you give to `chat({ subagents: { agents } })`.
+   */
+  subagents?: TSubagents
 } & ClientContextOptionFromTools<TTools, TContext>
 
 /**
@@ -127,10 +137,12 @@ export type UseChatReturn<
   TSchema extends SchemaInput | undefined = undefined,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     readonly [],
+  TSubagents extends ReadonlyArray<SubagentClientAgent> | undefined = undefined,
 > = BaseUseChatReturn<
   TTools,
   TSchema extends SchemaInput ? InferSchemaType<TSchema> : unknown,
-  TInterrupts
+  TInterrupts,
+  TSubagents
 > &
   (TSchema extends SchemaInput
     ? {
@@ -155,13 +167,23 @@ interface BaseUseChatReturn<
   TData = unknown,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     readonly [],
+  TSubagents extends ReadonlyArray<SubagentClientAgent> | undefined = undefined,
 > {
   /**
    * Current messages in the conversation. When `outputSchema` is supplied,
    * `messages[i].parts.find(p => p.type === 'structured-output')` is typed
    * with the schema's inferred shape — `data: T`, `partial: DeepPartial<T>`.
+   * When `subagents` is supplied, a `type: 'subagent'` part narrows on
+   * `subagent.name`, and that child's `messages` use the agent's tools.
+   */
+  messages: Array<UIMessage<TTools, TData, TSubagents>>
+
+  /**
+   * Live child-agent invocations, nested cards included. Each entry is the
+   * same object as the matching `part.subagent`, including `stop()`.
+   * When `subagents` is supplied, `name` is one of those agent names.
    */
-  messages: Array<UIMessage<TTools, TData>>
+  subagents: Array<SubagentHandles<TSubagents>>
 
   /**
    * Send a message and get a response.

package/src/ui.ts

@@ -15,6 +15,8 @@ export {
   type MessageProps,
   type PartProps,
   type QueueProps,
+  type SubagentPartsProps,
+  type SubagentProps,
   type ToolProps,
 } from './chat-ui/create-ui'
 export { createChatHook } from './chat-ui/create-chat-hook'

package/src/use-chat.ts

@@ -40,9 +40,11 @@ export function useChat<
   const TInterrupts extends ReadonlyArray<
     InterruptDefinition<any, any, any, any>
   > = readonly [],
+  const TSubagents extends ReadonlyArray<{ name: string }> | undefined =
+    undefined,
 >(
-  options: UseChatOptions<TTools, TSchema, TContext, TInterrupts>,
-): UseChatReturn<TTools, TSchema, TInterrupts> {
+  options: UseChatOptions<TTools, TSchema, TContext, TInterrupts, TSubagents>,
+): UseChatReturn<TTools, TSchema, TInterrupts, TSubagents> {
   // The hook's identity is its `threadId`. Reload with the same `threadId`
   // restores the same conversation. `hookId` is only a React recreation key
   // when no `threadId` is given. It is never sent on the wire.
@@ -94,7 +96,9 @@ export function useChat<
 
   // Track current options in a ref to avoid recreating client when options change
   const optionsRef =
-    useRef<UseChatOptions<TTools, TSchema, TContext, TInterrupts>>(options)
+    useRef<UseChatOptions<TTools, TSchema, TContext, TInterrupts, TSubagents>>(
+      options,
+    )
   optionsRef.current = options
 
   const syncResumeState = useCallback((target: ChatClient | null) => {
@@ -609,12 +613,15 @@ export function useChat<
     return activeStructuredPart.data as Final
   }, [activeStructuredPart])
 
+  const subagents = useMemo(() => client.getSubagents(), [renderedMessages])
+
   // The runtime shape unconditionally exposes partial/final; the public
   // return type hides them when no outputSchema was supplied. TS can't
   // structurally narrow across that conditional, so the `as` is the seam.
   // oxlint-disable-next-line eslint-js/no-restricted-syntax -- hook return shape diverges from generic UseChatReturn<TTools, TSchema> due to conditional type on TSchema; TS can't structurally narrow
   return {
     messages: renderedMessages,
+    subagents,
     sendMessage,
     append,
     reload,
@@ -645,5 +652,5 @@ export function useChat<
     resumeInterrupts,
     partial,
     final,
-  } as unknown as UseChatReturn<TTools, TSchema, TInterrupts>
+  } as unknown as UseChatReturn<TTools, TSchema, TInterrupts, TSubagents>
 }