mac-voice-mcp 0.1.0

package/dist/endpointer.js

@@ -0,0 +1,171 @@
+/**
+ * Turn-taking without a model (pure, unit-tested): an energy-based voice-activity
+ * detector that adapts to the room's background noise.
+ *
+ *   - waits for speech (≥120 ms above threshold) for up to `startTimeoutMs`
+ *   - once speaking, ends the turn after `endSilenceMs` of quiet
+ *   - ignores blips shorter than 300 ms (a cough, a click) and keeps listening
+ *   - hard stop at `maxMs`
+ */
+export const SAMPLE_RATE = 16000;
+export const FRAME_MS = 30;
+export const FRAME_SAMPLES = (SAMPLE_RATE * FRAME_MS) / 1000; // 480
+export const FRAME_BYTES = FRAME_SAMPLES * 2; // 16-bit mono
+const ONSET_FRAMES = 4; // 120 ms of sound before we believe it's speech
+const MIN_UTTERANCE_MS = 300; // shorter bursts are treated as noise
+const SETTLE_FRAMES = 3; // ignore the first 90 ms while the mic settles
+const FLOOR_WINDOW_FRAMES = 50; // background level = quietest frame of the last 1.5 s
+const STEADY_SPREAD_DB = 2.5; // sound this steady for a whole end-silence window is noise, not speech
+const STEADY_BELOW_SPEECH_DB = 6; // …as long as it's also clearly quieter than the user's voice
+function meanStd(values) {
+    if (!values.length)
+        return [Number.NaN, Number.NaN];
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((a, b) => a + (b - mean) ** 2, 0) / values.length;
+    return [mean, Math.sqrt(variance)];
+}
+export class Endpointer {
+    opts;
+    maxFrames;
+    startTimeoutFrames;
+    endSilenceFrames;
+    historySize;
+    /** Recent frame levels in dB, newest last. */
+    history = [];
+    floorDb = -90;
+    speechDb = Number.NaN;
+    frames = 0;
+    loudRun = 0;
+    quietRun = 0;
+    voicedFrames = 0;
+    started = false;
+    everStarted = false;
+    /** Frame index where the current utterance began (-1 = none yet). */
+    speechStartFrame = -1;
+    /** Frame index of the last voiced frame (-1 = none yet). */
+    lastVoicedFrame = -1;
+    /** False while every sample so far has been exactly zero (a blocked mic). */
+    anyNonZero = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.maxFrames = Math.ceil(opts.maxMs / FRAME_MS);
+        this.startTimeoutFrames = Math.ceil(Math.min(opts.startTimeoutMs, opts.maxMs) / FRAME_MS);
+        this.endSilenceFrames = Math.ceil(opts.endSilenceMs / FRAME_MS);
+        this.historySize = Math.max(FLOOR_WINDOW_FRAMES, this.endSilenceFrames, Math.ceil(1000 / FRAME_MS));
+    }
+    /** Feed one 30 ms frame of 16-bit little-endian PCM; returns a reason once the turn is over. */
+    push(frame) {
+        const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+        let sumSq = 0;
+        const n = frame.byteLength >> 1;
+        for (let i = 0; i < n; i++) {
+            const v = view.getInt16(i * 2, true);
+            if (v !== 0)
+                this.anyNonZero = true;
+            sumSq += v * v;
+        }
+        const rms = Math.sqrt(sumSq / Math.max(1, n)) / 32768;
+        const db = Math.max(-100, 20 * Math.log10(rms + 1e-9));
+        const idx = this.frames++;
+        if (idx >= SETTLE_FRAMES) {
+            this.history.push(db);
+            if (this.history.length > this.historySize)
+                this.history.shift();
+        }
+        // Background level = the quietest frame of the last 1.5 s. Because it keeps
+        // updating while the user talks (the gaps between words are quiet), it follows
+        // a room that gets louder — a fan, or a laptop mic's automatic gain boosting the
+        // noise after speech — as well as one that gets quieter.
+        if (this.history.length) {
+            this.floorDb = Math.min(-30, Math.max(-90, Math.min(...this.history.slice(-FLOOR_WINDOW_FRAMES))));
+        }
+        const threshold = Math.max(this.floorDb + this.opts.marginDb, this.opts.minSpeechDb);
+        const loud = db > threshold && idx >= SETTLE_FRAMES;
+        if (loud) {
+            this.loudRun++;
+            this.quietRun = 0;
+            if (this.started) {
+                this.voicedFrames++;
+                this.lastVoicedFrame = idx;
+                this.speechDb = 0.9 * this.speechDb + 0.1 * db;
+            }
+            else if (this.loudRun >= ONSET_FRAMES) {
+                this.started = true;
+                this.everStarted = true;
+                this.speechStartFrame = idx - this.loudRun + 1;
+                this.voicedFrames = this.loudRun;
+                this.lastVoicedFrame = idx;
+                this.speechDb = Number.isNaN(this.speechDb) ? db : this.speechDb;
+            }
+        }
+        else {
+            this.loudRun = 0;
+            this.quietRun++;
+        }
+        if (this.started) {
+            // End of turn: a stretch of quiet, or a stretch of steady sound clearly below
+            // the voice (speech rises and falls with every syllable; background noise doesn't).
+            let ended = this.quietRun >= this.endSilenceFrames;
+            if (!ended && this.history.length >= this.endSilenceFrames) {
+                const [mean, spread] = meanStd(this.history.slice(-this.endSilenceFrames));
+                if (spread < STEADY_SPREAD_DB && mean < this.speechDb - STEADY_BELOW_SPEECH_DB) {
+                    ended = true;
+                    this.lastVoicedFrame = Math.max(this.speechStartFrame, idx - this.endSilenceFrames);
+                    this.voicedFrames = Math.max(0, this.voicedFrames - this.endSilenceFrames + this.quietRun);
+                }
+            }
+            if (ended) {
+                if (this.voicedFrames * FRAME_MS < MIN_UTTERANCE_MS) {
+                    // Too short to be an answer (cough, click, chair). Keep waiting.
+                    this.started = false;
+                    this.everStarted = false;
+                    this.voicedFrames = 0;
+                    this.speechStartFrame = -1;
+                    this.lastVoicedFrame = -1;
+                    this.speechDb = Number.NaN;
+                }
+                else {
+                    return "end-of-turn";
+                }
+            }
+        }
+        if (this.frames >= this.maxFrames)
+            return this.everStarted ? "max-duration" : "no-speech";
+        if (!this.everStarted && this.frames >= this.startTimeoutFrames)
+            return "no-speech";
+        return null;
+    }
+    /** Levels behind the last decision — reported when listening hits its time limit, to help tuning. */
+    diagnostics() {
+        const [recentDb, recentSpreadDb] = meanStd(this.history.slice(-Math.ceil(1000 / FRAME_MS)));
+        return { floorDb: this.floorDb, speechDb: this.speechDb, recentDb, recentSpreadDb };
+    }
+    get speechSeconds() {
+        return (this.voicedFrames * FRAME_MS) / 1000;
+    }
+    /** Frame range worth transcribing: the utterance plus `padMs` either side. */
+    trimRange(totalFrames, padMs = 300) {
+        const pad = Math.round(padMs / FRAME_MS);
+        const first = this.speechStartFrame >= 0 ? Math.max(0, this.speechStartFrame - pad) : 0;
+        const last = this.lastVoicedFrame >= 0 ? Math.min(totalFrames, this.lastVoicedFrame + 1 + pad) : totalFrames;
+        return [first, last];
+    }
+}
+/** 44-byte header for 16 kHz mono 16-bit PCM WAV. */
+export function wavHeader(dataBytes) {
+    const h = Buffer.alloc(44);
+    h.write("RIFF", 0, "ascii");
+    h.writeUInt32LE(36 + dataBytes, 4);
+    h.write("WAVE", 8, "ascii");
+    h.write("fmt ", 12, "ascii");
+    h.writeUInt32LE(16, 16);
+    h.writeUInt16LE(1, 20); // PCM
+    h.writeUInt16LE(1, 22); // mono
+    h.writeUInt32LE(SAMPLE_RATE, 24);
+    h.writeUInt32LE(SAMPLE_RATE * 2, 28);
+    h.writeUInt16LE(2, 32);
+    h.writeUInt16LE(16, 34);
+    h.write("data", 36, "ascii");
+    h.writeUInt32LE(dataBytes, 40);
+    return h;
+}

