@tanstack/ai 0.58.0 → 0.59.0

package/src/activities/chat/tools/tool-calls.ts

@@ -8,8 +8,10 @@ import type {
   ContentPart,
   CustomEvent,
   EmitCustomEventOptions,
+  Interrupt,
   ModelMessage,
   RunFinishedEvent,
+  StreamChunk,
   Tool,
   ToolCall,
   ToolCallArgsEvent,
@@ -38,6 +40,25 @@ function safeJsonParse(value: string): unknown {
   }
 }
 
+/** Marks the synthetic tool that runs a subagent. */
+export const SUBAGENT_TOOL = Symbol.for('tanstack.ai.subagentTool')
+
+/** Set on the tool context of a subagent tool. Streams a child chunk live. */
+export const EMIT_STREAM_CHUNK = Symbol.for('tanstack.ai.emitStreamChunk')
+
+/** What a subagent tool's `execute` returns. */
+export interface SubagentToolOutcome {
+  subagentRunId: string
+  text: string
+  error?: string
+  /** Set when the child stopped for outside input. The tool call stays open. */
+  interrupts?: Array<Interrupt>
+}
+
+function isSubagentTool(tool: AnyTool): boolean {
+  return (tool as { [SUBAGENT_TOOL]?: true })[SUBAGENT_TOOL] === true
+}
+
 /**
  * MCP Apps metadata attached to a server tool at discovery (see
  * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).
@@ -505,6 +526,8 @@ interface ExecuteToolCallsResult {
   needsApproval: Array<ApprovalRequest>
   /** Tools that need client-side execution */
   needsClientExecution: Array<ClientToolRequest>
+  /** Interrupts raised by subagents that run as tools */
+  subagentInterrupts: Array<Interrupt>
 }
 
 /**
@@ -514,8 +537,8 @@ interface ExecuteToolCallsResult {
  */
 async function* executeWithEventPolling<T>(
   executionPromise: Promise<T>,
-  pendingEvents: Array<CustomEvent>,
-): AsyncGenerator<CustomEvent, T, void> {
+  pendingEvents: Array<CustomEvent | StreamChunk>,
+): AsyncGenerator<CustomEvent | StreamChunk, T, void> {
   // Use an object to track mutable state across the async boundary
   const state = { done: false, result: undefined as T }
   const executionWithFlag = executionPromise.then((r) => {
@@ -532,14 +555,14 @@ async function* executeWithEventPolling<T>(
     ])
 
     // Flush any pending events
-    let event: CustomEvent | undefined
+    let event: CustomEvent | StreamChunk | undefined
     while ((event = pendingEvents.shift()) !== undefined) {
       yield event
     }
   }
 
   // Final flush in case events were emitted right at completion
-  let event: CustomEvent | undefined
+  let event: CustomEvent | StreamChunk | undefined
   while ((event = pendingEvents.shift()) !== undefined) {
     yield event
   }
@@ -612,19 +635,59 @@ export async function* executeServerTool<TContext = unknown>(
   toolName: string,
   input: unknown,
   context: ToolExecutionContext<TContext>,
-  pendingEvents: Array<CustomEvent>,
+  pendingEvents: Array<CustomEvent | StreamChunk>,
   results: Array<ToolResult>,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
-): AsyncGenerator<CustomEvent, void, void> {
+  subagentInterrupts?: Array<Interrupt>,
+): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
   const startTime = Date.now()
   try {
     if (!tool.execute) {
       throw new Error(`Tool ${toolName} has no execute() implementation`)
     }
+    const subagent = isSubagentTool(tool)
+    if (subagent) {
+      Object.assign(context, {
+        [EMIT_STREAM_CHUNK]: (chunk: StreamChunk) => pendingEvents.push(chunk),
+      })
+    }
     const executionPromise = Promise.resolve(tool.execute(input, context))
     let result = yield* executeWithEventPolling(executionPromise, pendingEvents)
     const duration = Date.now() - startTime
 
+    if (subagent) {
+      const outcome = result as SubagentToolOutcome
+      if (outcome.interrupts?.length) {
+        // The child waits for outside input. Leave the call open so the
+        // resume run executes it again and continues the same child.
+        subagentInterrupts?.push(...outcome.interrupts)
+        return
+      }
+      const modelResult = outcome.error
+        ? { subagentRunId: outcome.subagentRunId, error: outcome.error }
+        : { subagentRunId: outcome.subagentRunId, result: outcome.text }
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: modelResult,
+        input,
+        output: modelResult,
+        duration,
+        ...(outcome.error ? { state: 'output-error' as const } : {}),
+      })
+      await middlewareHooks?.onAfterToolCall?.({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        duration,
+        ...(outcome.error
+          ? { ok: false as const, error: new Error(outcome.error) }
+          : { ok: true as const, result: modelResult }),
+      })
+      return
+    }
+
     // MCP Apps: if this tool links a ui:// resource, eagerly read it and queue
     // a `ui-resource` CUSTOM event. The MCP source stays live until the run
     // drains (MCPManager's `connection:'close'` policy disposes on completion),
