@tanstack/ai-react 0.27.3 → 0.29.1

package/src/chat-ui/create-ui.tsx

@@ -1,4 +1,4 @@
-import { createContext, memo, useContext } from 'react'
+import { createContext, memo, useContext, useMemo } from 'react'
 import type { ComponentProps, ComponentType, Context, ReactNode } from 'react'
 import {
   automaticPartsForMessage,
@@ -8,8 +8,10 @@ import {
   selectMessageUI,
 } from '@tanstack/ai-client/ui'
 import type {
+  ChatUIApprovalToolName,
   ChatUIData,
   ChatUIHasNamedInterrupts,
+  ChatUIHasNamedSubagents,
   ChatUIHasNamedTools,
   ChatUIInterrupt,
   ChatUIInterruptName,
@@ -22,6 +24,9 @@ import type {
   ChatUISchemaOf,
   ChatUISelectedPart,
   ChatUISelectedPartOf,
+  ChatUISubagentName,
+  ChatUISubagentOf,
+  ChatUISubagentOptions,
   ChatUIToolApproval,
   ChatUIToolName,
   ChatUIToolsOf,
@@ -29,6 +34,8 @@ import type {
 import type {
   MessagePart,
   QueuedMessage,
+  SubagentHandle,
+  SubagentHandles,
   ToolCallPart,
   ToolResultPart,
   UIMessage,
@@ -56,6 +63,7 @@ export type LayoutProps<
   Messages: ComponentType
   Interrupts: ComponentType
   Queue: ComponentType
+  Subagents: ComponentType
   readonly __ui?: TOptions
 } & (TInput extends ComponentType<any> ? { Input: ComponentType } : {})
 
@@ -77,6 +85,38 @@ export type PartProps<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = {
   part: ChatUIPartOf<TOptions, TKey>
 }
 
+/**
+ * Widgets for one subagent card. Each entry replaces the enclosing entry of
+ * the same key: the root map at top level, the outer card's map when nested.
+ * It applies to this card and the children nested in it. An unset key keeps
+ * the enclosing entry. Tool names and tool props come from that agent's
+ * `tools`.
+ */
+export type SubagentPartsProps<
+  TOptions,
+  TName extends ChatUISubagentName<TOptions> = ChatUISubagentName<TOptions>,
+> = {
+  partsComponents?: ChatUIPartsComponents<
+    ChatUISubagentOptions<TOptions, TName>
+  >
+  toolsComponents?: {
+    [K in ChatUIToolName<
+      ChatUISubagentOptions<TOptions, TName>
+    >]?: ComponentType<ToolProps<ChatUISubagentOptions<TOptions, TName>, K>>
+  }
+}
+
+export type SubagentProps<
+  TOptions,
+  TName extends ChatUISubagentName<TOptions> = ChatUISubagentName<TOptions>,
+> = {
+  subagent: [ChatUISubagentOf<TOptions, TName>] extends [never]
+    ? SubagentHandle & { name: TName }
+    : SubagentHandles<ReadonlyArray<ChatUISubagentOf<TOptions, TName>>>
+  Parts: ComponentType<SubagentPartsProps<TOptions, TName>>
+  readonly __ui?: TOptions
+}
+
 export type ToolProps<
   TOptions,
   TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>,
@@ -108,7 +148,7 @@ type GenericInterruptComponents<TOptions> =
       }
 
 type ToolApprovalMap<TOptions> = {
-  [K in ChatUIToolName<TOptions>]?: ComponentType<
+  [K in ChatUIApprovalToolName<TOptions>]?: ComponentType<
     InterruptProps<TOptions, K & ChatUIInterruptName<TOptions>>
   >
 }
@@ -161,6 +201,21 @@ export type ChatUIComponents<
           tools?: ToolApprovalMap<TOptions>
           generic?: GenericInterruptComponents<TOptions>
         }
+      }) &
+  (ChatUIHasNamedSubagents<TOptions> extends true
+    ? {
+        subagentsComponents: {
+          [K in ChatUISubagentName<TOptions>]: ComponentType<
+            SubagentProps<TOptions, K>
+          >
+        }
+      }
+    : {
+        subagentsComponents?: {
+          [K in ChatUISubagentName<TOptions>]?: ComponentType<
+            SubagentProps<TOptions, K>
+          >
+        }
       })
 
 /** Scoped contexts, for widgets in other files or nested chat trees. */
