@tanstack/ai-client 0.33.2 → 0.35.1

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,

package/src/web-mcp-tools.ts

@@ -209,3 +209,184 @@ export async function registerWebMCPTools<
     throw error
   }
 }
+
+/** A tool that a page registered with WebMCP, as `getTools()` returns it. */
+export interface WebMCPPageTool {
+  name: string
+  title?: string
+  description: string
+  /** A JSON Schema object for the tool input. */
+  inputSchema?: object
+  /** The origin of the document that registered the tool. */
+  origin: string
+  annotations?: WebMCPToolAnnotations
+}
+
+interface WebMCPToolReader {
+  getTools: () => Promise<Array<WebMCPPageTool>>
+  executeTool: (
+    tool: WebMCPPageTool,
+    input: unknown,
+    options: { signal?: AbortSignal },
+  ) => Promise<string>
+  addEventListener: EventTarget['addEventListener']
+  removeEventListener: EventTarget['removeEventListener']
+}
+
+/** Options for {@link getWebMCPTools}. */
+export interface GetWebMCPToolsOptions {
+  /** Return `false` to skip a tool. */
+  filter?: (tool: WebMCPPageTool) => boolean
+}
+
+/** Options for {@link subscribeWebMCPTools}. */
+export interface SubscribeWebMCPToolsOptions extends GetWebMCPToolsOptions {
+  /** Stops the subscription when it aborts. */
+  signal: AbortSignal
+  /** Receives a failure from the WebMCP `getTools()` call. */
+  onError?: (error: unknown) => void
+}
+
+function isWebMCPToolReader(value: unknown): value is WebMCPToolReader {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'getTools' in value &&
+    typeof value.getTools === 'function' &&
+    'executeTool' in value &&
+    typeof value.executeTool === 'function' &&
+    'addEventListener' in value &&
+    typeof value.addEventListener === 'function' &&
+    'removeEventListener' in value &&
+    typeof value.removeEventListener === 'function'
+  )
+}
+
+function getWebMCPToolReader() {
+  if (
+    typeof document === 'undefined' ||
+    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||
+    !('modelContext' in document) ||
+    !isWebMCPToolReader(document.modelContext)
+  ) {
+    return undefined
+  }
+  return document.modelContext
+}
+
+function parseToolResult(result: string): unknown {
+  try {
+    return JSON.parse(result)
+  } catch {
+    return result
+  }
+}
+
+async function readWebMCPTools(
+  reader: WebMCPToolReader,
+  options: GetWebMCPToolsOptions | undefined,
+): Promise<Array<AnyClientTool>> {
+  const pageTools = await reader.getTools()
+  const names = new Set<string>()
+  return pageTools
+    .filter((tool) => options?.filter?.(tool) ?? true)
+    .map((tool) => {
+      if (names.has(tool.name)) {
+        throw new Error(
+          `Duplicate WebMCP tool name "${tool.name}". Use a filter or register tools with unique names.`,
+        )
+      }
+      names.add(tool.name)
+      return {
+        __toolSide: 'client' as const,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema ?? { type: 'object' },
+        async execute(input: unknown, context?: { abortSignal?: AbortSignal }) {
+          const result = await reader.executeTool(
+            tool,
+            input,
+            context?.abortSignal ? { signal: context.abortSignal } : {},
+          )
+          return parseToolResult(result)
+        },
+      }
+    })
+}
+
+/**
+ * Reads the WebMCP tools on the page and returns them as client tools.
+ *
+ * Pass the result to a chat as `tools`. Each tool runs through the WebMCP
+ * `executeTool()` call. Unsupported browsers and server environments return
+ * an empty array.
+ *
+ * @param options - A filter that skips tools.
+ *
+ * @example
+ * ```ts
+ * const tools = await getWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * ```
+ */
+export async function getWebMCPTools(
+  options?: GetWebMCPToolsOptions,
+): Promise<Array<AnyClientTool>> {
+  const reader = getWebMCPToolReader()
+  return reader ? readWebMCPTools(reader, options) : []
+}
+
+/**
+ * Calls `listener` with the page WebMCP tools now and after each
+ * `toolchange` event, until `options.signal` aborts.
+ *
+ * Unsupported browsers and server environments call `listener` once with an
+ * empty array. When a read fails, `options.onError` gets the error and the
+ * listener keeps the last list.
+ *
+ * @param listener - Receives the current client tools.
+ * @param options - The subscription signal, a filter, and an error callback.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {
+ *   signal: controller.signal,
+ * })
+ * ```
+ */
+export function subscribeWebMCPTools(
+  listener: (tools: Array<AnyClientTool>) => void,
+  options: SubscribeWebMCPToolsOptions,
+): void {
+  if (options.signal.aborted) return
+  const reader = getWebMCPToolReader()
+  if (!reader) {
+    listener([])
+    return
+  }
+
+  let latestRead = 0
+  const refresh = () => {
+    const read = ++latestRead
+    const isCurrent = () => read === latestRead && !options.signal.aborted
+    readWebMCPTools(reader, options).then(
+      (tools) => {
+        if (isCurrent()) listener(tools)
+      },
+      (error: unknown) => {
+        if (isCurrent()) options.onError?.(error)
+      },
+    )
+  }
+
+  // Remove the listener by hand: Zone.js breaks the `signal` listener option.
+  reader.addEventListener('toolchange', refresh)
+  options.signal.addEventListener(
+    'abort',
+    () => reader.removeEventListener('toolchange', refresh),
+    { once: true },
+  )
+  refresh()
+}