package/dist/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * mac-voice-mcp — a local voice bridge for MCP clients.
+ *
+ * Tools
+ *   speak_and_listen(text_to_speak, listen_seconds?)
+ *     1. speaks the text with native TTS (`say` on macOS)
+ *     2. listens like a conversation turn: waits for the user to start talking and
+ *        stops ~1.2 s after they finish (adaptive voice-activity detection)
+ *     3. transcribes on-device with whisper.cpp (a warm whisper-server keeps the
+ *        model loaded between turns; whisper-cli is the fallback)
+ *     4. returns the transcript to the model
+ *   voice_setup(install?)
+ *     checks what's already installed and — only with the user's OK — installs
+ *     what's missing (Homebrew packages, the speech model). Reuses everything.
+ *
+ * Everything runs locally. No audio leaves the machine.
+ * stdout is reserved for the MCP protocol; all logging goes to stderr.
+ *
+ * Module map
+ *   config.ts       settings (env vars), logging, PATH fix-up for GUI apps
+ *   proc.ts         which / run helpers, error types
+ *   speech-text.ts  screen text → ear text; transcript clean-up        (pure)
+ *   endpointer.ts   turn-taking voice-activity detection               (pure)
+ *   audio.ts        TTS, chimes, streaming microphone capture
+ *   model.ts        find / symlink / download the whisper model
+ *   stt.ts          warm whisper-server + whisper-cli fallback
+ *   setup.ts        requirement checks and consent-based installs
+ *   voice.ts        the speak → listen → transcribe round trip
+ *   texts.ts        everything the model reads (rules, instructions, prompts)
+ *   server.ts       MCP tools and prompts
+ */
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_LISTEN_SECONDS, envNum, log, PKG } from "./config.js";
+import { startServer } from "./server.js";
+import { runSetupFlow } from "./setup.js";
+import { stopWhisperServer } from "./stt.js";
+import { speakAndListen } from "./voice.js";
+function printHelp() {
+    console.error(`${PKG.name} v${PKG.version} — local voice bridge MCP server
+
+Usage:
+  npx -y ${PKG.name}                  Start the MCP server on stdio (what MCP clients run)
+  npx -y ${PKG.name} setup            Check what's installed; offers to install what's missing
+  npx -y ${PKG.name} setup --install  Install what's missing without asking (brew + model download)
+  npx -y ${PKG.name} test ["text"]    Speak, listen for one turn and print the transcript
+  npx -y ${PKG.name} --version
+
+Environment variables (all optional):
+  VOICE_MCP_WHISPER_MODEL          whisper.cpp model name (default: base.en)
+  VOICE_MCP_WHISPER_MODEL_PATH     use this ggml model file
+  VOICE_MCP_MODEL_SEARCH_PATHS     extra folders to look in for an existing model (":"-separated)
+  VOICE_MCP_LANGUAGE               spoken language: en, th, de, … or auto
+  VOICE_MCP_WHISPER_PROMPT         words to bias recognition toward (names, jargon)
+  VOICE_MCP_VOICE / _RATE          macOS say voice and words-per-minute
+  VOICE_MCP_END_SILENCE_MS         pause length that ends your turn (default 1200)
+  VOICE_MCP_START_TIMEOUT_SECONDS  wait this long for you to start talking (default 8)
+  VOICE_MCP_SPEECH_MARGIN_DB       how far above room noise counts as speech (default 12)
+  VOICE_MCP_WHISPER_SERVER         0 to always use whisper-cli (no warm server)
+  VOICE_MCP_SERVER_IDLE_MINUTES    stop the warm server after this idle time (default 15)
+  VOICE_MCP_CHIME                  0 to disable the mic open/close sounds
+  VOICE_MCP_DEBUG                  1 for verbose logs and timings (stderr)`);
+}
+async function runSetupCli(args) {
+    console.error(`${PKG.name} v${PKG.version} on ${process.platform}/${process.arch}, Node ${process.version}\n`);
+    const force = args.includes("--install") || args.includes("-y");
+    let outcome = await runSetupFlow(force, (m) => console.error(`  … ${m}`));
+    // Interactive terminal: offer to install right away.
+    if (!force && !outcome.ready && !outcome.installing && process.stdin.isTTY && /ask the user whether/.test(outcome.report)) {
+        console.error(outcome.report.replace(/\nNext:.*$/s, ""));
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const answer = (await rl.question("\nInstall the missing pieces now? [Y/n] ")).trim().toLowerCase();
+        rl.close();
+        if (answer !== "" && !answer.startsWith("y"))
+            return 1;
+        outcome = await runSetupFlow(true, (m) => console.error(`  … ${m}`));
+    }
+    // In a terminal we can simply wait for background installs to finish.
+    while (outcome.installing)
+        outcome = await runSetupFlow(false, (m) => console.error(`  … ${m}`));
+    console.error(outcome.report);
+    return outcome.ready ? 0 : 1;
+}
+async function runTestCli(text) {
+    const prompt = text || "Voice bridge test. Say something after the chime, and I'll print what I heard.";
+    try {
+        const result = await speakAndListen(prompt, envNum("VOICE_MCP_TEST_SECONDS", DEFAULT_LISTEN_SECONDS), undefined, (p) => console.error(`  … ${p}`));
+        process.stdout.write(result.text + "\n");
+        for (const note of result.notes)
+            console.error(note);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : e);
+        return 1;
+    }
+    finally {
+        stopWhisperServer();
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case undefined:
+        case "serve":
+            return startServer();
+        case "setup":
+        case "doctor":
+            process.exit(await runSetupCli(rest));
+        case "test":
+            process.exit(await runTestCli(rest.join(" ").trim()));
+        case "-v":
+        case "--version":
+            console.log(PKG.version);
+            return;
+        case "-h":
+        case "--help":
+        case "help":
+            printHelp();
+            return;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            printHelp();
+            process.exit(2);
+    }
+}
+main().catch((err) => {
+    log("Fatal:", err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(1);
+});

package/dist/model.js

@@ -0,0 +1,189 @@
+/**
+ * The whisper.cpp speech model: find it without redoing work, download only with consent.
+ *
+ *   1. VOICE_MCP_WHISPER_MODEL_PATH
+ *   2. our cache (a real file, or a symlink made by an earlier run)
+ *   3. the same model elsewhere on this machine → symlinked into the cache
+ *   4. a one-time download — only via voice_setup(install=true) / `setup`
+ */
+import { closeSync, createWriteStream, existsSync, lstatSync, openSync, readSync, statSync } from "node:fs";
+import { mkdir, rename, rm, symlink, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { CONFIG, debug, IS_MAC, log } from "./config.js";
+import { run, SetupError } from "./proc.js";
+/** Approximate download sizes, for the setup report. */
+export const MODEL_SIZES_MB = {
+    "tiny.en": 75, tiny: 75, "base.en": 142, base: 142, "small.en": 466, small: 466,
+    "medium.en": 1500, medium: 1500, "large-v3-turbo": 1620, "large-v3-turbo-q5_0": 547, "large-v3": 3100,
+};
+/** How the current model was obtained — shown in the setup report. */
+export let modelSource = "";
+export function modelFile() {
+    if (CONFIG.modelPath)
+        return CONFIG.modelPath;
+    if (!/^[A-Za-z0-9._-]+$/.test(CONFIG.modelName)) {
+        throw new SetupError(`Invalid VOICE_MCP_WHISPER_MODEL "${CONFIG.modelName}".`);
+    }
+    return path.join(CONFIG.modelsDir, `ggml-${CONFIG.modelName}.bin`);
+}
+/** whisper.cpp ggml model files start with the magic 0x67676d6c ("ggml"). */
+export function isGgmlModel(file) {
+    let fd;
+    try {
+        if (statSync(file).size < 1_000_000)
+            return false;
+        fd = openSync(file, "r");
+        const head = Buffer.alloc(4);
+        return readSync(fd, head, 0, 4, 0) === 4 && head.readUInt32LE(0) === 0x67676d6c;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/**
+ * Look for the same model elsewhere before downloading: whisper.cpp checkouts,
+ * Homebrew's share folder, other tools' caches, and (on macOS) Spotlight.
+ */
+async function findExistingModel(fileName) {
+    const home = os.homedir();
+    const dirs = [
+        ...CONFIG.modelSearchPaths,
+        "/opt/homebrew/share/whisper-cpp",
+        "/opt/homebrew/share/whisper-cpp/models",
+        "/usr/local/share/whisper-cpp",
+        "/usr/local/share/whisper-cpp/models",
+        path.join(home, ".cache", "claude-voice-mcp", "models"), // this project's cache before it was renamed
+        path.join(home, ".cache", "whisper.cpp"),
+        path.join(home, ".cache", "whisper"),
+        path.join(home, ".local", "share", "whisper.cpp", "models"),
+        path.join(home, "Library", "Application Support", "whisper.cpp"),
+        ...["", "src", "code", "Code", "dev", "Developer", "projects", "Projects", "workspace", "git", "repos", "GitHub"].map((d) => path.join(home, d, "whisper.cpp", "models")),
+    ];
+    for (const dir of dirs) {
+        const candidate = path.join(dir, fileName);
+        if (existsSync(candidate) && isGgmlModel(candidate))
+            return candidate;
+    }
+    if (IS_MAC && existsSync("/usr/bin/mdfind")) {
+        try {
+            const r = await run("/usr/bin/mdfind", ["-name", fileName], { timeoutMs: 4000 });
+            for (const line of r.stdout.split("\n").map((l) => l.trim())) {
+                if (path.basename(line) === fileName && !line.startsWith(CONFIG.modelsDir) && isGgmlModel(line))
+                    return line;
+            }
+        }
+        catch {
+            /* Spotlight unavailable — fine */
+        }
+    }
+    return null;
+}
+/** Point our cache at an existing file (symlink), so later lookups are instant. */
+async function linkIntoCache(target, linkPath) {
+    try {
+        await mkdir(path.dirname(linkPath), { recursive: true });
+        await symlink(target, linkPath);
+        return linkPath;
+    }
+    catch (e) {
+        debug("symlink failed, using the file in place:", e);
+        return target;
+    }
+}
+let resolvedModel = null;
+let modelDownload = null;
+/** Find the model on this machine (steps 1–3). Returns null if it isn't here at all. Never downloads. */
+export async function locateModel() {
+    if (resolvedModel && existsSync(resolvedModel))
+        return resolvedModel;
+    if (CONFIG.modelPath) {
+        if (!existsSync(CONFIG.modelPath)) {
+            throw new SetupError(`VOICE_MCP_WHISPER_MODEL_PATH does not exist: ${CONFIG.modelPath}`);
+        }
+        modelSource = "from VOICE_MCP_WHISPER_MODEL_PATH";
+        return (resolvedModel = CONFIG.modelPath);
+    }
+    const file = modelFile();
+    if (existsSync(file) && isGgmlModel(file)) {
+        modelSource = lstatSync(file).isSymbolicLink() ? "reused (symlinked from an existing copy)" : "cached";
+        return (resolvedModel = file);
+    }
+    // A dangling symlink (the original was deleted) or a corrupt file: clear it.
+    try {
+        if (lstatSync(file))
+            await unlink(file);
+    }
+    catch {
+        /* nothing there */
+    }
+    const existing = await findExistingModel(path.basename(file));
+    if (existing) {
+        log(`Reusing existing model ${existing}`);
+        modelSource = `reused ${existing}`;
+        return (resolvedModel = await linkIntoCache(existing, file));
+    }
+    return null;
+}
+/** locateModel(), plus — only when allowed — a one-time download into the cache. */
+export async function ensureModel(opts) {
+    const found = await locateModel();
+    if (found)
+        return found;
+    if (!opts.download) {
+        throw new SetupError(`The speech model "${CONFIG.modelName}" isn't on this computer yet. ` +
+            "Call the voice_setup tool (with install=true once the user agrees) to download it.");
+    }
+    modelDownload ??= downloadModel(modelFile()).finally(() => {
+        modelDownload = null;
+    });
+    const downloaded = await modelDownload;
+    modelSource = "downloaded";
+    return (resolvedModel = downloaded);
+}
+/** Is a download currently running (e.g. started by an earlier voice_setup call)? */
+export const isModelDownloading = () => modelDownload !== null;
+async function downloadModel(dest) {
+    await mkdir(path.dirname(dest), { recursive: true });
+    const url = `${CONFIG.modelBaseUrl}/ggml-${CONFIG.modelName}.bin`;
+    log(`Downloading whisper model "${CONFIG.modelName}" → ${dest}`);
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok || !res.body) {
+        throw new SetupError(`Could not download whisper model from ${url} (HTTP ${res.status}). ` +
+            "Check the model name, or download it manually and set VOICE_MCP_WHISPER_MODEL_PATH.");
+    }
+    const total = Number(res.headers.get("content-length")) || 0;
+    const tmp = `${dest}.${process.pid}.part`;
+    let received = 0;
+    let lastLogged = -1;
+    try {
+        await pipeline(Readable.fromWeb(res.body), async function* (source) {
+            for await (const chunk of source) {
+                received += chunk.length;
+                if (total) {
+                    const pct = Math.floor((received / total) * 10) * 10;
+                    if (pct > lastLogged) {
+                        lastLogged = pct;
+                        log(`  model download ${pct}% (${(received / 1e6).toFixed(0)} / ${(total / 1e6).toFixed(0)} MB)`);
+                    }
+                }
+                yield chunk;
+            }
+        }, createWriteStream(tmp));
+        if (!isGgmlModel(tmp))
+            throw new Error("downloaded file is not a whisper.cpp ggml model");
+        await rename(tmp, dest);
+    }
+    catch (e) {
+        await rm(tmp, { force: true });
+        throw e;
+    }
+    log(`Model ready: ${dest}`);
+    return dest;
+}

package/dist/proc.js

@@ -0,0 +1,112 @@
+/** Child-process helpers: PATH lookup, a promise-based runner, and error types. */
+import { spawn } from "node:child_process";
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import path from "node:path";
+import { debug, IS_WIN } from "./config.js";
+/** Something the user has to install or configure — the message says how. */
+export class SetupError extends Error {
+    name = "SetupError";
+}
+export class CancelledError extends Error {
+    name = "CancelledError";
+    constructor() {
+        super("Cancelled by client");
+    }
+}
+export function isExecutable(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const whichCache = new Map();
+/** Forget cached lookups — needed right after `brew install` adds new binaries. */
+export function resetWhichCache() {
+    whichCache.clear();
+}
+/** Resolve a binary on PATH (cached). Absolute paths are checked as-is. */
+export function which(bin) {
+    if (whichCache.has(bin))
+        return whichCache.get(bin);
+    let found = null;
+    if (path.isAbsolute(bin)) {
+        found = isExecutable(bin) ? bin : null;
+    }
+    else {
+        const exts = IS_WIN ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").concat([""]) : [""];
+        outer: for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+            if (!dir)
+                continue;
+            for (const ext of exts) {
+                const candidate = path.join(dir, bin + ext);
+                if (isExecutable(candidate)) {
+                    found = candidate;
+                    break outer;
+                }
+            }
+        }
+    }
+    whichCache.set(bin, found);
+    return found;
+}
+/** Every child we start, so shutdown can stop them all. */
+export const activeChildren = new Set();
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        if (opts.signal?.aborted)
+            return reject(new CancelledError());
+        debug("exec:", cmd, args.join(" "));
+        const child = spawn(cmd, args, {
+            stdio: [opts.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+            windowsHide: true,
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+        activeChildren.add(child);
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout?.setEncoding("utf8").on("data", (d) => (stdout += d));
+        child.stderr?.setEncoding("utf8").on("data", (d) => (stderr += d));
+        const kill = () => {
+            child.kill(opts.killSignal ?? "SIGTERM");
+            setTimeout(() => child.exitCode === null && child.kill("SIGKILL"), 2000).unref();
+        };
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                kill();
+            }, opts.timeoutMs)
+            : undefined;
+        opts.signal?.addEventListener("abort", kill, { once: true });
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", kill);
+            activeChildren.delete(child);
+        };
+        child.on("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        child.on("close", (code) => {
+            cleanup();
+            if (opts.signal?.aborted)
+                reject(new CancelledError());
+            else
+                resolve({ code, stdout, stderr, timedOut });
+        });
+        if (opts.input !== undefined && child.stdin) {
+            child.stdin.on("error", () => { }); // ignore EPIPE if the process exits early
+            child.stdin.end(opts.input);
+        }
+    });
+}
+export function tail(s, lines = 6) {
+    return s.trim().split("\n").slice(-lines).join("\n");
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));