@p8n.ai/pi-listens 0.1.0

package/src/audio.ts

@@ -0,0 +1,361 @@
+import { mkdir, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { once } from "node:events";
+import type { PiListensConfig } from "./config.js";
+
+export interface AudioRuntime {
+	record(seconds?: number, signal?: AbortSignal): Promise<string>;
+	streamPcm(signal?: AbortSignal): AsyncIterable<Buffer>;
+	play(path: string, signal?: AbortSignal): Promise<void>;
+	cleanup(path: string): Promise<void>;
+	stopAll(): void;
+	describe(): { recorder: string; player: string };
+}
+
+export function createAudioRuntime(config: PiListensConfig): AudioRuntime {
+	const recorder = config.recordCommand ? "custom" : detectRecorder();
+	const player = config.playCommand ? "custom" : detectPlayer();
+
+	return {
+		async record(seconds = config.recordSeconds, signal?: AbortSignal): Promise<string> {
+			if (!recorder) {
+				throw new Error(
+					"No microphone recorder found. Install sox (`rec`) or ffmpeg, or set PI_LISTENS_RECORD_COMMAND. See README for command templates.",
+				);
+			}
+			await mkdir(config.audioDir, { recursive: true });
+			const path = join(config.audioDir, `pi-listens-input-${Date.now()}-${randomUUID()}.wav`);
+			const useUtteranceMode = config.recordMode === "utterance" && recorder === "rec";
+			const command = config.recordCommand
+				? customCommand(config.recordCommand, {
+					path,
+					seconds,
+					sampleRate: config.recordSampleRate,
+					silenceStartSeconds: config.silenceStartSeconds,
+					silenceStopSeconds: config.silenceStopSeconds,
+					silenceThreshold: config.silenceThreshold,
+				})
+				: useUtteranceMode
+					? utteranceRecorderCommand(recorder, path, config.recordSampleRate, config.silenceStartSeconds, config.silenceStopSeconds, config.silenceThreshold)
+					: recorderCommand(recorder, path, seconds, config.recordSampleRate);
+			await run(command.command, command.args, signal, useUtteranceMode ? { timeoutMs: seconds * 1000, resolveOnTimeout: true } : undefined);
+			return path;
+		},
+
+		streamPcm(signal?: AbortSignal): AsyncIterable<Buffer> {
+			if (!recorder) {
+				throw new Error(
+					"No microphone recorder found. Install sox (`rec`) or ffmpeg, or set PI_LISTENS_STREAM_COMMAND. See README for command templates.",
+				);
+			}
+			const command = config.streamCommand
+				? customCommand(config.streamCommand, { sampleRate: config.recordSampleRate })
+				: pcmStreamCommand(recorder, config.recordSampleRate);
+			return streamCommandOutput(command.command, command.args, signal);
+		},
+
+		async play(path: string, signal?: AbortSignal): Promise<void> {
+			if (!player) {
+				throw new Error(
+					"No audio player found. Install afplay, sox (`play`), ffplay, or aplay, or set PI_LISTENS_PLAY_COMMAND. See README for command templates.",
+				);
+			}
+			const command = config.playCommand ? customCommand(config.playCommand, { path }) : playerCommand(player, path);
+			await run(command.command, command.args, signal);
+		},
+
+		async cleanup(path: string): Promise<void> {
+			if (!config.deleteAudio) return;
+			await rm(path, { force: true }).catch(() => undefined);
+		},
+
+		stopAll(): void {
+			stopActiveAudioProcesses();
+		},
+
+		describe() {
+			return { recorder: recorder ?? "missing", player: player ?? "missing" };
+		},
+	};
+}
+
+type CommandSpec = { command: string; args: string[] };
+
+function recorderCommand(recorder: string, path: string, seconds: number, sampleRate: number): CommandSpec {
+	if (recorder === "rec") {
+		return { command: "rec", args: ["-q", "-r", String(sampleRate), "-c", "1", "-b", "16", path, "trim", "0", String(seconds)] };
+	}
+	if (recorder === "ffmpeg-avfoundation") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-y", "-f", "avfoundation", "-i", ":0", "-t", String(seconds), "-ar", String(sampleRate), "-ac", "1", path],
+		};
+	}
+	if (recorder === "ffmpeg-alsa") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-y", "-f", "alsa", "-i", "default", "-t", String(seconds), "-ar", String(sampleRate), "-ac", "1", path],
+		};
+	}
+	if (recorder === "ffmpeg-pulse") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-y", "-f", "pulse", "-i", "default", "-t", String(seconds), "-ar", String(sampleRate), "-ac", "1", path],
+		};
+	}
+	throw new Error(`Unsupported recorder: ${recorder}`);
+}
+
+function pcmStreamCommand(recorder: string, sampleRate: number): CommandSpec {
+	if (recorder === "rec") {
+		return { command: "rec", args: ["-q", "-r", String(sampleRate), "-c", "1", "-b", "16", "-e", "signed-integer", "-t", "raw", "-"] };
+	}
+	if (recorder === "ffmpeg-avfoundation") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-f", "avfoundation", "-i", ":0", "-ar", String(sampleRate), "-ac", "1", "-f", "s16le", "pipe:1"],
+		};
+	}
+	if (recorder === "ffmpeg-alsa") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-f", "alsa", "-i", "default", "-ar", String(sampleRate), "-ac", "1", "-f", "s16le", "pipe:1"],
+		};
+	}
+	if (recorder === "ffmpeg-pulse") {
+		return {
+			command: "ffmpeg",
+			args: ["-hide_banner", "-loglevel", "error", "-f", "pulse", "-i", "default", "-ar", String(sampleRate), "-ac", "1", "-f", "s16le", "pipe:1"],
+		};
+	}
+	throw new Error(`Unsupported streaming recorder: ${recorder}`);
+}
+
+function utteranceRecorderCommand(
+	recorder: string,
+	path: string,
+	sampleRate: number,
+	silenceStartSeconds: number,
+	silenceStopSeconds: number,
+	silenceThreshold: string,
+ ): CommandSpec {
+	if (recorder === "rec") {
+		return {
+			command: "rec",
+			args: [
+				"-q",
+				"-r",
+				String(sampleRate),
+				"-c",
+				"1",
+				"-b",
+				"16",
+				path,
+				"silence",
+				"1",
+				String(silenceStartSeconds),
+				silenceThreshold,
+				"1",
+				String(silenceStopSeconds),
+				silenceThreshold,
+			],
+		};
+	}
+	throw new Error(`Unsupported utterance recorder: ${recorder}`);
+}
+
+function playerCommand(player: string, path: string): CommandSpec {
+	if (player === "afplay") return { command: "afplay", args: [path] };
+	if (player === "play") return { command: "play", args: ["-q", path] };
+	if (player === "ffplay") return { command: "ffplay", args: ["-nodisp", "-autoexit", "-loglevel", "error", path] };
+	if (player === "aplay") return { command: "aplay", args: [path] };
+	throw new Error(`Unsupported player: ${player}`);
+}
+
+function customCommand(template: string, values: Record<string, string | number>): CommandSpec {
+	let command = template;
+	for (const [key, value] of Object.entries(values)) {
+		command = command.replaceAll(`{${key}}`, shellQuote(String(value)));
+	}
+	return { command: "sh", args: ["-lc", command] };
+}
+
+function detectRecorder(): string | null {
+	if (isCommandAvailable("rec")) return "rec";
+	if (isCommandAvailable("ffmpeg")) {
+		if (process.platform === "darwin") return "ffmpeg-avfoundation";
+		if (process.platform === "linux") return "ffmpeg-alsa";
+	}
+	return null;
+}
+
+function detectPlayer(): string | null {
+	if (process.platform === "darwin" && isCommandAvailable("afplay")) return "afplay";
+	if (isCommandAvailable("play")) return "play";
+	if (isCommandAvailable("ffplay")) return "ffplay";
+	if (isCommandAvailable("aplay")) return "aplay";
+	return null;
+}
+
+function isCommandAvailable(command: string): boolean {
+	const paths = (process.env.PATH ?? "").split(":").filter(Boolean);
+	for (const dir of paths) {
+		try {
+			accessSync(join(dir, command), constants.X_OK);
+			return true;
+		} catch {
+			// keep looking
+		}
+	}
+	return false;
+}
+
+function run(command: string, args: string[], signal?: AbortSignal, options: { timeoutMs?: number; resolveOnTimeout?: boolean } = {}): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error("Cancelled"));
+			return;
+		}
+
+		const child = spawnManaged(command, args);
+		let stderr = "";
+		let stdout = "";
+		let timedOut = false;
+		const timeout = options.timeoutMs
+			? setTimeout(() => {
+				timedOut = true;
+				terminateChild(child);
+			}, options.timeoutMs)
+			: undefined;
+		const onAbort = () => terminateChild(child);
+		signal?.addEventListener("abort", onAbort, { once: true });
+
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+
+		const cleanup = () => {
+			signal?.removeEventListener("abort", onAbort);
+			if (timeout) clearTimeout(timeout);
+		};
+
+		child.on("error", (err) => {
+			cleanup();
+			reject(err);
+		});
+		child.on("close", (code, termSignal) => {
+			cleanup();
+			if (signal?.aborted) {
+				reject(new Error("Cancelled"));
+				return;
+			}
+			if (code === 0 || (timedOut && options.resolveOnTimeout)) {
+				resolve();
+				return;
+			}
+			const output = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+			reject(new Error(`${command} failed${termSignal ? ` (${termSignal})` : ""}${code === null ? "" : ` with exit code ${code}`}${output ? `: ${output}` : ""}`));
+		});
+	});
+}
+
+async function* streamCommandOutput(command: string, args: string[], signal?: AbortSignal): AsyncIterable<Buffer> {
+	if (signal?.aborted) throw new Error("Cancelled");
+	const child = spawnManaged(command, args);
+	let stderr = "";
+	let exitCode: number | null = null;
+	let exitSignal: NodeJS.Signals | null = null;
+	let spawnError: Error | undefined;
+
+	const stop = () => terminateChild(child);
+	signal?.addEventListener("abort", stop, { once: true });
+	child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+	child.on("error", (err) => { spawnError = err; });
+	child.on("close", (code, termSignal) => { exitCode = code; exitSignal = termSignal; });
+
+	try {
+		if (!child.stdout) throw new Error(`${command} did not provide stdout for audio streaming`);
+		for await (const chunk of child.stdout) {
+			if (signal?.aborted) throw new Error("Cancelled");
+			yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		}
+		if (exitCode === null && !spawnError) await once(child, "close");
+		if (signal?.aborted) throw new Error("Cancelled");
+		if (spawnError) throw spawnError;
+		if (exitCode !== 0) {
+			const output = stderr.trim();
+			throw new Error(`${command} failed${exitSignal ? ` (${exitSignal})` : ""}${exitCode === null ? "" : ` with exit code ${exitCode}`}${output ? `: ${output}` : ""}`);
+		}
+	} finally {
+		signal?.removeEventListener("abort", stop);
+		if (!child.killed && exitCode === null) stop();
+	}
+}
+
+type ManagedChild = ReturnType<typeof spawn>;
+
+const activeChildren = new Set<ManagedChild>();
+const terminatingChildren = new WeakSet<ManagedChild>();
+let processExitCleanupInstalled = false;
+
+export function stopActiveAudioProcesses(force = false): void {
+	for (const child of [...activeChildren]) terminateChild(child, force);
+}
+
+function spawnManaged(command: string, args: string[]): ManagedChild {
+	installProcessExitCleanup();
+	const child = spawn(command, args, {
+		stdio: ["ignore", "pipe", "pipe"],
+		detached: process.platform !== "win32",
+	});
+	activeChildren.add(child);
+	const untrack = () => activeChildren.delete(child);
+	child.once("close", untrack);
+	child.once("error", untrack);
+	return child;
+}
+
+function installProcessExitCleanup(): void {
+	if (processExitCleanupInstalled) return;
+	processExitCleanupInstalled = true;
+	process.once("exit", () => stopActiveAudioProcesses(true));
+}
+
+function terminateChild(child: ManagedChild, force = false): void {
+	if (child.exitCode !== null || child.signalCode !== null || terminatingChildren.has(child)) return;
+	terminatingChildren.add(child);
+	sendSignal(child, "SIGTERM");
+	if (force) {
+		sendSignal(child, "SIGKILL");
+		return;
+	}
+	const killTimer = setTimeout(() => sendSignal(child, "SIGKILL"), 1500);
+	killTimer.unref();
+	child.once("close", () => clearTimeout(killTimer));
+}
+
+function sendSignal(child: ManagedChild, signal: NodeJS.Signals): void {
+	try {
+		if (process.platform !== "win32" && child.pid) {
+			process.kill(-child.pid, signal);
+			return;
+		}
+	} catch {
+		// Fall through to direct child signaling; the process may already be gone.
+	}
+	try {
+		child.kill(signal);
+	} catch {
+		// Best-effort cleanup only.
+	}
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/src/commands.ts

@@ -0,0 +1,286 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { VoiceToolServices } from "./tools.js";
+import { conciseTranscript, prepareSpokenText } from "./text.js";
+import { audioExtensionForCodec } from "./config.js";
+import { applyVoiceChrome, installVoiceUi, uninstallVoiceUi } from "./voice-ui.js";
+
+export type VoiceLoopStatus = "idle" | "listening" | "transcribing" | "agent" | "speaking" | "error";
+
+export interface VoiceModeState {
+	enabled: boolean;
+	autoListen: boolean;
+	autoSpeakAssistant: boolean;
+	isListening: boolean;
+	status: VoiceLoopStatus;
+	uiInstalled?: boolean;
+	previousEditorFactory?: unknown;
+	lastAssistantText?: string;
+	lastTranscript?: string;
+	lastError?: string;
+	recordSeconds?: number;
+	silenceStopSeconds?: number;
+	listenAbortController?: AbortController;
+	speakAbortController?: AbortController;
+}
+
+export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState) {
+	pi.registerCommand("listen", {
+		description: "Record speech, transcribe with Sarvam AI, and send it to pi as a user message",
+		handler: async (args, ctx) => {
+			await listenAndSend(pi, services, ctx, parseSeconds(args));
+		},
+	});
+
+	pi.registerCommand("speak", {
+		description: "Speak text with Sarvam AI TTS",
+		handler: async (args, ctx) => {
+			const text = args.trim();
+			if (!text) {
+				ctx.ui.notify("Usage: /speak <text>", "warning");
+				return;
+			}
+			await speakText(services, text, ctx.signal);
+		},
+	});
+
+	pi.registerCommand("voice-on", {
+		description: "Enable hands-free voice loop. Use --speak to read short assistant replies aloud.",
+		handler: async (args, ctx) => {
+			state.enabled = true;
+			if (args.includes("--speak")) state.autoSpeakAssistant = true;
+			if (args.includes("--no-speak")) state.autoSpeakAssistant = false;
+			state.autoListen = !args.includes("--manual");
+			installVoiceUi(ctx, state, createVoiceUiCallbacks(pi, services, state, ctx));
+			applyVoiceChrome(ctx, state);
+			ctx.ui.notify("Voice mode enabled. Press Q in the voice panel to close it.", "info");
+			if (!args.includes("--no-listen")) await listenAndSend(pi, services, ctx, parseSeconds(args));
+		},
+	});
+
+
+	pi.registerCommand("voice-status", {
+		description: "Show pi-listens Sarvam AI, recorder, player, and voice-mode status",
+		handler: async (_args, ctx) => {
+			const config = services.getConfig();
+			const audio = services.getAudio().describe();
+			ctx.ui.notify(
+				[
+					`Voice mode: ${state.enabled ? "on" : "off"}`,
+					`Auto-speak assistant: ${state.autoSpeakAssistant ? "on" : "off"}`,
+					`Auto-listen: ${state.autoListen ? "on" : "off"}`,
+					`Status: ${state.status}`,
+					`Sarvam API key: ${config.apiKey ? "set" : "missing"}`,
+					`Recorder: ${audio.recorder}`,
+					`Player: ${audio.player}`,
+					`STT: ${config.sttModel} (${config.translateInputToEnglish ? "translate→English" : config.sttMode}, ${config.sttLanguageCode})`,
+					`TTS: ${config.ttsModel} (${config.ttsLanguageCode}, speaker ${config.ttsSpeaker})`,
+				].join("\n"),
+				config.apiKey && audio.recorder !== "missing" && audio.player !== "missing" ? "info" : "warning",
+			);
+		},
+	});
+}
+
+export async function maybeContinueVoiceLoop(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState, ctx: ExtensionContext) {
+	if (!state.enabled || state.isListening) return;
+	if (state.autoSpeakAssistant && state.lastAssistantText) {
+		const spoken = prepareSpokenText(state.lastAssistantText, services.getConfig().maxAutoSpeakChars);
+		if (spoken) {
+			try {
+				await speakText(services, spoken, ctx.signal, state, ctx);
+			} catch (err) {
+				if (isCancelled(err)) {
+					state.status = "idle";
+					state.lastError = undefined;
+					applyVoiceChrome(ctx, state);
+					return;
+				}
+				state.status = "error";
+				state.lastError = errorMessage(err);
+				applyVoiceChrome(ctx, state);
+				ctx.ui.notify(`pi-listens could not speak assistant response: ${errorMessage(err)}`, "warning");
+			}
+		}
+	}
+	if (!state.enabled || !state.autoListen) { state.status = "idle"; applyVoiceChrome(ctx, state); return; }
+	ctx.ui.notify("Listening for your next instruction…", "info");
+	await listenAndSend(pi, services, ctx, undefined, { followUpWhenBusy: true });
+}
+
+async function listenAndSend(
+	pi: ExtensionAPI,
+	services: VoiceToolServices,
+	ctx: ExtensionContext | ExtensionCommandContext,
+	seconds: number | undefined,
+	options: { followUpWhenBusy?: boolean } = {},
+) {
+	const state = getStateFromServices(services);
+	if (state.isListening) {
+		state.listenAbortController?.abort();
+		return;
+	}
+	state.recordSeconds = seconds ?? services.getConfig().recordSeconds;
+	state.silenceStopSeconds = services.getConfig().silenceStopSeconds;
+	state.isListening = true;
+	state.status = "listening";
+	state.lastError = undefined;
+	const listenAbortController = new AbortController();
+	state.listenAbortController = listenAbortController;
+	const listenSignal = combineSignals(ctx.signal, listenAbortController.signal);
+	applyVoiceChrome(ctx, state);
+	if (ctx.hasUI) ctx.ui.setStatus("pi-listens", "listening…");
+	let transcript = "";
+	try {
+		const result = await services.getSpeech().transcribeMicrophone(services.getAudio(), listenSignal.signal, {
+			seconds: seconds ?? services.getConfig().recordSeconds,
+			mode: services.getConfig().translateInputToEnglish ? "translate" : services.getConfig().sttMode,
+		});
+		transcript = result.transcript.trim();
+
+		if (!transcript && services.getConfig().textFallback && ctx.hasUI) {
+			const typed = await ctx.ui.input("I did not catch that. Type your message:", "Type a message for pi");
+			transcript = typed?.trim() ?? "";
+		}
+
+		if (!transcript) {
+			ctx.ui.notify("No speech recognized.", "warning");
+			return;
+		}
+
+		ctx.ui.notify(`Heard: ${conciseTranscript(transcript)}`, "info");
+		state.lastTranscript = transcript;
+		state.status = "agent";
+		applyVoiceChrome(ctx, state);
+		if (ctx.isIdle()) {
+			pi.sendUserMessage(transcript);
+		} else {
+			pi.sendUserMessage(transcript, { deliverAs: options.followUpWhenBusy ? "followUp" : "steer" });
+		}
+	} catch (err) {
+		if (isCancelled(err)) {
+			state.status = "idle";
+			state.lastError = undefined;
+			if (state.enabled) ctx.ui.notify("Listening cancelled.", "info");
+		} else {
+			state.status = "error"; state.lastError = errorMessage(err); ctx.ui.notify(`pi-listens failed: ${errorMessage(err)}`, "error");
+		}
+	} finally {
+		listenSignal.cleanup();
+		state.isListening = false;
+		if (state.listenAbortController === listenAbortController) state.listenAbortController = undefined;
+		if (state.status !== "agent" && state.status !== "error") state.status = "idle";
+		applyVoiceChrome(ctx, state);
+	}
+}
+
+async function speakText(services: VoiceToolServices, text: string, signal?: AbortSignal, state?: VoiceModeState, ctx?: ExtensionContext) {
+	const config = services.getConfig();
+	const speakAbortController = state ? new AbortController() : undefined;
+	const speakSignal = combineSignals(signal, speakAbortController?.signal);
+	let path: string | undefined;
+
+	if (state) {
+		state.speakAbortController?.abort();
+		state.speakAbortController = speakAbortController;
+		state.status = "speaking";
+		if (ctx) applyVoiceChrome(ctx, state);
+	}
+
+	try {
+		await mkdir(config.audioDir, { recursive: true });
+		path = join(config.audioDir, `pi-listens-command-${Date.now()}.${audioExtensionForCodec(config.ttsOutputCodec)}`);
+		const result = await services.getSpeech().synthesizeToFile(text, path, speakSignal.signal);
+		path = result.path;
+		await services.getAudio().play(result.path, speakSignal.signal);
+	} finally {
+		speakSignal.cleanup();
+		if (path) await services.getAudio().cleanup(path);
+		if (state && state.speakAbortController === speakAbortController) state.speakAbortController = undefined;
+		if (state && state.status === "speaking") {
+			state.status = "idle";
+			if (ctx) applyVoiceChrome(ctx, state);
+		}
+	}
+}
+
+function parseSeconds(args: string): number | undefined {
+	const match = args.match(/(?:^|\s)(\d{1,4})(?:\s|$)/);
+	if (!match) return undefined;
+	const parsed = Number.parseInt(match[1]!, 10);
+	return Number.isFinite(parsed) ? Math.max(1, Math.min(3600, parsed)) : undefined;
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function createVoiceUiCallbacks(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState, ctx: ExtensionContext | ExtensionCommandContext) {
+	return {
+		startListening: () => { void listenAndSend(pi, services, ctx, undefined); },
+		disable: () => {
+			stopVoiceMode(services, state, ctx);
+		},
+		toggleSpeak: () => { state.autoSpeakAssistant = !state.autoSpeakAssistant; applyVoiceChrome(ctx, state); },
+		toggleAutoListen: () => { state.autoListen = !state.autoListen; applyVoiceChrome(ctx, state); },
+	};
+}
+
+type CombinedSignal = { signal?: AbortSignal; cleanup: () => void };
+
+function combineSignals(...signals: Array<AbortSignal | undefined>): CombinedSignal {
+	const active = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+	if (active.length === 0) return { signal: undefined, cleanup: () => undefined };
+	if (active.length === 1) return { signal: active[0], cleanup: () => undefined };
+	const controller = new AbortController();
+	const attached: AbortSignal[] = [];
+	const abort = () => controller.abort();
+	for (const signal of active) {
+		if (signal.aborted) { controller.abort(); break; }
+		signal.addEventListener("abort", abort, { once: true });
+		attached.push(signal);
+	}
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			for (const signal of attached) signal.removeEventListener("abort", abort);
+		},
+	};
+}
+
+function isCancelled(err: unknown): boolean {
+	return err instanceof Error && /cancelled|aborted/i.test(err.message);
+}
+
+export function stopVoiceMode(services: VoiceToolServices, state: VoiceModeState, ctx?: ExtensionContext | ExtensionCommandContext) {
+	state.enabled = false;
+	state.autoListen = false;
+	state.isListening = false;
+	state.status = "idle";
+	state.lastError = undefined;
+
+	const listenAbortController = state.listenAbortController;
+	state.listenAbortController = undefined;
+	listenAbortController?.abort();
+
+	const speakAbortController = state.speakAbortController;
+	state.speakAbortController = undefined;
+	speakAbortController?.abort();
+
+	services.getAudio().stopAll();
+
+	if (ctx) uninstallVoiceUi(ctx, state);
+}
+
+const serviceState = new WeakMap<VoiceToolServices, VoiceModeState>();
+
+export function attachStateToServices(services: VoiceToolServices, state: VoiceModeState) {
+	serviceState.set(services, state);
+}
+
+function getStateFromServices(services: VoiceToolServices): VoiceModeState {
+	const state = serviceState.get(services);
+	if (!state) throw new Error("voice mode state not attached");
+	return state;
+}