@@ -633,7 +696,7 @@ export async function* executeServerTool<TContext = unknown>(
     await emitUiResourceIfLinked(tool, context)
 
     // Flush remaining events (including any queued ui-resource event)
-    let pendingEvent: CustomEvent | undefined
+    let pendingEvent: CustomEvent | StreamChunk | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent
     }
@@ -671,7 +734,7 @@ export async function* executeServerTool<TContext = unknown>(
     const duration = Date.now() - startTime
 
     // Flush remaining events
-    let pendingEvent: CustomEvent | undefined
+    let pendingEvent: CustomEvent | StreamChunk | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent
     }
@@ -767,10 +830,11 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
-): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
+): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
+  const subagentInterrupts: Array<Interrupt> = []
 
   // Create tool lookup map
   const toolMap = new Map<string, AnyTool>()
@@ -871,7 +935,7 @@ export async function* executeToolCalls<TContext = unknown>(
     }
 
     // Create a ToolExecutionContext for this tool call with event emission
-    const pendingEvents: Array<CustomEvent> = []
+    const pendingEvents: Array<CustomEvent | StreamChunk> = []
     const context = {
       toolCallId: toolCall.id,
       context: userContext,
@@ -1007,6 +1071,7 @@ export async function* executeToolCalls<TContext = unknown>(
             pendingEvents,
             results,
             middlewareHooks,
+            subagentInterrupts,
           )
         } else {
           // User declined
@@ -1055,8 +1120,9 @@ export async function* executeToolCalls<TContext = unknown>(
       pendingEvents,
       results,
       middlewareHooks,
+      subagentInterrupts,
     )
   }
 
-  return { results, needsApproval, needsClientExecution }
+  return { results, needsApproval, needsClientExecution, subagentInterrupts }
 }

package/src/activities/index.ts

