dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/voice/src/stt/apple.js

@@ -0,0 +1,179 @@
+// Apple Speech STT engine (task-1282). On-device SFSpeechRecognizer via a tiny Swift helper compiled
+// on the fly with `swiftc` — no key, no network, streaming partials (the spike's recommended primary
+// engine). The compiled helper is cached under ~/.dexterm/voice-helper; it is rebuilt only when the
+// source hash changes.
+//
+// LIVE CAVEAT (disclosed in the handoff): this path needs macOS Speech + Microphone authorization,
+// which can only be granted at the Mac by a person the first time it runs. available() reports whether
+// swiftc is present and the helper compiles; it cannot assert that TCC authorization will be granted.
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { APPLE_HELPER_SWIFT } from "./apple-helper.swift.js";
+const CACHE_DIR = process.env.DEXTERM_VOICE_HELPER_DIR || join(homedir(), '.dexterm', 'voice-helper');
+const SRC = join(CACHE_DIR, 'recognize.swift');
+const BIN = join(CACHE_DIR, 'recognize');
+const SWIFTC = process.env.DEXTERM_SWIFTC || 'swiftc';
+function which(bin) {
+    if (bin.includes('/'))
+        return existsSync(bin);
+    for (const p of (process.env.PATH ?? '').split(':'))
+        if (p && existsSync(join(p, bin)))
+            return true;
+    return false;
+}
+/** Compile the helper if the cached binary is missing or older than the current source. Returns BIN or null. */
+export function ensureHelper() {
+    if (!which(SWIFTC))
+        return null;
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        const hash = createHash('sha256').update(APPLE_HELPER_SWIFT).digest('hex');
+        const stamp = join(CACHE_DIR, '.srchash');
+        const fresh = existsSync(BIN) && existsSync(stamp) && readFileSync(stamp, 'utf8') === hash && statSync(BIN).size > 0;
+        if (fresh)
+            return BIN;
+        writeFileSync(SRC, APPLE_HELPER_SWIFT);
+        const r = compileSync(SRC, BIN);
+        if (!r)
+            return null;
+        writeFileSync(stamp, hash);
+        return BIN;
+    }
+    catch {
+        return null;
+    }
+}
+function compileSync(src, out) {
+    // The compile is a one-time cost (cached by source hash); doing it synchronously keeps ensureHelper
+    // simple. It is only reached from available() / listen(), both already async from the caller's view.
+    try {
+        execFileSync(SWIFTC, ['-O', '-o', out, src], { timeout: 60_000, stdio: 'ignore' });
+        return existsSync(out);
+    }
+    catch {
+        return false;
+    }
+}
+export class AppleStt {
+    name = 'apple';
+    label = 'Apple Speech (on-device, no key)';
+    async available() {
+        if (process.platform !== 'darwin')
+            return false;
+        if (!which(SWIFTC))
+            return false;
+        return ensureHelper() !== null;
+    }
+    async listen() {
+        const bin = ensureHelper();
+        if (!bin)
+            throw new Error('Apple Speech helper unavailable (need swiftc)');
+        const t0 = Date.now();
+        const child = spawn(bin, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let partial = '';
+        let firstPartialMs = null;
+        let finalText = null;
+        let finalConfidence = 1;
+        let err = '';
+        let buf = '';
+        let readySeen = false;
+        let readyResolve = null;
+        const ready = new Promise((r) => { readyResolve = r; });
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (d) => {
+            buf += d;
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (!line.trim())
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (ev.type === 'partial' && typeof ev.text === 'string') {
+                    partial = ev.text;
+                    if (firstPartialMs === null && ev.text)
+                        firstPartialMs = Date.now() - t0;
+                }
+                else if (ev.type === 'final') {
+                    finalText = String(ev.text ?? partial);
+                    if (typeof ev.confidence === 'number')
+                        finalConfidence = ev.confidence;
+                }
+                else if (ev.type === 'ready') {
+                    readySeen = true;
+                    readyResolve?.();
+                }
+                else if (ev.type === 'error') {
+                    err = String(ev.message ?? 'speech error');
+                    readyResolve?.();
+                }
+            }
+        });
+        child.stderr?.on('data', (d) => { err += d.toString(); });
+        let closed = false;
+        let spawnError = null;
+        const settled = new Promise((resolve) => {
+            child.on('close', () => { closed = true; readyResolve?.(); resolve(); });
+            // A failed spawn (EACCES / ENOENT / EAGAIN) must never become an uncaughtException that takes the
+            // whole terminal down (task-1339, re-verify N5): record it so stop() rejects cleanly instead.
+            child.on('error', (e) => { spawnError = e; closed = true; if (!err)
+                err = `mic helper failed to start: ${e.message}`; readyResolve?.(); resolve(); });
+        });
+        // Spawn failures surface on the next tick: give them one turn so listen() rejects (the controller
+        // then says "mic/STT could not start") rather than reporting a mic that was never open.
+        await new Promise((r) => setImmediate(r));
+        if (spawnError)
+            throw new Error(err || `mic helper failed to start: ${spawnError.message}`);
+        // Force-terminate the helper so the mic process can never outlive the session (task-1282 rework D5).
+        const kill = () => {
+            if (closed)
+                return;
+            try {
+                child.kill('SIGINT');
+            }
+            catch { /* ignore */ }
+            // If SIGINT did not land promptly, escalate so the OS mic indicator can never be left on.
+            setTimeout(() => { if (!closed) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+            } }, 500).unref?.();
+        };
+        // The helper authorizes, loads the on-device model and opens the audio engine before it emits
+        // `ready`. Reporting "listening" earlier let the user talk (and press stop) into a mic that was not
+        // open yet: an empty transcript and a silent no-op. Wait for it (bounded; first run after a
+        // permission prompt can take a few seconds).
+        await Promise.race([ready, new Promise((r) => setTimeout(r, 10_000))]);
+        if (closed || !readySeen) {
+            kill();
+            throw new Error(err || (closed ? 'mic helper exited before it was ready' : 'mic helper did not become ready in 10 s (check System Settings > Privacy > Microphone / Speech Recognition for your terminal)'));
+        }
+        return {
+            stop: async () => {
+                try {
+                    child.stdin?.write('stop\n');
+                    child.stdin?.end();
+                }
+                catch { /* ignore */ }
+                await Promise.race([settled, new Promise((r) => setTimeout(r, 5000))]);
+                if (!closed)
+                    kill(); // the helper ignored `stop` within 3 s: kill it rather than orphan the mic
+                const text = (finalText ?? partial).trim();
+                if (!text && err)
+                    throw new Error(err);
+                return { text, confidence: text ? finalConfidence : 0, firstPartialMs, speakerCount: 1 };
+            },
+            cancel: () => { kill(); },
+        };
+    }
+}

