@tanstack/ai-client 0.23.3 → 0.25.1

package/dist/esm/index.d.ts

@@ -8,7 +8,7 @@ export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge.j
 export { RealtimeClient } from './realtime-client.js';
 export { GenerationClient } from './generation-client.js';
 export { VideoGenerationClient } from './video-generation-client.js';
-export type { UIMessage, MessagePart, TextPart, ToolCallPart, ToolResultPart, ThinkingPart, StructuredOutputPart, ChatClientPersistence, ChatPersistedState, ChatPersistenceOption, ChatStorageAdapter, ChatClientOptions, ChatPendingInterrupt, BoundInterruptBase, BoundInterrupts, ChatInterrupt, ChatInterruptState, GenericAGUIInterrupt, UnboundInterrupt, InterruptItemStatus, ToolApprovalInterrupt, ClientContextOptionFromTools, ChatResumeState, ChatRequestBody, InferChatMessages, InferredClientContext, ChatClientState, ConnectionStatus, ChatFetcher, ChatFetcherInput, ChatFetcherOptions, ChatTransport, DistributedOmit, MultimodalContent, QueuedMessage, WhenBusy, QueueBusyReason, QueueConfig, QueueStrategy, QueueOption, SendMessageOptions, } from './types.js';
+export type { UIMessage, MessagePart, TextPart, ToolCallPart, ToolResultPart, ThinkingPart, StructuredOutputPart, ChatClientPersistence, ChatPersistedState, ChatPersistenceOption, ChatPersistenceOptions, ChatStorageAdapter, ChatClientOptions, ChatPendingInterrupt, BoundInterruptBase, BoundInterrupts, ChatInterrupt, ChatInterruptState, GenericAGUIInterrupt, GenericInterrupt, RegisteredGenericInterrupt, ResolvableChatInterrupt, UnboundInterrupt, InterruptItemStatus, ToolApprovalInterrupt, ClientContextOptionFromTools, ChatResumeState, ChatRequestBody, InferChatMessages, InferredClientContext, ChatClientState, ConnectionStatus, ChatFetcher, ChatFetcherInput, ChatFetcherOptions, ChatTransport, DistributedOmit, MultimodalContent, QueuedMessage, WhenBusy, QueueBusyReason, QueueConfig, QueueStrategy, QueueOption, SendMessageOptions, } from './types.js';
 export type { InferGenerationOutput, InferGenerationOutputFromReturn, GenerationClientState, GenerationPersistenceOptions, GenerationClientOptions, GenerationFetcher, GenerationFetcherOptions, GenerationTransport, VideoGenerationClientOptions, VideoStatusInfo, VideoGenerateResult, ImageGenerateInput, AudioGenerateInput, SpeechGenerateInput, TranscriptionGenerateInput, SummarizeGenerateInput, VideoGenerateInput, GenerationRestoredResult, } from './generation-types.js';
 export { GENERATION_EVENTS } from './generation-types.js';
 export { reconstructImageResult, reconstructAudioResult, reconstructSpeechResult, reconstructTranscriptionResult, reconstructSummarizeResult, } from './generation-reconstruct.js';
@@ -20,6 +20,6 @@ export { createAIDevtoolsGenerationPreview, type AIDevtoolsClientMetadata, type
 export type { ExtractToolNames, ExtractToolInput, ExtractToolOutput, } from './tool-types.js';
 export type { AnyClientTool, Interrupt, PersistedArtifactActivity, PersistedArtifactRef, PersistedArtifactRole, RunAgentResumeItem, RunFinishedOutcome, } from '@tanstack/ai/client';
 export type { RealtimeAdapter, RealtimeConnection, RealtimeClientOptions, RealtimeClientState, RealtimeStateChangeCallback, } from './realtime-types.js';
-export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, StreamTruncatedError, DurableStreamIncompleteError, StreamReconnectLimitError, type ConnectConnectionAdapter, type ConnectionAdapter, type GenerationHydrationResult, type FetchConnectionOptions, type ReconnectOptions, type ResumableConnectConnectionAdapter, type RunAgentInputContext, type StreamConnectionHandlers, type SubscribeConnectionAdapter, type XhrConnectionOptions, } from './connection-adapters.js';
+export { fetchServerSentEvents, fetchHttpStream, xhrServerSentEvents, xhrHttpStream, stream, rpcStream, webSocket, StreamTruncatedError, DurableStreamIncompleteError, StreamReconnectLimitError, type ConnectConnectionAdapter, type ConnectionAdapter, type GenerationHydrationResult, type FetchConnectionOptions, type ReconnectOptions, type ResumableConnectConnectionAdapter, type RunAgentInputContext, type StreamConnectionHandlers, type SubscribeConnectionAdapter, type WebSocketConnectionOptions, type XhrConnectionOptions, } from './connection-adapters.js';
 export { uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, convertMessagesToModelMessages, normalizeToUIMessage, generateMessageId, } from '@tanstack/ai/client';
 export { StreamProcessor, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, parsePartialJSON, PartialJSONParser, defaultJSONParser, type ChunkStrategy, type StreamProcessorOptions, type StreamProcessorEvents, type InternalToolCallState, type ToolCallState, type ToolResultState, type JSONParser, type ChunkRecording, type ProcessorResult, type ProcessorState, } from '@tanstack/ai/client';

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 import { AudioRecorder } from "./audio-recorder.js";
 import { UnsupportedResponseStreamError } from "./response-stream.js";
