@tanstack/ai 0.58.0 → 0.59.0

package/dist/esm/activities/chat/agents/turn.js

@@ -0,0 +1,78 @@
+import { splitSubagentWire, subagentWireText, wireSubagentRunId } from "../../../utilities/subagent-wire.js";
+//#region src/activities/chat/agents/turn.ts
+/** Key of the router plan in `SUBAGENT_STARTED` metadata (`metadata.tanstack`). */
+var SUBAGENT_PLAN_KEY = "subagentPlan";
+function planOf(metadata) {
+	const tanstack = metadata?.tanstack;
+	if (typeof tanstack !== "object" || tanstack === null) return void 0;
+	return tanstack[SUBAGENT_PLAN_KEY];
+}
+function uiText(messages) {
+	return messages.flatMap((message) => message.role === "assistant" ? message.parts.flatMap((part) => part.type === "text" && part.content.trim() !== "" ? [part.content.trim()] : []) : []).join("\n\n");
+}
+function partInterruptIds(part) {
+	return [...part.subagent.interruptIds ?? [], ...part.subagent.messages.flatMap((message) => message.parts.flatMap((nested) => nested.type === "subagent" ? partInterruptIds(nested) : []))];
+}
+function groupInterruptIds(group) {
+	return [...group.info.interruptIds ?? [], ...splitSubagentWire(group.messages).groups.flatMap(groupInterruptIds)];
+}
+/**
+* Find the children of the trailing assistant turn that `resume` answers.
+* Returns undefined when no child owns a resume entry.
+*/
+function readSubagentTurn(messages, resume) {
+	if (!resume || resume.length === 0) return void 0;
+	const lastUser = messages.findLastIndex((message) => message.role === "user" && wireSubagentRunId(message) === void 0);
+	const before = messages.slice(0, lastUser + 1);
+	const turn = messages.slice(lastUser + 1);
+	const found = [];
+	let plan;
+	for (const message of turn) {
+		if (!("parts" in message)) continue;
+		for (const part of message.parts) {
+			if (part.type !== "subagent") continue;
+			plan ??= planOf(part.subagent.metadata);
+			found.push({
+				subagentRunId: part.subagent.id,
+				name: part.subagent.name,
+				status: part.subagent.status,
+				...part.subagent.parentToolCallId !== void 0 && { parentToolCallId: part.subagent.parentToolCallId },
+				messages: part.subagent.messages,
+				text: uiText(part.subagent.messages),
+				ids: new Set(partInterruptIds(part))
+			});
+		}
+	}
+	for (const group of splitSubagentWire(turn).groups) {
+		plan ??= planOf(group.info.metadata);
+		found.push({
+			subagentRunId: group.id,
+			name: group.info.name,
+			status: group.info.status,
+			...group.info.parentToolCallId !== void 0 && { parentToolCallId: group.info.parentToolCallId },
+			messages: group.messages,
+			text: subagentWireText(group.messages),
+			ids: new Set(groupInterruptIds(group))
+		});
+	}
+	const owned = /* @__PURE__ */ new Set();
+	const children = found.map(({ ids, ...child }) => {
+		const entries = resume.filter((entry) => ids.has(entry.interruptId));
+		for (const entry of entries) owned.add(entry.interruptId);
+		return {
+			...child,
+			resume: entries
+		};
+	});
+	if (owned.size === 0) return void 0;
+	return {
+		before,
+		children,
+		rest: resume.filter((entry) => !owned.has(entry.interruptId)),
+		...plan !== void 0 && { plan }
+	};
+}
+//#endregion
+export { SUBAGENT_PLAN_KEY, readSubagentTurn };
+
+//# sourceMappingURL=turn.js.map