package/dist/packages/voice/src/stt/fake.js

@@ -0,0 +1,34 @@
+// An STT engine that captures no audio — listen()/stop() replay a scripted transcript. It powers the
+// headless tests and the latency harness, and the `--text`/`--script` demo, so the whole pipeline is
+// exercisable with no mic and no model.
+export class FakeStt {
+    name = 'fake';
+    label = 'fake (scripted, for tests)';
+    queue;
+    deflt;
+    /** `scripts` are consumed one per listen(); once exhausted, `fallback` is reused. */
+    constructor(scripts = [], fallback = { text: '' }) {
+        this.queue = scripts.slice();
+        this.deflt = fallback;
+    }
+    async available() { return true; }
+    async listen() {
+        const s = this.queue.shift() ?? this.deflt;
+        let settled = null;
+        const resolveResult = () => (settled ??= {
+            text: s.text,
+            confidence: s.confidence ?? 1,
+            lowConfTokens: s.lowConfTokens ?? [],
+            firstPartialMs: s.firstPartialMs ?? null,
+            speakerCount: s.speakerCount ?? 1,
+            echoFlagged: s.echoFlagged ?? false,
+        });
+        return {
+            stop: () => new Promise((resolve) => {
+                const delay = Math.max(0, s.transcribeMs ?? 0);
+                setTimeout(() => resolve(resolveResult()), delay);
+            }),
+            cancel: () => { settled = resolveResult(); },
+        };
+    }
+}

package/dist/packages/voice/src/stt/whisper.js

