@tanstack/ai 0.46.0 → 0.47.2

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

@@ -11,19 +11,22 @@ import { canonicalInterruptJson, digestInterruptJson } from "../../interrupt-ser
 import "../../interrupts.js";
 import { convertSchemaForStructuredOutput, convertSchemaToJsonSchema, isStandardSchema, parseWithStandardSchema } from "./tools/schema-converter.js";
 import { hashSchemaInput, normalizeApprovalSchema } from "./tools/approval-schema.js";
-import { INTERRUPT_BINDING_METADATA_KEY, InterruptResumeValidationError, readUnopenedInterruptBinding, validateInterruptResumeBatch } from "../../interrupt-resume.js";
+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 { 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 { maxIterations } from "./agent-loop-strategies.js";
-import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage } from "./messages.js";
+import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, safeJsonStringify } from "./messages.js";
 import { MiddlewareRunner } from "./middleware/compose.js";
 import { provideSandboxRuntime } from "./middleware/sandbox-runtime.js";
 import { provideRunDisconnect } from "./middleware/run-disconnect.js";
 import { validateCapabilities } from "./middleware/validate.js";
 import { MCPManager } from "./mcp/manager.js";
+import { provideGenericInterruptDefinitionRegistry } from "./middleware/generic-interrupts.js";
 import "./adapter.js";
 import { devtoolsMiddleware } from "@tanstack/ai-event-client";
 import { undoNullWidening } from "@tanstack/ai-utils";
@@ -51,38 +54,11 @@ function structuralInterruptFailure(error) {
 	};
 }
 function normalizePublicInterruptBinding(value, expectedInterruptId) {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) return;
-	const binding = Object.fromEntries(Object.entries(value));
-	if (binding.interruptId !== expectedInterruptId || binding.v !== void 0 && binding.v !== 1 || typeof binding.interruptedRunId !== "string" || typeof binding.generation !== "number" || !Number.isInteger(binding.generation) || binding.generation < 0 || typeof binding.responseSchemaHash !== "string" || binding.expiresAt !== void 0 && typeof binding.expiresAt !== "string") return;
-	const base = {
-		v: 1,
-		interruptId: binding.interruptId,
-		interruptedRunId: binding.interruptedRunId,
-		generation: binding.generation,
-		responseSchemaHash: binding.responseSchemaHash,
-		...typeof binding.expiresAt === "string" ? { expiresAt: binding.expiresAt } : {}
-	};
-	if (binding.kind === "generic") return {
-		kind: binding.kind,
-		...base
-	};
-	if (typeof binding.toolName !== "string" || typeof binding.toolCallId !== "string") return;
-	if (binding.kind === "client-tool-execution" && typeof binding.outputSchemaHash === "string") return {
-		kind: binding.kind,
-		...base,
-		toolName: binding.toolName,
-		toolCallId: binding.toolCallId,
-		outputSchemaHash: binding.outputSchemaHash
-	};
-	if (binding.kind === "tool-approval" && Object.prototype.hasOwnProperty.call(binding, "originalArgs") && typeof binding.inputSchemaHash === "string" && typeof binding.approvalSchemaHash === "string") return {
-		kind: binding.kind,
-		...base,
-		toolName: binding.toolName,
-		toolCallId: binding.toolCallId,
-		originalArgs: binding.originalArgs,
-		inputSchemaHash: binding.inputSchemaHash,
-		approvalSchemaHash: binding.approvalSchemaHash
-	};
+	return readInterruptBinding({
+		id: expectedInterruptId,
+		reason: "",
+		metadata: { [INTERRUPT_BINDING_METADATA_KEY]: value }
+	});
 }
 /**
 * Create typed options for the chat() function without executing.
@@ -120,12 +96,15 @@ function combineAbortSignals(a, b) {
 }
 var TextEngine = class {
 	adapter;
+	interruptDefinitions;
 	params;
 	systemPrompts;
 	tools;
 	loopStrategy;
 	toolCallManager;
 	lazyToolManager;
+	/** A public interruption terminal must always have this run's start event. */
+	hasPublicRunStarted = false;
 	initialMessageCount;
 	requestId;
 	streamId;