package/dist/esm/activities/chat/agents/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","names":[],"sources":["../../../../../src/activities/chat/agents/turn.ts"],"sourcesContent":["import {\n  splitSubagentWire,\n  subagentWireText,\n  wireSubagentRunId,\n} from '../../../utilities/subagent-wire'\nimport type { SubagentWireGroup } from '../../../utilities/subagent-wire'\nimport type {\n  ModelMessage,\n  RunAgentResumeItem,\n  SubagentPart,\n  SubagentStatus,\n  UIMessage,\n} from '../../../types'\n\ntype AnyMessage = UIMessage | ModelMessage\n\nexport interface SubagentTurnChild {\n  subagentRunId: string\n  name: string\n  status: SubagentStatus\n  parentToolCallId?: string\n  /** The child's own messages from the earlier run. */\n  messages: Array<AnyMessage>\n  /** Text the child wrote. */\n  text: string\n  /** Resume entries for this child and its nested children. */\n  resume: Array<RunAgentResumeItem>\n}\n\n/** The interrupted turn that a resume continues. */\nexport interface SubagentTurn {\n  /**\n   * Messages up to and including the last top-level user message. Child wire\n   * messages do not count.\n   */\n  before: Array<AnyMessage>\n  /** Direct children of the parent in that turn. */\n  children: Array<SubagentTurnChild>\n  /** Resume entries that no child owns. They belong to the parent run. */\n  rest: Array<RunAgentResumeItem>\n  /** The router plan of the earlier run, from the children's metadata. */\n  plan?: unknown\n}\n\n/** Key of the router plan in `SUBAGENT_STARTED` metadata (`metadata.tanstack`). */\nexport const SUBAGENT_PLAN_KEY = 'subagentPlan'\n\nfunction planOf(metadata: Record<string, unknown> | undefined): unknown {\n  const tanstack = metadata?.tanstack\n  if (typeof tanstack !== 'object' || tanstack === null) return undefined\n  return (tanstack as Record<string, unknown>)[SUBAGENT_PLAN_KEY]\n}\n\nfunction uiText(messages: ReadonlyArray<UIMessage>) {\n  return messages\n    .flatMap((message) =>\n      message.role === 'assistant'\n        ? message.parts.flatMap((part) =>\n            part.type === 'text' && part.content.trim() !== ''\n              ? [part.content.trim()]\n              : [],\n          )\n        : [],\n    )\n    .join('\\n\\n')\n}\n\nfunction partInterruptIds(part: SubagentPart): Array<string> {\n  return [\n    ...(part.subagent.interruptIds ?? []),\n    ...part.subagent.messages.flatMap((message) =>\n      message.parts.flatMap((nested) =>\n        nested.type === 'subagent' ? partInterruptIds(nested) : [],\n      ),\n    ),\n  ]\n}\n\nfunction groupInterruptIds(group: SubagentWireGroup<unknown>): Array<string> {\n  return [\n    ...(group.info.interruptIds ?? []),\n    ...splitSubagentWire(group.messages).groups.flatMap(groupInterruptIds),\n  ]\n}\n\n/**\n * Find the children of the trailing assistant turn that `resume` answers.\n * Returns undefined when no child owns a resume entry.\n */\nexport function readSubagentTurn(\n  messages: ReadonlyArray<AnyMessage>,\n  resume: ReadonlyArray<RunAgentResumeItem> | undefined,\n): SubagentTurn | undefined {\n  if (!resume || resume.length === 0) return undefined\n  const lastUser = messages.findLastIndex(\n    (message) =>\n      message.role === 'user' && wireSubagentRunId(message) === undefined,\n  )\n  const before = messages.slice(0, lastUser + 1)\n  const turn = messages.slice(lastUser + 1)\n\n  const found: Array<Omit<SubagentTurnChild, 'resume'> & { ids: Set<string> }> =\n    []\n  let plan: unknown\n  for (const message of turn) {\n    if (!('parts' in message)) continue\n    for (const part of message.parts) {\n      if (part.type !== 'subagent') continue\n      plan ??= planOf(part.subagent.metadata)\n      found.push({\n        subagentRunId: part.subagent.id,\n        name: part.subagent.name,\n        status: part.subagent.status,\n        ...(part.subagent.parentToolCallId !== undefined && {\n          parentToolCallId: part.subagent.parentToolCallId,\n        }),\n        messages: part.subagent.messages,\n        text: uiText(part.subagent.messages),\n        ids: new Set(partInterruptIds(part)),\n      })\n    }\n  }\n  for (const group of splitSubagentWire(turn).groups) {\n    plan ??= planOf(group.info.metadata)\n    found.push({\n      subagentRunId: group.id,\n      name: group.info.name,\n      status: group.info.status,\n      ...(group.info.parentToolCallId !== undefined && {\n        parentToolCallId: group.info.parentToolCallId,\n      }),\n      messages: group.messages,\n      text: subagentWireText(group.messages),\n      ids: new Set(groupInterruptIds(group)),\n    })\n  }\n\n  const owned = new Set<string>()\n  const children = found.map(({ ids, ...child }) => {\n    const entries = resume.filter((entry) => ids.has(entry.interruptId))\n    for (const entry of entries) owned.add(entry.interruptId)\n    return { ...child, resume: entries }\n  })\n  if (owned.size === 0) return undefined\n  return {\n    before,\n    children,\n    rest: resume.filter((entry) => !owned.has(entry.interruptId)),\n    ...(plan !== undefined && { plan }),\n  }\n}\n"],"mappings":"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"}

