@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/tts/tts-worker.ts

@@ -0,0 +1,505 @@
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import type { ProgressInfo, RawAudio } from "@huggingface/transformers";
+import {
+	ensureRuntimeInstalled,
+	getTinyModelsCacheDir,
+	installRuntimeModuleResolver,
+	resolveRuntimeModule,
+} from "@prometheus-ai/utils";
+import { resolveTinyModelDevicePreference, type TinyModelDevice, tinyModelDeviceLoadOrder } from "../tiny/device";
+import { resolveTinyModelDtypeOverride, type TinyModelDtype } from "../tiny/dtype";
+import { getTtsLocalModelSpec, resolveTtsVoice, type TtsLocalModelKey, type TtsLocalModelSpec } from "./models";
+import {
+	getTtsRuntimeDir,
+	KOKORO_PACKAGE,
+	KOKORO_VERSION,
+	ONNXRUNTIME_NODE_PACKAGE,
+	ONNXRUNTIME_NODE_VERSION,
+} from "./runtime";
+import type { TtsProgressEvent, TtsTransport, TtsWorkerInbound } from "./tts-protocol";
+
+const TTS_TASK = "text-to-speech";
+const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
+// kokoro-js is NEVER a dependency of the main tree: its transformers@3.8.1 +
+// onnxruntime-node@1.21 graph must not pollute it (1.21 segfaults Bun on session
+// creation). It is lazily `bun install`ed into a side runtime dir on first use,
+// with onnxruntime-node force-pinned to the Bun-safe version the rest of the
+// stack runs. Bump KOKORO_VERSION to roll the cached runtime + model wrapper.
+
+const ttsDevicePreference = resolveTinyModelDevicePreference();
+const ttsDtypeOverride = resolveTinyModelDtypeOverride();
+
+/** Device values `kokoro-js` accepts; the tiny device order is mapped onto these. */
+type KokoroDevice = "cpu" | "wasm" | "webgpu";
+
+/** A loaded Kokoro voice synthesizer (subset of `kokoro-js`'s `KokoroTTS`). */
+interface KokoroTtsInstance {
+	generate(text: string, options: { voice: string }): Promise<RawAudio>;
+	stream(
+		text: string | TextSplitterStreamInstance,
+		options: { voice: string },
+	): AsyncGenerator<{ text: string; phonemes: string; audio: RawAudio }, void, void>;
+}
+
+/**
+ * Incremental text source for {@link KokoroTtsInstance.stream} (subset of
+ * `kokoro-js`'s `TextSplitterStream`). Text pushed at any time is split into
+ * complete sentences; `close` flushes the trailing buffer and ends the stream.
+ */
+interface TextSplitterStreamInstance {
+	push(...texts: string[]): void;
+	close(): void;
+}
+
+/** `KokoroTTS` static surface used to load a model from the Hugging Face Hub. */
+interface KokoroRuntime {
+	KokoroTTS: {
+		from_pretrained(
+			repo: string,
+			options: {
+				dtype: TinyModelDtype;
+				device: KokoroDevice;
+				progress_callback: (info: ProgressInfo) => void;
+			},
+		): Promise<KokoroTtsInstance>;
+	};
+	TextSplitterStream: new () => TextSplitterStreamInstance;
+}
+
+/**
+ * The `@huggingface/transformers` instance `kokoro-js` runs on. We only touch its
+ * `env` (cache dir + log level) and `LogLevel`; inference goes through Kokoro.
+ */
+interface TransformersEnv {
+	env: {
+		cacheDir?: string;
+		allowLocalModels?: boolean;
+		logLevel?: unknown;
+		backends?: {
+			onnx?: {
+				logLevel?: unknown;
+			};
+		};
+	};
+	LogLevel?: {
+		ERROR: unknown;
+	};
+}
+
+const models = new Map<TtsLocalModelKey, Promise<KokoroTtsInstance>>();
+let synthesizeQueue = Promise.resolve();
+let kokoroRuntime: Promise<KokoroRuntime> | null = null;
+
+/**
+ * In-flight streaming sessions keyed by request id. A session is created on
+ * `stream-start` and torn down when its generator finishes. Text pushed before
+ * the model finishes loading is held in `buffered` and flushed into the splitter
+ * once it exists; pushes after that go straight to the live splitter.
+ */
+interface StreamSession {
+	modelKey: TtsLocalModelKey;
+	voice: string | undefined;
+	buffered: string[];
+	splitter: TextSplitterStreamInstance | null;
+	ended: boolean;
+	cancelled: boolean;
+}
+const streamSessions = new Map<string, StreamSession>();
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function sendLog(
+	transport: TtsTransport,
+	level: "debug" | "warn" | "error",
+	msg: string,
+	meta?: Record<string, unknown>,
+): void {
+	transport.send({ type: "log", level, msg, meta });
+}
+
+function sendRuntimeInstallProgress(
+	transport: TtsTransport,
+	requestId: string,
+	modelKey: TtsLocalModelKey,
+	status: "initiate" | "download" | "done",
+): void {
+	transport.send({
+		type: "progress",
+		id: requestId,
+		event: { modelKey, status, name: `${KOKORO_PACKAGE}@${KOKORO_VERSION}` },
+	});
+}
+
+/**
+ * Map a tiny-model device onto the narrow set `kokoro-js` accepts. The worker
+ * always runs `kokoro-js` on Node, where `cpu` (onnxruntime-node) is the only
+ * safe option; `webgpu`/`wasm` are honored if explicitly requested.
+ */
+function toKokoroDevice(device: TinyModelDevice): KokoroDevice {
+	if (device === "wasm") return "wasm";
+	if (device === "webgpu" || device === "gpu") return "webgpu";
+	return "cpu";
+}
+
+function configureTransformers(transformers: TransformersEnv): void {
+	transformers.env.cacheDir = getTinyModelsCacheDir();
+	transformers.env.allowLocalModels = false;
+	transformers.env.logLevel = transformers.LogLevel?.ERROR ?? "error";
+	if (transformers.env.backends?.onnx) transformers.env.backends.onnx.logLevel = "error";
+}
+
+/**
+ * Lazily `bun install` `kokoro-js` into a side runtime dir (idempotent, version-
+ * keyed) and return its module, with the `@huggingface/transformers` instance it
+ * loads configured (cache dir + quiet logging). `kokoro-js` is NEVER a dependency
+ * of the main tree: its transformers@3.8.1 graph pulls onnxruntime-node@1.21,
+ * which segfaults Bun on session creation, so the runtime manifest force-pins
+ * onnxruntime-node to the Bun-safe version via `overrides`. `sharp` is stubbed —
+ * the TTS pipeline is audio-only, so the native image codec transformers eagerly
+ * requires is dead weight. Memoized so the runtime loads once per process.
+ */
+async function loadKokoroRuntime(
+	transport: TtsTransport,
+	requestId: string,
+	modelKey: TtsLocalModelKey,
+): Promise<KokoroRuntime> {
+	if (kokoroRuntime) return kokoroRuntime;
+	kokoroRuntime = (async () => {
+		const runtimeDir = await ensureRuntimeInstalled({
+			runtimeDir: getTtsRuntimeDir(),
+			install: {
+				dependencies: { [KOKORO_PACKAGE]: KOKORO_VERSION },
+				overrides: { [ONNXRUNTIME_NODE_PACKAGE]: ONNXRUNTIME_NODE_VERSION },
+				trustedDependencies: [ONNXRUNTIME_NODE_PACKAGE],
+			},
+			probePackage: KOKORO_PACKAGE,
+			onPhase: phase => sendRuntimeInstallProgress(transport, requestId, modelKey, phase),
+		});
+		const nodeModules = path.join(runtimeDir, "node_modules");
+		const sharpStub = path.join(runtimeDir, "prometheus-sharp-stub.cjs");
+		await Bun.write(sharpStub, "module.exports = {};\n");
+		installRuntimeModuleResolver({ runtimeNodeModules: nodeModules, stubs: { sharp: sharpStub } });
+		const kokoroEntry = resolveRuntimeModule(nodeModules, KOKORO_PACKAGE);
+		if (!kokoroEntry) throw new Error(`Unable to resolve ${KOKORO_PACKAGE} in runtime at ${nodeModules}`);
+		const transformersEntry = resolveRuntimeModule(nodeModules, TRANSFORMERS_PACKAGE);
+		if (!transformersEntry) throw new Error(`Unable to resolve ${TRANSFORMERS_PACKAGE} in runtime at ${nodeModules}`);
+		const runtimeRequire = createRequire(kokoroEntry);
+		configureTransformers(runtimeRequire(transformersEntry) as TransformersEnv);
+		return runtimeRequire(kokoroEntry) as KokoroRuntime;
+	})().catch(error => {
+		kokoroRuntime = null;
+		throw error;
+	});
+	return kokoroRuntime;
+}
+
+function toProgressEvent(modelKey: TtsLocalModelKey, info: ProgressInfo): TtsProgressEvent {
+	if (info.status === "ready") {
+		return { modelKey, status: info.status, task: info.task, model: info.model };
+	}
+	if (info.status === "progress_total") {
+		return {
+			modelKey,
+			status: info.status,
+			name: info.name,
+			progress: info.progress,
+			loaded: info.loaded,
+			total: info.total,
+			files: info.files,
+		};
+	}
+	if (info.status === "progress") {
+		return {
+			modelKey,
+			status: info.status,
+			name: info.name,
+			file: info.file,
+			progress: info.progress,
+			loaded: info.loaded,
+			total: info.total,
+		};
+	}
+	return { modelKey, status: info.status, name: info.name, file: info.file };
+}
+
+function sendProgress(transport: TtsTransport, id: string, modelKey: TtsLocalModelKey, info: ProgressInfo): void {
+	transport.send({ type: "progress", id, event: toProgressEvent(modelKey, info) });
+}
+
+async function loadModelOnDevice(
+	runtime: KokoroRuntime,
+	spec: TtsLocalModelSpec,
+	modelKey: TtsLocalModelKey,
+	transport: TtsTransport,
+	requestId: string,
+	device: KokoroDevice,
+): Promise<KokoroTtsInstance> {
+	return runtime.KokoroTTS.from_pretrained(spec.repo, {
+		device,
+		dtype: ttsDtypeOverride ?? spec.dtype,
+		progress_callback: info => sendProgress(transport, requestId, modelKey, info),
+	});
+}
+
+async function loadModelWithDeviceFallback(
+	runtime: KokoroRuntime,
+	spec: TtsLocalModelSpec,
+	modelKey: TtsLocalModelKey,
+	transport: TtsTransport,
+	requestId: string,
+): Promise<{ model: KokoroTtsInstance; device: KokoroDevice }> {
+	const order = tinyModelDeviceLoadOrder(ttsDevicePreference);
+	if (order[0] !== ttsDevicePreference.device) {
+		sendLog(transport, "warn", "tts: requested device is unsafe in the worker; using CPU", {
+			modelKey,
+			repo: spec.repo,
+			requestedDevice: ttsDevicePreference.device,
+			device: order[0],
+		});
+	}
+	const devices: KokoroDevice[] = [];
+	for (const device of order) {
+		const mapped = toKokoroDevice(device);
+		if (!devices.includes(mapped)) devices.push(mapped);
+	}
+	for (let i = 0; i < devices.length; i += 1) {
+		const device = devices[i]!;
+		try {
+			return { model: await loadModelOnDevice(runtime, spec, modelKey, transport, requestId, device), device };
+		} catch (error) {
+			if (i === devices.length - 1) throw error;
+			const fallbackDevice = devices[i + 1]!;
+			sendLog(transport, "warn", "tts: accelerated device failed; falling back", {
+				modelKey,
+				repo: spec.repo,
+				device,
+				fallbackDevice,
+				error: errorMessage(error),
+			});
+		}
+	}
+	throw new Error("No TTS devices configured");
+}
+
+async function loadModel(
+	modelKey: TtsLocalModelKey,
+	transport: TtsTransport,
+	requestId: string,
+): Promise<KokoroTtsInstance> {
+	const spec = getTtsLocalModelSpec(modelKey);
+	if (!spec) throw new Error(`Unknown local TTS model: ${modelKey}`);
+	const cached = models.get(modelKey);
+	if (cached) {
+		void cached
+			.then(() => {
+				transport.send({
+					type: "progress",
+					id: requestId,
+					event: { modelKey, status: "ready", task: TTS_TASK, model: spec.repo },
+				});
+			})
+			.catch(() => undefined);
+		return cached;
+	}
+
+	const runtime = await loadKokoroRuntime(transport, requestId, modelKey);
+	const startedAt = performance.now();
+	const loaded = loadModelWithDeviceFallback(runtime, spec, modelKey, transport, requestId).then(
+		({ model, device }) => {
+			sendLog(transport, "debug", "tts: local model loaded", {
+				modelKey,
+				repo: spec.repo,
+				device,
+				requestedDevice: ttsDevicePreference.device,
+				dtype: ttsDtypeOverride ?? spec.dtype,
+				elapsedMs: Math.round(performance.now() - startedAt),
+			});
+			transport.send({
+				type: "progress",
+				id: requestId,
+				event: { modelKey, status: "ready", task: TTS_TASK, model: spec.repo },
+			});
+			return model;
+		},
+		error => {
+			models.delete(modelKey);
+			throw error;
+		},
+	);
+	models.set(modelKey, loaded);
+	return loaded;
+}
+
+async function synthesize(
+	transport: TtsTransport,
+	requestId: string,
+	modelKey: TtsLocalModelKey,
+	text: string,
+	voice: string | undefined,
+): Promise<{ pcm: Float32Array; sampleRate: number }> {
+	const synthesizer = await loadModel(modelKey, transport, requestId);
+	const output = await synthesizer.generate(text, { voice: resolveTtsVoice(modelKey, voice) });
+	const spec = getTtsLocalModelSpec(modelKey);
+	const audio = Array.isArray(output.audio) ? output.audio[0] : output.audio;
+	if (!audio) throw new Error("Kokoro synthesis returned no audio samples");
+	return { pcm: audio, sampleRate: output.sampling_rate || spec?.sampleRate || 24_000 };
+}
+
+function enqueueRequest(
+	transport: TtsTransport,
+	request: Extract<TtsWorkerInbound, { type: "synthesize" | "download" }>,
+): void {
+	synthesizeQueue = synthesizeQueue.then(
+		async () => {
+			await handleQueuedRequest(transport, request);
+		},
+		async () => {
+			await handleQueuedRequest(transport, request);
+		},
+	);
+}
+
+async function handleQueuedRequest(
+	transport: TtsTransport,
+	request: Extract<TtsWorkerInbound, { type: "synthesize" | "download" }>,
+): Promise<void> {
+	try {
+		if (request.type === "download") {
+			await loadModel(request.modelKey, transport, request.id);
+			transport.send({ type: "downloaded", id: request.id });
+			return;
+		}
+		const { pcm, sampleRate } = await synthesize(
+			transport,
+			request.id,
+			request.modelKey,
+			request.text,
+			request.voice,
+		);
+		transport.send({ type: "audio", id: request.id, pcm, sampleRate });
+	} catch (error) {
+		transport.send({ type: "error", id: request.id, error: errorText(error) });
+	}
+}
+
+/**
+ * Drive one streaming session to completion: load the model, create the
+ * splitter, flush any text pushed before the model was ready, then emit one
+ * `audio-chunk` per synthesized sentence followed by a single `stream-done`.
+ * Serialized through {@link synthesizeQueue} so it never interleaves model
+ * access with a batch synthesize/download.
+ */
+async function runStreamSession(transport: TtsTransport, id: string, session: StreamSession): Promise<void> {
+	try {
+		if (session.cancelled) return;
+		const runtime = await loadKokoroRuntime(transport, id, session.modelKey);
+		if (session.cancelled) return;
+		const synthesizer = await loadModel(session.modelKey, transport, id);
+		if (session.cancelled) return;
+		const spec = getTtsLocalModelSpec(session.modelKey);
+		const splitter = new runtime.TextSplitterStream();
+		// Flush buffered text before exposing the splitter so a push racing this
+		// block can't slip ahead of the already-queued fragments.
+		for (const text of session.buffered) {
+			if (session.cancelled) return;
+			splitter.push(text);
+		}
+		session.buffered = [];
+		session.splitter = splitter;
+		if (session.ended || session.cancelled) splitter.close();
+		const voice = resolveTtsVoice(session.modelKey, session.voice);
+		let index = 0;
+		for await (const chunk of synthesizer.stream(splitter, { voice })) {
+			if (session.cancelled) break;
+			const audio = Array.isArray(chunk.audio.audio) ? chunk.audio.audio[0] : chunk.audio.audio;
+			if (!audio) continue;
+			transport.send({
+				type: "audio-chunk",
+				id,
+				index: index++,
+				text: chunk.text,
+				pcm: audio,
+				sampleRate: chunk.audio.sampling_rate || spec?.sampleRate || 24_000,
+			});
+		}
+		if (!session.cancelled) transport.send({ type: "stream-done", id });
+	} catch (error) {
+		if (!session.cancelled) transport.send({ type: "error", id, error: errorText(error) });
+	} finally {
+		streamSessions.delete(id);
+	}
+}
+
+function startStreamSession(
+	transport: TtsTransport,
+	message: Extract<TtsWorkerInbound, { type: "stream-start" }>,
+): void {
+	const session: StreamSession = {
+		modelKey: message.modelKey,
+		voice: message.voice,
+		buffered: [],
+		splitter: null,
+		ended: false,
+		cancelled: false,
+	};
+	streamSessions.set(message.id, session);
+	synthesizeQueue = synthesizeQueue.then(
+		() => runStreamSession(transport, message.id, session),
+		() => runStreamSession(transport, message.id, session),
+	);
+}
+
+function pushToStreamSession(id: string, text: string): void {
+	const session = streamSessions.get(id);
+	if (!session || session.cancelled) return;
+	if (session.splitter) session.splitter.push(text);
+	else session.buffered.push(text);
+}
+
+function endStreamSession(id: string): void {
+	const session = streamSessions.get(id);
+	if (!session || session.cancelled) return;
+	session.ended = true;
+	session.splitter?.close();
+}
+
+function cancelStreamSession(id: string): void {
+	const session = streamSessions.get(id);
+	if (!session) return;
+	session.cancelled = true;
+	session.buffered = [];
+	session.splitter?.close();
+	streamSessions.delete(id);
+}
+
+export function startTtsWorker(transport: TtsTransport): void {
+	transport.onMessage(message => {
+		switch (message.type) {
+			case "ping":
+				transport.send({ type: "pong", id: message.id });
+				return;
+			case "stream-start":
+				startStreamSession(transport, message);
+				return;
+			case "stream-push":
+				pushToStreamSession(message.id, message.text);
+				return;
+			case "stream-end":
+				endStreamSession(message.id);
+				return;
+			case "stream-cancel":
+				cancelStreamSession(message.id);
+				return;
+			default:
+				enqueueRequest(transport, message);
+				return;
+		}
+	});
+}