-import { DurableStreamIncompleteError, StreamReconnectLimitError, StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "./connection-adapters.js";
+import { DurableStreamIncompleteError, StreamReconnectLimitError, StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, webSocket, xhrHttpStream, xhrServerSentEvents } from "./connection-adapters.js";
 import { InterruptManager } from "./interrupt-manager.js";
 import { ChatClient } from "./chat-client.js";
 import { createMcpAppBridge } from "./mcp-app-bridge.js";
@@ -13,4 +13,4 @@ import { clientTools, createChatClientOptions } from "./types.js";
 import { StorageUnavailableError, indexedDBPersistence, localStoragePersistence, sessionStoragePersistence } from "./storage-adapters.js";
 import { createAIDevtoolsGenerationPreview } from "./devtools.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, convertMessagesToModelMessages, defaultJSONParser, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, uiMessageToModelMessages } from "@tanstack/ai/client";
-export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, xhrHttpStream, xhrServerSentEvents };
+export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents };

package/dist/esm/interrupt-manager.d.ts

@@ -1,5 +1,5 @@
-import { AnyClientTool, BatchInterruptError, Interrupt, RunAgentResumeItem } from '@tanstack/ai/client';
-import { BoundInterrupts, ChatInterrupt, ChatInterruptState } from './types.js';
+import { AnyClientTool, BatchInterruptError, Interrupt, InterruptDefinition, RunAgentResumeItem } from '@tanstack/ai/client';
+import { BoundInterrupts, ChatInterruptState, ResolvableChatInterrupt } from './types.js';
 export interface InterruptManagerHydration {
     threadId: string;
     interruptedRunId: string;
@@ -14,12 +14,14 @@ export interface InterruptManagerSubmission {
     canonicalResolutions: string;
     fingerprint: string;
 }
-export interface InterruptManagerOptions<TTools extends ReadonlyArray<AnyClientTool>> {
+export type InterruptManagerChangeSource = 'hydrate' | 'live';
+export interface InterruptManagerOptions<TTools extends ReadonlyArray<AnyClientTool>, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []> {
     tools?: TTools;
+    interrupts?: TInterrupts;
     submit: (submission: InterruptManagerSubmission) => Promise<void>;
-    onChange?: () => void;
+    onChange?: (source: InterruptManagerChangeSource) => void;
 }
-export declare class InterruptManager<TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>> {
+export declare class InterruptManager<TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []> {
     private readonly options;
     private hydration;
     private items;
@@ -31,19 +33,22 @@ export declare class InterruptManager<TTools extends ReadonlyArray<AnyClientTool
     private retrySubmission;
     private resuming;
     private tools;
-    constructor(options: InterruptManagerOptions<TTools>);
+    private readonly interruptDefinitions;
+    constructor(options: InterruptManagerOptions<TTools, TInterrupts>);
     updateTools(tools: TTools): void;
-    hydrate(hydration: InterruptManagerHydration): void;
-    getInterrupts(): BoundInterrupts<TTools>;
-    getState(): ChatInterruptState<TTools>;
+    hydrate(hydration: InterruptManagerHydration, source?: InterruptManagerChangeSource): void;
+    getInterrupts(): BoundInterrupts<TTools, TInterrupts>;
+    getState(): ChatInterruptState<TTools, TInterrupts>;
     getDescriptors(): ReadonlyArray<Interrupt>;
+    hasValidatedFirstPartyGenericBatch(): boolean;
     reset(options?: {
         preserveRootErrors?: boolean;
+        source?: InterruptManagerChangeSource;
     }): void;
     getInterruptErrors(): ReadonlyArray<BatchInterruptError>;
     getResuming(): boolean;
     resolve(approved: boolean): void;
-    resolve(resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void;
+    resolve(resolver: (interrupt: ResolvableChatInterrupt<TTools, TInterrupts>) => undefined): void;
     cancel(): void;
     retry(): void;
     resolveClientToolOutput(toolCallId: string, output: unknown): boolean;

package/dist/esm/interrupt-manager.js

@@ -1,5 +1,19 @@
-import { INTERRUPT_BINDING_METADATA_KEY, INTERRUPT_BINDING_VERSION, canonicalInterruptJson, canonicalizeInterruptResolutions, cloneAndDeepFreezeJson, digestInterruptJson, hashSchemaInput, isStandardSchema, normalizeApprovalSchema } from "@tanstack/ai/client";
+import { INTERRUPT_BINDING_METADATA_KEY, INTERRUPT_BINDING_VERSION, canonicalInterruptJson, canonicalizeInterruptResolutions, cloneAndDeepFreezeJson, digestInterruptJson, genericInterruptContinuationFromDescriptor, hashInterruptDefinitionSchema, hashSchemaInput, isStandardSchema, normalizeApprovalSchema, readInterruptBinding, wrapGenericInterruptContinuation } from "@tanstack/ai/client";
 //#region src/interrupt-manager.ts
+function isClientOwnedInterrupt(item) {
+	return item.resumable;
+}
+function resolutionWithContinuation(item, resolution) {
+	const continuation = genericInterruptContinuationFromDescriptor(item.descriptor);
+	if (!continuation) return resolution;
+	return {
+		...resolution,
+		metadata: wrapGenericInterruptContinuation(continuation)
+	};
+}
+function isRootResolvableInterrupt(interrupt) {
+	return "cancel" in interrupt && "clearResolution" in interrupt;
+}
 var itemErrorCodes = /* @__PURE__ */ new Set([
 	"invalid-payload",
 	"invalid-edited-args",
@@ -45,51 +59,24 @@ function isLegacyClientToolMetadata(value) {
 function isLegacyInterruptMetadata(interrupt) {
 	return isLegacyApprovalMetadata(interrupt.metadata) || isLegacyClientToolMetadata(interrupt.metadata);
 }
-function isBindingBase(value) {
-	return (value["v"] === void 0 || value["v"] === INTERRUPT_BINDING_VERSION) && typeof value["kind"] === "string" && typeof value["interruptId"] === "string" && typeof value["interruptedRunId"] === "string" && typeof value["generation"] === "number" && Number.isInteger(value["generation"]) && value["generation"] >= 0 && typeof value["responseSchemaHash"] === "string" && (value["expiresAt"] === void 0 || typeof value["expiresAt"] === "string" && Number.isFinite(Date.parse(value["expiresAt"])));
+function getDescriptorBinding(interrupt) {
+	return readInterruptBinding(interrupt);
 }
-function readBinding(value) {
-	if (!isUnknownObject(value) || !isBindingBase(value)) return void 0;
-	const expiresAt = typeof value["expiresAt"] === "string" ? value["expiresAt"] : void 0;
-	if (value["kind"] === "generic") return {
-		v: INTERRUPT_BINDING_VERSION,
-		kind: "generic",
-		interruptId: String(value["interruptId"]),
-		interruptedRunId: String(value["interruptedRunId"]),
-		generation: Number(value["generation"]),
-		responseSchemaHash: String(value["responseSchemaHash"]),
-		...expiresAt !== void 0 ? { expiresAt } : {}
-	};
-	if (value["kind"] === "client-tool-execution" && typeof value["toolName"] === "string" && typeof value["toolCallId"] === "string" && typeof value["outputSchemaHash"] === "string") return {
-		v: INTERRUPT_BINDING_VERSION,
-		kind: "client-tool-execution",
-		interruptId: String(value["interruptId"]),
-		interruptedRunId: String(value["interruptedRunId"]),
-		generation: Number(value["generation"]),
-		toolName: value["toolName"],
-		toolCallId: value["toolCallId"],
-		outputSchemaHash: value["outputSchemaHash"],
-		responseSchemaHash: String(value["responseSchemaHash"]),
-		...expiresAt !== void 0 ? { expiresAt } : {}
-	};
-	if (value["kind"] === "tool-approval" && typeof value["toolName"] === "string" && typeof value["toolCallId"] === "string" && typeof value["inputSchemaHash"] === "string" && typeof value["approvalSchemaHash"] === "string" && "originalArgs" in value) return {
-		v: INTERRUPT_BINDING_VERSION,
-		kind: "tool-approval",
-		interruptId: String(value["interruptId"]),
-		interruptedRunId: String(value["interruptedRunId"]),
-		generation: Number(value["generation"]),
-		toolName: value["toolName"],
-		toolCallId: value["toolCallId"],
-		originalArgs: value["originalArgs"],
-		inputSchemaHash: value["inputSchemaHash"],
-		approvalSchemaHash: value["approvalSchemaHash"],
-		responseSchemaHash: String(value["responseSchemaHash"]),
-		...expiresAt !== void 0 ? { expiresAt } : {}
-	};
+function hasReservedFirstPartyBindingMarker(interrupt) {
+	if (!isUnknownObject(interrupt.metadata)) return false;
+	const binding = interrupt.metadata[INTERRUPT_BINDING_METADATA_KEY];
+	if (!isUnknownObject(binding)) return false;
+	if (binding["v"] !== void 0 && binding["v"] !== INTERRUPT_BINDING_VERSION) return false;
+	return binding["kind"] === "generic" || binding["kind"] === "tool-approval" || binding["kind"] === "client-tool-execution" || "definitionId" in binding || "key" in binding || "batchIndex" in binding || "payloadSchemaHash" in binding;
 }
-function getDescriptorBinding(interrupt) {
-	const candidate = interrupt.metadata?.[INTERRUPT_BINDING_METADATA_KEY];
-	return readBinding(candidate);
+function hasFirstPartyGenericMarker(interrupt) {
+	if (!isUnknownObject(interrupt.metadata)) return false;
+	const binding = interrupt.metadata[INTERRUPT_BINDING_METADATA_KEY];
+	if (!isUnknownObject(binding) || binding["kind"] !== "generic") return false;
+	return "definitionId" in binding || "key" in binding || "batchIndex" in binding || "payloadSchemaHash" in binding;
+}
+function getInterruptPayload(interrupt) {
+	return interrupt.metadata?.["tanstack:interruptPayload"];
 }
 /**
 * Only used to route *legacy* (pre-binding) descriptors, which have no binding
@@ -106,6 +93,14 @@ function responseSchemaHash(interrupt) {
 		return;
 	}
 }
+function definitionSchemaHash(schema) {
+	if (schema === void 0) return void 0;
+	try {
+		return hashInterruptDefinitionSchema(schema);
+	} catch {
+		return;
+	}
+}
 function isPromiseLike(value) {
 	return value !== null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
@@ -179,17 +174,18 @@ function submissionErrorMatchesActiveBatch(error, submission) {
 	return error.scope === "item" ? interruptIds.includes(error.interruptId) : haveSameInterruptIds(error.interruptIds, interruptIds);
 }
 function genericBinding(interrupt, hydration, candidate) {
+	const schemaHash = responseSchemaHash(interrupt) ?? candidate?.responseSchemaHash;
 	return cloneAndDeepFreezeJson({
 		v: INTERRUPT_BINDING_VERSION,
 		kind: "generic",
 		interruptId: interrupt.id,
 		interruptedRunId: hydration.interruptedRunId,
 		generation: hydration.generation,
-		responseSchemaHash: responseSchemaHash(interrupt) ?? candidate?.responseSchemaHash ?? "invalid",
+		...schemaHash !== void 0 ? { responseSchemaHash: schemaHash } : {},
 		...interrupt.expiresAt !== void 0 ? { expiresAt: interrupt.expiresAt } : {}
 	});
 }
-function baseSnapshot(item, hydration, cancel, clearResolution) {
+function baseSnapshot(item, hydration) {
 	const descriptor = cloneAndDeepFreezeJson(item.descriptor);
 	const errors = item.error === void 0 ? Object.freeze([]) : Object.freeze([cloneAndDeepFreezeJson(item.error)]);
 	const error = errors[0];
@@ -207,9 +203,7 @@ function baseSnapshot(item, hydration, cancel, clearResolution) {
 		status: item.status,
 		errors,
 		...error !== void 0 ? { error } : {},
-		canResolve: item.canResolve,
-		cancel,
-		clearResolution
+		canResolve: item.canResolve
 	};
 }
 var InterruptManager = class {
@@ -229,26 +223,38 @@ var InterruptManager = class {
 	retrySubmission;
 	resuming = false;
 	tools;
+	interruptDefinitions;
 	constructor(options) {
 		this.options = options;
 		this.tools = options.tools;
+		const definitions = /* @__PURE__ */ new Map();
+		for (const definition of options.interrupts ?? []) {
+			if (definitions.has(definition.id)) throw new Error(`Duplicate interrupt definition id: ${definition.id}`);
+			definitions.set(definition.id, definition);
+		}
+		this.interruptDefinitions = definitions;
 	}
 	updateTools(tools) {
 		this.tools = tools;
 	}
-	hydrate(hydration) {
+	hydrate(hydration, source = "live") {
 		this.hydration = {
 			threadId: hydration.threadId,
 			interruptedRunId: hydration.interruptedRunId,
 			generation: hydration.generation,
 			interrupts: cloneAndDeepFreezeJson(hydration.interrupts)
 		};
-		this.items = hydration.interrupts.map((interrupt) => this.hydrateInterrupt(interrupt, hydration));
+		const firstPartyIndexes = /* @__PURE__ */ new Map();
+		for (const interrupt of hydration.interrupts) {
+			const binding = getDescriptorBinding(interrupt);
+			if (binding?.kind === "generic" && binding.definitionId !== void 0 && binding.key !== void 0 && binding.batchIndex !== void 0) firstPartyIndexes.set(binding.batchIndex, (firstPartyIndexes.get(binding.batchIndex) ?? 0) + 1);
+		}
+		this.items = hydration.interrupts.map((interrupt) => this.hydrateInterrupt(interrupt, hydration, firstPartyIndexes));
 		this.rootErrors = Object.freeze([]);
 		this.submissionRootErrors = Object.freeze([]);
 		this.retrySubmission = void 0;
 		this.resuming = false;
-		this.publish();
+		this.publish(source);
 	}
 	getInterrupts() {
 		return this.snapshot;
@@ -259,6 +265,9 @@ var InterruptManager = class {
 	getDescriptors() {
 		return this.hydration?.interrupts ?? Object.freeze([]);
 	}
+	hasValidatedFirstPartyGenericBatch() {
+		return this.items.some((item) => item.kind === "generic" && item.definition !== void 0);
+	}
 	reset(options) {
 		this.hydration = void 0;
 		this.items = [];
@@ -275,7 +284,7 @@ var InterruptManager = class {
 			interruptErrors: this.rootErrors,
 			resuming: false
 		});
-		this.options.onChange?.();
+		this.options.onChange?.(options?.source ?? "live");
 	}
 	getInterruptErrors() {
 		return this.rootErrors;
@@ -295,11 +304,12 @@ var InterruptManager = class {
 		this.assertRootMutable();
 		this.invalidateRetry();
 		for (const item of this.items) {
+			if (!isClientOwnedInterrupt(item)) continue;
 			item.validationGeneration++;
-			item.resolution = Object.freeze({
+			item.resolution = Object.freeze(resolutionWithContinuation(item, {
 				interruptId: item.descriptor.id,
 				status: "cancelled"
-			});
+			}));
 			item.status = "staged";
 			item.error = void 0;
 		}
@@ -327,19 +337,44 @@ var InterruptManager = class {
 		this.resolveItem(item.descriptor.id, { approved });
 		return true;
 	}
-	hydrateInterrupt(descriptor, hydration) {
+	hydrateInterrupt(descriptor, hydration, firstPartyIndexes) {
 		const interrupt = cloneAndDeepFreezeJson(descriptor);
 		const candidate = getDescriptorBinding(interrupt);
-		if (candidate === void 0 && !isLegacyInterruptMetadata(interrupt)) return {
+		const legacyResumable = candidate === void 0 && isLegacyInterruptMetadata(interrupt);
+		if (candidate === void 0 && !legacyResumable) {
+			if (hasReservedFirstPartyBindingMarker(interrupt)) return {
+				descriptor: interrupt,
+				binding: genericBinding(interrupt, hydration, void 0),
+				kind: "generic",
+				status: "error",
+				canResolve: false,
+				resumable: false,
+				error: this.itemError(interrupt.id, "stale", "The interrupt binding is invalid or incomplete."),
+				validationGeneration: 0
+			};
+			return {
+				descriptor: interrupt,
+				binding: void 0,
+				kind: "unbound",
+				status: "pending",
+				canResolve: false,
+				resumable: false,
+				validationGeneration: 0
+			};
+		}
+		const correlated = candidate !== void 0 && candidate.interruptId === interrupt.id && candidate.interruptedRunId === hydration.interruptedRunId && candidate.generation === hydration.generation && responseSchemaHash(interrupt) === candidate.responseSchemaHash;
+		const structurallyCorrelated = candidate !== void 0 && candidate.interruptId === interrupt.id && candidate.interruptedRunId === hydration.interruptedRunId && candidate.generation === hydration.generation && candidate.responseSchemaHash === (responseSchemaHash(interrupt) ?? candidate.responseSchemaHash);
+		if (candidate !== void 0 && hasFirstPartyGenericMarker(interrupt) && (!structurallyCorrelated || candidate.kind !== "generic" || candidate.definitionId === void 0 || candidate.key === void 0 || candidate.batchIndex === void 0)) return {
 			descriptor: interrupt,
-			binding: void 0,
-			kind: "unbound",
-			status: "pending",
+			binding: genericBinding(interrupt, hydration, candidate),
+			kind: "generic",
+			status: "error",
 			canResolve: false,
+			resumable: false,
+			error: this.itemError(interrupt.id, "stale", "The interrupt binding does not match this interrupted run."),
 			validationGeneration: 0
 		};
-		const correlated = candidate !== void 0 && candidate.interruptId === interrupt.id && candidate.interruptedRunId === hydration.interruptedRunId && candidate.generation === hydration.generation && candidate.responseSchemaHash === (responseSchemaHash(interrupt) ?? candidate.responseSchemaHash);
-		if (correlated && candidate.kind === "tool-approval") {
+		if (structurallyCorrelated && candidate.kind === "tool-approval") {
 			const tool = this.tools?.find((configured) => configured.name === candidate.toolName);
 			if (tool?.needsApproval === true && interrupt.toolCallId === candidate.toolCallId) try {
 				const approval = normalizeApprovalSchema(tool.approvalSchema, tool.inputSchema);
@@ -349,12 +384,13 @@ var InterruptManager = class {
 					kind: "tool-approval",
 					status: "pending",
 					canResolve: true,
+					resumable: true,
 					tool,
 					validationGeneration: 0
 				};
 			} catch {}
 		}
-		if (correlated && candidate.kind === "client-tool-execution") {
+		if (structurallyCorrelated && candidate.kind === "client-tool-execution") {
 			const tool = this.tools?.find((configured) => configured.name === candidate.toolName);
 			if (tool !== void 0 && interrupt.toolCallId === candidate.toolCallId && hashSchemaInput(tool.outputSchema) === candidate.outputSchemaHash) return {
 				descriptor: interrupt,
@@ -362,23 +398,53 @@ var InterruptManager = class {
 				kind: "client-tool-execution",
 				status: "pending",
 				canResolve: true,
+				resumable: true,
 				tool,
 				validationGeneration: 0
 			};
 		}
+		if (candidate !== void 0 && candidate.kind === "generic" && candidate.definitionId !== void 0 && candidate.key !== void 0 && candidate.batchIndex !== void 0 && candidate.key.length > 0 && firstPartyIndexes.get(candidate.batchIndex) !== 1) return {
+			descriptor: interrupt,
+			binding: cloneAndDeepFreezeJson(candidate),
+			kind: "generic",
+			status: "error",
+			canResolve: false,
+			resumable: false,
+			error: this.itemError(interrupt.id, "stale", "Generic interrupt batch contains a duplicate batchIndex."),
+			validationGeneration: 0
+		};
+		if (correlated && candidate.kind === "generic" && candidate.definitionId !== void 0 && candidate.key !== void 0 && candidate.batchIndex !== void 0 && candidate.key.length > 0 && firstPartyIndexes.get(candidate.batchIndex) === 1) {
+			const definition = this.interruptDefinitions.get(candidate.definitionId);
+			if (definition !== void 0 && definitionSchemaHash(definition.responseSchema) === candidate.responseSchemaHash && (definition.payloadSchema === void 0 ? candidate.payloadSchemaHash === void 0 : candidate.payloadSchemaHash === definitionSchemaHash(definition.payloadSchema))) {
+				const rawPayload = getInterruptPayload(interrupt);
+				return {
+					descriptor: interrupt,
+					binding: cloneAndDeepFreezeJson(candidate),
+					definition,
+					kind: "generic",
+					status: "pending",
+					canResolve: true,
+					resumable: true,
+					...rawPayload === void 0 ? {} : { payload: cloneAndDeepFreezeJson(rawPayload) },
+					validationGeneration: 0
+				};
+			}
+		}
+		const resumable = legacyResumable || candidate !== void 0 && candidate.interruptId === interrupt.id && candidate.interruptedRunId === hydration.interruptedRunId && candidate.generation === hydration.generation && (candidate.kind !== "generic" || responseSchemaHash(interrupt) === void 0 || candidate.responseSchemaHash === responseSchemaHash(interrupt));
 		return {
 			descriptor: interrupt,
 			binding: genericBinding(interrupt, hydration, candidate),
 			kind: "generic",
 			status: "pending",
-			canResolve: true,
+			canResolve: resumable,
+			resumable,
 			validationGeneration: 0
 		};
 	}
 	buildSnapshot(transaction) {
 		const hydration = this.requireHydration();
 		const next = this.items.filter((item) => item.kind !== "client-tool-execution" && item.status !== "submitting").map((item) => {
-			const base = baseSnapshot(item, hydration, () => this.cancelItem(item.descriptor.id, transaction), () => this.clearItem(item.descriptor.id, transaction));
+			const base = baseSnapshot(item, hydration);
 			if (item.kind === "unbound" || item.binding === void 0) {
 				const snapshot = {
 					...base,
@@ -396,6 +462,8 @@ var InterruptManager = class {
 					toolName: item.binding.toolName,
 					toolCallId: item.binding.toolCallId,
 					originalArgs: cloneAndDeepFreezeJson(item.binding.originalArgs),
+					cancel: () => this.cancelItem(item.descriptor.id, transaction),
+					clearResolution: () => this.clearItem(item.descriptor.id, transaction),
 					resolveInterrupt: (approved, options) => {
 						const details = isUnknownObject(options) ? options : void 0;
 						this.resolveItem(item.descriptor.id, {
@@ -413,19 +481,35 @@ var InterruptManager = class {
 				interruptId: item.descriptor.id,
 				interruptedRunId: hydration.interruptedRunId,
 				generation: hydration.generation,
-				responseSchemaHash: typeof item.binding.responseSchemaHash === "string" ? item.binding.responseSchemaHash : "none"
+				...typeof item.binding.responseSchemaHash === "string" ? { responseSchemaHash: item.binding.responseSchemaHash } : {}
 			});
+			if (item.definition !== void 0 && item.binding.kind === "generic") {
+				const snapshot = {
+					...base,
+					kind: "generic",
+					definitionId: item.definition.id,
+					key: item.binding.key ?? "",
+					payload: item.payload,
+					binding: boundGeneric,
+					cancel: () => this.cancelItem(item.descriptor.id, transaction),
+					clearResolution: () => this.clearItem(item.descriptor.id, transaction),
+					resolveInterrupt: (response) => this.resolveItem(item.descriptor.id, response, transaction)
+				};
+				return Object.freeze(snapshot);
+			}
 			const snapshot = {
 				...base,
 				kind: "generic",
 				binding: boundGeneric,
+				cancel: () => this.cancelItem(item.descriptor.id, transaction),
+				clearResolution: () => this.clearItem(item.descriptor.id, transaction),
 				resolveInterrupt: (payload) => this.resolveItem(item.descriptor.id, payload, transaction)
 			};
 			return Object.freeze(snapshot);
 		});
 		return Object.freeze(next);
 	}
-	publish() {
+	publish(source = "live") {
 		if (!this.hydration) {
 			this.snapshot = Object.freeze([]);
 			this.state = Object.freeze({
@@ -434,7 +518,7 @@ var InterruptManager = class {
 				interruptErrors: this.rootErrors,
 				resuming: this.resuming
 			});
-			this.options.onChange?.();
+			this.options.onChange?.(source);
 			return;
 		}
 		this.snapshot = this.buildSnapshot();
@@ -444,7 +528,7 @@ var InterruptManager = class {
 			interruptErrors: this.rootErrors,
 			resuming: this.resuming
 		});
-		this.options.onChange?.();
+		this.options.onChange?.(source);
 	}
 	resolveItem(interruptId, payload, transaction) {
 		this.assertItemMutable(transaction);
@@ -481,10 +565,10 @@ var InterruptManager = class {
 		const item = this.findItem(interruptId);
 		this.invalidateRetry();
 		item.validationGeneration++;
-		item.resolution = Object.freeze({
+		item.resolution = Object.freeze(resolutionWithContinuation(item, {
 			interruptId,
 			status: "cancelled"
-		});
+		}));
 		item.status = "staged";
 		item.error = void 0;
 		if (!transaction) {
@@ -503,7 +587,8 @@ var InterruptManager = class {
 		if (!transaction) this.publish();
 	}
 	maybeSubmit() {
-		const ours = this.items.filter((item) => item.kind !== "unbound");
+		const hasGeneric = this.items.some((item) => item.kind === "generic");
+		const ours = this.items.filter((item) => isClientOwnedInterrupt(item) && !(hasGeneric && item.kind === "client-tool-execution"));
 		if (ours.length === 0 || ours.some((item) => item.resolution === void 0 || item.status !== "staged")) return;
 		const hydration = this.requireHydration();
 		const canonical = canonicalizeInterruptResolutions(ours.map((item) => item.resolution).filter((item) => item !== void 0));
@@ -536,11 +621,11 @@ var InterruptManager = class {
 			if (!transaction) this.publish();
 			return;
 		}
-		item.resolution = cloneAndDeepFreezeJson({
+		item.resolution = cloneAndDeepFreezeJson(resolutionWithContinuation(item, {
 			interruptId: item.descriptor.id,
 			status: "resolved",
 			payload: result.payload
-		});
+		}));
 		item.status = "staged";
 		item.error = void 0;
 		if (!transaction) {
@@ -549,7 +634,15 @@ var InterruptManager = class {
 		}
 	}
 	validateCandidate(item, payload) {
-		if (item.kind === "generic") return validateWithSchema(item.descriptor.responseSchema, payload, "invalid-payload");
+		if (item.kind === "generic") {
+			const validation = validateWithSchema(item.definition?.responseSchema ?? item.descriptor.responseSchema, payload, "invalid-payload");
+			if (item.definition === void 0) return validation;
+			const preserveInput = (result) => "valid" in result ? {
+				valid: true,
+				payload
+			} : result;
+			return isPromiseLike(validation) ? Promise.resolve(validation).then(preserveInput) : preserveInput(validation);
+		}
 		if (item.kind === "client-tool-execution") return validateWithSchema(item.tool?.outputSchema, payload, "invalid-tool-output");
 		return this.validateApprovalCandidate(item, payload);
 	}
@@ -608,7 +701,7 @@ var InterruptManager = class {
 		return item.kind === "client-tool-execution" ? "invalid-tool-output" : "invalid-payload";
 	}
 	resolveBooleanBulk(approved) {
-		const resolvable = this.items.filter((item) => item.kind !== "client-tool-execution");
+		const resolvable = this.items.filter((item) => isClientOwnedInterrupt(item) && item.kind !== "client-tool-execution");
 		if (!resolvable.every((item) => item.kind === "tool-approval" && this.approvalBranchSchema(item.tool, approved) === void 0) || resolvable.length === 0) {
 			this.addRootError("unsupported-bulk-operation", "Boolean bulk resolution requires payloadless tool approvals.", false);
 			return;
@@ -636,7 +729,7 @@ var InterruptManager = class {
 		}));
 		const token = { active: true };
 		this.activeTransaction = token;
-		const stable = this.buildSnapshot(token);
+		const stable = this.buildSnapshot(token).filter(isRootResolvableInterrupt);
 		let failure;
 		try {
 			for (const interrupt of stable) {
@@ -649,7 +742,7 @@ var InterruptManager = class {
 					break;
 				}
 			}
-			if (failure === void 0 && this.items.some((item) => item.kind !== "client-tool-execution" && (item.resolution === void 0 || item.status !== "staged"))) failure = {
+			if (failure === void 0 && this.items.some((item) => isClientOwnedInterrupt(item) && item.kind !== "client-tool-execution" && (item.resolution === void 0 || item.status !== "staged"))) failure = {
 				code: "incomplete-batch",
 				message: "Interrupt transaction did not resolve every item."
 			};
@@ -696,7 +789,7 @@ var InterruptManager = class {
 	submitBatch(submission) {
 		this.resuming = true;
 		this.retrySubmission = void 0;
-		for (const item of this.items) item.status = "submitting";
+		for (const item of this.items) if (isClientOwnedInterrupt(item)) item.status = "submitting";
 		this.publish();
 		this.performSubmission(submission);
 	}
@@ -716,7 +809,7 @@ var InterruptManager = class {
 			const message = error instanceof Error ? error.message : String(error);
 			this.addRootError("transport", message, true, "transport");
 			this.retrySubmission = submission;
-			for (const item of this.items) item.status = "error";
+			for (const item of this.items) if (isClientOwnedInterrupt(item)) item.status = "error";
 			return;
 		}
 		const correlatedErrors = errors.filter((submissionError) => submissionErrorMatchesActiveBatch(submissionError, submission));
@@ -728,7 +821,7 @@ var InterruptManager = class {
 			if (submissionError.code === "stale" || submissionError.code === "expired" || submissionError.code === "conflict") nonRetryable = true;
 			retryable ||= submissionError.retryable;
 			if (submissionError.scope === "item") {
-				const item = this.items.find((candidate) => candidate.descriptor.id === submissionError.interruptId);
+				const item = this.items.find((candidate) => isClientOwnedInterrupt(candidate) && candidate.descriptor.id === submissionError.interruptId);
 				if (item) {
 					item.status = "error";
 					item.error = cloneAndDeepFreezeJson(submissionError);
@@ -738,7 +831,7 @@ var InterruptManager = class {
 		const mergedBatchErrors = mergeSubmissionBatchErrors(this.rootErrors, this.submissionRootErrors, batchErrors);
 		this.rootErrors = mergedBatchErrors.rootErrors;
 		this.submissionRootErrors = mergedBatchErrors.submissionRootErrors;
-		for (const item of this.items) if (item.status === "submitting") item.status = "error";
+		for (const item of this.items) if (isClientOwnedInterrupt(item) && item.status === "submitting") item.status = "error";
 		this.retrySubmission = retryable && !nonRetryable ? submission : void 0;
 	}
 	addRootError(code, message, retryable, source = "client") {
@@ -749,7 +842,7 @@ var InterruptManager = class {
 			message,
 			source,
 			retryable,
-			interruptIds: Object.freeze(this.items.map((item) => item.descriptor.id)),
+			interruptIds: Object.freeze(this.items.filter(isClientOwnedInterrupt).map((item) => item.descriptor.id)),
 			threadId: hydration.threadId,
 			interruptedRunId: hydration.interruptedRunId,
 			generation: hydration.generation