@tanstack/ai-client 0.24.0 → 0.25.2

package/dist/esm/chat-client.d.ts

@@ -1,13 +1,14 @@
-import { AnyClientTool, ModelMessage, RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client';
+import { AnyClientTool, InterruptDefinition, ModelMessage, RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client';
 import { ConnectionAdapter } from './connection-adapters.js';
-import { BoundInterrupts, ChatClientOptions, ChatClientState, ChatFetcher, ChatInterrupt, ChatInterruptState, ChatResumeState, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
-type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>> = {
+import { BoundInterrupts, ChatClientOptions, ChatClientState, ChatFetcher, ChatInterruptState, ResolvableChatInterrupt, ChatResumeState, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
+type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []> = {
     connection?: ConnectionAdapter;
     fetcher?: ChatFetcher;
     /** @deprecated Use `forwardedProps` instead. */
     body?: Record<string, any>;
     forwardedProps?: Record<string, any>;
     tools?: TTools;
+    interrupts?: TInterrupts;
     queue?: QueueOption;
     onResponse?: (response?: Response) => void | Promise<void>;
     onChunk?: (chunk: StreamChunk) => void;
@@ -17,13 +18,15 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     onConnectionStatusChange?: (status: ConnectionStatus) => void;
     onSessionGeneratingChange?: (isGenerating: boolean) => void;
     onQueueChange?: (queue: Array<QueuedMessage>) => void;
-    onResumeStateChange?: (resumeState: ChatResumeState | null, pendingInterrupts: BoundInterrupts<TTools>) => void;
+    onResumeStateChange?: (resumeState: ChatResumeState | null, pendingInterrupts: BoundInterrupts<TTools, TInterrupts>) => void;
     /**
      * Fires whenever the id of the run in flight changes: the new id when a run
      * starts (including a rejoin), `null` when it settles.
      */
     onRunIdChange?: (runId: string | null) => void;
-    onInterruptStateChange?: (state: ChatInterruptState<TTools>) => void;
+    onInterruptStateChange?: (state: ChatInterruptState<TTools, TInterrupts>, context: {
+        source: 'hydrate' | 'live';
+    }) => void;
     onCustomEvent?: (eventType: string, data: unknown, context: {
         toolCallId?: string;
     }) => void;
@@ -43,7 +46,7 @@ export interface NormalizedQueueConfig {
     strategy?: QueueStrategy;
 }
 export declare function normalizeQueueOption(option: QueueOption | undefined): NormalizedQueueConfig;
-export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown> {
+export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = any> {
     private readonly processor;
     private connection;
     private uniqueId;
@@ -130,7 +133,7 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private readonly cachesMessages;
     private devtoolsMounted;
     private readonly callbacksRef;
-    constructor(options: ChatClientOptions<TTools, TContext>);
+    constructor(options: ChatClientOptions<TTools, TContext, TInterrupts>);
     /**
      * START TAILING: re-attach to an in-flight run so its chunks arrive here.
      *
@@ -221,12 +224,12 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      */
     getCurrentRunId(): string | null;
     private setCurrentRunId;
-    getInterruptState(): ChatInterruptState<TTools>;
-    getInterrupts(): BoundInterrupts<TTools>;
+    getInterruptState(): ChatInterruptState<TTools, TInterrupts>;
+    getInterrupts(): BoundInterrupts<TTools, TInterrupts>;
     /** @deprecated Use getInterrupts(). */
-    getPendingInterrupts(): BoundInterrupts<TTools>;
+    getPendingInterrupts(): BoundInterrupts<TTools, TInterrupts>;
     resolveInterrupts(approved: boolean): void;
-    resolveInterrupts(resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void;
+    resolveInterrupts(resolver: (interrupt: ResolvableChatInterrupt<TTools, TInterrupts>) => undefined): void;
     cancelInterrupts(): void;
     retryInterrupts(): void;
     /** Unsafe low-level resume escape hatch. Prefer bound interrupt methods. */

package/dist/esm/chat-client.js

@@ -5,6 +5,13 @@ import { ClearedStreamTracker } from "./cleared-stream-tracker.js";
 import { InterruptManager } from "./interrupt-manager.js";
 import { StreamProcessor, convertSchemaToJsonSchema, generateMessageId, isStandardSchema, normalizeToUIMessage, parseWithStandardSchema } from "@tanstack/ai/client";
 //#region src/chat-client.ts
+function assertUniqueInterruptDefinitions(interrupts) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const interrupt of interrupts ?? []) {
+		if (ids.has(interrupt.id)) throw new Error(`Duplicate interrupt definition id: ${interrupt.id}`);
+		ids.add(interrupt.id);
+	}
+}
 function resolveTransport(transport) {
 	const { connection, fetcher } = transport;
 	if (connection && fetcher) throw new Error("ChatClient: pass either `connection` or `fetcher`, not both.");
@@ -197,6 +204,7 @@ var ChatClient = class {
 	devtoolsMounted = false;
 	callbacksRef;
 	constructor(options) {
+		assertUniqueInterruptDefinitions(options.interrupts);
 		this.threadId = options.threadId || "";
 		this.uniqueId = this.threadId;
 		let cachesMessages = true;
@@ -236,8 +244,9 @@ var ChatClient = class {
 		} };
 		this.interruptManager = new InterruptManager({
 			...options.tools !== void 0 ? { tools: options.tools } : {},
+			...options.interrupts !== void 0 ? { interrupts: options.interrupts } : {},
 			submit: (submission) => this.submitInterruptBatch(submission),
-			onChange: () => this.notifyResumeStateChange()
+			onChange: (source) => this.notifyResumeStateChange(source)
 		});
 		if (options.initialResumeSnapshot) this.applyResumeSnapshot(options.initialResumeSnapshot);
 		const persistedState = this.persistor?.readInitial();
@@ -399,13 +408,13 @@ var ChatClient = class {
 	applyResumeSnapshot(snapshot) {
 		const resumeState = readResumeState(snapshot);
 		if (resumeState === void 0) {
-			this.interruptManager.reset();
+			this.interruptManager.reset({ source: "hydrate" });
 			return;
 		}
 		this.lastResume = resumeState;
 		const pendingInterrupts = Array.isArray(snapshot.pendingInterrupts) ? snapshot.pendingInterrupts : [];
 		if (pendingInterrupts.length === 0) {
-			this.interruptManager.reset();
+			this.interruptManager.reset({ source: "hydrate" });
 			return;
 		}
 		const generation = this.interruptGeneration(pendingInterrupts);
@@ -414,7 +423,7 @@ var ChatClient = class {
 			interruptedRunId: resumeState.runId,
 			generation,
 			interrupts: pendingInterrupts
-		});
+		}, "hydrate");
 	}
 	/**
 	* Apply a resume snapshot read from durable storage. Restores interrupt state,
@@ -556,7 +565,7 @@ var ChatClient = class {
 				interruptedRunId,
 				generation: this.interruptGeneration(chunk.outcome.interrupts),
 				interrupts: chunk.outcome.interrupts
-			});
+			}, "live");
 			return;
 		}
 		const isRunlessSessionError = chunk.type === "RUN_ERROR" && !runId;
@@ -571,7 +580,7 @@ var ChatClient = class {
 			this.interruptManager.reset();
 			return;
 		}
-		this.notifyResumeStateChange();
+		this.notifyResumeStateChange("live");
 	}
 	/**
 	* The interrupt-resume state for the active/interrupted run (its run/thread
@@ -708,11 +717,12 @@ var ChatClient = class {
 		this.callbacksRef.current.onSessionGeneratingChange(isGenerating);
 		this.devtoolsBridge.emitSnapshot();
 	}
-	notifyResumeStateChange() {
+	notifyResumeStateChange(source) {
 		const resumeState = this.getResumeState();
+		const interruptState = this.interruptManager.getState();
 		this.persistResumeSnapshot(resumeState);
-		this.callbacksRef.current.onResumeStateChange(resumeState, this.interruptManager.getInterrupts());
-		this.callbacksRef.current.onInterruptStateChange(this.interruptManager.getState());
+		this.callbacksRef.current.onResumeStateChange(resumeState, interruptState.interrupts);
+		this.callbacksRef.current.onInterruptStateChange(interruptState, { source });
 	}
 	/**
 	* Build the durable resume snapshot from the current resume state + pending
@@ -901,6 +911,7 @@ var ChatClient = class {
 					}
 					await this.processIncomingChunk(chunk, { defer: false });
 				}
+				if (this.pendingToolExecutions.size > 0) await Promise.all(this.pendingToolExecutions.values());
 			} catch (error) {
 				const isAbort = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
 				if (!attached && !isAbort) refused = true;
@@ -915,6 +926,7 @@ var ChatClient = class {
 					this.abortController = null;
 					this.setIsLoading(false);
 					if (this.status === "streaming") this.setStatus("ready");
+					await this.drainPostStreamActions();
 				}
 			}
 		})();
@@ -947,7 +959,7 @@ var ChatClient = class {
 		this.processor.processChunk(chunk);
 		this.updateRunLifecycle(chunk);
 		this.observeInterruptState(chunk);
-		if (options?.defer !== false) await new Promise((resolve) => setTimeout(resolve, 0));
+		if (options?.defer !== false && (typeof document === "undefined" || !document.hidden)) await new Promise((resolve) => setTimeout(resolve, 0));
 		this.resolveJoinedRun(chunk);
 	}
 	isActiveInterruptSubmissionFailure(chunk) {
@@ -1484,6 +1496,9 @@ var ChatClient = class {
 	* a text-only response has nothing to auto-send.
 	*/
 	shouldAutoSend() {
+		if (this.lastResume) return false;
+		if (this.activeInterruptSubmission && this.hasPendingInterrupts()) return false;
+		if (this.interruptManager.getInterrupts().length > 0) return false;
 		const lastAssistant = this.processor.getMessages().findLast((m) => m.role === "assistant");
 		if (!lastAssistant) return false;
 		if (!lastAssistant.parts.some((p) => p.type === "tool-call")) return false;