@@ -191,7 +246,7 @@ type PartMixins<TOptions> = {
 type InterruptMixins<TOptions> = {
   [K in ChatUINamedInterruptId<TOptions>]: BoundWidget
 } & {
-  [K in ChatUIToolName<TOptions>]?: BoundWidget
+  [K in ChatUIApprovalToolName<TOptions>]?: BoundWidget
 } & {
   fallback?: BoundWidget
   Render: BoundWidget
@@ -227,6 +282,32 @@ function queueItemEqual(
   )
 }
 
+// The handle is one live object that the client updates in place, so a row
+// gets its changing card fields as separate props. Messages are not one of
+// them: `SubagentMessages` reads them from the chat context, so new child
+// text shows without a row render.
+type SubagentRowProps = {
+  handle: SubagentHandle
+  status: SubagentHandle['status']
+  error: SubagentHandle['error']
+}
+
+function subagentListItemEqual(prev: SubagentRowProps, next: SubagentRowProps) {
+  return (
+    prev.handle.id === next.handle.id &&
+    prev.handle.stop === next.handle.stop &&
+    prev.status === next.status &&
+    prev.error === next.error
+  )
+}
+
+function subagentMessagesEqual(
+  prev: { messages: SubagentHandle['messages'] },
+  next: { messages: SubagentHandle['messages'] },
+) {
+  return prev.messages === next.messages
+}
+
 function selectedPartPropsEqual(
   prev: { selected: ChatUISelectedPart },
   next: { selected: ChatUISelectedPart },
@@ -254,6 +335,18 @@ function isSelectedPart(
   return 'key' in value && 'part' in value
 }
 
+/** `base` with each set entry of `overrides`. An unset entry keeps `base`. */
+function withWidgets(
+  base: Record<string, ComponentType<any> | undefined>,
+  overrides: Record<string, ComponentType<any> | undefined> | undefined,
+) {
+  const out = { ...base }
+  for (const [key, component] of Object.entries(overrides ?? {})) {
+    if (component) out[key] = component
+  }
+  return out
+}
+
 function bindMap(
   map: Record<string, ComponentType<any> | undefined> | undefined,
   bind: (component: ComponentType<any>) => BoundWidget,
@@ -288,12 +381,14 @@ export function createChatUI<
     partsComponents: parts,
     toolsComponents: tools,
     interruptsComponents: interrupts,
+    subagentsComponents: subagentComponents,
   } = config as ChatUIFactoryConfig<TOptions, TInput> & {
     toolsComponents?: Record<string, ComponentType<any> | undefined>
     interruptsComponents?: {
       tools?: Record<string, ComponentType<any> | undefined>
       generic?: Record<string, ComponentType<any> | undefined>
     }
+    subagentsComponents?: Record<string, ComponentType<any> | undefined>
   }
   const {
     layout: Layout,
@@ -445,6 +540,7 @@ export function createChatUI<
     Messages: Messages as ComponentType,
     Interrupts: Interrupts as ComponentType,
     Queue: Queue as ComponentType,
+    Subagents: Subagents as ComponentType,
     Input: (InputComponent ?? MissingInput) as ComponentType,
   }
 
@@ -525,6 +621,19 @@ export function createChatUI<
     inlineToolNames: ReadonlyArray<string>
   }
   const MessageRenderContext = createContext<MessageRenderValue | null>(null)
+  const SubagentRenderContext = createContext<{
+    handle: SubagentHandle
+    /** A `Subagents` row. Its messages come from the live chat state. */
+    listed?: true
+  } | null>(null)
+  // The widgets that dispatch uses. A subagent card's `Parts` can replace
+  // entries for its subtree. Outside a card these are the factory maps.
+  type WidgetMap = Record<string, ComponentType<any> | undefined>
+  const rootWidgets: { parts: WidgetMap; tools: WidgetMap } = {
+    parts: parts as WidgetMap,
+    tools: tools ?? {},
+  }
+  const WidgetsContext = createContext(rootWidgets)
 
   function Parts() {
     const scope = useContext(MessageRenderContext)
@@ -588,7 +697,7 @@ export function createChatUI<
     interrupts,
     inlineToolNames: names,
   }: {
-    message: ChatUIMessages<TOptions>[number]
+    message: UIMessage
     interrupts: ReadonlyArray<ChatUIInterrupt>
     inlineToolNames: ReadonlyArray<string>
   }) {
@@ -610,9 +719,10 @@ export function createChatUI<
   }: {
     selected: ChatUISelectedPart
   }) {
+    const widgets = useContext(WidgetsContext)
     if (selected.key === 'toolCall') {
       const name = selected.part.name
-      const Tool = tools?.[name as ChatUIToolName<TOptions>] as
+      const Tool = widgets.tools[name] as
         | ComponentType<ToolProps<TOptions>>
         | undefined
       if (!Tool) {
@@ -628,9 +738,30 @@ export function createChatUI<
       )
     }
 
-    const PartComponent = (parts[selected.key] ?? parts.fallback) as
-      | ComponentType<PartProps<TOptions>>
-      | undefined
+    if (selected.key === 'subagent' && selected.part.type === 'subagent') {
+      const name = selected.part.subagent.name
+      const Subagent = subagentComponents?.[name] as
+        | ComponentType<SubagentProps<TOptions>>
+        | undefined
+      if (!Subagent) {
+        throw new Error(`[tanstack-ai-ui] Missing subagentsComponents.${name}`)
+      }
+      return (
+        <SubagentRenderContext.Provider
+          value={{ handle: selected.part.subagent }}
+        >
+          <Subagent
+            Parts={SubagentMessages}
+            subagent={
+              selected.part.subagent as SubagentProps<TOptions>['subagent']
+            }
+          />
+        </SubagentRenderContext.Provider>
+      )
+    }
+
+    const PartComponent = (widgets.parts[selected.key] ??
+      widgets.parts.fallback) as ComponentType<PartProps<TOptions>> | undefined
     if (!PartComponent) {
       warn(
         `part:${selected.key}`,
@@ -746,6 +877,115 @@ export function createChatUI<
     )
   })
 
