@tanstack/ai-client 0.34.0 → 0.36.0

package/README.md

@@ -240,6 +240,7 @@ Official adapters include:
 | [`@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                           |
 | [`@tanstack/ai-reactor`](https://tanstack.com/ai/latest/docs/adapters/reactor)       | Reactor live world and video generation (Orbis, Happy Oyster, LingBot, Helios, FastH3) |
+| [`@tanstack/ai-worldlabs`](https://tanstack.com/ai/latest/docs/adapters/worldlabs)   | World Labs Marble persistent 3D world generation                                       |
 | [`@tanstack/ai-cloudflare`](https://tanstack.com/ai/latest/docs/adapters/cloudflare) | Cloudflare Workers AI chat, embeddings, image, speech, transcription, and AI Gateway   |
 
 The adapter system is tree-shakeable by activity. Import `openaiText` for chat,

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

@@ -143,6 +143,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private readonly activeRunIds;
     /** Latched by `dispose()`; stops any late async callback starting new work. */
     private disposed;
+    /** The error a failed mount hydration set, cleared by the next successful one. */
+    private hydrationError;
     /** Whether a view is currently watching. See `attach` / `detach`. */
     private tailing;
     /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
@@ -219,6 +221,19 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * send that starts first owns the client (hydration then backs off).
      */
     private hydrateFromServer;
+    /**
+     * Surface a mount-hydration failure (`persistence: true`) on the observable
+     * fields, mirroring `GenerationClient.failHydration`, so "this thread failed
+     * to load" is distinguishable from "this thread has no messages" and the app
+     * can show an error / offer a retry. A genuine miss — the server having no
+     * record for a fresh thread — resolves normally and never reaches here; only a
+     * thrown transport / authorize-gate error does.
+     *
+     * Skipped when the view unmounted (`!tailing`) or a `sendMessage` took
+     * ownership while the hydrate GET was in flight, so a live run's state always
+     * wins over a stale mount-time failure — same guard as the success path above.
+     */
+    private failHydration;
     mountDevtools(): void;
     private ensureThreadId;
     /**
@@ -295,7 +310,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      */
     private startSubscription;
     /**
-     * Consume chunks from the connection subscription.
+     * Consume chunks from the connection subscription. Chunks are processed in
+     * order; the loop yields to the host after each processing budget.
      */
     private consumeSubscription;
     /**
@@ -317,7 +333,7 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * give up after {@link REJOIN_CONNECT_DEADLINE_MS} if no chunk arrives and
      * clear the dead pointer so it does not retry on the next load.
      *
-     * Replay chunks are processed WITHOUT the per-chunk yield the live path uses,
+     * Replay chunks are processed WITHOUT the time-slice yield the live path uses,
      * so the buffered prefix snaps in and only the genuinely-live tail streams at
      * network speed — a reload looks like the run continued, not like it re-typed.
      */

package/dist/esm/chat-client.js

@@ -6,9 +6,15 @@ import { fetcherToConnectionAdapter, getChunkRunId as getChunkRunId$1, normalize
 import { ChatPersistor } from "./client-persistor.js";
 import { ClearedStreamTracker } from "./cleared-stream-tracker.js";
 import { InterruptManager } from "./interrupt-manager.js";
-import { EventType, StreamProcessor, convertSchemaToJsonSchema, generateMessageId, isStandardSchema, mergeMetadata, normalizeToUIMessage, parseWithStandardSchema, restoreInboundChunk, tanstackMetadata } from "@tanstack/ai/client";
+import { EventType, StreamProcessor, cloneAndDeepFreezeJson, convertSchemaToJsonSchema, generateMessageId, isStandardSchema, mergeMetadata, normalizeToUIMessage, restoreInboundChunk, tanstackMetadata, validateWithStandardSchema } from "@tanstack/ai/client";
 import { ByokBlockedError, ByokMissingError, ByokUnresolvedProviderError } from "@tanstack/ai/byok";
 //#region src/chat-client.ts
+var STREAM_PROCESSING_BUDGET_MS = 8;
+function yieldToHost() {
+	const { scheduler } = globalThis;
+	if (scheduler?.yield) return scheduler.yield();
+	return new Promise((resolve) => setTimeout(resolve, 0));
+}
 function assertUniqueInterruptDefinitions(interrupts) {
 	const ids = /* @__PURE__ */ new Set();
 	for (const interrupt of interrupts ?? []) {
@@ -138,10 +144,16 @@ var REJOIN_CONNECT_DEADLINE_MS = 2e3;
 var REJOIN_REBUILD_TRIGGERS = /* @__PURE__ */ new Set([
 	"TEXT_MESSAGE_START",
 	"TEXT_MESSAGE_CONTENT",
+	"REASONING_MESSAGE_CONTENT",
 	"TOOL_CALL_START",
 	"MESSAGES_SNAPSHOT",
 	"SUBAGENT_STARTED"
 ]);
+function rebuildsAssistantMessage(chunk) {
+	if (chunk.type === "REASONING_ENCRYPTED_VALUE") return chunk.subtype === "message" && typeof chunk.encryptedValue === "string" && chunk.encryptedValue.length > 0;
+	if (chunk.type === "STEP_FINISHED") return "signature" in chunk && Boolean(chunk.signature);
+	return REJOIN_REBUILD_TRIGGERS.has(chunk.type);
+}
 /** Every subagent card in the messages, nested cards included. */
 function collectSubagentParts(messages) {
 	const cards = [];
@@ -258,6 +270,8 @@ var ChatClient = class {
 	activeRunIds = /* @__PURE__ */ new Set();
 	/** Latched by `dispose()`; stops any late async callback starting new work. */
 	disposed = false;
+	/** The error a failed mount hydration set, cleared by the next successful one. */
+	hydrationError;
 	/** Whether a view is currently watching. See `attach` / `detach`. */
 	tailing = false;
 	/** Constructor inputs `attach()` needs on every re-attach, not just the first. */
@@ -556,19 +570,25 @@ var ChatClient = class {
 			const generation = this.historyGeneration;
 			try {
 				result = await hydrate(this.threadId, hydrateOptions);
-			} catch {
+			} catch (cause) {
+				if (generation === this.historyGeneration) this.failHydration(cause);
 				return;
 			}
 			if (generation !== this.historyGeneration) return;
 			if (this.disposed || !this.tailing) return;
 			if (this.isLoading || this.abortController) return;
+			if (this.hydrationError && this.error === this.hydrationError) {
+				this.setError(void 0);
+				this.setStatus("ready");
+			}
+			this.hydrationError = void 0;
 			this.applyHydrationPage(result.page);
 			if (result.messages.length > 0) {
 				const windowMessages = normalizeMessagesDates(result.messages);
 				this.processor.setMessages(windowMessages);
 				this.rememberServerMessageIds(windowMessages);
 			}
-			if (result.interrupts && result.interrupts.pending.length > 0) this.applyResumeSnapshot({
+			if (result.interrupts && result.interrupts.pending.length > 0 && (!result.activeRun?.runId || result.activeRun.runId === result.interrupts.runId)) this.applyResumeSnapshot({
 				resumeState: {
 					threadId: this.threadId,
 					runId: result.interrupts.runId
@@ -578,6 +598,29 @@ var ChatClient = class {
 			else if (result.activeRun?.runId) this.maybeRejoinInFlight(result.activeRun.runId);
 		})();
 	}
+	/**
+	* Surface a mount-hydration failure (`persistence: true`) on the observable
+	* fields, mirroring `GenerationClient.failHydration`, so "this thread failed
+	* to load" is distinguishable from "this thread has no messages" and the app
+	* can show an error / offer a retry. A genuine miss — the server having no
+	* record for a fresh thread — resolves normally and never reaches here; only a
+	* thrown transport / authorize-gate error does.
+	*
+	* Skipped when the view unmounted (`!tailing`) or a `sendMessage` took
+	* ownership while the hydrate GET was in flight, so a live run's state always
+	* wins over a stale mount-time failure — same guard as the success path above.
+	*/
+	failHydration(cause) {
+		if (this.disposed || !this.tailing) return;
+		if (this.isLoading || this.abortController) return;
+		const error = cause instanceof Error ? cause : new Error(String(cause));
+		if (error instanceof ByokMissingError) this.byok?.request(error.provider, "missing");
+		if (error instanceof ByokBlockedError && error.reason === "locked") this.byok?.request(error.provider, "locked");
+		this.hydrationError = error;
+		this.setStatus("error");
+		this.setError(error);
+		this.callbacksRef.current.onError(error);
+	}
 	mountDevtools() {
 		this.ensureThreadId();
 		if (this.devtoolsMounted) return;
@@ -974,13 +1017,21 @@ var ChatClient = class {
 		});
 	}
 	/**
-	* Consume chunks from the connection subscription.
+	* Consume chunks from the connection subscription. Chunks are processed in
+	* order; the loop yields to the host after each processing budget.
 	*/
 	async consumeSubscription(signal) {
 		const stream = this.connection.subscribe(signal);
+		let chunkProcessingTime = 0;
 		for await (const chunk of stream) {
 			if (signal.aborted) break;
-			await this.processIncomingChunk(chunk);
+			const startedAt = performance.now();
+			this.processIncomingChunk(chunk);
+			chunkProcessingTime += performance.now() - startedAt;
+			if (chunkProcessingTime < STREAM_PROCESSING_BUDGET_MS) continue;
+			chunkProcessingTime = 0;
+			if (typeof document !== "undefined" && document.hidden) continue;
+			await yieldToHost();
 		}
 	}
 	/**
@@ -1002,7 +1053,7 @@ var ChatClient = class {
 	* give up after {@link REJOIN_CONNECT_DEADLINE_MS} if no chunk arrives and
 	* clear the dead pointer so it does not retry on the next load.
 	*
-	* Replay chunks are processed WITHOUT the per-chunk yield the live path uses,
+	* Replay chunks are processed WITHOUT the time-slice yield the live path uses,
 	* so the buffered prefix snaps in and only the genuinely-live tail streams at
 	* network speed — a reload looks like the run continued, not like it re-typed.
 	*/
@@ -1033,11 +1084,11 @@ var ChatClient = class {
 						attached = true;
 						clearTimeout(connectTimer);
 					}
-					if (!rebuilt && REJOIN_REBUILD_TRIGGERS.has(chunk.type)) {
+					if (!rebuilt && rebuildsAssistantMessage(chunk)) {
 						rebuilt = true;
 						this.dropTrailingInFlightAssistant();
 					}
-					await this.processIncomingChunk(chunk, { defer: false });
+					this.processIncomingChunk(chunk);
 				}
 				if (this.pendingToolExecutions.size > 0) await Promise.all(this.pendingToolExecutions.values());
 			} catch (error) {
@@ -1070,7 +1121,7 @@ var ChatClient = class {
 		const last = messages[messages.length - 1];
 		if (last && last.role === "assistant") this.processor.setMessages(messages.slice(0, -1));
 	}
-	async processIncomingChunk(chunk, options) {
+	processIncomingChunk(chunk) {
 		chunk = restoreInboundChunk(chunk);
 		if (chunk.type === "RUN_ERROR" && this.isActiveInterruptSubmissionFailure(chunk)) {
 			const interruptErrors = tanstackMetadata(chunk)?.interruptErrors;
@@ -1099,7 +1150,6 @@ var ChatClient = class {
 		this.syncSubagentHandles();
 		this.updateRunLifecycle(chunk);
 		this.observeInterruptState(chunk);
-		if (options?.defer !== false && (typeof document === "undefined" || !document.hidden)) await new Promise((resolve) => setTimeout(resolve, 0));
 		this.resolveJoinedRun(chunk);
 	}
 	isActiveInterruptSubmissionFailure(chunk) {
@@ -1554,10 +1604,12 @@ var ChatClient = class {
 		await this.addToolResultForClientTool(result, clientTool, this.streamContinuationGeneration);
 	}
 	async addToolResultForClientTool(result, clientTool, continuationGeneration, context) {
-		if (clientTool && result.state !== "output-error") try {
+		if (result.state !== "output-error") try {
+			let output = clientTool?.outputSchema && isStandardSchema(clientTool.outputSchema) ? await this.validateClientToolOutput(clientTool, result.output) : result.output;
+			if (this.interruptManager.getDescriptors().some((interrupt) => interrupt.toolCallId === result.toolCallId)) output = cloneAndDeepFreezeJson(output);
 			result = {
 				...result,
-				output: this.validateClientToolOutput(clientTool, result.output)
+				output
 			};
 		} catch (error) {
 			result = {
@@ -1571,16 +1623,17 @@ var ChatClient = class {
 		if (continuationGeneration !== this.continuationGeneration) return;
 		this.processor.addToolResult(result.toolCallId, result.output, result.state === "output-error" ? result.errorText || "Tool execution failed" : void 0);
 		this.devtoolsBridge.emitSnapshot();
-		if (this.interruptManager.resolveClientToolOutput(result.toolCallId, result.state === "output-error" ? { error: result.errorText || "Tool execution failed" } : result.output)) return;
+		if (result.state === "output-error" ? this.interruptManager.resolveClientToolError(result.toolCallId, result.errorText || "Tool execution failed") : this.interruptManager.resolveClientToolOutput(result.toolCallId, result.output)) return;
 		if (this.isLoading) {
 			this.queuePostStreamAction(() => continuationGeneration === this.continuationGeneration ? this.checkForContinuation() : Promise.resolve());
 			return;
 		}
 		await this.checkForContinuation();
 	}
-	validateClientToolOutput(clientTool, output) {
-		if (clientTool.outputSchema && isStandardSchema(clientTool.outputSchema)) return parseWithStandardSchema(clientTool.outputSchema, output);
-		return output;
+	async validateClientToolOutput(clientTool, output) {
+		const validation = await validateWithStandardSchema(clientTool.outputSchema, output);
+		if (!validation.success) throw new Error(validation.issues.map((issue) => issue.message).join(", "));
+		return validation.data;
 	}
 	/**
 	* Respond to a tool approval request