@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/tools/yield.ts

@@ -20,6 +20,14 @@ export interface YieldDetails {
 	data: unknown;
 	status: "success" | "aborted";
 	error?: string;
+	/**
+	 * Set when the yield tool exhausted its in-tool schema-retry budget
+	 * (MAX_SCHEMA_RETRIES) and accepted the data anyway. Surfaced so the
+	 * executor's post-mortem finalizer can honor the override instead of
+	 * re-rejecting the same payload with `schema_violation` — keeping the
+	 * subagent's acceptance and the parent's view of the result in lockstep.
+	 */
+	schemaOverridden?: boolean;
 }
 
 function formatSchema(schema: unknown): string {
@@ -237,7 +245,7 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 					: "Result submitted.";
 		return {
 			content: [{ type: "text", text: responseText }],
-			details: { data, status, error: errorMessage },
+			details: { data, status, error: errorMessage, schemaOverridden: schemaValidationOverridden || undefined },
 		};
 	}
 }
@@ -254,6 +262,7 @@ subprocessToolRegistry.register<YieldDetails>("yield", {
 			data: record.data,
 			status,
 			error: typeof record.error === "string" ? record.error : undefined,
+			schemaOverridden: record.schemaOverridden === true ? true : undefined,
 		};
 	},
 	shouldTerminate: event => !event.isError,

package/src/tts/downloader.ts