+  function readSubagentMessages() {
+    const scoped = useContext(SubagentRenderContext)
+    const chat = useChatContext()
+    if (scoped?.listed) {
+      const live = chat.subagents.find((item) => item.id === scoped.handle.id)
+      return (live ?? scoped.handle).messages
+    }
+    if (scoped) return scoped.handle.messages
+    const selected = useContext(PartContext)
+    if (selected?.key === 'subagent' && selected.part.type === 'subagent') {
+      return selected.part.subagent.messages
+    }
+    throw new Error(
+      '`Parts` must be rendered by a subagent component or `Subagents` item.',
+    )
+  }
+
+  const SubagentMessagesBody = memo(function SubagentMessagesBody({
+    messages,
+  }: {
+    messages: SubagentHandle['messages']
+  }) {
+    const chat = useChatContext()
+    const interrupts = readInterrupts(chat)
+    return (
+      <>
+        {messages.map((message) => (
+          <AutomaticParts
+            key={message.id}
+            inlineToolNames={inlineToolNames}
+            interrupts={interrupts}
+            message={message}
+          />
+        ))}
+      </>
+    )
+  }, subagentMessagesEqual)
+
+  function SubagentMessages({
+    partsComponents,
+    toolsComponents,
+  }: SubagentPartsProps<TOptions>) {
+    const messages = readSubagentMessages()
+    const outer = useContext(WidgetsContext)
+    const widgets = useMemo(
+      () =>
+        partsComponents || toolsComponents
+          ? {
+              parts: withWidgets(outer.parts, partsComponents),
+              tools: withWidgets(outer.tools, toolsComponents),
+            }
+          : outer,
+      [outer, partsComponents, toolsComponents],
+    )
+    // ponytail: root `<Interrupts />` still lists an approval for a tool call
+    // inside a card, so it shows in both places. Hiding it needs `selectChatUI`
+    // to collect tool-call ids from nested subagent messages (its `callIds` is
+    // top-level only) plus the card tool names in `inlineToolNames`.
+    return (
+      <WidgetsContext.Provider value={widgets}>
+        <SubagentMessagesBody messages={messages} />
+      </WidgetsContext.Provider>
+    )
+  }
+
+  const SubagentListItem = memo(function SubagentListItem({
+    handle,
+  }: SubagentRowProps) {
+    const Subagent = subagentComponents?.[handle.name] as
+      | ComponentType<SubagentProps<TOptions>>
+      | undefined
+    if (!Subagent) {
+      throw new Error(
+        `[tanstack-ai-ui] Missing subagentsComponents.${handle.name}`,
+      )
+    }
+    return (
+      <SubagentRenderContext.Provider value={{ handle, listed: true }}>
+        <Subagent
+          Parts={SubagentMessages}
+          subagent={handle as SubagentProps<TOptions>['subagent']}
+        />
+      </SubagentRenderContext.Provider>
+    )
+  }, subagentListItemEqual)
+
+  function Subagents({
+    children,
+  }: {
+    children?: (subagents: Array<SubagentHandle>) => ReactNode
+  } = {}) {
+    const chat = useChatContext()
+    const live = chat.subagents
+    if (children) return <>{children(live)}</>
+    if (live.length === 0) return null
+    return (
+      <>
+        {live.map((handle) => (
+          <SubagentListItem
+            key={handle.id}
+            handle={handle}
+            status={handle.status}
+            error={handle.error}
+          />
+        ))}
+      </>
+    )
+  }
+
   return {
     Chat,
     Provider,
@@ -755,6 +995,8 @@ export function createChatUI<
     Interrupts,
     Interrupt,
     Queue,
+    Subagents,
+    SubagentMessages,
     useChatContext,
     Input: InputComponent,
   }