@@ -0,0 +1,112 @@
+// whisper.cpp STT engine (task-1282). Local, no key, no network once the model is downloaded. This is
+// the portable fallback when Apple Speech is unavailable. The spike measured `base.en` at ~3.5–4.8 s
+// batch on a CPU-only Intel Mac with good accuracy; `large-v3-turbo` was unusable (55–93 s) — so this
+// engine defaults to `base.en` and the doctor steers the user to it, never to a turbo model on CPU.
+//
+// Capture: `sox`/`rec` or `ffmpeg -f avfoundation` writes a 16 kHz mono WAV while the key is held;
+// stop() finalises the WAV and runs whisper-cli on it. The WAV lives in the OS temp dir and is
+// DELETED immediately after transcription unless DEXTERM_VOICE_RECORD=1 — nothing is kept by default.
+import { spawn } from 'node:child_process';
+import { existsSync, rmSync, mkdtempSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const WHISPER_BIN = process.env.DEXTERM_WHISPER_BIN || 'whisper-cli';
+/** Default model — base.en, the spike's accurate+usable choice. Never large-v3-turbo on CPU. */
+export const WHISPER_MODEL = process.env.DEXTERM_WHISPER_MODEL || join(homedir(), '.dexterm', 'models', 'ggml-base.en.bin');
+/** Where the user is told to put the model (doctor fix line). */
+export const WHISPER_MODEL_DIR = join(homedir(), '.dexterm', 'models');
+/**
+ * Pick a mic-capture tool, best-first. sox (`rec`) is cross-platform; `arecord` (alsa-utils) is the
+ * native Linux capture tool (task-1408) and finalises its WAV header on SIGINT; ffmpeg is last and its
+ * input format is platform-specific (avfoundation on macOS, alsa on Linux). All write a 16 kHz mono
+ * 16-bit WAV, which is what whisper.cpp wants. Returns null when nothing is installed.
+ */
+export function pickRecorder() {
+    if (which('rec'))
+        return { cmd: 'rec', args: (wav) => ['-q', '-c', '1', '-r', '16000', '-b', '16', wav], stopSignal: 'SIGINT' };
+    if (which('sox'))
+        return { cmd: 'sox', args: (wav) => ['-q', '-d', '-c', '1', '-r', '16000', '-b', '16', wav], stopSignal: 'SIGINT' };
+    if (process.platform !== 'darwin' && which('arecord')) {
+        return { cmd: 'arecord', args: (wav) => ['-q', '-f', 'S16_LE', '-c', '1', '-r', '16000', wav], stopSignal: 'SIGINT' };
+    }
+    if (which('ffmpeg')) {
+        const linux = process.platform === 'linux';
+        const fmt = linux ? 'alsa' : 'avfoundation';
+        const dev = process.env.DEXTERM_FFMPEG_MIC || (linux ? 'default' : ':default');
+        return { cmd: 'ffmpeg', args: (wav) => ['-hide_banner', '-loglevel', 'error', '-f', fmt, '-i', dev, '-ac', '1', '-ar', '16000', '-y', wav], stopSignal: 'SIGINT' };
+    }
+    return null;
+}
+/** Synchronous PATH check without spawning (cheap; used by available() and pickRecorder). */
+function which(bin) {
+    const paths = (process.env.PATH ?? '').split(':');
+    for (const p of paths) {
+        if (p && existsSync(join(p, bin)))
+            return true;
+    }
+    return false;
+}
+export class WhisperStt {
+    name = 'whisper';
+    label = 'whisper.cpp base.en (local, no key)';
+    model;
+    recordToDisk = process.env.DEXTERM_VOICE_RECORD === '1';
+    constructor(model = WHISPER_MODEL) { this.model = model; }
+    async available() {
+        return (which(WHISPER_BIN) || existsSync(WHISPER_BIN)) && existsSync(this.model) && pickRecorder() !== null;
+    }
+    async listen() {
+        const rec = pickRecorder();
+        if (!rec)
+            throw new Error('no mic capture tool (install sox or ffmpeg)');
+        const dir = mkdtempSync(join(tmpdir(), 'dexterm-voice-'));
+        const wav = join(dir, 'capture.wav');
+        const t0 = Date.now();
+        const recorder = spawn(rec.cmd, rec.args(wav), { stdio: 'ignore' });
+        let cancelled = false;
+        const cleanup = () => {
+            if (this.recordToDisk)
+                return; // explicit opt-in to keep the audio
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        };
+        return {
+            stop: async () => {
+                // Ask the recorder to finalise the WAV header, then wait for it to exit.
+                try {
+                    recorder.kill(rec.stopSignal);
+                }
+                catch { /* already gone */ }
+                await new Promise((r) => { recorder.on('close', () => r()); setTimeout(r, 2000); });
+                if (cancelled || !existsSync(wav)) {
+                    cleanup();
+                    return { text: '', confidence: 0 };
+                }
+                try {
+                    const text = await transcribe(wav, this.model);
+                    return { text, confidence: text ? 0.9 : 0, firstPartialMs: null, speakerCount: 1 };
+                }
+                finally {
+                    cleanup();
+                }
+            },
+            cancel: () => { cancelled = true; try {
+                recorder.kill('SIGKILL');
+            }
+            catch { /* ignore */ } cleanup(); },
+        };
+    }
+}
+/** Run whisper-cli on a finished WAV and return the transcript text. Rejects on a non-zero exit. */
+function transcribe(wav, model) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(WHISPER_BIN, ['-m', model, '-f', wav, '-nt', '-l', 'en', '-t', '4'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '', err = '';
+        p.stdout.on('data', (d) => (out += d));
+        p.stderr.on('data', (d) => (err += d));
+        p.on('error', reject);
+        p.on('close', (code) => code === 0 ? resolve(out.replace(/\s+/g, ' ').trim()) : reject(new Error(`whisper exit ${code}: ${err.slice(-200)}`)));
+    });
+}

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