@@ -155,6 +134,8 @@ var TextEngine = class {
 	finishedEvent = null;
 	streamedToolErrorResults = /* @__PURE__ */ new Map();
 	deferredToolCallRunFinishedChunks = [];
+	/** The model terminal is held until afterModel can choose an interrupt. */
+	deferredModelRunFinishedChunks = [];
 	earlyTermination = false;
 	toolPhase = "continue";
 	cyclePhase = "processText";
@@ -164,6 +145,8 @@ var TextEngine = class {
 	resumeClientToolResults = /* @__PURE__ */ new Map();
 	resumeDeniedToolResults = /* @__PURE__ */ new Map();
 	resumeCancelledToolCallIds = /* @__PURE__ */ new Set();
+	resumeGenericInterrupts = /* @__PURE__ */ new Map();
+	resumeGenericInterruptRequests = /* @__PURE__ */ new Map();
 	threadId;
 	runIdOverride;
 	parentRunIdOverride;
@@ -185,6 +168,8 @@ var TextEngine = class {
 	disconnectListeners = [];
 	logger;
 	structuredOutputResult = null;
+	structuredOutputMessageId = null;
+	structuredOutputMessageCreatedAt = null;
 	combinedStartEmitted = false;
 	combinedStructuredMessageId = null;
 	validatedStructuredOutput = void 0;
@@ -195,6 +180,7 @@ var TextEngine = class {
 	constructor(config, logger) {
 		this.logger = logger;
 		this.adapter = config.adapter;
+		this.interruptDefinitions = new Map((config.params.interrupts ?? []).map((definition) => [definition.id, definition]));
 		this.finalStructuredOutput = config.finalStructuredOutput;
 		this.params = config.params;
 		this.systemPrompts = config.params.systemPrompts || [];
@@ -266,6 +252,7 @@ var TextEngine = class {
 			this.disconnectListeners.push(listener);
 			if (this.disconnected) this.runDisconnectListener(listener);
 		} });
+		provideGenericInterruptDefinitionRegistry(this.middlewareCtx, { definitions: this.interruptDefinitions });
 		provideSandboxRuntime(this.middlewareCtx, {
 			logger: this.logger,
 			emit: (event) => {
@@ -324,10 +311,25 @@ var TextEngine = class {
 			const transformedConfig = await this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig);
 			this.applyMiddlewareConfig(transformedConfig);
 			await this.applyEphemeralInterruptResume(transformedConfig);
+			await this.applyDurableGenericInterruptResolution();
 			await this.middlewareRunner.runOnStart(this.middlewareCtx);
+			if (this.earlyTermination) {
+				yield* this.emitSuccessfulEarlyTermination();
+				if (!this.terminalHookCalled) {
+					this.terminalHookCalled = true;
+					await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
+						finishReason: this.lastFinishReason,
+						duration: Date.now() - this.streamStartTime,
+						content: this.accumulatedContent,
+						usage: this.finishedEvent?.usage
+					});
+				}
+				return;
+			}
 			if ((yield* this.checkForPendingToolCalls()) === "wait") return;
 			if (!(!!this.finalStructuredOutput && this.tools.length === 0 && this.finalStructuredOutput.nativeCombined !== true)) do {
-				if (this.earlyTermination || this.isCancelled()) return;
+				if (this.earlyTermination) break;
+				if (this.isCancelled()) return;
 				this.logger.agentLoop(`iteration=${this.middlewareCtx.iteration}`, { iteration: this.middlewareCtx.iteration });
 				await this.beginCycle();
 				if (this.cyclePhase === "processText") {
@@ -336,7 +338,20 @@ var TextEngine = class {
 					const iterConfig = this.buildMiddlewareConfig();
 					const iterTransformedConfig = await this.middlewareRunner.runOnConfig(this.middlewareCtx, iterConfig);
 					this.applyMiddlewareConfig(iterTransformedConfig);
+					if (yield* this.emitBoundaryInterrupts("beforeModel", this.createSyntheticFinishedEvent())) {
+						this.setToolPhase("wait");
+						return;
+					}
 					yield* this.streamModelResponse();
+					if (this.earlyTermination) break;
+					if (yield* this.emitBoundaryInterrupts("afterModel", this.finishedEvent ?? this.createSyntheticFinishedEvent())) {
+						this.setToolPhase("wait");
+						return;
+					}
+					if (this.shouldExecuteToolPhase()) {
+						this.deferredToolCallRunFinishedChunks.push(...this.deferredModelRunFinishedChunks);
+						this.deferredModelRunFinishedChunks = [];
+					} else yield* this.flushDeferredModelRunFinishedChunks();
 				} else yield* this.processToolCalls();
 				this.endCycle();
 			} while (await this.shouldContinue());
@@ -358,7 +373,7 @@ var TextEngine = class {
 						duration: Date.now() - this.streamStartTime
 					});
 				} else {
-					this.addTerminalReasoningMessage();
+					this.addTerminalAssistantMessages();
 					this.terminalHookCalled = true;
 					await this.middlewareRunner.runOnFinish(this.middlewareCtx, {
 						finishReason: this.lastFinishReason,
@@ -513,7 +528,10 @@ var TextEngine = class {
 			if (chunk.type === EventType.CUSTOM && chunk.name === "structured-output.start") {
 				this.combinedStartEmitted = true;
 				const startValue = chunk.value;
-				if (startValue && typeof startValue === "object" && "messageId" in startValue && typeof startValue.messageId === "string") this.combinedStructuredMessageId = startValue.messageId;
+				if (startValue && typeof startValue === "object" && "messageId" in startValue && typeof startValue.messageId === "string") {
+					this.combinedStructuredMessageId = startValue.messageId;
+					this.captureStructuredOutputMessageIdentity(startValue.messageId);
+				}
 			}
 			let outboundChunk = chunk;
 			if (this.finalStructuredOutput?.source === "event" && chunk.type === EventType.CUSTOM && chunk.name === "structured-output.complete") {
@@ -526,6 +544,11 @@ var TextEngine = class {
 					};
 					this.combinedCompleteEmitted = true;
 					const value = chunk.value;
+					const completeMessageId = readCustomEventMessageId(value);
+					if (completeMessageId) {
+						this.combinedStructuredMessageId = completeMessageId;
+						this.captureStructuredOutputMessageIdentity(completeMessageId);
+					}
 					if (object !== parsed.object && value && typeof value === "object") outboundChunk = {
 						...chunk,
 						value: {
@@ -558,10 +581,15 @@ var TextEngine = class {
 			const suppressAgentLifecycle = !!this.finalStructuredOutput && this.finalStructuredOutput.yieldChunks && this.finalStructuredOutput.nativeCombined !== true;
 			for (const outputChunk of outputChunks) {
 				if (suppressAgentLifecycle && (outputChunk.type === EventType.RUN_STARTED || outputChunk.type === EventType.RUN_FINISHED)) continue;
+				if (outputChunk.type === EventType.RUN_FINISHED) {
+					this.deferredModelRunFinishedChunks.push(outputChunk);
+					continue;
+				}
 				if (this.shouldDeferToolCallRunFinished(outputChunk)) {
 					this.deferredToolCallRunFinishedChunks.push(outputChunk);
 					continue;
 				}
+				if (outputChunk.type === EventType.RUN_STARTED) this.hasPublicRunStarted = true;
 				this.logger.output(`type=${outputChunk.type}`, { chunk: outputChunk });
 				yield outputChunk;
 				this.middlewareCtx.chunkIndex++;
@@ -617,6 +645,10 @@ var TextEngine = class {
 			this.streamIdentityCaptured = true;
 		}
 	}
+	captureStructuredOutputMessageIdentity(messageId) {
+		this.structuredOutputMessageId = messageId;
+		this.structuredOutputMessageCreatedAt ??= /* @__PURE__ */ new Date();
+	}
 	handleToolCallStartEvent(chunk) {
 		if (typeof chunk.parentMessageId === "string" && chunk.parentMessageId !== "") this.captureStreamMessageIdentity(chunk.parentMessageId);
 		this.toolCallManager.addToolCallStartEvent(chunk);
@@ -643,8 +675,8 @@ var TextEngine = class {
 	}
 	handleRunErrorEvent(chunk) {
 		this.earlyTermination = true;
-		if (this.finalStructuredOutput && this.finalizationError === null) {
-			const message = chunk.message || chunk.error?.message || "Run failed before structured output completed";
+		if (this.finalizationError === null) {
+			const message = chunk.message || chunk.error?.message || "Run failed";
 			this.finalizationError = {
 				message,
 				...chunk.code !== void 0 ? { code: chunk.code } : chunk.error?.code !== void 0 ? { code: chunk.error.code } : {}
@@ -714,6 +746,11 @@ var TextEngine = class {
 			if (deferredErrorResults.length > 0) for (const chunk of this.buildToolResultChunks(deferredErrorResults, finishEvent, argsMap)) yield* this.pipeThroughMiddleware(chunk);
 			return "continue";
 		}
+		this.middlewareCtx.phase = "beforeTools";
+		if (yield* this.emitBoundaryInterrupts("beforeTools", finishEvent, executablePendingCalls)) {
+			this.setToolPhase("wait");
+			return "wait";
+		}
 		const { approvals, clientToolResults } = this.collectClientState();
 		const generator = executeToolCalls(executablePendingCalls, this.resolveExecutableTools(executablePendingCalls), approvals, clientToolResults, (eventName, data) => this.createCustomEventChunk(eventName, data), {
 			onBeforeToolCall: async (toolCall, tool, args) => {
@@ -802,6 +839,10 @@ var TextEngine = class {
 			return;
 		}
 		this.middlewareCtx.phase = "beforeTools";
+		if (yield* this.emitBoundaryInterrupts("beforeTools", finishEvent, executableToolCalls)) {
+			this.setToolPhase("wait");
+			return;
+		}
 		const { approvals, clientToolResults } = this.collectClientState();
 		const generator = executeToolCalls(executableToolCalls, this.resolveExecutableTools(executableToolCalls), approvals, clientToolResults, (eventName, data) => this.createCustomEventChunk(eventName, data), {
 			onBeforeToolCall: async (toolCall, tool, args) => {
@@ -842,14 +883,22 @@ var TextEngine = class {
 			needsApproval: executionResult.needsApproval,
 			needsClientExecution: executionResult.needsClientExecution
 		});
+		const afterToolBoundaryChunks = this.buildToolResultChunks(allResults, finishEvent);
+		const afterToolRequests = await this.middlewareRunner.runOnInterruptBoundary(this.middlewareCtx);
+		if (afterToolRequests.length > 0) {
+			for (const chunk of afterToolBoundaryChunks) yield* this.pipeThroughMiddleware(chunk);
+			yield* this.emitBoundaryInterrupts("afterTools", finishEvent, toolCalls, afterToolRequests);
+			this.setToolPhase("wait");
+			return;
+		}
 		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
-			if (allResults.length > 0) for (const chunk of this.buildToolResultChunks(allResults, finishEvent)) yield* this.pipeThroughMiddleware(chunk);
+			if (allResults.length > 0) for (const chunk of afterToolBoundaryChunks) yield* this.pipeThroughMiddleware(chunk);
 			const emitted = yield* this.emitActionableInterruptBoundary(finishEvent, executionResult.needsApproval, executionResult.needsClientExecution);
 			this.setToolPhase(emitted ? "wait" : "stop");
 			return;
 		}
 		yield* this.flushDeferredToolCallRunFinishedChunks();
-		const toolResultChunks = this.buildToolResultChunks(allResults, finishEvent);
+		const toolResultChunks = afterToolBoundaryChunks;
 		for (const chunk of toolResultChunks) yield* this.pipeThroughMiddleware(chunk);
 		if (this.lazyToolManager.hasNewlyDiscoveredTools()) {
 			this.tools = this.lazyToolManager.getActiveTools();
@@ -871,6 +920,37 @@ var TextEngine = class {
 		}
 		this.deferredToolCallRunFinishedChunks = [];
 	}
+	*flushDeferredModelRunFinishedChunks() {
+		for (const chunk of this.deferredModelRunFinishedChunks) {
+			this.logger.output(`type=${chunk.type}`, { chunk });
+			yield chunk;
+			this.middlewareCtx.chunkIndex++;
+		}
+		this.deferredModelRunFinishedChunks = [];
+	}
+	async *emitSyntheticRunStarted(finishEvent) {
+		if (this.hasPublicRunStarted) return;
+		yield* this.pipeThroughMiddleware({
+			type: EventType.RUN_STARTED,
+			runId: finishEvent.runId,
+			threadId: finishEvent.threadId,
+			model: finishEvent.model,
+			timestamp: Date.now()
+		});
+	}
+	async *emitSuccessfulEarlyTermination() {
+		this.lastFinishReason = "stop";
+		const finishEvent = {
+			...this.createSyntheticFinishedEvent(),
+			finishReason: "stop"
+		};
+		yield* this.emitSyntheticRunStarted(finishEvent);
+		yield* this.pipeThroughMiddleware({
+			...finishEvent,
+			timestamp: Date.now(),
+			outcome: { type: "success" }
+		});
+	}
 	discardDeferredToolCallRunFinishedChunks() {
 		this.deferredToolCallRunFinishedChunks = [];
 	}
@@ -889,18 +969,61 @@ var TextEngine = class {
 		}];
 		this.middlewareCtx.messages = this.messages;
 	}
-	addTerminalReasoningMessage() {
+	addTerminalAssistantMessages() {
 		this.finalizeCurrentThinkingStep();
-		if (this.accumulatedThinking.length === 0) return;
-		const messages = this.middlewareCtx.messages;
-		if (messages.some((message) => message.role === "assistant" && message.id === this.currentMessageId)) return;
-		this.messages = [...messages, {
-			role: "assistant",
-			content: this.accumulatedContent || null,
-			id: this.currentMessageId ?? void 0,
-			createdAt: this.currentMessageCreatedAt ?? void 0,
-			thinking: this.accumulatedThinking
-		}];
+		const structuredResult = this.structuredOutputResult;
+		const raw = structuredResult ? structuredResult.rawText || safeJsonStringify(structuredResult.data) : "";
+		const structuredOutput = structuredResult ? {
+			type: "structured-output",
+			status: "complete",
+			data: structuredResult.data,
+			partial: structuredResult.data,
+			raw,
+			...structuredResult.reasoning !== void 0 ? { reasoning: structuredResult.reasoning } : {}
+		} : void 0;
+		const nativeCombined = this.finalStructuredOutput?.nativeCombined === true;
+		const eventSourced = this.finalStructuredOutput?.source === "event";
+		const structuredId = this.structuredOutputMessageId ?? this.combinedStructuredMessageId ?? this.currentMessageId ?? this.createId("msg");
+		const splitStructuredMessage = Boolean(structuredOutput) && (!nativeCombined || eventSourced) && this.currentMessageId != null && structuredId !== this.currentMessageId;
+		const messages = [...this.middlewareCtx.messages];
+		const existingStructuredIndex = messages.findIndex((message) => message.role === "assistant" && message.id === structuredId);
+		const currentTurnAlreadyRecorded = messages.some((message) => message.role === "assistant" && message.id === this.currentMessageId);
+		const thinking = this.accumulatedThinking.length > 0 ? this.accumulatedThinking : void 0;
+		const startedLength = messages.length;
+		if (structuredOutput && existingStructuredIndex >= 0) {
+			const existing = messages[existingStructuredIndex];
+			if (existing) messages[existingStructuredIndex] = {
+				...existing,
+				content: raw || existing.content,
+				structuredOutput
+			};
+		} else if (structuredOutput && !splitStructuredMessage) {
+			if (!currentTurnAlreadyRecorded) messages.push({
+				role: "assistant",
+				content: this.accumulatedContent || raw || null,
+				id: structuredId,
+				createdAt: this.currentMessageCreatedAt ?? this.structuredOutputMessageCreatedAt ?? /* @__PURE__ */ new Date(),
+				structuredOutput,
+				...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 (structuredOutput) messages.push({
+				role: "assistant",
+				content: raw || null,
+				id: structuredId,
+				createdAt: this.structuredOutputMessageCreatedAt ?? /* @__PURE__ */ new Date(),
+				structuredOutput
+			});
+		}
+		if (messages.length === startedLength && existingStructuredIndex < 0) return;
+		this.messages = messages;
 		this.middlewareCtx.messages = this.messages;
 	}
 	/**
@@ -943,7 +1066,10 @@ var TextEngine = class {
 			clientToolResults
 		};
 	}
-	buildActionableInterrupts(approvals, clientRequests) {
+	genericInterruptId() {
+		return this.createId("interrupt");
+	}
+	buildActionableInterrupts(approvals, clientRequests, genericRequests = [], genericInterruptIds = []) {
 		const interrupts = [];
 		for (const approval of approvals) {
 			const tool = this.tools.find((candidate) => candidate.name === approval.toolName);
@@ -997,15 +1123,47 @@ var TextEngine = class {
 				}
 			});
 		}
+		for (const [index, request] of genericRequests.entries()) {
+			const batchIndex = interrupts.length;
+			const id = genericInterruptIds[index];
+			if (!id) throw new Error("Generic interrupt id is unavailable.");
+			const preEmission = createInterruptBinding(request, { batchIndex });
+			interrupts.push({
+				id,
+				reason: request.reason,
+				message: request.message,
+				...preEmission.descriptor.responseSchemaCanonicalJson !== void 0 ? { responseSchema: JSON.parse(preEmission.descriptor.responseSchemaCanonicalJson) } : {},
+				...request.expiresAt !== void 0 ? { expiresAt: request.expiresAt } : {},
+				metadata: {
+					[interruptBindingMetadataKey]: {
+						v: 1,
+						kind: "generic",
+						interruptId: id,
+						definitionId: preEmission.descriptor.definitionId,
+						key: preEmission.descriptor.key,
+						batchIndex,
+						...request.expiresAt !== void 0 ? { expiresAt: request.expiresAt } : {},
+						...preEmission.descriptor.payloadSchemaHash ? { payloadSchemaHash: preEmission.descriptor.payloadSchemaHash } : {},
+						...preEmission.descriptor.responseSchemaHash !== void 0 ? { responseSchemaHash: preEmission.descriptor.responseSchemaHash } : {}
+					},
+					...preEmission.payload !== void 0 ? { [INTERRUPT_PAYLOAD_METADATA_KEY]: preEmission.payload } : {}
+				}
+			});
+		}
+		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}`);
+			ids.add(interrupt.id);
+		}
 		return interrupts;
 	}
-	buildInterruptFinishedChunk(finishEvent, approvals, clientRequests) {
+	buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests = [], genericInterruptIds) {
 		return {
 			...finishEvent,
 			timestamp: Date.now(),
 			outcome: {
 				type: "interrupt",
-				interrupts: this.buildActionableInterrupts(approvals, clientRequests)
+				interrupts: this.buildActionableInterrupts(approvals, clientRequests, genericRequests, genericInterruptIds)
 			}
 		};
 	}
@@ -1013,7 +1171,7 @@ var TextEngine = class {
 		const messages = this.messages.map((message, index) => {
 			const content = typeof message.content === "string" ? message.content : message.content === null ? void 0 : JSON.stringify(message.content);
 			const id = message.id || `snapshot_${this.runIdOverride ?? this.requestId}_${index}`;
-			const parts = message.role === "assistant" && message.thinking?.length ? modelMessageToUIMessage(message, id).parts : void 0;
+			const parts = message.role === "assistant" && (message.thinking?.length || message.structuredOutput) ? modelMessageToUIMessage(message, id).parts : void 0;
 			return {
 				id,
 				role: message.role,
@@ -1097,8 +1255,10 @@ var TextEngine = class {
 		};
 		yield* this.pipeThroughMiddleware(this.buildInterruptRunErrorChunk(error));
 	}
-	async *emitActionableInterruptBoundary(finishEvent, approvals, clientRequests) {
-		const terminal = this.completeEphemeralInterruptBindings(this.buildInterruptFinishedChunk(finishEvent, approvals, clientRequests));
+	async *emitActionableInterruptBoundary(finishEvent, approvals, clientRequests, genericRequests = []) {
+		yield* this.emitSyntheticRunStarted(finishEvent);
+		const genericInterruptIds = genericRequests.map(() => this.genericInterruptId());
+		const terminal = this.completeEphemeralInterruptBindings(this.buildInterruptFinishedChunk(finishEvent, approvals, clientRequests, genericRequests, genericInterruptIds));
 		let terminalOutputs;
 		try {
 			terminalOutputs = await this.middlewareRunner.runOnChunk(this.middlewareCtx, terminal);
@@ -1119,6 +1279,59 @@ var TextEngine = class {
 		}
 		return true;
 	}
+	async *emitBoundaryInterrupts(phase, finishEvent, toolCalls = [], requests) {
+		this.middlewareCtx.phase = phase;
+		const boundaryRequests = requests ?? await this.middlewareRunner.runOnInterruptBoundary(this.middlewareCtx);
+		if (boundaryRequests.length === 0) return false;
+		for (const request of boundaryRequests) if (this.interruptDefinitions.get(request.definition.id) !== request.definition) throw new Error(`Generic interrupt definition ${request.definition.id} is not registered on this chat.`);
+		if (phase === "afterModel") {
+			if (this.toolCallManager.hasToolCalls()) this.addAssistantToolCallMessage(this.toolCallManager.getToolCalls());
+			else this.addAssistantTextMessageForInterrupt();
+		}
+		const actionable = this.getBoundaryActionableToolRequests(toolCalls);
+		yield* this.emitActionableInterruptBoundary(finishEvent, actionable.approvals, actionable.clientRequests, boundaryRequests);
+		return true;
+	}
+	addAssistantTextMessageForInterrupt() {
+		if (this.accumulatedContent.length === 0) return;
+		this.messages = [...this.messages, {
+			role: "assistant",
+			content: this.accumulatedContent
+		}];
+		this.middlewareCtx.messages = this.messages;
+	}
+	getBoundaryActionableToolRequests(toolCalls) {
+		const { approvals, clientToolResults } = this.collectClientState();
+		const approvalRequests = [];
+		const clientRequests = [];
+		for (const toolCall of toolCalls) {
+			const tool = this.resolveExecutableTools([toolCall]).find((candidate) => candidate.name === toolCall.function.name);
+			if (!tool) continue;
+			let input = {};
+			try {
+				const parsed = JSON.parse(toolCall.function.arguments.trim() || "{}");
+				input = parsed && typeof parsed === "object" ? parsed : {};
+			} catch {
+				input = {};
+			}
+			const approvalId = `approval_${toolCall.id}`;
+			if (tool.needsApproval && !approvals.has(approvalId)) approvalRequests.push({
+				toolCallId: toolCall.id,
+				toolName: toolCall.function.name,
+				input,
+				approvalId
+			});
+			else if (!tool.execute && !clientToolResults.has(toolCall.id) && !this.resumeCancelledToolCallIds.has(toolCall.id)) clientRequests.push({
+				toolCallId: toolCall.id,
+				toolName: toolCall.function.name,
+				input
+			});
+		}
+		return {
+			approvals: approvalRequests,
+			clientRequests
+		};
+	}
 	completeEphemeralInterruptBindings(chunk) {
 		if (chunk.type !== EventType.RUN_FINISHED || chunk.outcome?.type !== "interrupt") return chunk;
 		const interruptedRunId = this.runIdOverride ?? this.requestId;
@@ -1265,7 +1478,7 @@ var TextEngine = class {
 	createSyntheticFinishedEvent() {
 		return {
 			type: "RUN_FINISHED",
-			runId: this.createId("pending"),
+			runId: this.runIdOverride ?? this.requestId,
 			threadId: this.threadId,
 			model: this.params.model,
 			timestamp: Date.now(),
@@ -1451,6 +1664,7 @@ var TextEngine = class {
 		const buildSynthesizedStart = (timestamp = Date.now()) => {
 			const idForStart = structuredMessageId ?? generateMessageId();
 			structuredMessageId = idForStart;
+			this.captureStructuredOutputMessageIdentity(idForStart);
 			return {
 				type: EventType.CUSTOM,
 				name: "structured-output.start",
@@ -1468,7 +1682,10 @@ var TextEngine = class {
 			if (!startEmitted && chunk.type === EventType.CUSTOM && chunk.name === "structured-output.start") startEmitted = true;
 			if (!structuredMessageId) {
 				const extracted = extractMessageId(chunk);
-				if (extracted) structuredMessageId = extracted;
+				if (extracted) {
+					structuredMessageId = extracted;
+					this.captureStructuredOutputMessageIdentity(extracted);
+				}
 			}
 			if (this.finalStructuredOutput.yieldChunks) {
 				if (!startEmitted && (chunk.type === EventType.TEXT_MESSAGE_START || chunk.type === EventType.TEXT_MESSAGE_CONTENT || chunk.type === EventType.TEXT_MESSAGE_END)) {
@@ -1495,7 +1712,8 @@ var TextEngine = class {
 					const object = this.finalStructuredOutput.normalize ? this.finalStructuredOutput.normalize(parsed.object) : parsed.object;
 					this.structuredOutputResult = {
 						data: object,
-						rawText: parsed.raw
+						rawText: parsed.raw,
+						...parsed.reasoning !== void 0 ? { reasoning: parsed.reasoning } : {}
 					};
 					const value = chunk.value;
 					if (object !== parsed.object && value && typeof value === "object") outboundChunk = {
@@ -1752,6 +1970,7 @@ var TextEngine = class {
 				input: toolInputs.get(toolCall.id) ?? {}
 			});
 		}
+		const genericPending = this.getGenericContinuationPending(interruptedRunId);
 		const pending = this.buildActionableInterrupts(approvalRequests, clientRequests).flatMap((descriptor) => {
 			const unopened = readUnopenedInterruptBinding(descriptor);
 			return unopened ? [{
@@ -1764,6 +1983,7 @@ var TextEngine = class {
 				}
 			}] : [];
 		});
+		pending.push(...genericPending);
 		const validated = await validateInterruptResumeBatch({
 			threadId: this.threadId,
 			interruptedRunId,
@@ -1779,12 +1999,124 @@ var TextEngine = class {
 			...validated.resumeToolState,
 			approvals
 		});
+		const genericResolutions = validated.resumeToolState.genericInterrupts;
+		if (genericPending.length > 0 && genericResolutions) {
+			const resolutions = genericPending.sort((left, right) => {
+				return (left.binding.kind === "generic" ? left.binding.batchIndex ?? 0 : 0) - (right.binding.kind === "generic" ? right.binding.batchIndex ?? 0 : 0);
+			}).flatMap((record) => {
+				const resolution = genericResolutions.get(record.interruptId);
+				if (!resolution || !record.genericRequest) return [];
+				return [resolution.status === "resolved" ? {
+					request: record.genericRequest,
+					status: "resolved",
+					response: resolution.payload
+				} : {
+					request: record.genericRequest,
+					status: "cancelled"
+				}];
+			});
+			const policy = await this.middlewareRunner.runOnInterruptResolution(this.middlewareCtx, {
+				for: (definition) => resolutions.filter((resolution) => resolution.request.definition === definition),
+				all: (...definitions) => definitions.length === 0 ? resolutions : resolutions.filter((resolution) => definitions.includes(resolution.request.definition))
+			});
+			if (policy.toolResume === "stop") this.earlyTermination = true;
+			else if (policy.toolResume === "cancel") for (const request of pendingToolCalls) this.resumeCancelledToolCallIds.add(request.id);
+		}
+	}
+	getGenericContinuationPending(interruptedRunId) {
+		const fail = (message) => {
+			throw new InterruptResumeValidationError([{
+				scope: "batch",
+				threadId: this.threadId,
+				interruptedRunId,
+				generation: 0,
+				interruptIds: [],
+				code: "stale",
+				message,
+				source: "server",
+				retryable: false
+			}]);
+		};
+		const pending = [];
+		const ids = /* @__PURE__ */ new Set();
+		const batchIndexes = /* @__PURE__ */ new Set();
+		for (const resumeItem of this.params.resume ?? []) {
+			const parsed = readGenericInterruptContinuation(resumeItem.metadata);
+			if (parsed.status === "absent") continue;
+			if (parsed.status === "invalid") return fail(parsed.message);
+			const entry = parsed.value;
+			const id = resumeItem.interruptId;
+			const definition = this.interruptDefinitions.get(entry.definitionId);
+			if (!definition) return fail(`Generic interrupt definition ${entry.definitionId} is unavailable.`);
+			if (ids.has(id) || batchIndexes.has(entry.batchIndex)) return fail("Generic interrupt continuation contains duplicate entries.");
+			ids.add(id);
+			batchIndexes.add(entry.batchIndex);
+			let request;
+			try {
+				request = rehydrateInterruptRequest(definition, {
+					key: entry.key,
+					reason: entry.reason,
+					message: entry.message,
+					...typeof entry.expiresAt === "string" ? { expiresAt: entry.expiresAt } : {},
+					...Object.prototype.hasOwnProperty.call(entry, "payload") ? { payload: entry.payload } : {}
+				});
+			} catch (error) {
+				return fail(`Generic interrupt continuation ${id} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const emitted = createInterruptBinding(request, { batchIndex: entry.batchIndex });
+			if (entry.responseSchemaHash !== emitted.descriptor.responseSchemaHash || entry.payloadSchemaHash !== emitted.descriptor.payloadSchemaHash) return fail(`Generic interrupt continuation ${id} does not match its definition.`);
+			pending.push({
+				interruptId: id,
+				payload: {
+					id,
+					...emitted.descriptor.responseSchemaCanonicalJson !== void 0 ? { responseSchema: JSON.parse(emitted.descriptor.responseSchemaCanonicalJson) } : {}
+				},
+				binding: {
+					v: 1,
+					kind: "generic",
+					interruptId: id,
+					interruptedRunId,
+					generation: 0,
+					definitionId: entry.definitionId,
+					key: entry.key,
+					batchIndex: entry.batchIndex,
+					...typeof entry.expiresAt === "string" ? { expiresAt: entry.expiresAt } : {},
+					...emitted.descriptor.payloadSchemaHash ? { payloadSchemaHash: emitted.descriptor.payloadSchemaHash } : {},
+					...entry.responseSchemaHash !== void 0 ? { responseSchemaHash: entry.responseSchemaHash } : {}
+				},
+				genericRequest: request
+			});
+		}
+		return pending;
 	}
 	applyResumeToolState(state) {
 		if (state?.approvals) for (const [approvalId, resolution] of state.approvals) this.resumeApprovals.set(approvalId, resolution);
 		if (state?.clientToolResults) for (const [toolCallId, result] of state.clientToolResults) this.resumeClientToolResults.set(toolCallId, result);
 		if (state?.deniedToolResults) for (const [toolCallId, result] of state.deniedToolResults) this.resumeDeniedToolResults.set(toolCallId, result);
 		if (state?.cancelledToolCallIds) for (const toolCallId of state.cancelledToolCallIds) this.resumeCancelledToolCallIds.add(toolCallId);
+		if (state?.genericInterrupts) for (const [interruptId, resolution] of state.genericInterrupts) this.resumeGenericInterrupts.set(interruptId, resolution);
+		if (state?.genericInterruptRequests) for (const [interruptId, request] of state.genericInterruptRequests) this.resumeGenericInterruptRequests.set(interruptId, request);
+	}
+	async applyDurableGenericInterruptResolution() {
+		if (this.resumeGenericInterruptRequests.size === 0) return;
+		const resolutions = [...this.resumeGenericInterruptRequests.entries()].flatMap(([interruptId, request]) => {
+			const resolution = this.resumeGenericInterrupts.get(interruptId);
+			if (!resolution) return [];
+			return [resolution.status === "resolved" ? {
+				request,
+				status: "resolved",
+				response: resolution.payload
+			} : {
+				request,
+				status: "cancelled"
+			}];
+		});
+		const policy = await this.middlewareRunner.runOnInterruptResolution(this.middlewareCtx, {
+			for: (definition) => resolutions.filter((resolution) => resolution.request.definition === definition),
+			all: (...definitions) => definitions.length === 0 ? resolutions : resolutions.filter((resolution) => definitions.includes(resolution.request.definition))
+		});
+		if (policy.toolResume === "stop") this.earlyTermination = true;
+		else if (policy.toolResume === "cancel") for (const toolCall of this.getPendingToolCallsFromMessages()) this.resumeCancelledToolCallIds.add(toolCall.id);
 	}
 	applyMiddlewareConfig(config) {
 		this.applyResumeToolState(config.resumeToolState);
@@ -1813,6 +2145,7 @@ var TextEngine = class {
 	async *pipeThroughMiddleware(chunk) {
 		const outputChunks = await this.middlewareRunner.runOnChunk(this.middlewareCtx, chunk);
 		for (const outputChunk of outputChunks) {
+			if (outputChunk.type === EventType.RUN_STARTED) this.hasPublicRunStarted = true;
 			yield outputChunk;
 			this.middlewareCtx.chunkIndex++;
 		}
@@ -1914,28 +2247,47 @@ var TextEngine = class {
 * ```
 */
 function chat(options) {
-	validateCapabilities(options.middleware ?? [], options.adapter);
+	validateInterruptDefinitions(options.interrupts);
+	validateCapabilities(readRuntimeMiddleware(options.middleware) ?? [], options.adapter);
 	if (options.tools) assertUniqueToolNames(options.tools);
 	const { outputSchema, stream } = options;
-	if (outputSchema && stream === true) return runStreamingStructuredOutput({
-		...options,
+	if (outputSchema && stream === true) return runStreamingStructuredOutput(toRuntimeTextActivityOptions(options, {
 		outputSchema,
-		stream
-	});
-	if (outputSchema) return runAgenticStructuredOutput({
-		...options,
-		outputSchema
-	});
-	if (stream === false) return runNonStreamingText({
-		...options,
+		stream: true
+	}));
+	if (outputSchema) return runAgenticStructuredOutput(toRuntimeTextActivityOptions(options, {
+		outputSchema,
+		stream: false
+	}));
+	if (stream === false) return runNonStreamingText(toRuntimeTextActivityOptions(options, {
 		outputSchema: void 0,
-		stream
-	});
-	return runStreamingText({
-		...options,
+		stream: false
+	}));
+	return runStreamingText(toRuntimeTextActivityOptions(options, {
 		outputSchema: void 0,
-		stream
-	});
+		stream: true
+	}));
+}
+function readRuntimeMiddleware(middleware) {
+	if (middleware === void 0) return void 0;
+	if (!Array.isArray(middleware)) throw new TypeError("Chat middleware must be an array.");
+	return middleware;
+}
+function toRuntimeTextActivityOptions(options, overrides) {
+	const { middleware, ...rest } = options;
+	return {
+		...rest,
+		...overrides,
+		...middleware === void 0 ? {} : { middleware: readRuntimeMiddleware(middleware) }
+	};
+}
+function validateInterruptDefinitions(definitions) {
+	if (!definitions) return;
+	const seen = /* @__PURE__ */ new Set();
+	for (const definition of definitions) {
+		if (seen.has(definition.id)) throw new Error(`Duplicate interrupt definition id: ${definition.id}`);
+		seen.add(definition.id);
+	}
 }
 /**
 * Publish both delivery-side seams for `stream`.
@@ -1996,7 +2348,10 @@ async function* streamTextChunks(options, engineRef) {
 * Runs the full agentic loop (if tools are provided) but returns collected text.
 */
 function runNonStreamingText(options) {
-	const stream = runStreamingText(options);
+	const stream = runStreamingText({
+		...options,
+		stream: true
+	});
 	return streamToText(stream);
 }
 /**
@@ -2064,6 +2419,12 @@ async function runAgenticStructuredOutput(options) {
 * Uses an `unknown`-input runtime check rather than `as` casts so the engine
 * stays cast-free in its hot path.
 */
+function readCustomEventMessageId(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	if (!("messageId" in value)) return void 0;
+	const messageId = value.messageId;
+	return typeof messageId === "string" && messageId !== "" ? messageId : void 0;
+}
 function readStructuredOutputCompleteValue(value) {
 	if (typeof value !== "object" || value === null) return null;
 	if (!("object" in value) || !("raw" in value)) return null;