package/src/create-chat-hook.ts

@@ -12,6 +12,7 @@ type ChatHookOverrides<
   TSchema extends SchemaInput | undefined,
   TContext,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TSubagents extends ReadonlyArray<{ name: string }> | undefined,
 > = {
   threadId?: string
   live?: boolean
@@ -21,7 +22,8 @@ type ChatHookOverrides<
     TTools,
     TSchema,
     TContext,
-    TInterrupts
+    TInterrupts,
+    TSubagents
   >['initialMessages']
 }
 
@@ -53,9 +55,17 @@ export function createChatHook<
   const TInterrupts extends ReadonlyArray<
     InterruptDefinition<any, any, any, any>
   > = readonly [],
->(options: UseChatOptions<TTools, TSchema, TContext, TInterrupts>) {
+  const TSubagents extends ReadonlyArray<{ name: string }> | undefined =
+    undefined,
+>(options: UseChatOptions<TTools, TSchema, TContext, TInterrupts, TSubagents>) {
   function useChat(
-    overrides?: ChatHookOverrides<TTools, TSchema, TContext, TInterrupts>,
+    overrides?: ChatHookOverrides<
+      TTools,
+      TSchema,
+      TContext,
+      TInterrupts,
+      TSubagents
+    >,
   ) {
     if (!overrides) {
       return useUnboundChat(options)

package/src/index.ts

@@ -4,8 +4,16 @@ export { useByok } from './use-byok'
 export { useRealtimeChat } from './use-realtime-chat'
 export { useMcpAppBridge } from './use-mcp-app-bridge'
 export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge'
-export { useWebMCPTools } from './use-web-mcp-tools'
-export type { UseWebMCPToolsOptions } from './use-web-mcp-tools'
+export {
+  usePageWebMCPTools,
+  useRegisterWebMCPTools,
+  useWebMCPTools,
+} from './use-web-mcp-tools'
+export type {
+  UsePageWebMCPToolsOptions,
+  UseRegisterWebMCPToolsOptions,
+  UseWebMCPToolsOptions,
+} from './use-web-mcp-tools'
 export type {
   DeepPartial,
   UseChatOptions,
@@ -105,6 +113,11 @@ export {
   PartialJSONParser,
   defaultJSONParser,
   registerWebMCPTools,
+  getWebMCPTools,
+  subscribeWebMCPTools,
+  type GetWebMCPToolsOptions,
+  type SubscribeWebMCPToolsOptions,
+  type WebMCPPageTool,
   clientTools,
   fetchServerSentEvents,
   localStoragePersistence,

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>
 }