package/dist/esm/activities/chat/index.d.ts

@@ -1,4 +1,6 @@
 import { InterruptDefinition } from '../../interrupt-definition.js';
+import { DefinedAgent } from './agents/define-agent.js';
+import { SubagentsBag } from './agents/spawn.js';
 import { AnyTextAdapter } from './adapter.js';
 import { AnyTool, ChatStream, ConstrainedModelMessage, InferSchemaType, LazyToolsConfig, ModelMessage, ProviderTool, SchemaInput, StructuredOutputStream, TextOptions, UIMessage } from '../../types.js';
 import { AnyChatMiddleware, ChatMiddleware } from './middleware/types.js';
@@ -45,7 +47,7 @@ type RuntimeContextOption<TTools, TMiddleware, TContext> = [
 };
 type ExactMiddlewareOption<TTools, TContext, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>, TMiddleware extends Array<unknown> | undefined> = [TMiddleware] extends [undefined] ? Array<RegistryChatMiddleware<InlineChatContext<TTools, TContext>, NoInfer<TInterrupts>>> : TMiddleware & (TMiddleware extends Array<RegistryChatMiddleware<InlineChatContext<TTools, NoInfer<TContext>>, NoInfer<TInterrupts>>> ? Array<RegistryChatMiddleware<InlineChatContext<TTools, TContext>, NoInfer<TInterrupts>>> : CheckInterruptRegistry<TInterrupts, TMiddleware>) & CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>;
 type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [
-], TContext = unknown, TMiddleware extends Array<unknown> | undefined = undefined> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any>, 'tools' | 'middleware' | 'context' | 'interrupts'> & {
+], TContext = unknown, TMiddleware extends Array<unknown> | undefined = undefined, TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>> = Omit<TextActivityOptions<TAdapter, TSchema, TStream, any, TAgents>, 'tools' | 'middleware' | 'context' | 'interrupts'> & {
     tools?: TTools;
     interrupts?: TInterrupts & CheckUniqueInterruptDefinitions<TInterrupts>;
     middleware?: ExactMiddlewareOption<TTools, TContext, TInterrupts, TMiddleware>;
@@ -59,7 +61,7 @@ type TextActivityOptionsWithContext<TAdapter extends AnyTextAdapter, TSchema ext
  * @template TStream - Whether to stream the output (default: true)
  * @template TContext - Runtime context value threaded to middleware hooks and server tools
  */
-export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown> {
+export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined, TStream extends boolean, TContext = unknown, TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>> {
     /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */
     adapter: TAdapter;
     /**
@@ -125,6 +127,8 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     runId?: TextOptions['runId'];
     /** Parent run ID for AG-UI protocol nested run correlation. */
     parentRunId?: TextOptions['parentRunId'];
+    /** Subagent run id when this chat runs as a child. See `defineAgent`. */
+    subagentRunId?: TextOptions['subagentRunId'];
     /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
     state?: TextOptions['state'];
     /**
@@ -132,6 +136,12 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
      * before accepting new input on a thread with pending interrupts.
      */
     resume?: TextOptions['resume'];
+    /**
+     * Named child agents. When `router` is set, the library spawns that agent
+     * directly. When `router` is omitted, the main model gets one synthetic
+     * server tool per agent and picks the child.
+     */
+    subagents?: SubagentsBag<TAgents>;
     /**
      * Optional Standard Schema for structured output.
      * When provided, the activity will:
@@ -299,6 +309,6 @@ export type TextActivityResult<TSchema extends SchemaInput | undefined, TStream
  * // result is { summary: string, keyPoints: string[] }
  * ```
  */
-export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [], TContext = unknown, const TMiddleware extends Array<unknown> | undefined = undefined>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware>): TextActivityResult<TSchema, TStream, TTools>;
+export declare function chat<TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [], TContext = unknown, const TMiddleware extends Array<unknown> | undefined = undefined, const TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>>(options: TextActivityOptionsWithContext<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>): TextActivityResult<TSchema, TStream, TTools>;
 export type { TextAdapter, TextAdapterConfig, StructuredOutputOptions, StructuredOutputResult, } from './adapter.js';
 export { BaseTextAdapter } from './adapter.js';

package/dist/esm/activities/chat/index.js

@@ -18,6 +18,7 @@ import { INTERRUPT_BINDING_METADATA_KEY, InterruptResumeValidationError, readInt
 import { INTERRUPT_PAYLOAD_METADATA_KEY, createInterruptBinding, rehydrateInterruptRequest } from "../../interrupt-definition.js";
 import { readGenericInterruptContinuation } from "../../generic-interrupt-continuation.js";
 import { normalizeToolResult } from "../../utilities/tool-result.js";
+import { subagentHostMessageId } from "../../utilities/subagent-wire.js";
 import { isProviderExecutedToolCall } from "../../utilities/provider-executed.js";
 import { appendUiResourceToModelMessages, convertMessagesToModelMessages, generateMessageId, modelMessagesToUIMessages, safeJsonStringify, uiResourcePartFromCustomValue } from "./messages.js";
 import { uiMessagesToWire } from "../../utilities/ag-ui-wire.js";
@@ -25,6 +26,8 @@ import { restorePublicUsage } from "../../utilities/restore-inbound-chunk.js";
 import { LazyToolManager } from "./tools/lazy-tool-manager.js";
 import { assertUniqueToolNames } from "./tools/unique-tool-names.js";
 import { MiddlewareAbortError, ToolCallManager, executeToolCalls } from "./tools/tool-calls.js";
+import { collectNamedText, createSubagentSink, createSyntheticSubagentTools, normalizeRouterPick, rebindInterrupts, spawnNamedAgents, subagentCallMessages, withChildUsage } from "./agents/spawn.js";
+import { SUBAGENT_PLAN_KEY, readSubagentTurn } from "./agents/turn.js";
 import { maxIterations } from "./agent-loop-strategies.js";
 import { MiddlewareRunner } from "./middleware/compose.js";
 import { provideSandboxRuntime } from "./middleware/sandbox-runtime.js";
@@ -45,6 +48,14 @@ import { undoNullWidening } from "@tanstack/ai-utils";
 /** The adapter kind this activity handles */
 var kind = "text";
 var interruptBindingMetadataKey = INTERRUPT_BINDING_METADATA_KEY;
+/** Resume entries a subagent tool call owns. The parent run skips them. */
+var CHILD_RESUME_IDS = Symbol("tanstack.ai.childResumeIds");
+function assertNoFileSources(adapterName, messages) {
+	for (const message of messages) {
+		if (!Array.isArray(message.content)) continue;
+		for (const part of message.content) if ("source" in part && part.source.type === "file") throw new Error(`${adapterName} does not support provider file-handle sources ({ type: 'file' }). Pass a data or url source.`);
+	}
+}
 function isInterruptSubmissionError(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
 	if (!("scope" in value) || !("code" in value) || !("message" in value) || !("source" in value) || !("retryable" in value) || !("threadId" in value) || !("interruptedRunId" in value) || !("generation" in value) || typeof value.code !== "string" || typeof value.message !== "string" || typeof value.retryable !== "boolean" || typeof value.threadId !== "string" || typeof value.interruptedRunId !== "string" || typeof value.generation !== "number") return false;
@@ -155,6 +166,7 @@ var TextEngine = class {
 	threadId;
 	runIdOverride;
 	parentRunIdOverride;
+	subagentRunIdOverride;
 	middlewareRunner;
 	middlewareCtx;
 	sandboxFileQueue = [];
@@ -210,6 +222,7 @@ var TextEngine = class {
 		this.threadId = config.params.threadId || config.params.conversationId || this.createId("thread");
 		this.runIdOverride = config.params.runId;
 		this.parentRunIdOverride = config.params.parentRunId;
+		this.subagentRunIdOverride = config.params.subagentRunId;
 		const allMiddleware = [devtoolsMiddleware(), ...config.middleware || []];
 		this.middlewareRunner = new MiddlewareRunner(allMiddleware, logger);
 		this.middlewareAbortController = new AbortController();
@@ -219,6 +232,7 @@ var TextEngine = class {
 			streamId: this.streamId,
 			runId: this.runIdOverride ?? this.requestId,
 			parentRunId: this.parentRunIdOverride,
+			subagentRunId: this.subagentRunIdOverride,
 			threadId: this.threadId,
 			conversationId: this.threadId,
 			phase: "init",
@@ -517,6 +531,7 @@ var TextEngine = class {
 		const { approvals } = this.collectClientState();
 		const adapterApprovals = /* @__PURE__ */ new Map();
 		for (const [approvalId, resolution] of approvals) adapterApprovals.set(approvalId, typeof resolution === "boolean" ? resolution : resolution.approved);
+		assertNoFileSources(this.adapter.name, this.messages);
 		for await (const raw of this.adapter.chatStream({
 			model: this.params.model,
 			messages: this.providerMessages,
@@ -835,10 +850,10 @@ var TextEngine = class {
 			needsApproval: executionResult.needsApproval,
 			needsClientExecution: executionResult.needsClientExecution
 		}));
-		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
+		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0 || executionResult.subagentInterrupts.length > 0) {
 			this.discardDeferredToolCallRunFinishedChunks();
 			if (allResults.length > 0) for (const chunk of this.buildToolResultChunks(allResults, finishEvent)) yield* this.pipeThroughMiddleware(chunk);
-			const emitted = yield* this.emitActionableInterruptBoundary(finishEvent, executionResult.needsApproval, executionResult.needsClientExecution);
+			const emitted = yield* this.emitActionableInterruptBoundary(finishEvent, executionResult.needsApproval, executionResult.needsClientExecution, [], executionResult.subagentInterrupts);
 			this.setToolPhase(emitted ? "wait" : "stop");
 			return emitted ? "wait" : "stop";
 		}
@@ -936,9 +951,9 @@ var TextEngine = class {
 			this.setToolPhase("wait");
 			return;
 		}
-		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
+		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0 || executionResult.subagentInterrupts.length > 0) {
 			if (allResults.length > 0) for (const chunk of afterToolBoundaryChunks) yield* this.pipeThroughMiddleware(chunk);
-			const emitted = yield* this.emitActionableInterruptBoundary(finishEvent, executionResult.needsApproval, executionResult.needsClientExecution);
+			const emitted = yield* this.emitActionableInterruptBoundary(finishEvent, executionResult.needsApproval, executionResult.needsClientExecution, [], executionResult.subagentInterrupts);
 			this.setToolPhase(emitted ? "wait" : "stop");
 			return;
 		}
@@ -1110,7 +1125,7 @@ var TextEngine = class {
 	genericInterruptId() {
 		return this.createId("interrupt");
 	}
-	buildActionableInterrupts(approvals, clientRequests, genericRequests = [], genericInterruptIds = []) {
+	buildActionableInterrupts(approvals, clientRequests, genericRequests = [], genericInterruptIds = [], childInterrupts = []) {
 		const interrupts = [];
 		for (const approval of approvals) {
 			const tool = this.tools.find((candidate) => candidate.name === approval.toolName);
@@ -1191,6 +1206,7 @@ var TextEngine = class {
 				}
 			});
 		}
+		interrupts.push(...childInterrupts);
 		const ids = /* @__PURE__ */ new Set();
 		for (const interrupt of interrupts) {
 			if (ids.has(interrupt.id)) throw new Error(`Duplicate interrupt id in final batch: ${interrupt.id}`);
@@ -1198,13 +1214,13 @@ var TextEngine = class {
 		}
 		return interrupts;
 	}
-	buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests = [], genericInterruptIds) {
+	buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests = [], genericInterruptIds, childInterrupts) {
 		return {
 			...finishEvent,
 			timestamp: Date.now(),
 			outcome: {
 				type: "interrupt",
-				interrupts: this.buildActionableInterrupts(approvals, clientRequests, genericRequests, genericInterruptIds)
+				interrupts: this.buildActionableInterrupts(approvals, clientRequests, genericRequests, genericInterruptIds, childInterrupts)
 			}
 		};
 	}
@@ -1298,10 +1314,10 @@ var TextEngine = class {
 		};
 		yield* this.pipeThroughMiddleware(this.buildInterruptRunErrorChunk(error));
 	}
-	async *emitActionableInterruptBoundary(finishEvent, approvals, clientRequests, genericRequests = []) {
+	async *emitActionableInterruptBoundary(finishEvent, approvals, clientRequests, genericRequests = [], childInterrupts = []) {
 		yield* this.emitSyntheticRunStarted(finishEvent);
 		const genericInterruptIds = genericRequests.map(() => this.genericInterruptId());
-		const terminal = this.completeEphemeralInterruptBindings(this.buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests, genericInterruptIds));
+		const terminal = this.completeEphemeralInterruptBindings(this.buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests, genericInterruptIds, childInterrupts));
 		let terminalOutputs;
 		try {
 			terminalOutputs = [...this.emitPublicChunks(await this.middlewareRunner.runOnChunk(this.middlewareCtx, terminal))];
@@ -1666,6 +1682,7 @@ var TextEngine = class {
 			tools: baseConfig.tools
 		}));
 		this.applyMiddlewareConfig(postOnConfig);
+		assertNoFileSources(this.adapter.name, this.messages);
 		const structuredCallOptions = {
 			chatOptions: {
 				model: this.params.model,
@@ -1907,7 +1924,16 @@ var TextEngine = class {
 			modelOptions: this.params.modelOptions
 		};
 	}
-	async applyEphemeralInterruptResume(config) {
+	/** Resume entries this run answers itself. A subagent tool owns the rest. */
+	ownResume(resume) {
+		const childIds = this.params[CHILD_RESUME_IDS];
+		return childIds ? resume?.filter((entry) => !childIds.has(entry.interruptId)) : resume;
+	}
+	async applyEphemeralInterruptResume(middlewareConfig) {
+		const config = {
+			...middlewareConfig,
+			resume: this.ownResume(middlewareConfig.resume)
+		};
 		if ((config.resume?.length ?? 0) === 0) return;
 		const interruptedRunId = this.parentRunIdOverride;
 		if (!interruptedRunId) throw new InterruptResumeValidationError([{
@@ -2026,7 +2052,7 @@ var TextEngine = class {
 		const pending = [];
 		const ids = /* @__PURE__ */ new Set();
 		const batchIndexes = /* @__PURE__ */ new Set();
-		for (const resumeItem of this.params.resume ?? []) {
+		for (const resumeItem of this.ownResume(this.params.resume) ?? []) {
 			const parsed = readGenericInterruptContinuation(resumeItem.metadata);
 			if (parsed.status === "absent") continue;
 			if (parsed.status === "invalid") return fail(parsed.message);
@@ -2300,6 +2326,7 @@ function chat(options) {
 	validateCapabilities(readRuntimeMiddleware(options.middleware) ?? [], options.adapter);
 	if (options.tools) assertUniqueToolNames(options.tools);
 	const { outputSchema, stream } = options;
+	if (outputSchema && (options.subagents?.agents.length ?? 0) > 0) throw new Error("chat() does not support subagents together with outputSchema. Put outputSchema on a child chat() instead.");
 	if (outputSchema && stream === true) return runStreamingStructuredOutput(toRuntimeTextActivityOptions(options, {
 		outputSchema,
 		stream: true
@@ -2368,8 +2395,8 @@ function runStreamingText(options) {
 	publishDeliverySeams(stream, engineRef);
 	return stream;
 }
-async function* streamTextChunks(options, engineRef) {
-	const { adapter, middleware, context, debug, mcp, ...textOptions } = options;
+async function* runChatEngine(options, engineRef) {
+	const { adapter, middleware, context, debug, mcp, subagents: _subagents, ...textOptions } = options;
 	const model = adapter.model;
 	const logger = resolveDebugOption(debug);
 	const mcpManager = MCPManager.from(mcp);
@@ -2392,6 +2419,303 @@ async function* streamTextChunks(options, engineRef) {
 		await mcpManager.dispose();
 	}
 }
+async function* streamTextChunks(options, engineRef) {
+	const bag = options.subagents;
+	const agents = bag?.agents ?? [];
+	if (bag && agents.length > 0 && bag.router) {
+		yield* runRoutedSubagents(options, engineRef);
+		return;
+	}
+	if (bag && agents.length > 0) {
+		const threadId = options.threadId ?? `thread-${Date.now()}`;
+		const runId = options.runId ?? `run-${Date.now()}`;
+		const messages = options.messages ?? [];
+		const turn = readSubagentTurn(messages, options.resume);
+		const sink = createSubagentSink();
+		const calls = subagentCallMessages(new Set(bag.agents.map((agent) => agent.name)));
+		const synthetic = createSyntheticSubagentTools(bag, {
+			messages: turn?.before ?? messages,
+			messagesFor: calls.messagesFor,
+			threadId,
+			runId,
+			...options.parentRunId !== void 0 && { interruptedRunId: options.parentRunId },
+			...options.abortController && { abortSignal: options.abortController.signal },
+			...turn && { turn },
+			sink
+		});
+		yield* streamWithChildUsage(runChatEngine({
+			...options,
+			threadId,
+			runId,
+			...turn && { [CHILD_RESUME_IDS]: new Set(turn.children.flatMap((child) => child.resume.map((entry) => entry.interruptId))) },
+			tools: [...options.tools ?? [], ...synthetic],
+			middleware: [...options.middleware ?? [], calls.middleware]
+		}, engineRef), sink);
+		return;
+	}
+	yield* runChatEngine(options, engineRef);
+}
+/** Add child usage to the next RUN_FINISHED of the parent. */
+async function* streamWithChildUsage(stream, sink) {
+	for await (const chunk of stream) yield chunk.type === EventType.RUN_FINISHED ? withChildUsage(chunk, sink) : chunk;
+}
+async function* runRoutedSubagents(options, engineRef) {
+	const bag = options.subagents;
+	if (!bag?.router) {
+		yield* runChatEngine(options, engineRef);
+		return;
+	}
+	const threadId = options.threadId ?? `thread-${Date.now()}`;
+	const runId = options.runId ?? `run-${Date.now()}`;
+	const messages = options.messages ?? [];
+	const turn = readSubagentTurn(messages, options.resume);
+	if (!turn && (options.resume?.length ?? 0) > 0) {
+		yield* runChatEngine({
+			...options,
+			threadId,
+			runId,
+			subagents: void 0
+		}, engineRef);
+		return;
+	}
+	const abortSignal = options.abortController?.signal;
+	const turnMessages = turn?.before ?? messages;
+	const subagentPersistence = readRoutedSubagentPersistence(options.middleware);
+	await subagentPersistence?.start({
+		threadId,
+		runId,
+		messages,
+		...options.resume && { resume: options.resume }
+	});
+	try {
+		const plan = savedPlan(turn?.plan, bag.agents, {
+			threadId,
+			interruptedRunId: options.parentRunId ?? runId,
+			interruptIds: options.resume?.map((entry) => entry.interruptId) ?? []
+		}) ?? normalizeRouterPick(await bag.router({
+			messages: turnMessages,
+			agents: bag.agents,
+			...abortSignal && { abortSignal }
+		}), bag.agents);
+		if (abortSignal?.aborted) {
+			const error = /* @__PURE__ */ new Error("Aborted");
+			error.name = "AbortError";
+			await subagentPersistence?.abort({
+				threadId,
+				runId,
+				error
+			});
+			return;
+		}
+		const onlyStep = plan.steps.length === 1 ? plan.steps[0] : void 0;
+		if (onlyStep?.names.length === 1 && onlyStep.names[0] === "main") {
+			if (turn) await subagentPersistence?.finish({
+				threadId,
+				runId
+			});
+			yield* runChatEngine({
+				...options,
+				threadId,
+				runId,
+				subagents: void 0,
+				...turn && { resume: turn.rest }
+			}, engineRef);
+			return;
+		}
+		yield {
+			type: EventType.RUN_STARTED,
+			threadId,
+			runId,
+			timestamp: Date.now()
+		};
+		const earlier = [...turn?.children ?? []];
+		const takeEarlier = (name) => {
+			const index = earlier.findIndex((child) => child.name === name);
+			return index === -1 ? void 0 : earlier.splice(index, 1)[0];
+		};
+		const sink = createSubagentSink();
+		const stepTexts = [];
+		let stepMessages = turnMessages;
+		let failure;
+		for (const step of plan.steps) {
+			const entries = [];
+			const textByName = /* @__PURE__ */ new Map();
+			for (const name of step.names) {
+				const prior = takeEarlier(name);
+				if (prior?.status === "finished") {
+					textByName.set(name, prior.text);
+					continue;
+				}
+				entries.push(prior?.status === "suspended" ? {
+					name,
+					resume: {
+						subagentRunId: prior.subagentRunId,
+						messages: prior.messages,
+						entries: prior.resume,
+						text: prior.text
+					}
+				} : { name });
+			}
+			const stepChunks = [];
+			if (entries.length > 0) for await (const chunk of spawnNamedAgents(entries, {
+				...bag,
+				order: step.order ?? bag.order
+			}, {
+				messages: stepMessages,
+				...abortSignal && { abortSignal },
+				threadId,
+				parentRunId: runId,
+				...options.parentRunId !== void 0 && { interruptedRunId: options.parentRunId }
+			}, sink)) {
+				const tagged = withPlan(chunk, plan);
+				stepChunks.push(tagged);
+				await subagentPersistence?.chunk({
+					threadId,
+					runId,
+					chunk: tagged
+				});
+				yield tagged;
+			}
+			failure = stepChunks.find((chunk) => chunk.type === EventType.SUBAGENT_ERROR);
+			if (failure) break;
+			if (sink.interrupts.length > 0) break;
+			for (const entry of entries) {
+				const text = collectNamedText(stepChunks, [entry.name]);
+				textByName.set(entry.name, [entry.resume?.text, text].filter(Boolean).join("\n\n"));
+			}
+			const text = step.names.map((name) => textByName.get(name)?.trim() ?? "").filter((block) => block !== "").join("\n\n");
+			if (text) {
+				stepTexts.push(text);
+				stepMessages = [...stepMessages, {
+					role: "assistant",
+					content: text
+				}];
+			}
+		}
+		if (abortSignal?.aborted) {
+			const error = /* @__PURE__ */ new Error("Aborted");
+			error.name = "AbortError";
+			await subagentPersistence?.abort({
+				threadId,
+				runId,
+				error
+			});
+			yield withChildUsage({
+				type: EventType.RUN_FINISHED,
+				threadId,
+				runId,
+				outcome: { type: "cancelled" },
+				timestamp: Date.now()
+			}, sink);
+			return;
+		}
+		if (failure) {
+			const message = failure.message || "A subagent failed";
+			await subagentPersistence?.abort({
+				threadId,
+				runId,
+				error: new Error(message)
+			});
+			yield withChildUsage({
+				type: EventType.RUN_ERROR,
+				threadId,
+				runId,
+				message,
+				...failure.code !== void 0 ? { code: failure.code } : {},
+				timestamp: Date.now()
+			}, sink);
+			return;
+		}
+		if (sink.interrupts.length > 0) {
+			const interrupts = rebindInterrupts(sink.interrupts, runId);
+			await subagentPersistence?.suspend?.({
+				threadId,
+				runId,
+				interrupts
+			});
+			yield withChildUsage({
+				type: EventType.RUN_FINISHED,
+				threadId,
+				runId,
+				outcome: {
+					type: "interrupt",
+					interrupts
+				},
+				timestamp: Date.now()
+			}, sink);
+			return;
+		}
+		if ((bag.strategy ?? "exclusive") === "handoff") {
+			const childText = stepTexts.join("\n\n");
+			await subagentPersistence?.finish({
+				threadId,
+				runId
+			});
+			yield* streamWithChildUsage(runChatEngine({
+				...options,
+				threadId,
+				runId,
+				subagents: void 0,
+				...turn && { resume: turn.rest },
+				messages: [...turnMessages, {
+					id: subagentHostMessageId(runId),
+					role: "assistant",
+					content: childText || "Subagent finished.",
+					metadata: { tanstack: { runId } }
+				}]
+			}, engineRef), sink);
+			return;
+		}
+		await subagentPersistence?.finish({
+			threadId,
+			runId
+		});
+		yield withChildUsage({
+			type: EventType.RUN_FINISHED,
+			threadId,
+			runId,
+			timestamp: Date.now()
+		}, sink);
+	} catch (error) {
+		await subagentPersistence?.abort({
+			threadId,
+			runId,
+			error
+		});
+		throw error;
+	}
+}
+/**
+* The plan from a resumed turn, or undefined when it is absent. A plan that
+* names agents this chat does not have is stale: re-routing would strand the
+* suspended child that owns the answers, so fail the resume instead.
+*/
+function savedPlan(plan, agents, run) {
+	if (typeof plan !== "object" || plan === null || !("steps" in plan)) return;
+	try {
+		return normalizeRouterPick(plan, agents);
+	} catch (error) {
+		throw new InterruptResumeValidationError([{
+			scope: "batch",
+			threadId: run.threadId,
+			interruptedRunId: run.interruptedRunId,
+			generation: 0,
+			interruptIds: run.interruptIds,
+			code: "stale",
+			message: `The saved subagent plan does not match the agents of this chat. ${error instanceof Error ? error.message : String(error)}`,
+			source: "server",
+			retryable: false
+		}]);
+	}
+}
+/** Put the router plan on a direct child's SUBAGENT_STARTED metadata. */
+function withPlan(chunk, plan) {
+	if (chunk.type !== EventType.SUBAGENT_STARTED || chunk.parentSubagentRunId !== void 0) return chunk;
+	return withTanstackMetadata(chunk, { [SUBAGENT_PLAN_KEY]: plan });
+}
+function readRoutedSubagentPersistence(middleware) {
+	for (const item of middleware ?? []) if (item.routedSubagentPersistence) return item.routedSubagentPersistence;
+}
 /**
 * Run non-streaming text - collects all content and returns as a string.
 * Runs the full agentic loop (if tools are provided) but returns collected text.