@@ -0,0 +1,44 @@
+// Turn an analyst answer into its spoken form. It used to read only the FIRST ~2 sentences; since 2026-10-12
+// the whole answer is read, so the default is now every sentence, capped for sanity (a long-form dossier). The analyst's answer arrives either as a verdict + summary lines (structured
+// skills) or as free prose (chat follow-ups); this flattens both and trims to a speakable length.
+//
+// Pure and dependency-free so it is unit-tested headless.
+const MAX_CHARS = 1800;
+/** Collapse whitespace and strip markup/markdown that would be read aloud as noise. */
+function tidy(s) {
+    return s
+        .replace(/[*_`#>]/g, ' ') // markdown emphasis / headings / code / quotes
+        .replace(/\[[^\]]*\]\([^)]*\)/g, (m) => m.replace(/\]\([^)]*\)/, ']').replace(/[[\]]/g, '')) // [label](url) -> label
+        .replace(/https?:\/\/\S+/g, 'a link')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Split into sentences on ., !, ? boundaries, keeping it simple and robust. */
+export function splitSentences(text) {
+    const t = tidy(text);
+    if (!t)
+        return [];
+    const parts = t.match(/[^.!?]+[.!?]+|[^.!?]+$/g);
+    return (parts ?? [t]).map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Build the spoken summary. A verdict (e.g. "AVOID", "LARP") is spoken first as its own short clause,
+ * then the whole answer (every summary/prose sentence unless `maxSentences` limits it). Capped at MAX_CHARS.
+ */
+export function spokenSummary(src, maxSentences = Infinity) {
+    const chunks = [];
+    const verdict = (src.verdict ?? '').trim();
+    if (verdict)
+        chunks.push(`Verdict: ${verdict}.`);
+    const body = (src.summary && src.summary.length ? src.summary.join('. ') : (src.text ?? '')).trim();
+    const sentences = splitSentences(body).slice(0, maxSentences);
+    chunks.push(...sentences);
+    let out = tidy(chunks.join(' '));
+    if (out.length > MAX_CHARS) {
+        // Cut at the last sentence boundary that fits, else hard-trim.
+        const cut = out.slice(0, MAX_CHARS);
+        const lastStop = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+        out = (lastStop > 80 ? cut.slice(0, lastStop + 1) : cut.trimEnd() + '…');
+    }
+    return out;
+}

package/dist/packages/voice/src/tts/espeak.js

@@ -0,0 +1,131 @@
+// Portable (Linux/Windows) TTS via espeak-ng (task-1393 Part 2). espeak-ng is free, local, ships in or
+// installs trivially on every Linux distro, and runs on Windows too. It is the "works everywhere" baseline
+// off macOS; a Piper neural voice is a higher-quality upgrade that needs a downloaded model (see doctor).
+//
+// It carries the SAME contract as the macOS engine: text is SANITISED and delivered on STDIN (espeak-ng
+// treats `[[…]]` as phoneme input, so stripping it is a safety requirement, not a nicety), a new speak()
+// cleanly interrupts the current one (single queue), and the default voice is an explicit deep British
+// male (`en-gb+m3`) — never a surprise.
+//
+// VERIFICATION NOTE: the logic is unit-tested against a fake binary; it was NOT run against real
+// espeak-ng audio because the Linux (WSL) box was unreachable during this task. See the handoff.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizeSpeech } from "./voices.js";
+/** espeak-ng first (actively maintained), then the older espeak. Overridable for tests. */
+export const ESPEAK_BIN = process.env.DEXTERM_ESPEAK_BIN || '';
+/** The default portable voice: a British male. `+m3` is a deeper male variant. */
+export const DEFAULT_ESPEAK_VOICE = 'en-gb+m3';
+/** espeak words-per-minute default (close to the macOS 190 feel). */
+export const DEFAULT_ESPEAK_RATE = 175;
+function which(bin) {
+    if (!bin)
+        return null;
+    if (bin.includes('/') || bin.includes('\\'))
+        return existsSync(bin) ? bin : null;
+    for (const p of (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':')) {
+        if (!p)
+            continue;
+        if (existsSync(join(p, bin)))
+            return join(p, bin);
+        if (process.platform === 'win32' && existsSync(join(p, `${bin}.exe`)))
+            return join(p, `${bin}.exe`);
+    }
+    return null;
+}
+/** Resolve the espeak binary path: an explicit override, else espeak-ng, else espeak. */
+export function resolveEspeakBin() {
+    return which(ESPEAK_BIN) || which('espeak-ng') || which('espeak');
+}
+/**
+ * espeak voice names are language codes, optionally with a variant: `en`, `en-gb`, `en-us+m3`, `de+f2`.
+ * A macOS voice name like "Eddy (English (UK))" or "Daniel" is NOT one and must never be passed to
+ * espeak verbatim (task-1408 residual) — it would be an invalid `-v` argument. This matches only the
+ * espeak form, so a Mac voice name is rejected and the engine default is used instead.
+ */
+const ESPEAK_VOICE_RE = /^[a-z]{2,3}(-[a-z0-9]+)*(\+[a-z0-9]+)?$/i;
+/** A valid espeak voice token, or null when `configured` is empty or is a macOS voice name. */
+export function espeakVoiceFor(configured) {
+    const v = configured?.trim();
+    if (!v)
+        return null;
+    return ESPEAK_VOICE_RE.test(v) ? v : null;
+}
+export class EspeakTts {
+    name = 'espeak';
+    label = 'espeak-ng (local, no key)';
+    defaultVoice;
+    current = null;
+    constructor(defaultVoice = DEFAULT_ESPEAK_VOICE) { this.defaultVoice = defaultVoice; }
+    get voiceName() { return this.defaultVoice; }
+    async available() { return resolveEspeakBin() !== null; }
+    /** espeak-ng has no per-machine "installed voices" list the user cycles; the default covers it. */
+    async listVoices() { return [this.defaultVoice]; }
+    speak(text, opts = {}) {
+        this.stopCurrent(); // single queue: never two speakers at once
+        const bin = resolveEspeakBin();
+        const voice = opts.voice ?? this.defaultVoice;
+        const rate = opts.rate ?? DEFAULT_ESPEAK_RATE;
+        const safe = sanitizeSpeech(text);
+        const args = ['-v', voice, '-s', String(rate)];
+        if (typeof opts.pitch === 'number' && Number.isFinite(opts.pitch)) {
+            args.push('-p', String(Math.max(0, Math.min(99, Math.round(opts.pitch))))); // 0-99, lower = deeper
+        }
+        args.push('--stdin'); // read the utterance from stdin — never an argv word
+        let child = null;
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        const finish = () => { if (!stopped) {
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            resolve();
+        } };
+        try {
+            if (!bin)
+                throw new Error('espeak not found');
+            child = spawn(bin, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.stdin?.on('error', () => { });
+            try {
+                child.stdin?.end(safe);
+            }
+            catch { /* child gone */ }
+            child.on('spawn', () => { if (!stopped)
+                opts.onFirstAudio?.(); });
+            child.on('error', finish);
+            child.on('close', finish);
+        }
+        catch {
+            queueMicrotask(finish); // no espeak → degrade to text
+        }
+        const handle = {
+            done,
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                if (this.current === handle)
+                    this.current = null;
+                try {
+                    child?.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                resolve();
+            },
+        };
+        this.current = handle;
+        return handle;
+    }
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/packages/voice/src/tts/fake.js

@@ -0,0 +1,30 @@
+// A TTS engine that produces no audio — it records what would have been spoken and resolves at once.
+// Used by the headless tests and the latency harness so speech-out is deterministic and silent.
+export class FakeTts {
+    name = 'fake';
+    label = 'fake (silent, for tests)';
+    /** Every text passed to speak(), in order, for assertions. */
+    spoken = [];
+    /** How many times stop() interrupted a live utterance. */
+    stops = 0;
+    voices;
+    constructor(voices = ['Samantha', 'Alex', 'Daniel']) { this.voices = voices; }
+    async available() { return true; }
+    async listVoices() { return this.voices.slice(); }
+    speak(text, opts = {}) {
+        this.spoken.push(text);
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        // Fire first-audio on the next tick so latency timing sees a realistic (tiny) gap, then finish.
+        const t = setTimeout(() => { if (!stopped) {
+            opts.onFirstAudio?.();
+            resolve();
+        } }, 0);
+        return {
+            done,
+            stop: () => { if (stopped)
+                return; stopped = true; clearTimeout(t); this.stops++; resolve(); },
+        };
+    }
+}