@@ -0,0 +1,64 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getTinyModelsCacheDir } from "@prometheus-ai/utils";
+import { getTtsLocalModelSpec } from "./models";
+import { isTtsRuntimeCached } from "./runtime";
+import { ttsClient } from "./tts-client";
+
+export interface TtsDownloadProgress {
+	stage: string;
+	/** Integer 0–100 download percent when known. */
+	percent?: number;
+}
+
+/**
+ * Whether the selected local TTS model and the side Kokoro runtime are already
+ * present. transformers.js stores `main`-revision files at
+ * `<cacheDir>/<repo>/...`, so any `.onnx` weight under the repo dir means the
+ * model weights can load without a network fetch; the Kokoro package runtime is
+ * version-keyed separately and must also exist before setup can report ready.
+ */
+export async function isTtsModelCached(modelKey: string): Promise<boolean> {
+	const spec = getTtsLocalModelSpec(modelKey);
+	if (!spec) return false;
+	const repoDir = path.join(getTinyModelsCacheDir(), ...spec.repo.split("/"));
+	try {
+		const entries = await fs.readdir(repoDir, { recursive: true });
+		const hasWeights = entries.some(entry => typeof entry === "string" && entry.endsWith(".onnx"));
+		return hasWeights && (await isTtsRuntimeCached());
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Ensure the selected local TTS model is downloaded into the transformers.js
+ * cache (and warm in the worker), streaming integer-percent Hub progress. The
+ * worker resolves the request once every model file is cached. Returns `false`
+ * if the worker is unavailable or the download failed.
+ */
+export async function downloadTtsModel(
+	modelKey: string,
+	onProgress?: (progress: TtsDownloadProgress) => void,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	const spec = getTtsLocalModelSpec(modelKey);
+	if (!spec) return false;
+	onProgress?.({ stage: `Preparing ${spec.label}...` });
+	return ttsClient.downloadModel(spec.key, {
+		signal,
+		onProgress: event => {
+			if (event.status === "ready" || event.status === "done") {
+				onProgress?.({ stage: `${spec.label} ready`, percent: 100 });
+				return;
+			}
+			const percent =
+				typeof event.total === "number" && event.total > 0 && typeof event.loaded === "number"
+					? Math.round((event.loaded / event.total) * 100)
+					: typeof event.progress === "number"
+						? Math.round(event.progress)
+						: undefined;
+			onProgress?.({ stage: `Downloading ${spec.label}`, percent });
+		},
+	});
+}

package/src/tts/index.ts

@@ -0,0 +1,8 @@
+export * from "./downloader";
+export * from "./models";
+export * from "./runtime";
+export * from "./tts-client";
+export * from "./tts-protocol";
+export * from "./tts-worker";
+export * from "./vocalizer";
+export * from "./wav";

package/src/tts/models.ts

@@ -0,0 +1,137 @@
+import type { TinyModelDtype } from "../tiny/dtype";
+
+/**
+ * Voice exposed by a local TTS model. Kokoro ships a fixed catalog of named
+ * voices; a voice is just a stable id (e.g. `af_heart`) plus a display label.
+ * Selection is purely on-device — generating with a different voice needs no
+ * extra network fetch once the model weights are cached.
+ */
+export interface TtsLocalVoiceSpec {
+	id: string;
+	label: string;
+}
+
+/**
+ * A local (on-device, ONNX) text-to-speech model the worker can load. `repo` is
+ * the Hugging Face model id loaded through `kokoro-js`
+ * (`KokoroTTS.from_pretrained`), which runs on the same `@huggingface/transformers`
+ * + `onnxruntime` runtime as the rest of the tiny-model stack and bundles the
+ * misaki/espeak phonemizer Kokoro needs. `dtype` is the default ONNX precision
+ * (overridable via `providers.tinyModelDtype`/`PROMETHEUS_TINY_DTYPE`).
+ */
+export interface TtsLocalModelSpec {
+	key: string;
+	repo: string;
+	dtype: TinyModelDtype;
+	/** PCM sample rate the model emits; fallback only — the worker uses the value RawAudio reports. */
+	sampleRate: number;
+	label: string;
+	description: string;
+	/** First entry is the model's default voice. */
+	voices: readonly TtsLocalVoiceSpec[];
+}
+
+/**
+ * Curated Kokoro-82M voice catalog. Kokoro ships ~28 voices; we surface the
+ * higher-graded ones across American/British × female/male so the picker stays
+ * useful without listing every D/F-grade sample. `af_heart` (grade A) leads and
+ * is the default voice. Grades are Kokoro's own `overallGrade` ratings.
+ */
+export const KOKORO_VOICES: readonly TtsLocalVoiceSpec[] = [
+	{ id: "af_heart", label: "Heart (American female)" },
+	{ id: "af_bella", label: "Bella (American female)" },
+	{ id: "af_nicole", label: "Nicole (American female)" },
+	{ id: "af_aoede", label: "Aoede (American female)" },
+	{ id: "af_kore", label: "Kore (American female)" },
+	{ id: "af_sarah", label: "Sarah (American female)" },
+	{ id: "am_michael", label: "Michael (American male)" },
+	{ id: "am_fenrir", label: "Fenrir (American male)" },
+	{ id: "am_puck", label: "Puck (American male)" },
+	{ id: "bf_emma", label: "Emma (British female)" },
+	{ id: "bm_george", label: "George (British male)" },
+	{ id: "bm_fable", label: "Fable (British male)" },
+] as const;
+
+/** Default voice within the default model — Kokoro's flagship grade-A voice. */
+export const DEFAULT_TTS_VOICE = "af_heart";
+
+/** Default local TTS model used when `tts.localModel` is unset. */
+export const DEFAULT_TTS_LOCAL_MODEL_KEY = "kokoro";
+
+/**
+ * Local TTS model registry. Kokoro-82M is the on-device SoTA tiny TTS (tops the
+ * TTS Arena leaderboard); the `onnx-community` ONNX export runs through
+ * `kokoro-js` on the shared transformers.js/onnxruntime worker. q8 keeps the
+ * weights ~100 MB and CPU inference fast while preserving quality. One model
+ * spans every voice/accent — language selection is a voice choice, not a
+ * separate download.
+ */
+export const TTS_LOCAL_MODELS = [
+	{
+		key: "kokoro",
+		repo: "onnx-community/Kokoro-82M-v1.0-ONNX",
+		dtype: "q8",
+		sampleRate: 24_000,
+		label: "Kokoro-82M",
+		description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local",
+		voices: KOKORO_VOICES,
+	},
+] as const satisfies readonly TtsLocalModelSpec[];
+
+export type TtsLocalModelKey = (typeof TTS_LOCAL_MODELS)[number]["key"];
+
+export const TTS_LOCAL_MODEL_VALUES = ["kokoro"] as const;
+
+type MissingTtsModelValue = Exclude<TtsLocalModelKey, (typeof TTS_LOCAL_MODEL_VALUES)[number]>;
+type ExtraTtsModelValue = Exclude<(typeof TTS_LOCAL_MODEL_VALUES)[number], TtsLocalModelKey>;
+const TTS_LOCAL_MODEL_VALUES_MATCH_REGISTRY: MissingTtsModelValue extends never
+	? ExtraTtsModelValue extends never
+		? true
+		: never
+	: never = true;
+void TTS_LOCAL_MODEL_VALUES_MATCH_REGISTRY;
+
+export const TTS_LOCAL_MODEL_OPTIONS = [
+	{
+		value: "kokoro",
+		label: "Kokoro-82M",
+		description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local",
+	},
+] as const satisfies ReadonlyArray<{ value: TtsLocalModelKey; label: string; description: string }>;
+
+/** Voice options for the `tts.localVoice` setting picker (default model's catalog). */
+export const TTS_LOCAL_VOICE_OPTIONS = KOKORO_VOICES.map(voice => ({
+	value: voice.id,
+	label: voice.label,
+})) as ReadonlyArray<{ value: string; label: string }>;
+
+/** Accepted `tts.localVoice` values (default model's catalog) for schema validation. */
+export const TTS_LOCAL_VOICE_VALUES = KOKORO_VOICES.map(voice => voice.id) as readonly string[];
+
+export function getTtsLocalModelSpec(key: string): TtsLocalModelSpec | undefined {
+	return TTS_LOCAL_MODELS.find(model => model.key === key);
+}
+
+export function isTtsLocalModelKey(value: string): value is TtsLocalModelKey {
+	return getTtsLocalModelSpec(value) !== undefined;
+}
+
+/** Resolve a model key (or the default) to its Hugging Face repo id. */
+export function resolveTtsRepo(modelKey: string | undefined): string {
+	const spec = (modelKey && getTtsLocalModelSpec(modelKey)) || getTtsLocalModelSpec(DEFAULT_TTS_LOCAL_MODEL_KEY);
+	if (!spec) throw new Error(`No local TTS model registered for key: ${modelKey ?? DEFAULT_TTS_LOCAL_MODEL_KEY}`);
+	return spec.repo;
+}
+
+/**
+ * Resolve a requested voice id to a concrete voice the model supports, falling
+ * back to the model's default voice (first entry) when the id is unknown or the
+ * legacy `"default"` sentinel. The returned id is always a valid Kokoro voice.
+ */
+export function resolveTtsVoice(modelKey: string | undefined, voice: string | undefined): string {
+	const spec = (modelKey && getTtsLocalModelSpec(modelKey)) || getTtsLocalModelSpec(DEFAULT_TTS_LOCAL_MODEL_KEY);
+	const fallback = spec?.voices[0]?.id ?? DEFAULT_TTS_VOICE;
+	if (!spec || !voice) return fallback;
+	const match = spec.voices.find(v => v.id === voice);
+	return match ? match.id : fallback;
+}

package/src/tts/player.ts

@@ -0,0 +1,137 @@
+/**
+ * Cross-platform audio-file playback via the system's built-in players.
+ *
+ * The selection logic is split into a pure, injectable builder
+ * ({@link playerCommandsFor}) so it can be unit-tested without spawning a
+ * process or touching PATH, and a thin runtime wrapper ({@link playAudioFile})
+ * that walks the resulting fallback chain.
+ */
+import * as fs from "node:fs/promises";
+import { $which } from "@prometheus-ai/utils";
+import { getToolPath } from "../utils/tools-manager";
+
+export interface PlayerCommand {
+	cmd: string;
+	args: string[];
+}
+
+/** Injection seam for {@link playerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface PlayerLookup {
+	which?: (bin: string) => string | null;
+	ffmpeg?: () => string | null;
+}
+
+/**
+ * Build the ordered list of playback commands to try for `filePath` on the
+ * given platform. Pure + injectable so the selection logic is testable without
+ * spawning anything.
+ *
+ * - darwin: `afplay` (always present on macOS).
+ * - win32: PowerShell `Media.SoundPlayer.PlaySync()` (no extra deps).
+ * - linux/other POSIX: `paplay` (PulseAudio) → `aplay` (ALSA) → the bundled
+ *   static `ffmpeg` (`-f pulse` then `-f alsa`). Empty result means nothing is
+ *   available and the caller should surface an install hint.
+ */
+export function playerCommandsFor(
+	platform: NodeJS.Platform,
+	filePath: string,
+	lookup: PlayerLookup = {},
+): PlayerCommand[] {
+	const which = lookup.which ?? $which;
+	const ffmpeg = lookup.ffmpeg ?? ((): string | null => getToolPath("ffmpeg"));
+
+	if (platform === "darwin") {
+		return [{ cmd: "afplay", args: [filePath] }];
+	}
+	if (platform === "win32") {
+		return [
+			{
+				cmd: "powershell",
+				args: ["-NoProfile", "-Command", `(New-Object Media.SoundPlayer '${filePath}').PlaySync()`],
+			},
+		];
+	}
+
+	// Linux and other POSIX desktops share the PulseAudio/ALSA fallback chain.
+	const commands: PlayerCommand[] = [];
+	const paplay = which("paplay");
+	if (paplay) commands.push({ cmd: paplay, args: [filePath] });
+	const aplay = which("aplay");
+	if (aplay) commands.push({ cmd: aplay, args: [filePath] });
+	const ffmpegBin = ffmpeg();
+	if (ffmpegBin) {
+		commands.push({
+			cmd: ffmpegBin,
+			args: ["-loglevel", "error", "-nostdin", "-i", filePath, "-f", "pulse", "default"],
+		});
+		commands.push({
+			cmd: ffmpegBin,
+			args: ["-loglevel", "error", "-nostdin", "-i", filePath, "-f", "alsa", "default"],
+		});
+	}
+	return commands;
+}
+
+export interface PlayAudioOptions {
+	signal?: AbortSignal;
+}
+
+function playbackAbortError(signal: AbortSignal): Error {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new DOMException("Audio playback aborted", "AbortError");
+}
+
+/**
+ * Play `filePath` through the speakers, trying each candidate command in order
+ * and returning on the first clean exit. Throws an actionable Error if no
+ * player exists or every candidate fails (with the collected stderr).
+ */
+export async function playAudioFile(filePath: string, options: PlayAudioOptions = {}): Promise<void> {
+	const { signal } = options;
+	if (signal?.aborted) throw playbackAbortError(signal);
+	const commands = playerCommandsFor(process.platform, filePath);
+	if (commands.length === 0) {
+		throw new Error(
+			"No audio player available. Install PulseAudio (paplay) or ALSA (aplay), " +
+				"or run `prometheus setup speech` to download a bundled ffmpeg.",
+		);
+	}
+
+	const failures: string[] = [];
+	for (const command of commands) {
+		if (signal?.aborted) throw playbackAbortError(signal);
+		try {
+			const proc = Bun.spawn([command.cmd, ...command.args], { stdout: "ignore", stderr: "pipe" });
+			let killTimer: NodeJS.Timeout | undefined;
+			const abort = (): void => {
+				proc.kill("SIGTERM");
+				killTimer = setTimeout(() => proc.kill("SIGKILL"), 500);
+				killTimer.unref?.();
+			};
+			signal?.addEventListener("abort", abort, { once: true });
+			try {
+				const code = await proc.exited;
+				if (signal?.aborted) throw playbackAbortError(signal);
+				if (code === 0) return;
+				let stderr = "";
+				if (proc.stderr && typeof proc.stderr !== "number") {
+					stderr = await new Response(proc.stderr as ReadableStream).text();
+				}
+				failures.push(`${command.cmd} exited ${code}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+			} finally {
+				signal?.removeEventListener("abort", abort);
+				if (killTimer) clearTimeout(killTimer);
+			}
+		} catch (err) {
+			if (signal?.aborted) throw playbackAbortError(signal);
+			failures.push(`${command.cmd}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+
+	throw new Error(`Audio playback failed:\n${failures.join("\n")}`);
+}
+
+/** Best-effort temp-file cleanup used by callers after playback. */
+export async function removeTempFile(filePath: string): Promise<void> {
+	await fs.unlink(filePath).catch(() => {});
+}

package/src/tts/runtime.ts

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+import { getTinyModelsCacheDir } from "@prometheus-ai/utils";
+
+export const KOKORO_PACKAGE = "kokoro-js";
+export const KOKORO_VERSION = "1.2.1";
+export const ONNXRUNTIME_NODE_PACKAGE = "onnxruntime-node";
+export const ONNXRUNTIME_NODE_VERSION = "1.26.0";
+
+export function getTtsRuntimeDir(): string {
+	const runtimeKey = KOKORO_VERSION.replace(/[^A-Za-z0-9._-]/g, "_");
+	return path.join(path.dirname(getTinyModelsCacheDir()), "tts-runtime", `kokoro-${runtimeKey}`);
+}
+
+export async function isTtsRuntimeCached(): Promise<boolean> {
+	try {
+		const pkg = await Bun.file(path.join(getTtsRuntimeDir(), "node_modules", KOKORO_PACKAGE, "package.json")).json();
+		return typeof pkg === "object" && pkg !== null && "version" in pkg && pkg.version === KOKORO_VERSION;
+	} catch {
+		return false;
+	}
+}

package/src/tts/streaming-player.ts

@@ -0,0 +1,266 @@
+/**
+ * Gapless streaming audio output for assistant speech.
+ *
+ * Replaces the spawn-`afplay`-per-sentence approach (a fresh process per chunk
+ * meant audible gaps, per-spawn latency, and no way to interrupt a clip mid-play)
+ * with a single persistent player process fed raw 32-bit-float mono PCM over
+ * stdin. Chunks are queued and drained by one writer so sentences play back to
+ * back; writes are paced to stay only {@link LEAD_SECONDS} ahead of realtime so
+ * ducking and stop take effect promptly instead of after seconds of buffered
+ * audio. {@link StreamingAudioPlayer.stop} kills the process for instant silence.
+ *
+ * Where no streaming backend exists (Windows, or macOS without the bundled
+ * ffmpeg), it degrades to the per-file {@link playAudioFile} path so speech still
+ * works — just without gapless playback or mid-clip interruption.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $which, logger, Snowflake } from "@prometheus-ai/utils";
+import type { FileSink, Subprocess } from "bun";
+import { getToolPath } from "../utils/tools-manager";
+import { type PlayerCommand, playAudioFile } from "./player";
+import { encodeWav } from "./wav";
+
+/** Kokoro emits 24 kHz mono; used when a chunk does not declare a rate. */
+const DEFAULT_SAMPLE_RATE = 24_000;
+/** Cap how far ahead of realtime we buffer into the player so duck/stop are responsive. */
+const LEAD_SECONDS = 0.6;
+/** Output gain applied while ducked (the user is speaking over the assistant). */
+export const DUCK_GAIN = 0.25;
+
+/** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface StreamingPlayerLookup {
+	which?: (bin: string) => string | null;
+	ffmpeg?: () => string | null;
+}
+
+/**
+ * Ordered candidate commands for a persistent raw-PCM player on `platform`: each
+ * reads 32-bit-float little-endian mono PCM at `sampleRate` from stdin (`pipe:0`)
+ * and plays it to the default output device. An empty list means no streaming
+ * backend is available and the caller should fall back to per-file playback.
+ *
+ * - darwin: none; `afplay` is file-only, so macOS uses the interruptible
+ *   per-file fallback.
+ * - linux/other POSIX: `ffmpeg` (`-f pulse` then `-f alsa`) → `paplay`/`aplay`
+ *   raw fallbacks.
+ * - win32: none (PowerShell `SoundPlayer` is file-only).
+ */
+export function streamingPlayerCommandsFor(
+	platform: NodeJS.Platform,
+	sampleRate: number,
+	lookup: StreamingPlayerLookup = {},
+): PlayerCommand[] {
+	const which = lookup.which ?? $which;
+	const ffmpeg = lookup.ffmpeg ?? ((): string | null => getToolPath("ffmpeg"));
+	const rate = String(sampleRate > 0 ? sampleRate : DEFAULT_SAMPLE_RATE);
+	const input = ["-loglevel", "error", "-nostdin", "-f", "f32le", "-ar", rate, "-ac", "1", "-i", "pipe:0"];
+
+	if (platform === "darwin") return [];
+	if (platform === "win32") {
+		return [];
+	}
+
+	const commands: PlayerCommand[] = [];
+	const ffmpegBin = ffmpeg();
+	if (ffmpegBin) {
+		commands.push({ cmd: ffmpegBin, args: [...input, "-f", "pulse", "default"] });
+		commands.push({ cmd: ffmpegBin, args: [...input, "-f", "alsa", "default"] });
+	}
+	const paplay = which("paplay");
+	if (paplay) commands.push({ cmd: paplay, args: ["--raw", `--rate=${rate}`, "--format=float32le", "--channels=1"] });
+	const aplay = which("aplay");
+	if (aplay) commands.push({ cmd: aplay, args: ["-q", "-f", "FLOAT_LE", "-r", rate, "-c", "1", "-"] });
+	return commands;
+}
+
+/**
+ * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
+ * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
+ * reusable after stop/end — create a new instance per utterance.
+ */
+export class StreamingAudioPlayer {
+	#queue: Float32Array[] = [];
+	#sampleRate = DEFAULT_SAMPLE_RATE;
+	#gain = 1;
+	#mode: "stream" | "file" = "file";
+	#proc: Subprocess<"pipe", "ignore", "ignore"> | null = null;
+	#sink: FileSink | null = null;
+	#writtenSec = 0;
+	#startedAt = 0;
+	#started = false;
+	#inputClosed = false;
+	#stopped = false;
+	#abortController = new AbortController();
+	#wake: (() => void) | null = null;
+	#drain: Promise<void> = Promise.resolve();
+
+	/** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
+	start(sampleRate: number): void {
+		if (this.#started || this.#stopped) return;
+		this.#started = true;
+		this.#sampleRate = sampleRate > 0 ? sampleRate : DEFAULT_SAMPLE_RATE;
+		this.#mode = this.#spawnStream() ? "stream" : "file";
+		this.#startedAt = performance.now();
+		this.#drain = this.#drainLoop();
+	}
+
+	/** Queue a mono float32 PCM chunk for playback in arrival order. */
+	write(pcm: Float32Array): void {
+		if (this.#stopped) return;
+		this.#queue.push(pcm);
+		this.#signal();
+	}
+
+	/** Scale subsequent output (1 = normal, <1 = ducked). Applies within {@link LEAD_SECONDS}. */
+	setGain(gain: number): void {
+		this.#gain = gain < 0 ? 0 : gain;
+	}
+
+	/** Close the input; resolves once all queued audio has finished playing. */
+	async end(): Promise<void> {
+		this.#inputClosed = true;
+		this.#signal();
+		await this.#drain;
+	}
+
+	/** Stop immediately: kill the player, drop everything still queued. */
+	stop(): void {
+		if (this.#stopped) return;
+		this.#stopped = true;
+		this.#queue.length = 0;
+		this.#abortController.abort();
+		this.#signal();
+		try {
+			this.#sink?.end();
+		} catch {}
+		try {
+			this.#proc?.kill("SIGKILL");
+		} catch {}
+	}
+
+	#spawnStream(): boolean {
+		for (const command of streamingPlayerCommandsFor(process.platform, this.#sampleRate)) {
+			try {
+				const proc = Bun.spawn([command.cmd, ...command.args], {
+					stdin: "pipe",
+					stdout: "ignore",
+					stderr: "ignore",
+				});
+				this.#proc = proc;
+				this.#sink = proc.stdin;
+				return true;
+			} catch (error) {
+				logger.debug("tts: streaming player spawn failed", {
+					cmd: command.cmd,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		return false;
+	}
+
+	#signal(): void {
+		const wake = this.#wake;
+		this.#wake = null;
+		wake?.();
+	}
+
+	async #drainLoop(): Promise<void> {
+		try {
+			while (!this.#stopped) {
+				const chunk = this.#queue.shift();
+				if (!chunk) {
+					if (this.#inputClosed) break;
+					await this.#waitForWork();
+					continue;
+				}
+				if (this.#mode === "stream") {
+					// Pace writes so the player buffers ~LEAD_SECONDS, no more, keeping
+					// ducking and stop responsive instead of locked behind buffered audio.
+					const ahead = this.#writtenSec - (performance.now() - this.#startedAt) / 1000;
+					if (ahead > LEAD_SECONDS) {
+						await Bun.sleep((ahead - LEAD_SECONDS) * 1000);
+						if (this.#stopped) return;
+					}
+					this.#writeStream(chunk);
+					this.#writtenSec += chunk.length / this.#sampleRate;
+				} else {
+					await this.#playFile(chunk);
+				}
+			}
+			if (!this.#stopped && this.#mode === "stream") {
+				try {
+					await this.#sink?.end();
+				} catch {}
+				if (this.#proc) {
+					try {
+						await this.#proc.exited;
+					} catch {}
+				}
+			}
+		} catch (error) {
+			logger.debug("tts: streaming player drain failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	/** Block until a chunk is queued, the input closes, or stop is called. */
+	#waitForWork(): Promise<void> {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#wake = resolve;
+		// Re-check after arming to close the gap between the empty shift and here.
+		if (this.#queue.length > 0 || this.#inputClosed || this.#stopped) {
+			this.#wake = null;
+			resolve();
+		}
+		return promise;
+	}
+
+	#writeStream(pcm: Float32Array): void {
+		const sink = this.#sink;
+		if (!sink) return;
+		try {
+			sink.write(this.#bytes(pcm));
+			sink.flush();
+		} catch (error) {
+			logger.debug("tts: streaming write failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	async #playFile(pcm: Float32Array): Promise<void> {
+		const wavPath = path.join(os.tmpdir(), `prometheus-speech-${Snowflake.next()}.wav`);
+		try {
+			await fs.writeFile(wavPath, encodeWav(this.#scaled(pcm), this.#sampleRate));
+			if (!this.#stopped) await playAudioFile(wavPath, { signal: this.#abortController.signal });
+		} catch (error) {
+			logger.debug("tts: file playback failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		} finally {
+			await fs.unlink(wavPath).catch(() => {});
+		}
+	}
+
+	/** Raw f32le bytes for the stream sink, applying gain only when ducked (avoids a copy at unity). */
+	#bytes(pcm: Float32Array): Uint8Array {
+		if (this.#gain === 1) return new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+		return new Uint8Array(this.#scaled(pcm).buffer);
+	}
+
+	#scaled(pcm: Float32Array): Float32Array {
+		if (this.#gain === 1) return pcm;
+		const out = new Float32Array(pcm.length);
+		for (let i = 0; i < pcm.length; i++) out[i] = (pcm[i] ?? 0) * this.#gain;
+		return out;
+	}
+}
+
+/** Factory the vocalizer calls; a function so tests can stub it without spawning a player. */
+export function createStreamingPlayer(): StreamingAudioPlayer {
+	return new StreamingAudioPlayer();
+}