dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/voice/src/controller.js

@@ -0,0 +1,407 @@
+// VoiceController (task-1282): the push-to-talk state machine that ties speech-in, the safe router,
+// and speech-out together, measures latency, and stays entirely UI-agnostic so it runs headless in
+// tests (fake engines) and in the app (real macOS engines). It emits a decision the app performs; it
+// NEVER performs a trade itself. The mic is open only in the 'listening' mode — the single place
+// listen() is called — so the on-screen indicator and the real mic state can never disagree.
+import { route, isSafe } from "./router.js";
+import { spokenSummary } from "./summary.js";
+import { isBannedVoice } from "./tts/voices.js";
+export class VoiceController {
+    stt;
+    tts;
+    opts;
+    now;
+    enabled = false;
+    mode = 'off';
+    muted;
+    voice;
+    rate;
+    pitch;
+    voices = [];
+    lastTranscript = null;
+    lastSay = null;
+    message = null;
+    session = null;
+    speaking = null;
+    /** Key-release timestamp awaiting its first-spoken-word, and the path it will be attributed to. */
+    pendingLatency = null;
+    maxListenMs;
+    setTimer;
+    clearTimer;
+    /** The live mic's auto-stop handle; non-null only while listening. */
+    listenTimer = null;
+    /**
+     * True from the talk key until stt.listen() has resolved (task-1339, re-verify N3). A second talk key
+     * in that window is ignored instead of opening a second, orphaned mic session; a cancel in that
+     * window closes the session the moment it arrives.
+     */
+    starting = false;
+    startCancelled = false;
+    samples = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.stt = opts.stt;
+        this.tts = opts.tts;
+        this.muted = opts.muted ?? false;
+        this.voice = opts.voice ?? null;
+        this.rate = opts.rate ?? 190;
+        this.pitch = opts.pitch;
+        this.now = opts.now ?? (() => Date.now());
+        this.maxListenMs = opts.maxListenMs ?? 15_000;
+        this.setTimer = opts.setTimer ?? ((fn, ms) => { const h = setTimeout(fn, ms); h.unref?.(); return h; });
+        this.clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+    }
+    status() {
+        return {
+            enabled: this.enabled,
+            mode: this.mode,
+            starting: this.starting,
+            muted: this.muted,
+            voice: this.voice,
+            sttLabel: this.stt?.label ?? null,
+            ttsLabel: this.tts?.label ?? null,
+            lastTranscript: this.lastTranscript,
+            lastSay: this.lastSay,
+            message: this.message,
+        };
+    }
+    notify() { try {
+        this.opts.onState?.(this.status());
+    }
+    catch { /* UI handler must not break us */ } }
+    setMode(m) { this.mode = m; this.notify(); }
+    get isEnabled() { return this.enabled; }
+    get isListening() { return this.mode === 'listening'; }
+    /** The mic is live OR about to be (listen() in flight): the states a key must cancel. */
+    get micEngaged() { return this.mode === 'listening' || this.starting; }
+    /**
+     * Load the voice list lazily (used by cycleVoice and the status line). Novelty voices on the ban-list
+     * are filtered OUT so the user can never cycle into "Zarvox" / "Bad News" and so a null starting voice
+     * is seeded to a safe one, never the machine's (possibly novelty) system voice (task-1393).
+     */
+    async loadVoices() {
+        if (!this.tts)
+            return;
+        try {
+            this.voices = (await this.tts.listVoices()).filter((n) => !isBannedVoice(n));
+            if (!this.voice && this.voices.length)
+                this.voice = this.voices[0];
+        }
+        catch {
+            this.voices = [];
+        }
+    }
+    /** Turn voice mode on/off. Enabling with no STT engine still works for spoken replies to typed Qs. */
+    enable() {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        this.message = this.stt ? null : 'voice-in unavailable on this machine — type questions; replies are still spoken';
+        this.setMode('idle');
+        void this.loadVoices();
+    }
+    disable() {
+        if (!this.enabled)
+            return;
+        this.cancelListen();
+        this.stopSpeaking();
+        this.enabled = false;
+        this.pendingLatency = null;
+        this.setMode('off');
+    }
+    toggle() { this.enabled ? this.disable() : this.enable(); }
+    /**
+     * The push-to-talk key. Terminals deliver no key-up, so this toggles: first press opens the mic
+     * (mode 'listening' — the only place the mic is live), second press closes it, transcribes, and
+     * routes. Starting to talk also interrupts any reply in progress. Returns when the decision (if any)
+     * has been emitted, so tests can await it.
+     */
+    async toggleTalk() {
+        if (!this.enabled)
+            this.enable();
+        if (this.mode === 'listening')
+            return this.stopTalkAndRoute();
+        if (this.mode === 'transcribing' || this.mode === 'thinking')
+            return; // busy; ignore re-press
+        if (this.starting)
+            return; // a second press while the mic is opening: never a second session (N3)
+        return this.startTalk();
+    }
+    async startTalk() {
+        if (!this.stt) {
+            this.message = 'voice-in unavailable — type your question instead';
+            this.notify();
+            return;
+        }
+        this.stopSpeaking(); // starting to talk cuts off any reply
+        this.starting = true;
+        this.startCancelled = false;
+        this.notify();
+        let session = null;
+        try {
+            session = await this.stt.listen();
+        }
+        catch (e) {
+            this.starting = false;
+            this.session = null;
+            this.message = `mic/STT could not start: ${describe(e)}`;
+            this.setMode('idle');
+            return;
+        }
+        this.starting = false;
+        // The user moved on (a key, esc, disable) while the mic was opening: close it at once (N3/N8).
+        if (this.startCancelled || !this.enabled) {
+            try {
+                session.cancel();
+            }
+            catch { /* ignore */ }
+            this.session = null;
+            this.setMode(this.enabled ? 'idle' : 'off');
+            return;
+        }
+        this.session = session;
+        this.setMode('listening');
+        this.armListenTimeout(); // the mic can never stay live indefinitely (task-1282 rework D2)
+    }
+    /** Start the hard cap that auto-stops a live mic. Cleared whenever we leave 'listening'. */
+    armListenTimeout() {
+        this.clearListenTimeout();
+        if (this.maxListenMs <= 0)
+            return;
+        this.listenTimer = this.setTimer(() => {
+            this.listenTimer = null;
+            if (this.mode === 'listening') {
+                this.cancelListen();
+                this.message = 'mic timed out — press v to talk again';
+                this.notify();
+            }
+        }, this.maxListenMs);
+    }
+    clearListenTimeout() {
+        if (this.listenTimer !== null) {
+            try {
+                this.clearTimer(this.listenTimer);
+            }
+            catch { /* ignore */ }
+            this.listenTimer = null;
+        }
+    }
+    async stopTalkAndRoute() {
+        this.clearListenTimeout(); // leaving 'listening': the mic is no longer live
+        const session = this.session;
+        this.session = null;
+        this.setMode('transcribing');
+        // "Key release": the clock for key-release → first-spoken-word starts now.
+        const releaseAt = this.now();
+        let result;
+        try {
+            result = session ? await session.stop() : { text: '', confidence: 0 };
+        }
+        catch (e) {
+            // Always release the capture on a transcription error so the mic can never be left open.
+            try {
+                session?.cancel();
+            }
+            catch { /* ignore */ }
+            this.message = `transcription failed: ${describe(e)}`;
+            this.setMode('idle');
+            return;
+        }
+        this.lastTranscript = result.text || null;
+        // An empty capture used to route to a silent 'ignore': the user saw the badge vanish and nothing else.
+        if (!result.text.trim()) {
+            this.message = "didn't hear anything — press v, wait for the red LISTENING badge, speak, then press v";
+            this.setMode('idle');
+            return;
+        }
+        const ss = this.opts.getScreenState?.() ?? {};
+        const prov = {
+            pttActive: true, // this transcript came from a real PTT session, by construction
+            speakerCount: result.speakerCount ?? 1,
+            echoFlagged: result.echoFlagged ?? false,
+            sttConfidence: result.confidence,
+            lowConfTokens: result.lowConfTokens ?? [],
+        };
+        const decision = route(result.text, prov, ss);
+        // Hard safety gate: never act on a decision that is not in the safe set (defence in depth).
+        if (!isSafe(decision)) {
+            this.message = 'blocked an unsafe voice decision';
+            this.setMode('idle');
+            return;
+        }
+        this.dispatch(decision, releaseAt);
+    }
+    /** Emit the decision for the app, speak any immediate confirmation, and arm latency timing. */
+    dispatch(d, releaseAt) {
+        if (d.kind === 'analyst') {
+            // The spoken output is the analyst's answer; the app calls speakAnswer() when it lands. Time the
+            // key-release → first word of that answer.
+            this.pendingLatency = { at: releaseAt, path: 'analyst', transcript: this.lastTranscript ?? '' };
+            this.setMode('thinking');
+            try {
+                this.opts.onDecision?.(d);
+            }
+            catch { /* app handler */ }
+            return;
+        }
+        // Instant paths (navigate/open/filter/watchlist/open-ticket/popup/clarify) speak their own one-liner —
+        // unless the app answered itself (returned false): then its reply stands and `say` is NOT read over
+        // it, so a clarify such as "I see 2 tokens called X" is what the user actually hears (N1).
+        this.pendingLatency = { at: releaseAt, path: 'instant', transcript: this.lastTranscript ?? '' };
+        let appAnswered = false;
+        try {
+            appAnswered = this.opts.onDecision?.(d) === false;
+        }
+        catch { /* app handler */ }
+        if (appAnswered) {
+            if (this.mode !== 'speaking')
+                this.setMode('idle');
+            return;
+        }
+        const line = d.kind === 'clarify' ? d.question : ('say' in d ? d.say : null);
+        if (line)
+            this.speak(line);
+        else {
+            this.setMode('idle');
+        }
+    }
+    /**
+     * Speak the analyst's answer (first ~2 sentences). Called by the app when a turn settles. Honours
+     * mute, is interruptible, and records the pending analyst-path latency on the first audio sample.
+     */
+    speakAnswer(src) {
+        const line = spokenSummary(src);
+        if (!line) {
+            this.setMode('idle');
+            return;
+        }
+        this.speak(line);
+    }
+    /** Low-level speak: stops any current reply, then reads `text`. Muted → skip audio but update state. */
+    speak(text) {
+        this.lastSay = text;
+        if (!this.tts || this.muted) {
+            // Still resolve the latency sample (the "spoken word" is just suppressed) so the table is complete.
+            this.recordFirstAudio();
+            this.setMode('idle');
+            this.notify();
+            return;
+        }
+        this.stopSpeaking();
+        this.setMode('speaking');
+        const handle = this.tts.speak(text, {
+            voice: this.voice ?? undefined,
+            rate: this.rate,
+            pitch: this.pitch,
+            onFirstAudio: () => this.recordFirstAudio(),
+        });
+        this.speaking = handle;
+        handle.done.then(() => {
+            if (this.speaking === handle) {
+                this.speaking = null;
+                if (this.mode === 'speaking')
+                    this.setMode('idle');
+            }
+        });
+    }
+    recordFirstAudio() {
+        const p = this.pendingLatency;
+        if (!p)
+            return;
+        this.pendingLatency = null;
+        this.samples.push({ path: p.path, ms: this.now() - p.at, transcript: p.transcript });
+    }
+    /** Interrupt a spoken reply (a key, or the user starting to talk). */
+    stopSpeaking() {
+        if (this.speaking) {
+            try {
+                this.speaking.stop();
+            }
+            catch { /* ignore */ }
+            this.speaking = null;
+        }
+        if (this.mode === 'speaking')
+            this.setMode('idle');
+    }
+    /** Abandon a live capture without transcribing. Always closes the mic and the auto-stop timer. */
+    cancelListen() {
+        this.clearListenTimeout();
+        if (this.starting)
+            this.startCancelled = true; // the session is closed the moment listen() resolves
+        if (this.session) {
+            try {
+                this.session.cancel();
+            }
+            catch { /* ignore */ }
+            this.session = null;
+        }
+        if (this.mode === 'listening')
+            this.setMode('idle');
+    }
+    /**
+     * Interrupt whatever voice is doing and return to idle — a mic capture, a spoken reply, OR a pending
+     * analyst turn ('thinking') / in-flight 'transcribing'. Resetting 'thinking' is the task-1282 rework
+     * D3 fix: an analyst error used to leave the mode stuck in 'thinking', where toggleTalk ignores every
+     * press, so voice was dead until restart. Now any key (esc) or an error cleanly returns to idle.
+     */
+    interrupt() {
+        this.stopSpeaking();
+        this.cancelListen();
+        this.pendingLatency = null;
+        if (this.enabled && this.mode !== 'idle' && this.mode !== 'off')
+            this.setMode('idle');
+    }
+    /**
+     * Abort the current turn because the analyst run failed/was cancelled, and surface a clear error both
+     * on screen (the HUD message) and aloud. Always leaves voice in idle so the next `v` works
+     * (task-1282 rework D3).
+     */
+    abortTurn(message = "Sorry — I couldn't get an answer. Try again.") {
+        this.interrupt();
+        if (!this.enabled) {
+            this.setMode('off');
+            return;
+        }
+        this.message = message;
+        this.mode = 'idle'; // speak()'s done handler returns to idle from 'speaking'
+        this.speak(message);
+    }
+    setMuted(m) { this.muted = m; if (m)
+        this.stopSpeaking(); this.notify(); }
+    toggleMute() { this.setMuted(!this.muted); }
+    get isMuted() { return this.muted; }
+    /** Cycle to the next installed (safe) voice and persist the choice. No-op when there are none. */
+    cycleVoice() {
+        if (!this.voices.length) {
+            this.notify();
+            return;
+        }
+        const i = this.voice ? this.voices.indexOf(this.voice) : -1;
+        this.voice = this.voices[(i + 1) % this.voices.length];
+        try {
+            this.opts.onVoiceChange?.(this.voice);
+        }
+        catch { /* persistence is best-effort; never break the UI */ }
+        this.notify();
+    }
+    currentVoice() { return this.voice; }
+    availableVoices() { return this.voices.slice(); }
+    /** A compact latency report for the handoff / `--latency` demo. */
+    report() {
+        const paths = ['instant', 'analyst'];
+        return paths.map((path) => {
+            const xs = this.samples.filter((s) => s.path === path).map((s) => s.ms).sort((a, b) => a - b);
+            return { path, n: xs.length, p50: pct(xs, 0.5), min: xs[0] ?? null, max: xs[xs.length - 1] ?? null };
+        });
+    }
+}
+function pct(sorted, p) {
+    if (!sorted.length)
+        return null;
+    const i = Math.min(sorted.length - 1, Math.floor(p * sorted.length));
+    return sorted[i];
+}
+function describe(e) {
+    const m = e?.message;
+    return typeof m === 'string' ? m : String(e);
+}

