@tanstack/ai-client 0.23.3 → 0.25.1

package/README.md

@@ -36,6 +36,14 @@
   </a>
 </div>
 
+<br />
+
+<div align="center">
+  <a href="https://tanstack.com/blog/tanstack-open-source-awards-2026">
+    <img src="https://raw.githubusercontent.com/TanStack/ai/16826d81cade868956df240d6239a671e689193c/media/js-open-source-award-2026-ai-project-of-the-year.svg" alt="Winner of the 2026 JavaScript Open Source Award for AI Project of the Year" width="250" />
+  </a>
+</div>
+
 # TanStack AI
 
 Type-safe, provider-agnostic TypeScript SDK for building streaming chat,
@@ -191,7 +199,7 @@ Learn more in the
   build low-latency realtime voice experiences.
 - [Code Mode](https://tanstack.com/ai/latest/docs/code-mode/code-mode) - let
   models write and execute TypeScript inside a secure isolate.
-- [Code Mode with Skills](https://tanstack.com/ai/latest/docs/code-mode/code-mode-with-skills) -
+- [Code Mode with Snippets](https://tanstack.com/ai/latest/docs/code-mode/code-mode-with-snippets) -
   give Code Mode reusable runtime capabilities.
 
 ## Providers
@@ -208,6 +216,7 @@ Official adapters include:
 | [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok)             | xAI Grok chat, images, and realtime                                            |
 | [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq)             | Groq low-latency inference                                                     |
 | [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects     |
+| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus)     | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR    |
 | [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal)               | fal.ai image, video, audio, speech, and transcription models                   |
 
 The adapter system is tree-shakeable by activity. Import `openaiText` for chat,

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,11 +46,11 @@ 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 readonly uniqueId;
-    private readonly threadId;
+    private uniqueId;
+    private threadId;
     private readonly persistor?;
     private readonly clearedStreamTracker;
     private currentRunId;
@@ -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.
      *
@@ -190,6 +193,7 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      */
     private hydrateFromServer;
     mountDevtools(): void;
+    private ensureThreadId;
     /**
      * Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
      * still tracking. The persistor owns the cleared-run bookkeeping; the client
@@ -220,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,13 +204,16 @@ var ChatClient = class {
 	devtoolsMounted = false;
 	callbacksRef;
 	constructor(options) {
-		this.threadId = options.threadId || this.generateUniqueId("thread");
-		this.uniqueId = options.id || this.threadId;
+		assertUniqueInterruptDefinitions(options.interrupts);
+		this.threadId = options.threadId || "";
+		this.uniqueId = this.threadId;
 		let cachesMessages = true;
-		if (options.persistence === true) cachesMessages = false;
-		else if (options.persistence) {
-			const persistenceKey = options.id ?? this.threadId;
-			this.persistor = new ChatPersistor(options.persistence, persistenceKey, (messages) => this.processor.setMessages(messages), (snapshot) => this.applyPersistedResume(snapshot));
+		if (options.persistence === true) {
+			if (!options.threadId) throw new Error("[TanStack AI] persistence needs a stable `threadId` to key on. Pass a threadId from your app (for example support-42).");
+			cachesMessages = false;
+		} else if (options.persistence) {
+			if (!options.threadId) throw new Error("[TanStack AI] persistence needs a stable `threadId` to key on. Pass a threadId from your app (for example support-42).");
+			this.persistor = new ChatPersistor(options.persistence, options.threadId, (messages) => this.processor.setMessages(messages), (snapshot) => this.applyPersistedResume(snapshot));
 		}
 		this.bodyOption = options.body || {};
 		this.forwardedPropsOption = options.forwardedProps || {};
@@ -234,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();
@@ -367,6 +378,7 @@ var ChatClient = class {
 	*/
 	attach() {
 		if (this.disposed || this.tailing) return;
+		this.ensureThreadId();
 		this.tailing = true;
 		if (this.rejoinRunId) this.maybeRejoinInFlight(this.rejoinRunId);
 		if (!this.cachesMessages && this.connection.hydrate) this.hydrateFromServer();
@@ -396,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);
@@ -411,7 +423,7 @@ var ChatClient = class {
 			interruptedRunId: resumeState.runId,
 			generation,
 			interrupts: pendingInterrupts
-		});
+		}, "hydrate");
 	}
 	/**
 	* Apply a resume snapshot read from durable storage. Restores interrupt state,
@@ -474,10 +486,16 @@ var ChatClient = class {
 		})();
 	}
 	mountDevtools() {
+		this.ensureThreadId();
 		if (this.devtoolsMounted) return;
 		this.devtoolsMounted = true;
 		this.devtoolsBridge.mountWithTools(this.processor.getMessages().length);
 	}
+	ensureThreadId() {
+		if (!this.threadId) this.threadId = this.generateUniqueId("thread");
+		this.uniqueId = this.threadId;
+		return this.threadId;
+	}
 	/**
 	* Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
 	* still tracking. The persistor owns the cleared-run bookkeeping; the client
@@ -547,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;
@@ -562,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
@@ -699,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
@@ -732,10 +751,17 @@ var ChatClient = class {
 		this.events.errorChanged(error?.message || null);
 	}
 	buildDevtoolsBridgeOptions(devtools) {
+		const client = this;
 		return {
-			hookId: this.uniqueId,
-			clientId: this.uniqueId,
-			threadId: this.threadId,
+			get hookId() {
+				return client.uniqueId;
+			},
+			get clientId() {
+				return client.uniqueId;
+			},
+			get threadId() {
+				return client.threadId;
+			},
 			metadata: {
 				hookName: devtools?.hookName ?? "useChat",
 				outputKind: devtools?.outputKind ?? "chat",
@@ -885,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;
@@ -899,6 +926,7 @@ var ChatClient = class {
 					this.abortController = null;
 					this.setIsLoading(false);
 					if (this.status === "streaming") this.setStatus("ready");
+					await this.drainPostStreamActions();
 				}
 			}
 		})();
@@ -1468,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;