@tanstack/ai 0.57.0 → 0.59.0

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

@@ -7,8 +7,11 @@ import type {
   AnyTool,
   ContentPart,
   CustomEvent,
+  EmitCustomEventOptions,
+  Interrupt,
   ModelMessage,
   RunFinishedEvent,
+  StreamChunk,
   Tool,
   ToolCall,
   ToolCallArgsEvent,
@@ -37,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()`).
@@ -504,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>
 }
 
 /**
@@ -513,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) => {
@@ -531,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
   }
@@ -611,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),
@@ -632,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
     }
@@ -670,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
     }
@@ -760,15 +824,17 @@ export async function* executeToolCalls<TContext = unknown>(
   createCustomEventChunk?: (
     eventName: string,
     value: Record<string, any>,
+    options?: EmitCustomEventOptions,
   ) => CustomEvent,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
   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>()
@@ -869,18 +935,26 @@ 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,
       abortSignal,
-      emitCustomEvent: (eventName: string, value: Record<string, any>) => {
+      emitCustomEvent: (
+        eventName: string,
+        value: Record<string, any>,
+        options?: EmitCustomEventOptions,
+      ) => {
         if (createCustomEventChunk) {
           pendingEvents.push(
-            createCustomEventChunk(eventName, {
-              ...value,
-              toolCallId: toolCall.id,
-            }),
+            createCustomEventChunk(
+              eventName,
+              {
+                ...value,
+                toolCallId: toolCall.id,
+              },
+              options,
+            ),
           )
         }
       },
@@ -997,6 +1071,7 @@ export async function* executeToolCalls<TContext = unknown>(
             pendingEvents,
             results,
             middlewareHooks,
+            subagentInterrupts,
           )
         } else {
           // User declined
@@ -1045,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,

package/src/stream-to-response.ts

@@ -9,6 +9,10 @@ import { notifyRunDisconnected } from './delivery-disconnect'
 import { resolveResumeRunId } from './stream-durability'
 import { EventType } from './types'
 import { toWireChunk } from './strip-to-spec-middleware'
+import {
+  isDurabilityBatchedCustom,
+  stripDurabilityBatchHint,
+} from './utilities/durability-batch'
 import { resolveDebugOption } from './logger/resolve'
 import { runErrorEventToError } from './utilities/errors'
 import type { LockStore } from './activities/chat/middleware/locks'
@@ -319,23 +323,29 @@ function resolveBatchSize(batch: number | undefined): number {
 
 /**
  * Boundaries at which the batching producer flushes early, regardless of the
- * batch size — the run-start marker, terminal events, and tool-call ends.
- * Flushing here keeps the durability log promptly consistent at semantically
- * meaningful points.
+ * batch size: run-start, terminals, tool-call ends, and CUSTOM events that
+ * are not high-volume adapter output.
  *
  * `RUN_STARTED` matters especially for one-shot activities (image, speech,
  * transcription, summarize): they emit `RUN_STARTED`, then await the provider
  * for seconds, then a terminal. Without flushing `RUN_STARTED` the log stays
  * empty for the whole run, so a mount-time `joinRun` finds nothing and its
- * empty-log deadline fast-fails as "run gone" — even though the run is alive.
+ * empty-log deadline fast-fails as "run gone" even though the run is alive.
  * Flushing it immediately makes the run resumable from the instant it starts.
+ *
+ * CUSTOM progress events (compaction, tool progress, middleware) flush at
+ * emit time so a live indicator can render. `process.stdout`,
+ * `process.stderr`, `sandbox.file`, and `sandbox.file.diff` stay batched.
+ * `emitCustomEvent(name, value, { batch: true })` opts a single event into
+ * that same batch.
  */
 function isDurabilityFlushBoundary(chunk: StreamChunk): boolean {
   return (
     chunk.type === 'RUN_STARTED' ||
     chunk.type === 'RUN_FINISHED' ||
     chunk.type === 'RUN_ERROR' ||
-    chunk.type === 'TOOL_CALL_END'
+    chunk.type === 'TOOL_CALL_END' ||
+    (chunk.type === 'CUSTOM' && !isDurabilityBatchedCustom(chunk))
   )
 }
 
@@ -446,7 +456,7 @@ export function durableStreamSource<TOffset extends string>(
 
     async function* flush(): AsyncIterable<StreamChunk> {
       if (batch.length === 0) return
-      const toForward = batch
+      const toForward = batch.map(stripDurabilityBatchHint)
       batch = []
       // Tag each chunk with the exact backend offset. Requiring one opaque
       // token per chunk preserves exact-once resume at any batch size.

package/src/strip-to-spec-middleware.ts

@@ -6,6 +6,7 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from './utilities/merge-metadata'
+import { stripDurabilityBatchHint } from './utilities/durability-batch'
 import { normalizeStreamChunk } from './utilities/normalize-stream-chunk'
 import { isSpecTopLevelKey } from './utilities/spec-event-keys'
 
@@ -54,5 +55,5 @@ export function toWireChunk(
   chunk: StreamChunk | AdapterYieldChunk,
 ): StreamChunk {
   const [normalized] = normalizeStreamChunk(chunk)
-  return stripToSpec(normalized ?? chunk)
+  return stripDurabilityBatchHint(stripToSpec(normalized ?? chunk))
 }