@tanstack/ai 0.58.0 → 0.61.0

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

@@ -17,14 +17,18 @@ import { hashSchemaInput, normalizeApprovalSchema } from "./tools/approval-schem
 import { INTERRUPT_BINDING_METADATA_KEY, InterruptResumeValidationError, readInterruptBinding, readUnopenedInterruptBinding, validateInterruptResumeBatch } from "../../interrupt-resume.js";
 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 { isProviderExecutedToolCall } from "../../utilities/provider-executed.js";
+import { normalizeToolResult, parseToolOutput, toolResultErrorText } from "../../utilities/tool-result.js";
+import { subagentHostMessageId } from "../../utilities/subagent-wire.js";
 import { appendUiResourceToModelMessages, convertMessagesToModelMessages, generateMessageId, modelMessagesToUIMessages, safeJsonStringify, uiResourcePartFromCustomValue } from "./messages.js";
 import { uiMessagesToWire } from "../../utilities/ag-ui-wire.js";
 import { restorePublicUsage } from "../../utilities/restore-inbound-chunk.js";
+import { assertMessagesFileSourceSupport } from "../../utilities/content-source.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 +49,8 @@ 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 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;
@@ -132,6 +138,15 @@ var TextEngine = class {
 	streamIdentityCaptured = false;
 	accumulatedContent = "";
 	accumulatedThinking = [];
+	/**
+	* Arrival order of this iteration's thinking steps, text and tool calls.
+	* A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a
+	* provider turn that thinks between provider-executed tools would otherwise
+	* be recorded as "all thinking, then text, then tools" and the provider
+	* rejects the replay (signed thinking must keep its position). `null` once
+	* the order could no longer be tracked (callers fall back to one message).
+	*/
+	turnParts = [];
 	currentThinkingContent = "";
 	currentThinkingSignature = "";
 	eventOptions;
@@ -155,6 +170,7 @@ var TextEngine = class {
 	threadId;
 	runIdOverride;
 	parentRunIdOverride;
+	subagentRunIdOverride;
 	middlewareRunner;
 	middlewareCtx;
 	sandboxFileQueue = [];
@@ -210,6 +226,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 +236,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",
@@ -487,6 +505,7 @@ var TextEngine = class {
 		this.streamIdentityCaptured = false;
 		this.accumulatedContent = "";
 		this.accumulatedThinking = [];
+		this.turnParts = [];
 		this.currentThinkingContent = "";
 		this.currentThinkingSignature = "";
 		this.finishedEvent = null;
@@ -517,6 +536,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);
+		assertMessagesFileSourceSupport(this.adapter, this.messages);
 		for await (const raw of this.adapter.chatStream({
 			model: this.params.model,
 			messages: this.providerMessages,
@@ -651,9 +671,23 @@ var TextEngine = class {
 	}
 	handleTextMessageContentEvent(chunk) {
 		const extra = chunk;
+		const before = this.accumulatedContent;
 		if (typeof extra.content === "string" && extra.content !== "") this.accumulatedContent = extra.content;
 		else this.accumulatedContent += chunk.delta;
 		this.middlewareCtx.accumulatedContent = this.accumulatedContent;
+		if (!this.turnParts) return;
+		if (!this.accumulatedContent.startsWith(before)) {
+			this.turnParts = null;
+			return;
+		}
+		const delta = this.accumulatedContent.slice(before.length);
+		if (delta === "") return;
+		const last = this.turnParts[this.turnParts.length - 1];
+		if (last && last.type === "text") last.content += delta;
+		else this.turnParts.push({
+			type: "text",
+			content: delta
+		});
 	}
 	captureStreamMessageIdentity(messageId) {
 		this.currentMessageId = messageId;
@@ -670,6 +704,11 @@ var TextEngine = class {
 	handleToolCallStartEvent(chunk) {
 		if (typeof chunk.parentMessageId === "string" && chunk.parentMessageId !== "") this.captureStreamMessageIdentity(chunk.parentMessageId);
 		this.toolCallManager.addToolCallStartEvent(chunk);
+		if (this.turnParts && !this.turnParts.some((part) => part.type === "call" && part.id === chunk.toolCallId)) this.turnParts.push({
+			type: "call",
+			id: chunk.toolCallId,
+			providerExecuted: isProviderExecutedToolCall({ metadata: chunk.metadata })
+		});
 		const metadata = chunk.metadata;
 		const thoughtSignature = metadata != null && typeof metadata === "object" && "thoughtSignature" in metadata && typeof metadata.thoughtSignature === "string" && metadata.thoughtSignature !== "" ? metadata.thoughtSignature : void 0;
 		if (thoughtSignature === void 0) return;
@@ -731,17 +770,42 @@ var TextEngine = class {
 				content: this.currentThinkingContent,
 				...this.currentThinkingSignature && { signature: this.currentThinkingSignature }
 			});
+			if (this.turnParts) {
+				const placeholder = [...this.turnParts].reverse().find((part) => part.type === "thinking" && part.index === -1);
+				const index = this.accumulatedThinking.length - 1;
+				if (placeholder) placeholder.index = index;
+				else this.turnParts.push({
+					type: "thinking",
+					index
+				});
+			}
 			this.currentThinkingContent = "";
 			this.currentThinkingSignature = "";
 		}
 	}
+	/**
+	* Record where the current thinking step sits among this turn's parts. A
+	* step is finalized only when the next step starts (or the turn ends), by
+	* which time later tool calls have already arrived, so the position has to
+	* be noted when the step's first content or signature shows up.
+	*/
+	noteThinkingStepPosition() {
+		if (this.turnParts && this.currentThinkingContent === "" && this.currentThinkingSignature === "") this.turnParts.push({
+			type: "thinking",
+			index: -1
+		});
+	}
 	handleStepStartedEvent() {
 		this.finalizeCurrentThinkingStep();
 	}
 	handleStepFinishedEvent(chunk) {
-		if (typeof chunk.signature === "string" && chunk.signature !== "") this.currentThinkingSignature = chunk.signature;
+		if (typeof chunk.signature === "string" && chunk.signature !== "") {
+			this.noteThinkingStepPosition();
+			this.currentThinkingSignature = chunk.signature;
+		}
 	}
 	handleReasoningMessageContentEvent(chunk) {
+		this.noteThinkingStepPosition();
 		this.currentThinkingContent += chunk.delta;
 	}
 	handleReasoningEncryptedValueEvent(chunk) {
@@ -753,6 +817,7 @@ var TextEngine = class {
 			};
 			return;
 		}
+		this.noteThinkingStepPosition();
 		this.currentThinkingSignature = chunk.encryptedValue;
 	}
 	/**
@@ -835,10 +900,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 +1001,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;
 		}
@@ -998,16 +1063,67 @@ var TextEngine = class {
 	shouldExecuteToolPhase() {
 		return this.lastFinishReason === "tool_calls" && this.tools.length > 0 && this.toolCallManager.hasToolCalls();
 	}
+	/**
+	* Split this iteration into assistant ModelMessages that keep the provider's
+	* block order: a new segment starts at every thinking step that follows a
+	* provider-executed tool call (the rule buildAssistantMessages applies to
+	* UIMessages). Segments after the first get `${id}-segment-${n}` ids.
+	* Returns null when no split is needed or the order could not be tracked,
+	* so callers fall back to the single-message shape.
+	*/
+	buildOrderedAssistantSegments(toolCalls, id, createdAt) {
+		const parts = this.turnParts;
+		if (!parts) return null;
+		const providerCallIds = new Set(parts.flatMap((part) => part.type === "call" && part.providerExecuted ? [part.id] : []));
+		let current = {
+			thinking: [],
+			text: "",
+			callIds: []
+		};
+		const segments = [current];
+		let split = false;
+		for (const part of parts) if (part.type === "thinking") {
+			const thinking = this.accumulatedThinking[part.index];
+			if (!thinking) return null;
+			if (current.callIds.some((callId) => providerCallIds.has(callId))) {
+				current = {
+					thinking: [thinking],
+					text: "",
+					callIds: []
+				};
+				segments.push(current);
+				split = true;
+			} else current.thinking.push(thinking);
+		} else if (part.type === "text") current.text += part.content;
+		else current.callIds.push(part.id);
+		if (!split) return null;
+		if (segments.map((segment) => segment.text).join("") !== this.accumulatedContent) return null;
+		if (segments.reduce((n, segment) => n + segment.thinking.length, 0) !== this.accumulatedThinking.length) return null;
+		const placed = new Set(segments.flatMap((segment) => segment.callIds));
+		for (const toolCall of toolCalls) if (!placed.has(toolCall.id)) current.callIds.push(toolCall.id);
+		return segments.map((segment, index) => {
+			const segmentCalls = toolCalls.filter((toolCall) => segment.callIds.includes(toolCall.id));
+			return {
+				role: "assistant",
+				content: segment.text || null,
+				...segmentCalls.length > 0 && { toolCalls: segmentCalls },
+				id: id === void 0 ? void 0 : index === 0 ? id : `${id}-segment-${index}`,
+				createdAt,
+				...segment.thinking.length > 0 && { thinking: segment.thinking }
+			};
+		});
+	}
 	addAssistantToolCallMessage(toolCalls) {
 		this.finalizeCurrentThinkingStep();
-		this.messages = [...this.messages, {
+		const segments = this.buildOrderedAssistantSegments(toolCalls, this.currentMessageId ?? void 0, this.currentMessageCreatedAt ?? void 0);
+		this.messages = [...this.messages, ...segments ?? [{
 			role: "assistant",
 			content: this.accumulatedContent || null,
 			toolCalls,
 			id: this.currentMessageId ?? void 0,
 			createdAt: this.currentMessageCreatedAt ?? void 0,
 			...this.accumulatedThinking.length > 0 && { thinking: this.accumulatedThinking }
-		}];
+		}]];
 		this.middlewareCtx.messages = this.messages;
 	}
 	addTerminalAssistantMessages() {
@@ -1048,13 +1164,17 @@ var TextEngine = class {
 				...thinking ? { thinking } : {}
 			});
 		} else {
-			if (!currentTurnAlreadyRecorded && (this.accumulatedContent !== "" || thinking)) messages.push({
-				role: "assistant",
-				content: this.accumulatedContent || null,
-				id: this.currentMessageId ?? this.createId("msg"),
-				createdAt: this.currentMessageCreatedAt ?? /* @__PURE__ */ new Date(),
-				...thinking ? { thinking } : {}
-			});
+			if (!currentTurnAlreadyRecorded && (this.accumulatedContent !== "" || thinking)) {
+				const id = this.currentMessageId ?? this.createId("msg");
+				const createdAt = this.currentMessageCreatedAt ?? /* @__PURE__ */ new Date();
+				messages.push(...this.buildOrderedAssistantSegments(this.toolCallManager.getToolCalls(), id, createdAt) ?? [{
+					role: "assistant",
+					content: this.accumulatedContent || null,
+					id,
+					createdAt,
+					...thinking ? { thinking } : {}
+				}]);
+			}
 			if (structuredOutput) messages.push({
 				role: "assistant",
 				content: raw || null,
@@ -1110,7 +1230,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 +1311,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 +1319,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 +1419,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))];
@@ -1344,6 +1465,7 @@ var TextEngine = class {
 		const approvalRequests = [];
 		const clientRequests = [];
 		for (const toolCall of toolCalls) {
+			if (isProviderExecutedToolCall(toolCall)) continue;
 			const tool = this.resolveExecutableTools([toolCall]).find((candidate) => candidate.name === toolCall.function.name);
 			if (!tool) continue;
 			let input = {};
@@ -1444,7 +1566,8 @@ var TextEngine = class {
 			const newToolMessage = {
 				role: "tool",
 				content,
-				toolCallId: result.toolCallId
+				toolCallId: result.toolCallId,
+				...result.state === "output-error" && { error: toolResultErrorText(parseToolOutput(wireContent)) }
 			};
 			if (placeholderIdx >= 0) this.messages = [
 				...this.messages.slice(0, placeholderIdx),
@@ -1666,6 +1789,7 @@ var TextEngine = class {
 			tools: baseConfig.tools
 		}));
 		this.applyMiddlewareConfig(postOnConfig);
+		assertMessagesFileSourceSupport(this.adapter, this.messages);
 		const structuredCallOptions = {
 			chatOptions: {
 				model: this.params.model,
@@ -1815,7 +1939,12 @@ var TextEngine = class {
 	async *harvestCombinedStructuredOutput() {
 		if (!this.finalStructuredOutput) throw new Error("harvestCombinedStructuredOutput called without finalStructuredOutput config");
 		const yieldChunks = this.finalStructuredOutput.yieldChunks;
-		if ((this.finalStructuredOutput.source ?? "text") === "event") {
+		const source = this.finalStructuredOutput.source ?? "text";
+		if (this.lastFinishReason === "length") this.finalizationError = {
+			message: "The response was cut off because the maximum token limit was reached (finish_reason=length); raise the output token limit.",
+			code: "max_tokens"
+		};
+		else if (source === "event") {
 			if (!this.structuredOutputResult) this.finalizationError = {
 				message: "missing structured result",
 				code: "structured-output-missing-result"
@@ -1907,7 +2036,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 +2164,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 +2438,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 +2507,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 +2531,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.