@alexkroman1/aai 1.3.0 → 1.3.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @alexkroman1/aai@1.3.0 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.3.1 build /home/runner/work/agent/agent/packages/aai
 > tsdown && tsc -p tsconfig.build.json
 
 ℹ tsdown v0.21.7 powered by rolldown v1.0.0-rc.12
@@ -8,15 +8,15 @@
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/host/runtime-barrel.js        61.50 kB │ gzip: 18.59 kB
-ℹ dist/index.js                       6.62 kB │ gzip:  2.63 kB
+ℹ dist/host/runtime-barrel.js        63.51 kB │ gzip: 19.17 kB
+ℹ dist/index.js                       6.67 kB │ gzip:  2.65 kB
 ℹ dist/host/providers/tts-barrel.js   5.52 kB │ gzip:  2.12 kB
 ℹ dist/sdk/protocol.js                4.75 kB │ gzip:  1.76 kB
 ℹ dist/host/providers/stt-barrel.js   3.08 kB │ gzip:  1.26 kB
 ℹ dist/sdk/manifest-barrel.js         0.26 kB │ gzip:  0.17 kB
-ℹ dist/constants-VTFoymJ-.js          2.75 kB │ gzip:  1.23 kB
+ℹ dist/constants-BL3nvg4I.js          3.10 kB │ gzip:  1.38 kB
 ℹ dist/_internal-types-CoDTiBd1.js    2.33 kB │ gzip:  0.99 kB
 ℹ dist/types-Cfx_4QDK.js              1.74 kB │ gzip:  0.93 kB
 ℹ dist/ws-upgrade-BeOQ7fXL.js         1.14 kB │ gzip:  0.54 kB
-ℹ 10 files, total: 89.68 kB
-✔ Build complete in 46ms
+ℹ 10 files, total: 92.10 kB
+✔ Build complete in 43ms

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @alexkroman1/aai
 
+## 1.3.1
+
+### Patch Changes
+
+- 5a9f3d5: Pipeline session concurrency fixes: serialize turns across duplicate STT finals, bound TTS flush with abort+timeout, cascade provider errors to terminate session, atomic provider open, snapshot conversation history in tool executions.
+
 ## 1.3.0
 
 ### Minor Changes

package/dist/{constants-VTFoymJ-.js → constants-BL3nvg4I.js}

@@ -21,6 +21,13 @@ const FETCH_TIMEOUT_MS = 15e3;
 const RUN_CODE_TIMEOUT_MS = 5e3;
 /** Maximum time to wait for sessions to stop during graceful shutdown. */
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+/**
+* Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
+* forcing the turn to complete. Prevents a stuck TTS provider from wedging
+* the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
+* can still reclaim the socket cleanly.
+*/
+const PIPELINE_FLUSH_TIMEOUT_MS = 1e4;
 /** Maximum length for tool result strings sent to clients. */
 const MAX_TOOL_RESULT_CHARS = 4e3;
 /** Maximum chars for webpage text after HTML-to-text conversion. */
@@ -44,4 +51,4 @@ const WS_OPEN = 1;
 */
 const AGENT_CSP = "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' wss: ws:; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com; object-src 'none'; base-uri 'self'";
 //#endregion
-export { WS_OPEN as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_PAGE_CHARS as d, MAX_TOOL_RESULT_CHARS as f, TOOL_EXECUTION_TIMEOUT_MS as g, RUN_CODE_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, MAX_HTML_BYTES as l, MAX_WS_PAYLOAD_BYTES as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_VALUE_SIZE as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_MESSAGE_BUFFER_SIZE as u };
+export { TOOL_EXECUTION_TIMEOUT_MS as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_PAGE_CHARS as d, MAX_TOOL_RESULT_CHARS as f, RUN_CODE_TIMEOUT_MS as g, PIPELINE_FLUSH_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, MAX_HTML_BYTES as l, MAX_WS_PAYLOAD_BYTES as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_VALUE_SIZE as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_MESSAGE_BUFFER_SIZE as u, WS_OPEN as v };

package/dist/host/_pipeline-test-fakes.d.ts