package/dist/packages/voice/src/doctor.js

@@ -0,0 +1,131 @@
+// Voice-mode doctor checks (task-1282 scope item 4). Returns the same check shape the CLI doctor uses
+// so `dexterm doctor` can render them inline. Everything the checks depend on (platform, which engines
+// resolved, whether swiftc / a whisper model / a mic tool are present) is injected, so the checks are
+// deterministic in tests and never spawn or hang. The guiding rule: if a component is missing, say
+// exactly what to install, and make clear voice DEGRADES TO TEXT rather than breaking the app.
+/** Produce the voice checks. Never throws. */
+export function voiceDoctor(deps) {
+    const checks = [];
+    if (deps.platform !== 'darwin') {
+        const win = deps.platform === 'win32';
+        // Speech OUT off macOS: Piper (neural, preferred) → espeak-ng (baseline) → warn (task-1408).
+        // NOTE: `apt install piper` on Debian is an UNRELATED gaming-mouse tool — never suggest it; the
+        // Piper TTS binary comes from the rhasspy/piper prebuilt release, the voice from `dexterm voice download`.
+        const piperRelease = 'github.com/rhasspy/piper/releases';
+        const whisperRelease = 'github.com/ggml-org/whisper.cpp/releases';
+        const piperReady = !!deps.piperPresent && !!deps.piperVoicePresent && !!deps.playerName;
+        // What Piper is still missing (for an upgrade hint / the no-voice fix).
+        const piperBits = [];
+        if (!deps.piperPresent)
+            piperBits.push(`the Piper binary (prebuilt from ${piperRelease} into \`~/.dexterm/piper/\`, NOT \`apt install piper\`)`);
+        if (!deps.piperVoicePresent)
+            piperBits.push('the voice model (`dexterm voice download piper-voice` — asks first, checksum-verified)');
+        if (!deps.playerName)
+            piperBits.push(win ? 'an audio player (ffplay from ffmpeg)' : 'an audio player (`sudo apt install alsa-utils` for aplay, or pulseaudio-utils for paplay)');
+        if (piperReady) {
+            checks.push({ name: 'Voice out (Piper)', status: 'pass', detail: `Piper neural voice ready — en_GB-alan-medium, plays via ${deps.playerName} (local, no key)` });
+        }
+        else if (deps.espeakPresent) {
+            checks.push({
+                name: 'Voice out (espeak-ng)', status: 'pass',
+                detail: `espeak-ng ready — British male default (local, no key). For a higher-quality neural voice, add Piper: ${piperBits.join('; ')}`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'Voice out', status: 'warn',
+                detail: `spoken replies are off on ${deps.platform} until a speech engine is installed; the analyst still answers in text`,
+                fix: win
+                    ? 'Install espeak-ng (`choco install espeak` or the espeak-ng release). For a neural voice, add Piper (prebuilt from '
+                        + `${piperRelease}) + \`dexterm voice download piper-voice\` + ffplay.`
+                    : 'Fastest: `sudo apt install espeak-ng`. Better (neural): install the Piper prebuilt binary from '
+                        + `${piperRelease} into \`~/.dexterm/piper/\`, run \`dexterm voice download piper-voice\`, and \`sudo apt install alsa-utils\` for a player. `
+                        + 'Do NOT `apt install piper` — on Debian that is an unrelated mouse tool.',
+            });
+        }
+        // Speech IN — whisper.cpp (the default off macOS). Not in Debian: use the prebuilt release.
+        if (deps.resolvedStt === 'whisper' || (deps.whisperBinPresent && deps.whisperModelPresent && deps.micToolPresent)) {
+            checks.push({ name: 'Voice in (whisper)', status: 'pass', detail: 'whisper.cpp base.en + a mic tool (local, no key)' });
+        }
+        else {
+            const bits = [];
+            if (!deps.whisperBinPresent)
+                bits.push('no whisper-cli');
+            else if (!deps.whisperModelPresent)
+                bits.push('no base.en model');
+            if (!deps.micToolPresent)
+                bits.push('no mic tool (arecord/sox/ffmpeg)');
+            checks.push({
+                name: 'Voice in', status: 'warn',
+                detail: `speech-to-text is off (${bits.join(', ') || 'whisper not set up'}); you can still type questions — voice degrades to text`,
+                fix: `Install whisper.cpp (not in Debian — use the prebuilt release from ${whisperRelease}) + a mic tool `
+                    + '(`sudo apt install alsa-utils` for arecord, or sox), then `dexterm voice download whisper` (asks first, checksum-verified).',
+            });
+        }
+        if (win) {
+            checks.push({
+                name: 'Windows voice', status: 'warn',
+                detail: 'espeak-ng (or Piper) is the supported Windows speech-out path; native SAPI is not wired in this build',
+                fix: 'Use espeak-ng or Piper on Windows for now. (SAPI support is a later enhancement.)',
+            });
+        }
+        return checks;
+    }
+    // Speech OUT — macOS say.
+    if (deps.sayAvailable) {
+        checks.push({ name: 'Voice out (say)', status: 'pass', detail: `macOS \`say\` ready · ${deps.voiceCount} voice${deps.voiceCount === 1 ? '' : 's'} (press the voice key, then cycle the voice)` });
+        // Which voice speaks, and why — so a machine can never silently use a novelty/odd system voice (task-1393).
+        if (deps.resolvedVoice) {
+            checks.push({ name: 'Default voice', status: 'pass', detail: `${deps.resolvedVoiceReason ?? deps.resolvedVoice} · , changes it` });
+        }
+        else if (deps.resolvedVoice === null) {
+            checks.push({
+                name: 'Default voice', status: 'warn',
+                detail: deps.resolvedVoiceReason ?? 'no safe voice installed — spoken replies are off (text still works)',
+                fix: 'Install a British male voice in System Settings → Accessibility → Spoken Content → System Voice → Manage Voices (Daniel, English (UK)); the Enhanced/Premium download sounds best.',
+            });
+        }
+    }
+    else {
+        checks.push({
+            name: 'Voice out (say)', status: 'warn',
+            detail: 'macOS `say` not found; spoken replies are off, the analyst still answers in text',
+            fix: '`say` ships with macOS — if it is missing, reinstall the Command Line Tools (`xcode-select --install`).',
+        });
+    }
+    // Speech IN — Apple Speech (preferred) or whisper (fallback).
+    if (deps.resolvedStt === 'apple' || deps.swiftcPresent) {
+        checks.push({ name: 'Voice in (Apple Speech)', status: 'pass', detail: 'on-device Apple Speech via swiftc (no key, streaming) — the first run asks for Microphone + Speech permission at the Mac' });
+    }
+    else if (deps.resolvedStt === 'whisper' || (deps.whisperBinPresent && deps.whisperModelPresent && deps.micToolPresent)) {
+        checks.push({ name: 'Voice in (whisper)', status: 'pass', detail: 'whisper.cpp base.en + a mic tool (local, no key)' });
+    }
+    else {
+        // Nothing for voice-in: steer to the fastest free path and make clear text still works.
+        const bits = [];
+        if (!deps.swiftcPresent)
+            bits.push('no swiftc (Apple Speech)');
+        if (!deps.whisperBinPresent)
+            bits.push('no whisper-cli');
+        else if (!deps.whisperModelPresent)
+            bits.push('no base.en model');
+        if (!deps.micToolPresent)
+            bits.push('no mic tool (sox/ffmpeg)');
+        checks.push({
+            name: 'Voice in', status: 'warn',
+            detail: `speech-to-text is off (${bits.join(', ')}); you can still type questions — voice degrades to text`,
+            fix: 'Fastest free path: install Xcode command line tools for Apple Speech (`xcode-select --install`). '
+                + 'Or whisper: `brew install whisper-cpp sox`, then `dexterm voice download whisper` (asks first, checksum-verified, writes '
+                + '`~/.dexterm/models/ggml-base.en.bin`). Never use large-v3-turbo on a CPU-only Mac — it is unusably slow.',
+        });
+    }
+    // Mic-capture tool note (only relevant to the whisper path; Apple Speech captures its own audio).
+    if (!deps.micToolPresent && deps.resolvedStt !== 'apple') {
+        checks.push({
+            name: 'Mic capture', status: 'warn',
+            detail: 'no sox/ffmpeg found; the whisper voice-in path needs one (Apple Speech does not)',
+            fix: '`brew install sox` (smallest) or `brew install ffmpeg`.',
+        });
+    }
+    return checks;
+}