mac-voice-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,122 @@
+/** MCP wiring: two tools (speak_and_listen, voice_setup) and two prompts (setup, voice_mode). */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CONFIG, DEFAULT_LISTEN_SECONDS, log, MAX_LISTEN_SECONDS, PKG } from "./config.js";
+import { locateModel } from "./model.js";
+import { activeChildren, SetupError } from "./proc.js";
+import { runSetupFlow } from "./setup.js";
+import { stopWhisperServer } from "./stt.js";
+import { SERVER_INSTRUCTIONS, SETUP_PROMPT, SETUP_TOOL_DESCRIPTION, SPEAK_TOOL_DESCRIPTION, VOICE_MODE_PROMPT } from "./texts.js";
+import { exclusive, speakAndListen } from "./voice.js";
+/**
+ * MCP progress notifications, when the client asked for them (it sent a progressToken).
+ * They show what's happening and keep clients that reset their timeout on progress happy.
+ */
+function progressReporter(extra) {
+    const token = extra._meta?.progressToken;
+    if (token === undefined)
+        return undefined;
+    let progress = 0;
+    return (message) => {
+        extra
+            .sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: ++progress, message } })
+            .catch(() => { });
+    };
+}
+export function createServer() {
+    const server = new McpServer({ name: "voice-mcp", title: "Voice bridge", version: PKG.version }, { instructions: SERVER_INSTRUCTIONS });
+    server.registerTool("speak_and_listen", {
+        title: "Speak and listen",
+        description: SPEAK_TOOL_DESCRIPTION,
+        inputSchema: {
+            text_to_speak: z.string().min(1).describe("The summary or message to read aloud to the user. Plain, conversational text."),
+            listen_seconds: z
+                .number()
+                .positive()
+                .optional()
+                .describe(`Upper limit on how long to listen, in seconds (default ${DEFAULT_LISTEN_SECONDS}, max ${MAX_LISTEN_SECONDS}). ` +
+                "Listening already stops when the user finishes talking, so you rarely need this."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ text_to_speak, listen_seconds }, extra) => {
+        const progress = progressReporter(extra);
+        try {
+            const result = await exclusive(() => speakAndListen(text_to_speak, listen_seconds ?? DEFAULT_LISTEN_SECONDS, extra.signal, (phase) => progress?.(phase)));
+            return {
+                content: [{ type: "text", text: result.text }, ...result.notes.map((note) => ({ type: "text", text: `\n\n${note}` }))],
+                isError: !result.ok,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log("speak_and_listen failed:", message);
+            const prefix = err instanceof SetupError ? "voice-mcp is not set up yet: " : "voice-mcp error: ";
+            return { content: [{ type: "text", text: prefix + message }], isError: true };
+        }
+    });
+    server.registerTool("voice_setup", {
+        title: "Voice setup",
+        description: SETUP_TOOL_DESCRIPTION,
+        inputSchema: {
+            install: z
+                .boolean()
+                .optional()
+                .describe("false (default): only check. true: brew install missing packages and download the model. Ask the user first."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ install }, extra) => {
+        try {
+            const outcome = await exclusive(() => runSetupFlow(install === true, progressReporter(extra)));
+            return { content: [{ type: "text", text: outcome.report }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log("voice_setup failed:", message);
+            return { content: [{ type: "text", text: `voice_setup error: ${message}` }], isError: true };
+        }
+    });
+    // Claude Code: /mcp__voice-mcp__setup
+    server.registerPrompt("setup", { title: "Set up voice", description: "Check what voice-mcp needs, install what's missing (with your OK), then test it." }, () => ({ messages: [{ role: "user", content: { type: "text", text: SETUP_PROMPT } }] }));
+    // Claude Code: /mcp__voice-mcp__voice_mode [task]; Claude Desktop and Cursor: the prompt picker.
+    server.registerPrompt("voice_mode", {
+        title: "Voice mode",
+        description: "Hands-free session: Claude checks in out loud via speak_and_listen, using speakable phrasing.",
+        argsSchema: {
+            task: z.string().optional().describe("Optional: what to work on. Claude will read its plan back to you first."),
+        },
+    }, ({ task }) => ({
+        messages: [{ role: "user", content: { type: "text", text: VOICE_MODE_PROMPT(task?.trim() || undefined) } }],
+    }));
+    return server;
+}
+export async function startServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    let shuttingDown = false;
+    const shutdown = async (code = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        stopWhisperServer();
+        for (const child of activeChildren)
+            child.kill("SIGTERM");
+        try {
+            await server.close();
+        }
+        catch {
+            /* ignore */
+        }
+        process.exit(code);
+    };
+    process.stdin.on("close", () => void shutdown(0));
+    process.on("SIGINT", () => void shutdown(0));
+    process.on("SIGTERM", () => void shutdown(0));
+    await server.connect(transport);
+    log(`${PKG.name} v${PKG.version} ready on stdio (model: ${CONFIG.modelPath ?? CONFIG.modelName}, language: ${CONFIG.language})`);
+    if (process.stdin.isTTY) {
+        log("This is an MCP server and expects an MCP client on stdin. Try `setup` or `test` instead, or see --help.");
+    }
+    // Cheap, install-free: link an existing model into the cache if there is one.
+    void locateModel().catch(() => null);
+}

package/dist/setup.js

@@ -0,0 +1,183 @@
+/**
+ * voice_setup: check what's already on this machine, install only what's missing,
+ * and only when asked (install=true, after the user agreed).
+ *
+ * Installs run in the background: if they take longer than a tool call should
+ * wait, the report says "installing…" and the next voice_setup call picks up
+ * the result. A slow `brew install` can never time the client out.
+ */
+import { statSync } from "node:fs";
+import { describeRecorder, findRecorder, findTts } from "./audio.js";
+import { CONFIG, IS_MAC, IS_WIN, log } from "./config.js";
+import { ensureModel, isModelDownloading, locateModel, modelSource, MODEL_SIZES_MB } from "./model.js";
+import { isExecutable, resetWhichCache, run, sleep, tail, which } from "./proc.js";
+import { describeStt, findWhisperCli, findWhisperServer } from "./stt.js";
+/** How long one voice_setup call waits for installs before reporting "still installing". */
+const INSTALL_WAIT_MS = 40_000;
+export function findBrew() {
+    if (process.env.VOICE_MCP_EXTRA_PATH !== undefined)
+        return which("brew"); // isolated (tests): PATH only
+    return which("brew") ?? ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"].find(isExecutable) ?? null;
+}
+let brewJob = null;
+let modelJob = null;
+/** Results of finished jobs not yet shown to the user. */
+const finishedMessages = [];
+function startJob(label, work) {
+    const job = { label, startedAt: Date.now(), done: false, promise: Promise.resolve() };
+    job.promise = work()
+        .then((msg) => {
+        job.result = msg;
+    })
+        .catch((e) => {
+        job.result = `${label} failed: ${e instanceof Error ? e.message : e}`;
+    })
+        .finally(() => {
+        job.done = true;
+        resetWhichCache();
+        finishedMessages.push(job.result);
+        log(job.result);
+    });
+    return job;
+}
+function startBrewInstall(brew, formulae) {
+    return startJob(`brew install ${formulae.join(" ")}`, async () => {
+        log(`Running: brew install ${formulae.join(" ")}`);
+        const r = await run(brew, ["install", ...formulae], {
+            timeoutMs: 30 * 60_000,
+            env: { HOMEBREW_NO_AUTO_UPDATE: "1", HOMEBREW_NO_ENV_HINTS: "1", HOMEBREW_NO_INSTALL_CLEANUP: "1", NONINTERACTIVE: "1" },
+        });
+        if (r.code !== 0)
+            throw new Error(`exit ${r.code}: ${tail(r.stderr, 4)}`);
+        return `Installed with Homebrew: ${formulae.join(", ")}.`;
+    });
+}
+function startModelDownload() {
+    return startJob(`Downloading the ${CONFIG.modelName} model`, async () => {
+        await ensureModel({ download: true });
+        return `Downloaded the ${CONFIG.modelName} speech model.`;
+    });
+}
+const running = (j) => !!j && !j.done;
+const elapsed = (j) => `${Math.round((Date.now() - j.startedAt) / 1000)}s`;
+// --- Checks -------------------------------------------------------------------------------
+async function checkRequirements() {
+    const checks = [];
+    const brewing = running(brewJob);
+    const tts = findTts();
+    checks.push(tts
+        ? { label: "Text-to-speech", status: "ok", detail: IS_MAC ? "macOS `say` (built in)" : tts }
+        : { label: "Text-to-speech", status: "missing", detail: "no engine found — install espeak-ng (`sudo apt install espeak-ng`)" });
+    const rec = findRecorder();
+    checks.push(rec
+        ? { label: "Recorder", status: "ok", detail: describeRecorder(rec) }
+        : { label: "Recorder", status: brewing ? "installing" : "missing", detail: "SoX is not installed", brew: IS_WIN ? undefined : "sox" });
+    const cli = findWhisperCli();
+    const server = findWhisperServer();
+    if (cli || server) {
+        checks.push({ label: "Speech-to-text", status: "ok", detail: `whisper.cpp — ${describeStt()}` });
+    }
+    else {
+        checks.push({
+            label: "Speech-to-text",
+            status: brewing ? "installing" : "missing",
+            detail: "whisper.cpp is not installed",
+            brew: IS_WIN ? undefined : "whisper-cpp",
+        });
+    }
+    try {
+        const model = running(modelJob) || isModelDownloading() ? null : await locateModel();
+        if (model) {
+            const mb = (statSync(model).size / 1e6).toFixed(0);
+            checks.push({ label: "Speech model", status: "ok", detail: `${CONFIG.modelName} (${mb} MB) — ${modelSource}` });
+        }
+        else {
+            const size = MODEL_SIZES_MB[CONFIG.modelName];
+            checks.push({
+                label: "Speech model",
+                status: running(modelJob) ? "installing" : "missing",
+                detail: running(modelJob)
+                    ? `downloading ${CONFIG.modelName} (${elapsed(modelJob)} so far)`
+                    : `${CONFIG.modelName} is not on this computer — one-time download${size ? ` of ~${size} MB` : ""} to ${CONFIG.modelsDir}`,
+                model: true,
+            });
+        }
+    }
+    catch (e) {
+        checks.push({ label: "Speech model", status: "missing", detail: e instanceof Error ? e.message : String(e) });
+    }
+    if (checks.some((c) => c.brew && c.status === "missing")) {
+        const brew = findBrew();
+        checks.push(brew
+            ? { label: "Homebrew", status: "ok", detail: `found (${brew})` }
+            : {
+                label: "Homebrew",
+                status: "missing",
+                detail: "not installed, so packages can't be installed automatically — install it in Terminal from https://brew.sh (it needs your password), then run setup again",
+            });
+    }
+    return checks;
+}
+// --- The flow ------------------------------------------------------------------------------
+/**
+ * @param install    true only after the user agreed: brew-install missing formulae, download the model if absent.
+ * @param onProgress optional heartbeat while waiting (used for MCP progress notifications).
+ */
+export async function runSetupFlow(install, onProgress) {
+    let checks = await checkRequirements();
+    if (install) {
+        const formulae = [...new Set(checks.filter((c) => c.status === "missing" && c.brew).map((c) => c.brew))];
+        const brew = findBrew();
+        if (formulae.length && brew && !running(brewJob))
+            brewJob = startBrewInstall(brew, formulae);
+        if (checks.some((c) => c.model && c.status === "missing") && !running(modelJob))
+            modelJob = startModelDownload();
+    }
+    // Wait (bounded) for anything in flight, with a heartbeat.
+    const jobs = [brewJob, modelJob].filter(running);
+    if (jobs.length) {
+        const deadline = Date.now() + INSTALL_WAIT_MS;
+        while (jobs.some((j) => !j.done) && Date.now() < deadline) {
+            onProgress?.(jobs.filter((j) => !j.done).map((j) => `${j.label} (${elapsed(j)})`).join("; "));
+            await Promise.race([Promise.all(jobs.map((j) => j.promise)), sleep(5000)]);
+        }
+        checks = await checkRequirements();
+    }
+    const installing = running(brewJob) || running(modelJob);
+    const ready = checks.every((c) => c.status === "ok" || c.status === "optional");
+    const icon = { ok: "✔", missing: "✘", optional: "•", installing: "…" };
+    const done = finishedMessages.splice(0);
+    const lines = [
+        `voice-mcp setup — ${ready ? "READY" : installing ? "INSTALLING" : "NOT READY"}`,
+        "",
+        ...checks.map((c) => `${icon[c.status]} ${c.label}: ${c.detail}${c.brew && c.status === "missing" ? ` → brew install ${c.brew}` : ""}`),
+        IS_MAC ? "• Microphone: macOS asks for permission the first time speak_and_listen listens — click Allow." : "",
+    ];
+    if (done.length)
+        lines.push("", "What was done:", ...done.map((d) => `- ${d}`));
+    if (install && !done.length && !installing && ready)
+        lines.push("", "Nothing to install — everything was already present.");
+    const toInstall = [...new Set(checks.filter((c) => c.status === "missing" && c.brew).map((c) => c.brew))];
+    const needsModel = checks.some((c) => c.model && c.status === "missing");
+    lines.push("");
+    if (ready) {
+        lines.push("Next: everything is in place — speak_and_listen is ready to use.");
+    }
+    else if (installing) {
+        lines.push("Next: installation is still running in the background. Tell the user, wait about a minute, then call voice_setup again (install=false) to check.");
+    }
+    else if (!install && (toInstall.length || needsModel) && (findBrew() || !toInstall.length)) {
+        const steps = [toInstall.length ? `brew install ${toInstall.join(" ")}` : "", needsModel ? `download the ${CONFIG.modelName} model` : ""]
+            .filter(Boolean)
+            .join(" and ");
+        lines.push(`Next: ask the user whether to ${steps}. Only if they agree, call voice_setup with install=true.`);
+    }
+    else {
+        lines.push("Next: the items marked ✘ need the user's attention (see details above); then call voice_setup again.");
+    }
+    return {
+        ready,
+        installing,
+        report: lines.filter((l, i, a) => !(l === "" && (i === 0 || a[i - 1] === ""))).join("\n").trim(),
+    };
+}

package/dist/speech-text.js

@@ -0,0 +1,104 @@
+/**
+ * Pure text helpers (no I/O, unit-tested):
+ *   - prepareSpeech: turn "screen text" into "ear text" before it's spoken
+ *   - cleanTranscript: strip whisper.cpp's non-speech markers from a transcript
+ */
+/**
+ * Safety net for speakability. The model is asked (tool description, server
+ * instructions, voice_mode prompt) to send plain spoken sentences; this catches
+ * whatever slips through so the user never hears "backtick backtick backtick"
+ * or a 40-segment file path read aloud.
+ */
+export function prepareSpeech(input, opts = {}) {
+    const maxWords = opts.maxWords ?? 120;
+    const maxChars = opts.maxChars ?? 4000;
+    const notes = new Set();
+    let s = input.replace(/\r\n?/g, "\n");
+    // Fenced code blocks and markdown tables can't be spoken meaningfully.
+    s = s.replace(/```[\s\S]*?(?:```|$)/g, () => {
+        notes.add("code blocks");
+        return "\n(I've left the code on screen.)\n";
+    });
+    s = s.replace(/(?:^[ \t]*\|.*\|[ \t]*$\n?){2,}/gm, () => {
+        notes.add("tables");
+        return "\n(There's a table on screen.)\n";
+    });
+    // Inline code: keep short, word-like snippets; drop long or symbol-heavy ones.
+    s = s.replace(/`([^`\n]+)`/g, (_m, code) => {
+        if (code.length <= 32 && !/[{}();=<>[\]$]/.test(code))
+            return code;
+        notes.add("inline code");
+        return "that code";
+    });
+    s = s
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images → alt text
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links → link text
+        .replace(/<\/?[a-z][^>]*>/gi, " "); // stray HTML tags
+    // Bare URLs → "a link to github.com".
+    s = s.replace(/\bhttps?:\/\/(?:www\.)?([^\s/?#)]+)[^\s)]*?(?=[.,;:!?)]*(?:\s|$))/g, (_m, host) => {
+        notes.add("URLs");
+        return `a link to ${host}`;
+    });
+    // Long file paths → just the file name.
+    s = s.replace(/(?<![\w/:])(?:(?:~|\.{1,2})?(?:\/[\w@.+-]+){2,}|[\w@.+-]+(?:\/[\w@.+-]+){2,})\/?/g, (m) => {
+        if (/^[\d/.-]+$/.test(m))
+            return m; // dates like 9/23/2026
+        notes.add("file paths");
+        const parts = m.split("/").filter(Boolean);
+        return parts[parts.length - 1] ?? m;
+    });
+    s = s
+        .replace(/\b([\w-]+\.[a-z]{1,5}):\d+(?::\d+)?\b/gi, "$1") // index.ts:120 → index.ts
+        .replace(/(?<![\d/])(\d+)\/(\d+)(?![\d/])/g, "$1 of $2"); // 42/42 → 42 of 42
+    // Markdown structure → sentences. Headings and bullets become their own sentence.
+    s = s
+        .split("\n")
+        .map((line) => line
+        .replace(/^\s{0,3}#{1,6}\s+/, "")
+        .replace(/^\s*>\s?/, "")
+        .replace(/^\s*(?:[-*+•]|\d+[.)])\s+/, "")
+        .replace(/^\s*[-*_]{3,}\s*$/, "")
+        .trim())
+        .filter(Boolean)
+        .map((line) => (/[.!?:;,…)]$/.test(line) ? line : `${line}.`))
+        .join(" ");
+    s = s
+        .replace(/(\*\*|__|\*|~~)(?=\S)([\s\S]*?\S)\1/g, "$2") // emphasis markers
+        .replace(/\p{Extended_Pictographic}️?/gu, "") // emoji
+        .replace(/\s*(?:->|=>|→)\s*/g, " to ")
+        .replace(/\s&\s/g, " and ")
+        .replace(/[*_#~|^\\]+/g, " ")
+        .replace(/\s+([.,;:!?])/g, "$1")
+        .replace(/([.!?])\.+/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+    // Keep it listenable: cut at a sentence boundary once it gets long.
+    const words = s.split(" ");
+    if (maxWords > 0 && words.length > maxWords) {
+        let cut = words.slice(0, maxWords).join(" ");
+        const lastStop = Math.max(cut.lastIndexOf(". "), cut.lastIndexOf("? "), cut.lastIndexOf("! "));
+        if (lastStop > cut.length * 0.4)
+            cut = cut.slice(0, lastStop + 1);
+        s = `${cut} The rest is on screen.`;
+        notes.add(`length (over ${maxWords} words)`);
+    }
+    s = s.slice(0, maxChars);
+    const noteList = notes.size
+        ? [
+            `voice-mcp note: text_to_speak was rewritten for speech (removed/shortened: ${[...notes].join(", ")}). ` +
+                "Next time send only short, plain spoken sentences — keep code, paths, links and tables in your on-screen reply.",
+        ]
+        : [];
+    return { text: s, notes: noteList };
+}
+/** Remove timestamps and non-speech markers like [BLANK_AUDIO] from whisper output. */
+export function cleanTranscript(raw) {
+    return raw
+        .split("\n")
+        .map((l) => l.replace(/^\s*\[[\d:.\s\->]+\]\s*/, "")) // stray timestamps
+        .join(" ")
+        .replace(/\[(?:BLANK_AUDIO|MUSIC|NOISE|SILENCE|INAUDIBLE|_[A-Z_]+_)[^\]]*\]/gi, " ")
+        .replace(/\[\s*(?:silence|music|noise|inaudible)\s*\]/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/stt.js

@@ -0,0 +1,266 @@
+/**
+ * Speech-to-text with whisper.cpp.
+ *
+ * Fast path: a warm `whisper-server` on 127.0.0.1 keeps the model loaded between
+ * turns, so each reply skips the model load (and Metal start-up on Apple Silicon).
+ * It's started in the background while the question is being spoken, and stopped
+ * after VOICE_MCP_SERVER_IDLE_MINUTES of inactivity to give the memory back.
+ *
+ * Fallback: `whisper-cli`, one process per transcription. Always correct, just slower.
+ */
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { CONFIG, debug, IS_WIN, log } from "./config.js";
+import { CancelledError, isExecutable, run, SetupError, sleep, tail, which } from "./proc.js";
+import { cleanTranscript } from "./speech-text.js";
+export const STT_MISSING = "whisper.cpp (speech-to-text) is not installed. Call the voice_setup tool to check and install what's missing " +
+    "(or run `brew install whisper-cpp`, or set VOICE_MCP_WHISPER_BIN to an existing `whisper-cli`).";
+/** Where people usually clone and build whisper.cpp themselves. */
+function sourceBuildDirs() {
+    const home = os.homedir();
+    return ["", "src", "code", "Code", "dev", "Developer", "projects", "Projects", "workspace", "git", "repos", "GitHub", "Downloads"].flatMap((d) => [path.join(home, d, "whisper.cpp", "build", "bin"), path.join(home, d, "whisper.cpp")]);
+}
+export function findWhisperCli() {
+    if (CONFIG.whisperBin)
+        return which(CONFIG.whisperBin);
+    // Homebrew's whisper-cpp formula ships `whisper-cli` (older releases: `whisper-cpp`).
+    for (const bin of ["whisper-cli", "whisper-cpp", "whisper-cpp-cli"]) {
+        const found = which(bin);
+        if (found)
+            return found;
+    }
+    // A whisper.cpp you built yourself and never put on PATH. Old builds call the CLI `main`.
+    for (const dir of sourceBuildDirs()) {
+        for (const bin of ["whisper-cli", "main"]) {
+            const candidate = path.join(dir, bin);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export function findWhisperServer() {
+    if (CONFIG.whisperServerBin)
+        return which(CONFIG.whisperServerBin);
+    const onPath = which("whisper-server");
+    if (onPath)
+        return onPath;
+    const cli = findWhisperCli();
+    if (!cli)
+        return null;
+    // Next to the CLI; old source builds call the server `server` (and the CLI `main`).
+    const names = path.basename(cli) === "main" ? ["whisper-server", "server"] : ["whisper-server"];
+    for (const name of names) {
+        const sibling = path.join(path.dirname(cli), IS_WIN ? `${name}.exe` : name);
+        if (isExecutable(sibling))
+            return sibling;
+    }
+    return null;
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/** fetch() with a timeout that also honours the caller's abort signal (Node 18 compatible). */
+async function fetchWithin(url, init, timeoutMs, signal) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    const onAbort = () => ctl.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        return await fetch(url, { ...init, signal: ctl.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}
+class WarmWhisperServer {
+    child = null;
+    ready = null;
+    model = null;
+    idleTimer;
+    stderrTail = "";
+    failures = 0;
+    /** Too many start failures (e.g. an old whisper.cpp build) → stop trying for this session. */
+    get disabled() {
+        return this.failures >= 2;
+    }
+    get running() {
+        return !!this.child && this.child.exitCode === null;
+    }
+    /** Start (or reuse) a server for `model`. Resolves with its base URL once the model is loaded. */
+    warm(model) {
+        if (this.ready && this.model === model && this.running) {
+            this.touch();
+            return this.ready;
+        }
+        this.stop();
+        const bin = findWhisperServer();
+        if (!bin)
+            return Promise.reject(new Error("whisper-server is not installed"));
+        this.model = model;
+        const ready = this.start(bin, model);
+        this.ready = ready;
+        ready.then(() => {
+            this.failures = 0;
+        }, (e) => {
+            this.failures++;
+            debug("whisper-server failed to start:", e instanceof Error ? e.message : e);
+            if (this.ready === ready)
+                this.stop();
+        });
+        this.touch();
+        return ready;
+    }
+    async start(bin, model) {
+        const port = await freePort();
+        const args = ["-m", model, "--host", "127.0.0.1", "--port", String(port), "-t", String(CONFIG.threads), "-l", CONFIG.language, "-nt"];
+        if (CONFIG.prompt)
+            args.push("--prompt", CONFIG.prompt);
+        debug("starting whisper-server:", bin, args.join(" "));
+        // Orphan guard: the server runs under a tiny shell that waits on our stdin pipe
+        // and kills the server when that pipe closes — i.e. whenever this process exits,
+        // even if it's killed hard. `detached` gives it a process group we can stop as one.
+        const child = IS_WIN
+            ? spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"], windowsHide: true })
+            : spawn("/bin/sh", ["-c", '"$@" </dev/null & pid=$!; read -r _; kill $pid 2>/dev/null; wait $pid 2>/dev/null', "voice-mcp-whisper", bin, ...args], { stdio: ["pipe", "ignore", "pipe"], detached: true });
+        this.child = child;
+        this.stderrTail = "";
+        child.stdin?.on("error", () => { });
+        child.stderr?.setEncoding("utf8").on("data", (d) => (this.stderrTail = (this.stderrTail + d).slice(-3000)));
+        child.on("exit", () => {
+            if (this.child === child) {
+                this.child = null;
+                this.ready = null;
+            }
+        });
+        const base = `http://127.0.0.1:${port}`;
+        const deadline = Date.now() + 180_000; // large models can take a while to load
+        while (Date.now() < deadline) {
+            if (this.child !== child)
+                throw new Error(`whisper-server exited during start-up: ${tail(this.stderrTail, 3)}`);
+            try {
+                const res = await fetchWithin(`${base}/health`, {}, 1000);
+                // 503 = still loading. 404 = an older server without /health, but it's up.
+                if (res.ok || res.status === 404) {
+                    debug("whisper-server ready at", base);
+                    return base;
+                }
+            }
+            catch {
+                /* not listening yet */
+            }
+            await sleep(100);
+        }
+        throw new Error("whisper-server did not become ready in time");
+    }
+    async transcribe(wavFile, signal) {
+        if (!this.ready)
+            throw new Error("whisper-server is not running");
+        const base = await this.ready;
+        const form = new FormData();
+        form.append("file", new Blob([await readFile(wavFile)], { type: "audio/wav" }), "reply.wav");
+        form.append("temperature", "0.0");
+        form.append("temperature_inc", "0.2");
+        form.append("response_format", "json");
+        const res = await fetchWithin(`${base}/inference`, { method: "POST", body: form }, 120_000, signal);
+        if (signal?.aborted)
+            throw new CancelledError();
+        if (!res.ok)
+            throw new Error(`whisper-server HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+        const json = (await res.json());
+        if (json.error)
+            throw new Error(`whisper-server: ${json.error}`);
+        this.touch();
+        return cleanTranscript(json.text ?? "");
+    }
+    touch() {
+        clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            debug("whisper-server idle — stopping it to free memory");
+            this.stop();
+        }, CONFIG.serverIdleMinutes * 60_000);
+        this.idleTimer.unref();
+    }
+    stop() {
+        clearTimeout(this.idleTimer);
+        const child = this.child;
+        this.child = null;
+        this.ready = null;
+        if (!child)
+            return;
+        child.stdin?.end(); // wrapper kills the server on EOF
+        try {
+            if (!IS_WIN && child.pid)
+                process.kill(-child.pid, "SIGTERM");
+            else
+                child.kill("SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+const warmServer = new WarmWhisperServer();
+const serverUsable = () => CONFIG.useWhisperServer && !warmServer.disabled && !!findWhisperServer();
+/** Start loading the model in the background (called while the question is being spoken). */
+export function prewarm(model) {
+    if (serverUsable())
+        warmServer.warm(model).catch(() => { });
+}
+export function stopWhisperServer() {
+    warmServer.stop();
+}
+/** Which engine the next transcription will use — for the setup report. */
+export function describeStt() {
+    const cli = findWhisperCli();
+    const server = findWhisperServer();
+    const parts = [cli ? `whisper-cli (${cli})` : "", server ? "fast mode via whisper-server" : ""].filter(Boolean);
+    if (server && !CONFIG.useWhisperServer)
+        parts[parts.length - 1] = "whisper-server disabled by VOICE_MCP_WHISPER_SERVER=0";
+    return parts.join("; ");
+}
+async function transcribeCli(bin, wavFile, model, signal) {
+    const args = ["-m", model, "-f", wavFile, "-l", CONFIG.language, "-t", String(CONFIG.threads), "-nt", "-np"];
+    if (CONFIG.prompt)
+        args.push("--prompt", CONFIG.prompt);
+    const result = await run(bin, args, { signal, timeoutMs: 180_000 });
+    if (result.code !== 0) {
+        throw new Error(`whisper.cpp failed (exit ${result.code}): ${tail(result.stderr) || "no output"}`);
+    }
+    return cleanTranscript(result.stdout);
+}
+export async function transcribe(wavFile, model, signal) {
+    const started = Date.now();
+    if (serverUsable()) {
+        try {
+            await warmServer.warm(model);
+            const text = await warmServer.transcribe(wavFile, signal);
+            debug(`transcribed via whisper-server in ${Date.now() - started} ms`);
+            return text;
+        }
+        catch (e) {
+            if (signal?.aborted || e instanceof CancelledError)
+                throw new CancelledError();
+            log("whisper-server unavailable, using whisper-cli:", e instanceof Error ? e.message : e);
+            warmServer.stop();
+        }
+    }
+    const cli = findWhisperCli();
+    if (!cli)
+        throw new SetupError(STT_MISSING);
+    const text = await transcribeCli(cli, wavFile, model, signal);
+    debug(`transcribed via whisper-cli in ${Date.now() - started} ms`);
+    return text;
+}