@@ -39,6 +39,21 @@ export {
   type TextActivityResult,
 } from './chat/index'
 
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './chat/agents/define-agent'
+export { subagentRoute, type SubagentRouteOptions } from './chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './chat/agents/spawn'
+
 export {
   BaseTextAdapter,
   type AnyTextAdapter,

package/src/client.ts

@@ -224,41 +224,25 @@ export async function generationParamsFromRequest<TKind extends GenerationKind>(
   return generationParamsFromBody(kind, body)
 }
 
-export enum EventType {
-  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
-  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
-  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',
-  TEXT_MESSAGE_CHUNK = 'TEXT_MESSAGE_CHUNK',
-  TOOL_CALL_START = 'TOOL_CALL_START',
-  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',
-  TOOL_CALL_END = 'TOOL_CALL_END',
-  TOOL_CALL_CHUNK = 'TOOL_CALL_CHUNK',
-  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',
-  THINKING_START = 'THINKING_START',
-  THINKING_END = 'THINKING_END',
-  THINKING_TEXT_MESSAGE_START = 'THINKING_TEXT_MESSAGE_START',
-  THINKING_TEXT_MESSAGE_CONTENT = 'THINKING_TEXT_MESSAGE_CONTENT',
-  THINKING_TEXT_MESSAGE_END = 'THINKING_TEXT_MESSAGE_END',
-  STATE_SNAPSHOT = 'STATE_SNAPSHOT',
-  STATE_DELTA = 'STATE_DELTA',
-  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',
-  ACTIVITY_SNAPSHOT = 'ACTIVITY_SNAPSHOT',
-  ACTIVITY_DELTA = 'ACTIVITY_DELTA',
-  RAW = 'RAW',
-  CUSTOM = 'CUSTOM',
-  RUN_STARTED = 'RUN_STARTED',
-  RUN_FINISHED = 'RUN_FINISHED',
-  RUN_ERROR = 'RUN_ERROR',
-  STEP_STARTED = 'STEP_STARTED',
-  STEP_FINISHED = 'STEP_FINISHED',
-  REASONING_START = 'REASONING_START',
-  REASONING_MESSAGE_START = 'REASONING_MESSAGE_START',
-  REASONING_MESSAGE_CONTENT = 'REASONING_MESSAGE_CONTENT',
-  REASONING_MESSAGE_END = 'REASONING_MESSAGE_END',
-  REASONING_MESSAGE_CHUNK = 'REASONING_MESSAGE_CHUNK',
-  REASONING_END = 'REASONING_END',
-  REASONING_ENCRYPTED_VALUE = 'REASONING_ENCRYPTED_VALUE',
-}
+export { EventType } from '@ag-ui/core'
+
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './activities/chat/agents/define-agent'
+export {
+  subagentRoute,
+  type SubagentRouteOptions,
+} from './activities/chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './activities/chat/agents/spawn'
 
 export {
   toolDefinition,
@@ -349,6 +333,9 @@ export type {
   AudioPart,
   ContentPart,
   ContentPartDataSource,
+  ContentPartFileSource,
+  SubagentHandleData,
+  SubagentStatus,
   ContentPartSource,
   ContentPartUrlSource,
   CustomEvent,

package/src/index.ts

@@ -78,6 +78,24 @@ export { BaseRerankAdapter } from './activities/rerank/adapter'
 // Evaluate adapter base + types
 export { BaseEvaluateAdapter } from './activities/evaluate/adapter'
 
+export {
+  defineAgent,
+  type DefinedAgent,
+  type SubagentChoiceOptions,
+  type SubagentRunContext,
+} from './activities/chat/agents/define-agent'
+export {
+  subagentRoute,
+  type SubagentRouteOptions,
+} from './activities/chat/agents/route'
+export type {
+  SubagentOrder,
+  SubagentRouterPick,
+  SubagentRouterPlan,
+  SubagentStep,
+  SubagentStepsPlan,
+} from './activities/chat/agents/spawn'
+
 // Tool definition
 export {
   toolDefinition,
@@ -494,6 +512,11 @@ export { generationParamsFromBody, generationParamsFromRequest } from './client'
 
 // AG-UI wire serialization (used internally by @tanstack/ai-client)
 export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { SubagentWireInfo } from './utilities/subagent-wire'
+export {
+  subagentHostMessageId,
+  wireSubagentInfo,
+} from './utilities/subagent-wire'
 export { mergeMetadata, withTanstackMetadata } from './utilities/merge-metadata'
 export { fromSpecTokenUsage, toSpecTokenUsage } from './utilities/ag-ui-usage'
 export type { SpecTokenUsage } from './utilities/ag-ui-usage'

package/src/middlewares/content-guard.ts

@@ -3,6 +3,7 @@ import type {
   ChatMiddlewareContext,
 } from '../activities/chat/middleware/types'
 import type { StreamChunk } from '../types'
+import type { AdapterYieldChunk } from '../utilities/adapter-yield-chunk'
 
 /**
  * A content guard rule — either a regex pattern with replacement, or a transform function.
@@ -142,11 +143,12 @@ function createDeltaStrategy(
 
       if (blockOnMatch) return null // drop chunk
 
-      // Strip out the previous `content` field by destructuring it away — with
-      // `exactOptionalPropertyTypes` we can't assign `content: undefined`
-      // against `content?: string`. The replacement event carries only the
-      // filtered delta.
-      const { content: _strippedContent, ...rest } = chunk
+      // Drop the adapter-era content field; the replacement event carries only
+      // the filtered delta.
+      const { content: _strippedContent, ...rest } = chunk as Extract<
+        AdapterYieldChunk,
+        { type: 'TEXT_MESSAGE_CONTENT' }
+      >
       void _strippedContent
       return {
         ...rest,