package/src/tts/vocalizer.ts

@@ -0,0 +1,162 @@
+/**
+ * Streaming assistant speech-vocalization.
+ *
+ * The vocalizer turns the assistant's STREAMING output into spoken audio as a
+ * side effect of the normal turn. Text deltas are streamed *straight into the
+ * TTS engine* ({@link Vocalizer.pushDelta} → the worker's incremental text
+ * input): the engine splits the running text at sentence boundaries and emits
+ * one audio chunk per sentence, which a single {@link StreamingAudioPlayer}
+ * plays back gaplessly. So the assistant starts speaking sentence 1 while later
+ * sentences are still being generated — low latency, never overlapping.
+ *
+ * Overspeech control:
+ * - {@link clear} stops playback instantly (kills the player) and aborts
+ *   in-flight synthesis — wired to a new turn, an Esc/Ctrl+C interrupt, and a
+ *   sent message.
+ * - {@link duck}/{@link unduck} lower/restore the volume while the user is
+ *   speaking (push-to-talk), so the assistant doesn't talk over them.
+ * - Sessions are chained, so sequential utterances queue and drain in order
+ *   rather than overlapping.
+ *
+ * Errors are swallowed (debug-logged) so a synthesis or playback failure never
+ * throws into the turn. A process-level singleton ({@link vocalizer}) is shared
+ * by the event controller (streaming deltas) and the ask tool (spoken questions).
+ */
+import { logger } from "@prometheus-ai/utils";
+import { settings } from "../config/settings";
+import { DEFAULT_TTS_VOICE } from "./models";
+import { createStreamingPlayer, DUCK_GAIN } from "./streaming-player";
+import { type TtsStreamHandle, ttsClient } from "./tts-client";
+
+export interface VocalizerPlayer {
+	start(sampleRate: number): void;
+	write(pcm: Float32Array): void;
+	setGain(gain: number): void;
+	end(): Promise<void>;
+	stop(): void;
+}
+
+export class Vocalizer {
+	/** Open stream session for the current utterance; null when none is active. */
+	#handle: TtsStreamHandle | null = null;
+	/** Aborts the in-flight session on {@link clear}; replaced per session. */
+	#abort: AbortController | null = null;
+	/** The current session's player; stopped on {@link clear}, gain-tracked for ducking. */
+	#player: VocalizerPlayer | null = null;
+	/** Serialized playback chain across sessions; awaited by {@link idle}. */
+	#chain: Promise<void> = Promise.resolve();
+	/** Whether the user is currently speaking; new sessions open ducked. */
+	#ducked = false;
+	#createPlayer: () => VocalizerPlayer;
+
+	constructor(createPlayer: () => VocalizerPlayer = createStreamingPlayer) {
+		this.#createPlayer = createPlayer;
+	}
+
+	/**
+	 * Stream a delta of assistant text into the engine. No-op when vocalization
+	 * is disabled. The engine buffers the running text and emits audio for each
+	 * complete sentence; the trailing partial is flushed by {@link flush}.
+	 */
+	pushDelta(text: string): void {
+		if (!settings.get("speech.enabled")) return;
+		if (!text) return;
+		this.#ensureSession().push(text);
+	}
+
+	/**
+	 * Close the current input stream (call at message/turn end). The engine
+	 * flushes its trailing partial as a final chunk; the player keeps draining
+	 * queued audio until it completes.
+	 */
+	flush(): void {
+		this.#handle?.end();
+		this.#handle = null;
+	}
+
+	/**
+	 * Speak a complete piece of text in one shot (ask questions, yield-mode final
+	 * message): stream it in and immediately close the input. No-op when disabled.
+	 */
+	speak(text: string): void {
+		if (!settings.get("speech.enabled")) return;
+		if (!text) return;
+		this.#ensureSession().push(text);
+		this.flush();
+	}
+
+	/**
+	 * Interrupt and drop the current session, killing in-flight playback and
+	 * synthesis (new turn / user message / Esc interrupt). Audio stops at once.
+	 */
+	clear(): void {
+		this.#handle = null;
+		this.#abort?.abort();
+		this.#abort = null;
+		this.#player?.stop();
+		this.#player = null;
+	}
+
+	/** Lower the volume while the user is speaking (push-to-talk), so speech doesn't drown them out. */
+	duck(): void {
+		this.#ducked = true;
+		this.#player?.setGain(DUCK_GAIN);
+	}
+
+	/** Restore full volume once the user stops speaking. */
+	unduck(): void {
+		this.#ducked = false;
+		this.#player?.setGain(1);
+	}
+
+	/** Resolve once the playback chain has drained (tests / shutdown). */
+	idle(): Promise<void> {
+		return this.#chain;
+	}
+
+	/**
+	 * Open a streaming-synthesis session lazily on the first delta and chain its
+	 * playback after any prior session's, so sequential utterances never overlap.
+	 */
+	#ensureSession(): TtsStreamHandle {
+		if (this.#handle) return this.#handle;
+		const modelKey = settings.get("tts.localModel");
+		const voice = settings.get("speech.voice") || DEFAULT_TTS_VOICE;
+		const abort = new AbortController();
+		this.#abort = abort;
+		const handle = ttsClient.synthesizeStream(modelKey, { voice, signal: abort.signal });
+		this.#handle = handle;
+		const player = this.#createPlayer();
+		player.setGain(this.#ducked ? DUCK_GAIN : 1);
+		this.#player = player;
+		this.#chain = this.#chain.then(() => this.#play(handle, player, abort.signal));
+		return handle;
+	}
+
+	/** Feed each synthesized sentence into the player in arrival order; abort stops it. */
+	async #play(handle: TtsStreamHandle, player: VocalizerPlayer, signal: AbortSignal): Promise<void> {
+		let started = false;
+		try {
+			for await (const chunk of handle.chunks) {
+				if (signal.aborted) break;
+				if (!started) {
+					player.start(chunk.sampleRate);
+					started = true;
+				}
+				player.write(chunk.pcm);
+			}
+			if (started && !signal.aborted) {
+				await player.end();
+				return;
+			}
+		} catch (error) {
+			logger.debug("vocalizer: stream failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		player.stop();
+	}
+}
+
+/** Process-level vocalizer shared by the event controller and the ask tool. */
+export const vocalizer = new Vocalizer();