@tanstack/ai 0.51.0 → 0.52.1

package/README.md

@@ -61,12 +61,8 @@ framework bindings as your app needs them.
 
 - [Overview](https://tanstack.com/ai/latest/docs/getting-started/overview) -
   what TanStack AI is and how the packages fit together.
-- [Quick Start: React](https://tanstack.com/ai/latest/docs/getting-started/quick-start) -
-  add streaming chat to a React app.
-- [Quick Start: Vue](https://tanstack.com/ai/latest/docs/getting-started/quick-start-vue) -
-  build with Vue composables.
-- [Quick Start: Svelte](https://tanstack.com/ai/latest/docs/getting-started/quick-start-svelte) -
-  build with Svelte 5 runes.
+- [Quick Start](https://tanstack.com/ai/latest/docs/getting-started/quick-start) -
+  add streaming chat. Pick your framework at the top of the page.
 - [Quick Start: Server Only](https://tanstack.com/ai/latest/docs/getting-started/quick-start-server) -
   use TanStack AI from a server endpoint, script, or backend service.
 - [TanStack AI vs Vercel AI SDK](https://tanstack.com/ai/latest/docs/comparison/vercel-ai-sdk) -

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

@@ -115,6 +115,7 @@ var TextEngine = class {
 	effectiveRequest;
 	effectiveSignal;
 	messages;
+	providerMessages;
 	iterationCount = 0;
 	/** Cumulative tool calls counted in this run (emitted + pending resume). */
 	toolCallCount = 0;
@@ -156,6 +157,9 @@ var TextEngine = class {
 	middlewareRunner;
 	middlewareCtx;
 	sandboxFileQueue = [];
+	middlewareCustomQueue = [];
+	middlewareCustomWaiters = [];
+	drainingMiddlewareCustom = false;
 	deferredPromises = [];
 	abortReason;
 	middlewareAbortController;
@@ -193,6 +197,7 @@ var TextEngine = class {
 		this.initialApprovals = approvals;
 		this.initialClientToolResults = clientToolResults;
 		this.messages = convertMessagesToModelMessages(config.params.messages);
+		this.providerMessages = this.messages;
 		assertUniqueToolNames(config.params.tools || []);
 		this.lazyToolManager = new LazyToolManager(config.params.tools || [], this.messages, config.params.lazyToolsConfig);
 		this.tools = this.lazyToolManager.getActiveTools();
@@ -223,6 +228,12 @@ var TextEngine = class {
 				this.abortReason = reason;
 				this.middlewareAbortController?.abort(reason);
 			},
+			emitCustomEvent: (name, value) => {
+				this.middlewareCustomQueue.push(this.createCustomEventChunk(name, value));
+				const waiters = this.middlewareCustomWaiters;
+				this.middlewareCustomWaiters = [];
+				for (const waiter of waiters) waiter();
+			},
 			context: config.context,
 			defer: (promise) => {
 				this.deferredPromises.push(promise);
@@ -304,14 +315,14 @@ var TextEngine = class {
 		this.beforeRun();
 		this.logger.agentLoop("run started", { threadId: this.middlewareCtx.threadId });
 		try {
-			await this.middlewareRunner.runSetup(this.middlewareCtx);
+			yield* this.runWhileYielding(this.middlewareRunner.runSetup(this.middlewareCtx));
 			this.middlewareCtx.phase = "init";
 			const initialConfig = this.buildMiddlewareConfig();
-			const transformedConfig = await this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig);
+			const transformedConfig = yield* this.runWhileYielding(this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig));
 			this.applyMiddlewareConfig(transformedConfig);
 			await this.applyEphemeralInterruptResume(transformedConfig);
 			await this.applyDurableGenericInterruptResolution();
-			await this.middlewareRunner.runOnStart(this.middlewareCtx);
+			yield* this.runWhileYielding(this.middlewareRunner.runOnStart(this.middlewareCtx));
 			if (this.earlyTermination) {
 				yield* this.emitSuccessfulEarlyTermination();
 				if (!this.terminalHookCalled) {
@@ -330,12 +341,12 @@ var TextEngine = class {
 				if (this.earlyTermination) break;
 				if (this.isCancelled()) return;
 				this.logger.agentLoop(`iteration=${this.middlewareCtx.iteration}`, { iteration: this.middlewareCtx.iteration });
-				await this.beginCycle();
+				yield* this.runWhileYielding(this.beginCycle());
 				if (this.cyclePhase === "processText") {
 					this.middlewareCtx.phase = "beforeModel";
 					this.middlewareCtx.iteration = this.iterationCount;
 					const iterConfig = this.buildMiddlewareConfig();
-					const iterTransformedConfig = await this.middlewareRunner.runOnConfig(this.middlewareCtx, iterConfig);
+					const iterTransformedConfig = yield* this.runWhileYielding(this.middlewareRunner.runOnConfig(this.middlewareCtx, iterConfig));
 					this.applyMiddlewareConfig(iterTransformedConfig);
 					if (yield* this.emitBoundaryInterrupts("beforeModel", this.createSyntheticFinishedEvent())) {
 						this.setToolPhase("wait");
@@ -353,7 +364,7 @@ var TextEngine = class {
 					} else yield* this.flushDeferredModelRunFinishedChunks();
 				} else yield* this.processToolCalls();
 				this.endCycle();
-			} while (await this.shouldContinue());
+			} while (yield* this.runWhileYielding(this.shouldContinue()));
 			this.logger.agentLoop("run finished", { finishReason: this.lastFinishReason });
 			if (this.finalStructuredOutput && this.toolPhase !== "wait" && !this.isCancelled() && !this.finalizationError && !this.earlyTermination) {
 				if (this.finalStructuredOutput.nativeCombined === true) yield* this.harvestCombinedStructuredOutput();
@@ -505,7 +516,7 @@ var TextEngine = class {
 		for (const [approvalId, resolution] of approvals) adapterApprovals.set(approvalId, typeof resolution === "boolean" ? resolution : resolution.approved);
 		for await (const raw of this.adapter.chatStream({
 			model: this.params.model,
-			messages: this.messages,
+			messages: this.providerMessages,
 			tools: toolsWithJsonSchemas,
 			metadata,
 			request: this.effectiveRequest,
@@ -581,16 +592,21 @@ var TextEngine = class {
 					this.deferredToolCallRunFinishedChunks.push(spec);
 					continue;
 				}
-				if (spec.type === EventType.RUN_STARTED) this.hasPublicRunStarted = true;
+				if (spec.type === EventType.RUN_STARTED) {
+					if (this.hasPublicRunStarted) continue;
+					this.hasPublicRunStarted = true;
+				}
 				this.logger.output(`type=${spec.type}`, { chunk: spec });
 				yield spec;
 				this.middlewareCtx.chunkIndex++;
 			}
 			if (raw.type === EventType.RUN_FINISHED) await this.runOnUsageFromChunk(raw);
 			yield* this.drainSandboxFileQueue();
+			yield* this.drainMiddlewareCustomQueue();
 			if (this.earlyTermination) break;
 		}
 		yield* this.drainSandboxFileQueue();
+		yield* this.drainMiddlewareCustomQueue();
 	}
 	handleStreamChunk(chunk) {
 		switch (chunk.type) {
@@ -810,12 +826,12 @@ var TextEngine = class {
 			return "stop";
 		}
 		const allResults = [...executionResult.results, ...deferredErrorResults];
-		await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+		yield* this.runWhileYielding(this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
 			toolCalls: pendingToolCalls,
 			results: allResults,
 			needsApproval: executionResult.needsApproval,
 			needsClientExecution: executionResult.needsClientExecution
-		});
+		}));
 		if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
 			this.discardDeferredToolCallRunFinishedChunks();
 			if (allResults.length > 0) for (const chunk of this.buildToolResultChunks(allResults, finishEvent)) yield* this.pipeThroughMiddleware(chunk);
@@ -903,14 +919,14 @@ var TextEngine = class {
 			return;
 		}
 		const allResults = [...executionResult.results, ...deferredErrorResults];
-		await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+		yield* this.runWhileYielding(this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
 			toolCalls,
 			results: allResults,
 			needsApproval: executionResult.needsApproval,
 			needsClientExecution: executionResult.needsClientExecution
-		});
+		}));
 		const afterToolBoundaryChunks = this.buildToolResultChunks(allResults, finishEvent);
-		const afterToolRequests = await this.middlewareRunner.runOnInterruptBoundary(this.middlewareCtx);
+		const afterToolRequests = yield* this.runWhileYielding(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);
@@ -1286,7 +1302,7 @@ var TextEngine = class {
 	}
 	async *emitBoundaryInterrupts(phase, finishEvent, toolCalls = [], requests) {
 		this.middlewareCtx.phase = phase;
-		const boundaryRequests = requests ?? await this.middlewareRunner.runOnInterruptBoundary(this.middlewareCtx);
+		const boundaryRequests = requests ?? (yield* this.runWhileYielding(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") {
@@ -1625,17 +1641,17 @@ var TextEngine = class {
 			...baseWithoutTools,
 			outputSchema: this.finalStructuredOutput.jsonSchema
 		};
-		structuredConfig = await this.middlewareRunner.runOnStructuredOutputConfig(this.middlewareCtx, structuredConfig);
+		structuredConfig = yield* this.runWhileYielding(this.middlewareRunner.runOnStructuredOutputConfig(this.middlewareCtx, structuredConfig));
 		const { outputSchema: pinnedSchema, ...chatConfigSlice } = structuredConfig;
-		const postOnConfig = await this.middlewareRunner.runOnConfig(this.middlewareCtx, {
+		const postOnConfig = yield* this.runWhileYielding(this.middlewareRunner.runOnConfig(this.middlewareCtx, {
 			...chatConfigSlice,
 			tools: baseConfig.tools
-		});
+		}));
 		this.applyMiddlewareConfig(postOnConfig);
 		const structuredCallOptions = {
 			chatOptions: {
 				model: this.params.model,
-				messages: this.messages,
+				messages: this.providerMessages,
 				metadata: postOnConfig.metadata,
 				modelOptions: postOnConfig.modelOptions,
 				systemPrompts: postOnConfig.systemPrompts,
@@ -1859,6 +1875,7 @@ var TextEngine = class {
 	buildMiddlewareConfig() {
 		return {
 			messages: this.messages,
+			providerMessages: this.messages,
 			systemPrompts: [...this.systemPrompts],
 			tools: [...this.tools],
 			resume: this.params.resume,
@@ -2072,6 +2089,7 @@ var TextEngine = class {
 	applyMiddlewareConfig(config) {
 		this.applyResumeToolState(config.resumeToolState);
 		this.messages = config.messages;
+		this.providerMessages = config.providerMessages ?? config.messages;
 		this.systemPrompts = config.systemPrompts;
 		assertUniqueToolNames(config.tools);
 		this.tools = config.tools;
@@ -2096,7 +2114,10 @@ var TextEngine = class {
 	*emitPublicChunks(outputs) {
 		for (const output of outputs) for (const spec of normalizeStreamChunk(output)) {
 			restorePublicUsage(spec);
-			if (spec.type === EventType.RUN_STARTED) this.hasPublicRunStarted = true;
+			if (spec.type === EventType.RUN_STARTED) {
+				if (this.hasPublicRunStarted) continue;
+				this.hasPublicRunStarted = true;
+			}
 			yield spec;
 			this.middlewareCtx.chunkIndex++;
 		}
@@ -2108,6 +2129,55 @@ var TextEngine = class {
 	async *pipeThroughMiddleware(chunk) {
 		const afterMw = await this.middlewareRunner.runOnChunk(this.middlewareCtx, chunk);
 		yield* this.emitPublicChunks(afterMw);
+		if (!this.drainingMiddlewareCustom) yield* this.drainMiddlewareCustomQueue();
+	}
+	/**
+	* Drain CUSTOM chunks pushed by `ctx.emitCustomEvent` through middleware
+	* and into the public stream. If the run has not yet sent `RUN_STARTED`,
+	* emit that first so CUSTOM events are not the first wire event.
+	*/
+	async *drainMiddlewareCustomQueue() {
+		if (this.drainingMiddlewareCustom) return;
+		if (this.middlewareCustomQueue.length === 0) return;
+		this.drainingMiddlewareCustom = true;
+		try {
+			yield* this.emitSyntheticRunStarted(this.createSyntheticFinishedEvent());
+			while (this.middlewareCustomQueue.length > 0) {
+				const chunk = this.middlewareCustomQueue.shift();
+				if (chunk) yield* this.pipeThroughMiddleware(chunk);
+			}
+		} finally {
+			this.drainingMiddlewareCustom = false;
+		}
+	}
+	/**
+	* Await `work` while yielding any `emitCustomEvent` chunks as they arrive.
+	*/
+	async *runWhileYielding(work) {
+		let settled = false;
+		let result;
+		let error;
+		const done = work.then((value) => {
+			settled = true;
+			result = value;
+		}, (err) => {
+			settled = true;
+			error = err;
+		});
+		while (!settled) {
+			yield* this.drainMiddlewareCustomQueue();
+			if (settled) break;
+			await Promise.race([done, new Promise((resolve) => {
+				if (this.middlewareCustomQueue.length > 0) {
+					resolve();
+					return;
+				}
+				this.middlewareCustomWaiters.push(resolve);
+			})]);
+		}
+		yield* this.drainMiddlewareCustomQueue();
+		if (error !== void 0) throw error;
+		return result;
 	}
 	/**
 	* Drain queued `sandbox.file` chunks (emitted via the SandboxRuntime sink)
@@ -2124,12 +2194,13 @@ var TextEngine = class {
 	* through the middleware pipeline and returning the final ExecuteToolCallsResult.
 	*/
 	async *drainToolCallGenerator(generator) {
-		let next = await generator.next();
-		while (!next.done) {
+		let pending = generator.next();
+		while (true) {
+			const next = yield* this.runWhileYielding(pending);
+			if (next.done) return next.value;
 			yield* this.pipeThroughMiddleware(next.value);
-			next = await generator.next();
+			pending = generator.next();
 		}
-		return next.value;
 	}
 	createCustomEventChunk(eventName, value) {
 		return {