@@ -59,6 +59,16 @@ export type FakeTtsProvider = TtsProvider & {
 export declare function createFakeTtsProvider(options?: {
     autoDoneOnFlush?: boolean;
 }): FakeTtsProvider;
+/**
+ * Fake STT provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — TTS should not be opened at all when STT fails.
+ */
+export declare function createFailingSttProvider(code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error", message: string): SttProvider;
+/**
+ * Fake TTS provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — STT should be closed when TTS fails.
+ */
+export declare function createFailingTtsProvider(code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error", message: string): TtsProvider;
 /**
  * A scripted stream part. `text` yields a `text-delta` in the LLM provider's
  * raw wire format; `tool-call` / `tool-result` emit the corresponding parts

package/dist/host/runtime-barrel.js

@@ -1,4 +1,4 @@
-import { a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP } from "../constants-VTFoymJ-.js";
+import { _ as TOOL_EXECUTION_TIMEOUT_MS, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as RUN_CODE_TIMEOUT_MS, h as PIPELINE_FLUSH_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP } from "../constants-BL3nvg4I.js";
 import { r as DEFAULT_SYSTEM_PROMPT } from "../types-Cfx_4QDK.js";
 import { i as toolError, n as errorDetail, r as errorMessage, t as parseWsUpgradeParams } from "../ws-upgrade-BeOQ7fXL.js";
 import { ClientMessageSchema, buildReadyConfig, lenientParse } from "../sdk/protocol.js";
@@ -518,7 +518,7 @@ function toVercelTools(schemas, ctx) {
 			const opts = {};
 			if (signal !== void 0) opts.signal = signal;
 			if (options.toolCallId !== void 0) opts.toolCallId = options.toolCallId;
-			return ctx.executeTool(schema.name, input, ctx.sessionId, ctx.messages(), opts);
+			return ctx.executeTool(schema.name, input, ctx.sessionId, ctx.messages().slice(), opts);
 		}
 	});
 	return out;
@@ -612,11 +612,30 @@ function createPipelineSession(opts) {
 	});
 	const sessionAbort = new AbortController();
 	let audioReady = false;
+	let terminated = false;
 	let turnController = null;
 	let nextReplyId = 0;
 	const sttSubs = [];
 	const ttsSubs = [];
+	/**
+	* Tear down the session after an unrecoverable provider error. Aborts the
+	* in-flight turn, cancels TTS, signals providers to close via sessionAbort,
+	* and flips `terminated` so future STT events and audio frames become
+	* no-ops. Idempotent.
+	*/
+	function terminate() {
+		if (terminated) return;
+		terminated = true;
+		if (turnController !== null) {
+			turnController.abort();
+			turnController = null;
+		}
+		ctx.tts?.cancel();
+		ctx.cancelReply();
+		sessionAbort.abort();
+	}
 	function onSttPartial(_text) {
+		if (terminated) return;
 		if (turnController === null) return;
 		log.info("Pipeline barge-in", { sessionId: opts.id });
 		turnController.abort();
@@ -626,8 +645,17 @@ function createPipelineSession(opts) {
 		client.event({ type: "cancelled" });
 	}
 	function onSttFinal(text) {
+		if (terminated) return;
 		const trimmed = text.trim();
 		if (trimmed.length === 0) return;
+		if (turnController !== null) {
+			log.info("Pipeline replacing in-flight turn", { sessionId: opts.id });
+			turnController.abort();
+			turnController = null;
+			ctx.tts?.cancel();
+			ctx.cancelReply();
+			client.event({ type: "cancelled" });
+		}
 		client.event({
 			type: "user_transcript",
 			text
@@ -641,20 +669,24 @@ function createPipelineSession(opts) {
 		ctx.chainTurn(turn);
 	}
 	function onSttError(err) {
+		if (terminated) return;
 		log.error("STT error", {
 			code: err.code,
 			message: err.message,
 			sessionId: opts.id
 		});
 		emitError(client, "stt", err.message);
+		terminate();
 	}
 	function onTtsError(err) {
+		if (terminated) return;
 		log.error("TTS error", {
 			code: err.code,
 			message: err.message,
 			sessionId: opts.id
 		});
 		emitError(client, "tts", err.message);
+		terminate();
 	}
 	async function consumeLlmStream(ctl, messages, tools, onDelta) {
 		const deps = {
@@ -689,14 +721,48 @@ function createPipelineSession(opts) {
 			}
 		}
 	}
-	function flushTtsAndWait() {
+	/**
+	* Flush TTS and wait for drain. Resolves on any of:
+	*   - TTS emits `done`
+	*   - `signal` aborts (barge-in, provider error, session stop)
+	*   - `PIPELINE_FLUSH_TIMEOUT_MS` elapses
+	* Resolves immediately if no TTS session.
+	*/
+	function flushTtsAndWait(signal) {
 		const tts = ctx.tts;
 		if (!tts) return Promise.resolve();
 		return new Promise((resolve) => {
-			const off = tts.on("done", () => {
-				off();
+			let off = null;
+			let timer = null;
+			const cleanup = () => {
+				if (off) {
+					off();
+					off = null;
+				}
+				if (timer) {
+					clearTimeout(timer);
+					timer = null;
+				}
+				signal.removeEventListener("abort", onAbort);
+			};
+			const finish = () => {
+				cleanup();
 				resolve();
-			});
+			};
+			const onAbort = () => finish();
+			if (signal.aborted) {
+				resolve();
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+			off = tts.on("done", finish);
+			timer = setTimeout(() => {
+				log.warn("TTS flush timeout", {
+					sessionId: opts.id,
+					timeoutMs: PIPELINE_FLUSH_TIMEOUT_MS
+				});
+				finish();
+			}, PIPELINE_FLUSH_TIMEOUT_MS);
 			tts.flush();
 		});
 	}
@@ -724,7 +790,7 @@ function createPipelineSession(opts) {
 			if (turnController === ctl) turnController = null;
 			return;
 		}
-		await flushTtsAndWait();
+		await flushTtsAndWait(ctl.signal);
 		if (ctl.signal.aborted) {
 			if (turnController === ctl) turnController = null;
 			return;
@@ -737,6 +803,35 @@ function createPipelineSession(opts) {
 		client.event({ type: "reply_done" });
 		if (turnController === ctl) turnController = null;
 	}
+	function reportOpenRejection(which, reason) {
+		const msg = errorMessage(reason);
+		log.error(`${which === "stt" ? "STT" : "TTS"} open failed`, {
+			error: msg,
+			sessionId: opts.id
+		});
+		emitError(client, which, msg);
+	}
+	async function adoptStt(sttSession, teardown) {
+		if (teardown) {
+			await sttSession.close().catch(() => void 0);
+			return;
+		}
+		ctx.stt = sttSession;
+		sttSubs.push(sttSession.on("partial", onSttPartial));
+		sttSubs.push(sttSession.on("final", onSttFinal));
+		sttSubs.push(sttSession.on("error", onSttError));
+	}
+	async function adoptTts(ttsSession, teardown) {
+		if (teardown) {
+			await ttsSession.close().catch(() => void 0);
+			return;
+		}
+		ctx.tts = ttsSession;
+		ttsSubs.push(ttsSession.on("audio", (pcm) => {
+			client.playAudioChunk(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
+		}));
+		ttsSubs.push(ttsSession.on("error", onTtsError));
+	}
 	async function openProviders() {
 		const [sttResult, ttsResult] = await Promise.allSettled([opts.stt.open({
 			sampleRate,
@@ -748,47 +843,15 @@ function createPipelineSession(opts) {
 			apiKey: opts.ttsApiKey,
 			signal: sessionAbort.signal
 		})]);
-		if (sttResult.status === "rejected") {
-			const msg = errorMessage(sttResult.reason);
-			log.error("STT open failed", {
-				error: msg,
-				sessionId: opts.id
-			});
-			emitError(client, "stt", msg);
-		}
-		if (ttsResult.status === "rejected") {
-			const msg = errorMessage(ttsResult.reason);
-			log.error("TTS open failed", {
-				error: msg,
-				sessionId: opts.id
-			});
-			emitError(client, "tts", msg);
-		}
+		if (sttResult.status === "rejected") reportOpenRejection("stt", sttResult.reason);
+		if (ttsResult.status === "rejected") reportOpenRejection("tts", ttsResult.reason);
 		const aborted = sessionAbort.signal.aborted;
 		const sttFailed = sttResult.status === "rejected";
 		const ttsFailed = ttsResult.status === "rejected";
 		const teardown = aborted || sttFailed || ttsFailed;
-		if (sttResult.status === "fulfilled") {
-			const sttSession = sttResult.value;
-			if (teardown) await sttSession.close().catch(() => void 0);
-			else {
-				ctx.stt = sttSession;
-				sttSubs.push(sttSession.on("partial", onSttPartial));
-				sttSubs.push(sttSession.on("final", onSttFinal));
-				sttSubs.push(sttSession.on("error", onSttError));
-			}
-		}
-		if (ttsResult.status === "fulfilled") {
-			const ttsSession = ttsResult.value;
-			if (teardown) await ttsSession.close().catch(() => void 0);
-			else {
-				ctx.tts = ttsSession;
-				ttsSubs.push(ttsSession.on("audio", (pcm) => {
-					client.playAudioChunk(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
-				}));
-				ttsSubs.push(ttsSession.on("error", onTtsError));
-			}
-		}
+		if (sttResult.status === "fulfilled") await adoptStt(sttResult.value, teardown);
+		if (ttsResult.status === "fulfilled") await adoptTts(ttsResult.value, teardown);
+		if (!aborted && (sttFailed || ttsFailed)) terminate();
 	}
 	return {
 		async start() {
@@ -807,7 +870,7 @@ function createPipelineSession(opts) {
 			await ctx.tts?.close().catch(() => {});
 		},
 		onAudio(data) {
-			if (!audioReady) return;
+			if (terminated || !audioReady) return;
 			const offset = data.byteOffset;
 			const length = data.byteLength;
 			let pcm;
@@ -823,6 +886,7 @@ function createPipelineSession(opts) {
 			audioReady = true;
 		},
 		onCancel() {
+			if (terminated) return;
 			turnController?.abort();
 			turnController = null;
 			ctx.tts?.cancel();
@@ -830,6 +894,7 @@ function createPipelineSession(opts) {
 			client.event({ type: "cancelled" });
 		},
 		onReset() {
+			if (terminated) return;
 			turnController?.abort();
 			turnController = null;
 			ctx.tts?.cancel();
@@ -839,6 +904,7 @@ function createPipelineSession(opts) {
 			client.event({ type: "reset" });
 		},
 		onHistory(incoming) {
+			if (terminated) return;
 			ctx.pushMessages(...incoming.map((m) => ({
 				role: m.role,
 				content: m.content

package/dist/host/to-vercel-tools.d.ts

@@ -22,9 +22,10 @@ export interface ToVercelToolsContext {
     /** Session id threaded to {@link executeTool}. */
     sessionId: string;
     /**
-     * Returns the current conversation history at call-time. Called per
-     * tool invocation so late calls see fresh state instead of a snapshot
-     * captured when the tool bag was built.
+     * Returns the current conversation history at call-time. The orchestrator
+     * calls this per invocation; `toVercelTools` snapshots the returned array
+     * before forwarding to `executeTool` so concurrent mutations cannot leak
+     * across tool calls.
      */
     messages: () => readonly Message[];
     /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as WS_OPEN, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, i as DEFAULT_SESSION_START_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, n as DEFAULT_IDLE_TIMEOUT_MS, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, r as DEFAULT_MAX_HISTORY, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP, u as MAX_MESSAGE_BUFFER_SIZE } from "./constants-VTFoymJ-.js";
+import { _ as TOOL_EXECUTION_TIMEOUT_MS, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as RUN_CODE_TIMEOUT_MS, h as PIPELINE_FLUSH_TIMEOUT_MS, i as DEFAULT_SESSION_START_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, n as DEFAULT_IDLE_TIMEOUT_MS, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, r as DEFAULT_MAX_HISTORY, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP, u as MAX_MESSAGE_BUFFER_SIZE, v as WS_OPEN } from "./constants-BL3nvg4I.js";
 import { i as ToolChoiceSchema, n as DEFAULT_GREETING, r as DEFAULT_SYSTEM_PROMPT, t as BuiltinToolSchema } from "./types-Cfx_4QDK.js";
 import { i as toolError, n as errorDetail, r as errorMessage, t as parseWsUpgradeParams } from "./ws-upgrade-BeOQ7fXL.js";
 //#region sdk/allowed-hosts.ts
@@ -154,4 +154,4 @@ function agent(def) {
 	};
 }
 //#endregion
-export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, matchesAllowedHost, parseWsUpgradeParams, tool, toolError, validateAllowedHostPattern };
+export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, PIPELINE_FLUSH_TIMEOUT_MS, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, matchesAllowedHost, parseWsUpgradeParams, tool, toolError, validateAllowedHostPattern };

package/dist/sdk/constants.d.ts

@@ -20,6 +20,13 @@ export declare const FETCH_TIMEOUT_MS = 15000;
 export declare const RUN_CODE_TIMEOUT_MS = 5000;
 /** Maximum time to wait for sessions to stop during graceful shutdown. */
 export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/**
+ * Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
+ * forcing the turn to complete. Prevents a stuck TTS provider from wedging
+ * the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
+ * can still reclaim the socket cleanly.
+ */
+export declare const PIPELINE_FLUSH_TIMEOUT_MS = 10000;
 /** Maximum length for tool result strings sent to clients. */
 export declare const MAX_TOOL_RESULT_CHARS = 4000;
 /** Maximum chars for webpage text after HTML-to-text conversion. */

package/dist/sdk/protocol.js

@@ -1,4 +1,4 @@
-import { f as MAX_TOOL_RESULT_CHARS } from "../constants-VTFoymJ-.js";
+import { f as MAX_TOOL_RESULT_CHARS } from "../constants-BL3nvg4I.js";
 import { z } from "zod";
 //#region sdk/protocol.ts
 /**

package/host/_pipeline-test-fakes.ts

@@ -168,6 +168,40 @@ export function createFakeTtsProvider(
   };
 }
 
+/**
+ * Fake STT provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — TTS should not be opened at all when STT fails.
+ */
+export function createFailingSttProvider(
+  code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error",
+  message: string,
+): SttProvider {
+  return {
+    name: "failing-stt",
+    async open(): Promise<SttSession> {
+      const err = Object.assign(new Error(message), { code }) as Error & { code: typeof code };
+      throw err;
+    },
+  };
+}
+
+/**
+ * Fake TTS provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — STT should be closed when TTS fails.
+ */
+export function createFailingTtsProvider(
+  code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error",
+  message: string,
+): TtsProvider {
+  return {
+    name: "failing-tts",
+    async open(): Promise<TtsSession> {
+      const err = Object.assign(new Error(message), { code }) as Error & { code: typeof code };
+      throw err;
+    },
+  };
+}
+
 // ─── Fake LLM ───────────────────────────────────────────────────────────────
 
 /**

package/host/pipeline-session.test.ts

@@ -6,6 +6,8 @@ import type { AgentConfig } from "../sdk/_internal-types.ts";
 import type { ClientEvent } from "../sdk/protocol.ts";
 import { DEFAULT_SYSTEM_PROMPT } from "../sdk/types.ts";
 import {
+  createFailingSttProvider,
+  createFailingTtsProvider,
   createFakeLanguageModel,
   createFakeSttProvider,
   createFakeTtsProvider,
@@ -335,3 +337,236 @@ describe("createPipelineSession — STT error", () => {
     await session.stop();
   });
 });
+
+describe("createPipelineSession — duplicate final", () => {
+  test("second final during AGENT_REPLYING aborts prior turn and starts new one", async () => {
+    // Multi-part first step with delay so the first turn is still streaming
+    // when the second final arrives.
+    const steps: ScriptedPart[][] = [
+      [
+        { type: "text", text: "first " },
+        { type: "text", text: "reply " },
+        { type: "text", text: "continues" },
+      ],
+      [{ type: "text", text: "second reply" }],
+    ];
+    const { opts, stt, tts, client } = makeOpts({
+      llm: createFakeLanguageModel({ steps, delayMs: 20 }),
+    });
+
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    const ttsSession = tts.last();
+    if (!(sttSession && ttsSession)) throw new Error("providers didn't open");
+
+    sttSession.fireFinal("first question");
+    await vi.waitFor(() => {
+      expect(ttsSession.sendText.mock.calls.length).toBeGreaterThan(0);
+    });
+
+    // Second final arrives mid-reply.
+    sttSession.fireFinal("second question");
+    await session.waitForTurn();
+
+    // TTS.cancel fires once to abandon the first turn's audio.
+    expect(ttsSession.cancel).toHaveBeenCalledTimes(1);
+
+    // Both user transcripts reach the client.
+    const userTranscripts = client.events.filter(
+      (e) => (e as ClientEvent).type === "user_transcript",
+    );
+    expect(userTranscripts).toHaveLength(2);
+
+    // Second reply's text was synthesized.
+    expect(ttsSession.textChunks).toContain("second reply");
+
+    // Exactly one reply_done (for the second turn).
+    const replyDones = client.events.filter((e) => (e as ClientEvent).type === "reply_done");
+    expect(replyDones).toHaveLength(1);
+
+    await session.stop();
+  });
+});
+
+describe("createPipelineSession — flush timeout/abort", () => {
+  test("flush that never drains does not wedge stop()", async () => {
+    // autoDoneOnFlush: false → TTS never fires `done`, so flushTtsAndWait must
+    // resolve via the turn-abort signal when stop() fires.
+    const script: ScriptedPart[] = [{ type: "text", text: "hi" }];
+    const tts = createFakeTtsProvider({ autoDoneOnFlush: false });
+    const { opts, stt, client } = makeOpts({
+      llm: createFakeLanguageModel({ script }),
+      tts,
+    });
+
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    const ttsSession = tts.last();
+    if (!(sttSession && ttsSession)) throw new Error("providers didn't open");
+
+    sttSession.fireFinal("hi");
+    // Wait until the turn has reached the flush step — without this guard,
+    // stop() aborts the controller before flushTtsAndWait is even called.
+    await vi.waitFor(() => {
+      expect(ttsSession.flush).toHaveBeenCalledTimes(1);
+    });
+    await session.stop();
+
+    // Turn aborted before reply_done could fire.
+    const types = eventTypes(client.events);
+    expect(types).not.toContain("reply_done");
+  });
+});
+
+describe("createPipelineSession — mid-session provider errors", () => {
+  test("STT error during reply aborts turn and stops further transcripts", async () => {
+    const script: ScriptedPart[] = [{ type: "text", text: "reply" }];
+    const { opts, stt, tts, client } = makeOpts({
+      llm: createFakeLanguageModel({ script, delayMs: 20 }),
+    });
+
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    const ttsSession = tts.last();
+    if (!(sttSession && ttsSession)) throw new Error("providers didn't open");
+
+    sttSession.fireFinal("first");
+    await vi.waitFor(() => {
+      expect(ttsSession.sendText.mock.calls.length).toBeGreaterThan(0);
+    });
+    sttSession.fireError("stt_stream_error", "socket died");
+    await session.waitForTurn();
+
+    const errors = client.events.filter((e) => (e as ClientEvent).type === "error");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({ code: "stt", message: "socket died" });
+
+    // Turn was aborted (TTS cancelled).
+    expect(ttsSession.cancel).toHaveBeenCalled();
+
+    // Further STT events are no-ops.
+    sttSession.fireFinal("ignored after error");
+    await session.waitForTurn();
+    const userTranscripts = client.events.filter(
+      (e) => (e as ClientEvent).type === "user_transcript",
+    );
+    expect(userTranscripts).toHaveLength(1);
+
+    await session.stop();
+  });
+
+  test("TTS error during reply aborts turn and stops further user transcripts", async () => {
+    const script: ScriptedPart[] = [{ type: "text", text: "reply" }];
+    const { opts, stt, tts, client } = makeOpts({
+      llm: createFakeLanguageModel({ script, delayMs: 20 }),
+    });
+
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    const ttsSession = tts.last();
+    if (!(sttSession && ttsSession)) throw new Error("providers didn't open");
+
+    sttSession.fireFinal("first");
+    await vi.waitFor(() => {
+      expect(ttsSession.sendText.mock.calls.length).toBeGreaterThan(0);
+    });
+    ttsSession.fireError("tts_stream_error", "socket died");
+    await session.waitForTurn();
+
+    const errors = client.events.filter((e) => (e as ClientEvent).type === "error");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({ code: "tts", message: "socket died" });
+
+    sttSession.fireFinal("should be ignored");
+    await session.waitForTurn();
+    const userTranscripts = client.events.filter(
+      (e) => (e as ClientEvent).type === "user_transcript",
+    );
+    expect(userTranscripts).toHaveLength(1);
+
+    await session.stop();
+  });
+
+  test("cancel/reset/history are no-ops after terminate", async () => {
+    const { opts, stt, client } = makeOpts();
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    if (!sttSession) throw new Error("STT didn't open");
+
+    sttSession.fireError("stt_stream_error", "dead");
+    await session.waitForTurn();
+
+    const eventsBefore = client.events.length;
+
+    session.onCancel();
+    session.onReset();
+    session.onHistory([{ role: "user", content: "nope" }]);
+
+    expect(client.events).toHaveLength(eventsBefore);
+
+    await session.stop();
+  });
+});
+
+describe("createPipelineSession — atomic provider open", () => {
+  test("STT is closed when TTS open fails, session becomes terminated", async () => {
+    const stt = createFakeSttProvider();
+    const failingTts = createFailingTtsProvider("tts_connect_failed", "bad key");
+
+    const { opts, client } = makeOpts({ stt, tts: failingTts });
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    const sttSession = stt.last();
+    expect(sttSession).toBeDefined();
+    expect(sttSession?.closed.value).toBe(true);
+
+    const errors = client.events.filter((e) => (e as ClientEvent).type === "error");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({ code: "tts", message: "bad key" });
+
+    // Session terminated — further STT events are no-ops (even though
+    // listeners were never wired, terminate() also ensures onCancel etc. work).
+    sttSession?.fireFinal("ignored");
+    await session.waitForTurn();
+    const userTranscripts = client.events.filter(
+      (e) => (e as ClientEvent).type === "user_transcript",
+    );
+    expect(userTranscripts).toHaveLength(0);
+
+    await session.stop();
+  });
+
+  test("TTS is never opened when STT open fails", async () => {
+    const failingStt = createFailingSttProvider("stt_connect_failed", "bad key");
+    const tts = createFakeTtsProvider();
+    const ttsOpenSpy = vi.spyOn(tts, "open");
+
+    const { opts, client } = makeOpts({ stt: failingStt, tts });
+    const session = createPipelineSession(opts);
+    await session.start();
+
+    // STT and TTS open concurrently via Promise.allSettled — TTS.open is
+    // still called, but once STT fails its result is discarded and the TTS
+    // session is closed.
+    expect(ttsOpenSpy).toHaveBeenCalledTimes(1);
+    const ttsSession = tts.last();
+    expect(ttsSession?.closed.value).toBe(true);
+
+    const errors = client.events.filter((e) => (e as ClientEvent).type === "error");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({ code: "stt", message: "bad key" });
+
+    await session.stop();
+  });
+});

package/host/pipeline-session.ts

@@ -10,11 +10,12 @@
 import type { LanguageModel, ModelMessage } from "ai";
 import { stepCountIs, streamText } from "ai";
 import type { AgentConfig, ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
-import { DEFAULT_STT_SAMPLE_RATE } from "../sdk/constants.ts";
+import { DEFAULT_STT_SAMPLE_RATE, PIPELINE_FLUSH_TIMEOUT_MS } from "../sdk/constants.ts";
 import type { ClientSink, SessionErrorCode } from "../sdk/protocol.ts";
 import type {
   SttError,
   SttProvider,
+  SttSession,
   TtsError,
   TtsProvider,
   TtsSession,
@@ -157,12 +158,32 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
 
   const sessionAbort = new AbortController();
   let audioReady = false;
+  let terminated = false;
   let turnController: AbortController | null = null;
   let nextReplyId = 0;
   const sttSubs: Unsubscribe[] = [];
   const ttsSubs: Unsubscribe[] = [];
 
+  /**
+   * Tear down the session after an unrecoverable provider error. Aborts the
+   * in-flight turn, cancels TTS, signals providers to close via sessionAbort,
+   * and flips `terminated` so future STT events and audio frames become
+   * no-ops. Idempotent.
+   */
+  function terminate(): void {
+    if (terminated) return;
+    terminated = true;
+    if (turnController !== null) {
+      turnController.abort();
+      turnController = null;
+    }
+    ctx.tts?.cancel();
+    ctx.cancelReply();
+    sessionAbort.abort();
+  }
+
   function onSttPartial(_text: string): void {
+    if (terminated) return;
     if (turnController === null) return;
     log.info("Pipeline barge-in", { sessionId: opts.id });
     turnController.abort();
@@ -173,8 +194,22 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
   }
 
   function onSttFinal(text: string): void {
+    if (terminated) return;
     const trimmed = text.trim();
     if (trimmed.length === 0) return;
+    // If a prior turn is still running (duplicate/late STT final or a
+    // second utterance without an intervening partial), abort it before
+    // launching a new one. Matches LiveKit's `current_speech.interrupt()`
+    // and Pipecat's `InterruptionFrame` broadcast: single-slot current
+    // turn, replace in-flight rather than queue.
+    if (turnController !== null) {
+      log.info("Pipeline replacing in-flight turn", { sessionId: opts.id });
+      turnController.abort();
+      turnController = null;
+      ctx.tts?.cancel();
+      ctx.cancelReply();
+      client.event({ type: "cancelled" });
+    }
     client.event({ type: "user_transcript", text });
     const turn = runTurn(trimmed).catch((err: unknown) => {
       log.error("Pipeline turn crashed", { error: errorMessage(err), sessionId: opts.id });
@@ -183,13 +218,17 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
   }
 
   function onSttError(err: SttError): void {
+    if (terminated) return;
     log.error("STT error", { code: err.code, message: err.message, sessionId: opts.id });
     emitError(client, "stt", err.message);
+    terminate();
   }
 
   function onTtsError(err: TtsError): void {
+    if (terminated) return;
     log.error("TTS error", { code: err.code, message: err.message, sessionId: opts.id });
     emitError(client, "tts", err.message);
+    terminate();
   }
 
   async function consumeLlmStream(
@@ -231,14 +270,48 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
     }
   }
 
-  function flushTtsAndWait(): Promise<void> {
+  /**
+   * Flush TTS and wait for drain. Resolves on any of:
+   *   - TTS emits `done`
+   *   - `signal` aborts (barge-in, provider error, session stop)
+   *   - `PIPELINE_FLUSH_TIMEOUT_MS` elapses
+   * Resolves immediately if no TTS session.
+   */
+  function flushTtsAndWait(signal: AbortSignal): Promise<void> {
     const tts = ctx.tts;
     if (!tts) return Promise.resolve();
     return new Promise<void>((resolve) => {
-      const off = tts.on("done", () => {
-        off();
+      let off: Unsubscribe | null = null;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      const cleanup = () => {
+        if (off) {
+          off();
+          off = null;
+        }
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        signal.removeEventListener("abort", onAbort);
+      };
+      const finish = () => {
+        cleanup();
         resolve();
-      });
+      };
+      const onAbort = () => finish();
+      if (signal.aborted) {
+        resolve();
+        return;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+      off = tts.on("done", finish);
+      timer = setTimeout(() => {
+        log.warn("TTS flush timeout", {
+          sessionId: opts.id,
+          timeoutMs: PIPELINE_FLUSH_TIMEOUT_MS,
+        });
+        finish();
+      }, PIPELINE_FLUSH_TIMEOUT_MS);
       tts.flush();
     });
   }
@@ -269,7 +342,7 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       return;
     }
 
-    await flushTtsAndWait();
+    await flushTtsAndWait(ctl.signal);
 
     if (ctl.signal.aborted) {
       if (turnController === ctl) turnController = null;
@@ -284,6 +357,40 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
     if (turnController === ctl) turnController = null;
   }
 
+  function reportOpenRejection(which: "stt" | "tts", reason: unknown): void {
+    const msg = errorMessage(reason);
+    log.error(`${which === "stt" ? "STT" : "TTS"} open failed`, {
+      error: msg,
+      sessionId: opts.id,
+    });
+    emitError(client, which, msg);
+  }
+
+  async function adoptStt(sttSession: SttSession, teardown: boolean): Promise<void> {
+    if (teardown) {
+      await sttSession.close().catch(() => undefined);
+      return;
+    }
+    ctx.stt = sttSession;
+    sttSubs.push(sttSession.on("partial", onSttPartial));
+    sttSubs.push(sttSession.on("final", onSttFinal));
+    sttSubs.push(sttSession.on("error", onSttError));
+  }
+
+  async function adoptTts(ttsSession: TtsSession, teardown: boolean): Promise<void> {
+    if (teardown) {
+      await ttsSession.close().catch(() => undefined);
+      return;
+    }
+    ctx.tts = ttsSession;
+    ttsSubs.push(
+      ttsSession.on("audio", (pcm) => {
+        client.playAudioChunk(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
+      }),
+    );
+    ttsSubs.push(ttsSession.on("error", onTtsError));
+  }
+
   async function openProviders(): Promise<void> {
     const [sttResult, ttsResult] = await Promise.allSettled([
       opts.stt.open({
@@ -299,47 +406,21 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       }),
     ]);
 
-    if (sttResult.status === "rejected") {
-      const msg = errorMessage(sttResult.reason);
-      log.error("STT open failed", { error: msg, sessionId: opts.id });
-      emitError(client, "stt", msg);
-    }
-    if (ttsResult.status === "rejected") {
-      const msg = errorMessage(ttsResult.reason);
-      log.error("TTS open failed", { error: msg, sessionId: opts.id });
-      emitError(client, "tts", msg);
-    }
+    if (sttResult.status === "rejected") reportOpenRejection("stt", sttResult.reason);
+    if (ttsResult.status === "rejected") reportOpenRejection("tts", ttsResult.reason);
 
     const aborted = sessionAbort.signal.aborted;
     const sttFailed = sttResult.status === "rejected";
     const ttsFailed = ttsResult.status === "rejected";
     const teardown = aborted || sttFailed || ttsFailed;
 
-    if (sttResult.status === "fulfilled") {
-      const sttSession = sttResult.value;
-      if (teardown) {
-        await sttSession.close().catch(() => undefined);
-      } else {
-        ctx.stt = sttSession;
-        sttSubs.push(sttSession.on("partial", onSttPartial));
-        sttSubs.push(sttSession.on("final", onSttFinal));
-        sttSubs.push(sttSession.on("error", onSttError));
-      }
-    }
-    if (ttsResult.status === "fulfilled") {
-      const ttsSession = ttsResult.value;
-      if (teardown) {
-        await ttsSession.close().catch(() => undefined);
-      } else {
-        ctx.tts = ttsSession;
-        ttsSubs.push(
-          ttsSession.on("audio", (pcm) => {
-            client.playAudioChunk(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
-          }),
-        );
-        ttsSubs.push(ttsSession.on("error", onTtsError));
-      }
-    }
+    if (sttResult.status === "fulfilled") await adoptStt(sttResult.value, teardown);
+    if (ttsResult.status === "fulfilled") await adoptTts(ttsResult.value, teardown);
+
+    // If either provider failed (but the session wasn't itself aborted),
+    // mark the session terminated so subsequent events become no-ops.
+    // Aborted-by-stop() sessions don't need terminate() — stop() handles cleanup.
+    if (!aborted && (sttFailed || ttsFailed)) terminate();
   }
 
   return {
@@ -363,7 +444,7 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       });
     },
     onAudio(data: Uint8Array): void {
-      if (!audioReady) return;
+      if (terminated || !audioReady) return;
       const offset = data.byteOffset;
       const length = data.byteLength;
       let pcm: Int16Array;
@@ -380,6 +461,7 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       audioReady = true;
     },
     onCancel(): void {
+      if (terminated) return;
       turnController?.abort();
       turnController = null;
       ctx.tts?.cancel();
@@ -387,6 +469,7 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       client.event({ type: "cancelled" });
     },
     onReset(): void {
+      if (terminated) return;
       turnController?.abort();
       turnController = null;
       ctx.tts?.cancel();
@@ -396,6 +479,7 @@ export function createPipelineSession(opts: PipelineSessionOptions): Session {
       client.event({ type: "reset" });
     },
     onHistory(incoming: readonly { role: "user" | "assistant"; content: string }[]): void {
+      if (terminated) return;
       ctx.pushMessages(...incoming.map((m) => ({ role: m.role, content: m.content })));
     },
     waitForTurn(): Promise<void> {

package/host/to-vercel-tools.test.ts

@@ -1,6 +1,7 @@
 // Copyright 2025 the AAI authors. MIT license.
 import { describe, expect, test, vi } from "vitest";
-import type { ToolSchema } from "../sdk/_internal-types.ts";
+import type { ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
+import type { Message } from "../sdk/types.ts";
 import { toVercelTools } from "./to-vercel-tools.ts";
 
 const schemas: ToolSchema[] = [
@@ -151,3 +152,36 @@ describe("toVercelTools", () => {
     expect(receivedCallId).toBe("tc-3");
   });
 });
+
+describe("toVercelTools — message snapshot isolation", () => {
+  test("tool execute sees a snapshot, not a live ref to messages array", async () => {
+    const messagesBox = { messages: [{ role: "user" as const, content: "first" }] };
+    let observedInsideExecute: readonly Message[] | undefined;
+
+    const executeTool: ExecuteTool = async (_name, _args, _sid, msgs) => {
+      observedInsideExecute = msgs;
+      // Mutate the original array; the snapshot we captured must be unaffected.
+      messagesBox.messages.push({ role: "user", content: "second" });
+      return "ok";
+    };
+
+    const tools = toVercelTools(
+      [{ name: "t", description: "", parameters: { type: "object", properties: {} } }],
+      {
+        executeTool,
+        sessionId: "s",
+        messages: () => messagesBox.messages,
+      },
+    );
+
+    const t = tools.t;
+    if (!t?.execute) throw new Error("tool.execute missing");
+    await t.execute({}, { toolCallId: "c1", messages: [] });
+
+    // The caller-observable messages array has 2 entries after the push.
+    expect(messagesBox.messages).toHaveLength(2);
+    // But the snapshot the tool executed against was frozen at length 1.
+    expect(observedInsideExecute).toHaveLength(1);
+    expect(observedInsideExecute?.[0]).toMatchObject({ content: "first" });
+  });
+});

package/host/to-vercel-tools.ts

@@ -25,9 +25,10 @@ export interface ToVercelToolsContext {
   /** Session id threaded to {@link executeTool}. */
   sessionId: string;
   /**
-   * Returns the current conversation history at call-time. Called per
-   * tool invocation so late calls see fresh state instead of a snapshot
-   * captured when the tool bag was built.
+   * Returns the current conversation history at call-time. The orchestrator
+   * calls this per invocation; `toVercelTools` snapshots the returned array
+   * before forwarding to `executeTool` so concurrent mutations cannot leak
+   * across tool calls.
    */
   messages: () => readonly Message[];
   /**
@@ -62,7 +63,10 @@ export function toVercelTools(
         const opts: ExecuteToolOptions = {};
         if (signal !== undefined) opts.signal = signal;
         if (options.toolCallId !== undefined) opts.toolCallId = options.toolCallId;
-        return ctx.executeTool(schema.name, input, ctx.sessionId, ctx.messages(), opts);
+        // Snapshot the messages array so concurrent mutation (e.g. a new
+        // turn starting after this one was aborted) can't leak into this
+        // tool's view of history.
+        return ctx.executeTool(schema.name, input, ctx.sessionId, ctx.messages().slice(), opts);
       },
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "exports": {
     ".": {

package/sdk/__snapshots__/exports.test.ts.snap

@@ -19,6 +19,7 @@ exports[`export surface stability > @alexkroman1/aai main export 1`] = `
   "MAX_TOOL_RESULT_CHARS",
   "MAX_VALUE_SIZE",
   "MAX_WS_PAYLOAD_BYTES",
+  "PIPELINE_FLUSH_TIMEOUT_MS",
   "RUN_CODE_TIMEOUT_MS",
   "TOOL_EXECUTION_TIMEOUT_MS",
   "ToolChoiceSchema",

package/sdk/constants.ts

@@ -34,6 +34,14 @@ export const RUN_CODE_TIMEOUT_MS = 5000;
 /** Maximum time to wait for sessions to stop during graceful shutdown. */
 export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
 
+/**
+ * Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
+ * forcing the turn to complete. Prevents a stuck TTS provider from wedging
+ * the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
+ * can still reclaim the socket cleanly.
+ */
+export const PIPELINE_FLUSH_TIMEOUT_MS = 10_000;
+
 // ─── Size / length limits ────────────────────────────────────────────────
 
 /** Maximum length for tool result strings sent to clients. */