dexterm-cli 0.1.1 → 0.1.3

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

@@ -5,6 +5,13 @@
 // 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 { speakable } from "./speakable.js";
+import { isBannedVoice } from "./tts/voices.js";
+import { DEFAULT_RATE } from "./tts/say.js";
+/** Live rate-nudge bounds and step (task-1411, the < / > keys). Clamped so a voice stays intelligible. */
+export const RATE_MIN = 120;
+export const RATE_MAX = 320;
+export const RATE_STEP = 15;
 export class VoiceController {
     stt;
     tts;
@@ -15,6 +22,7 @@ export class VoiceController {
     muted;
     voice;
     rate;
+    pitch;
     voices = [];
     lastTranscript = null;
     lastSay = null;
@@ -42,7 +50,8 @@ export class VoiceController {
         this.tts = opts.tts;
         this.muted = opts.muted ?? false;
         this.voice = opts.voice ?? null;
-        this.rate = opts.rate ?? 190;
+        this.rate = opts.rate ?? DEFAULT_RATE;
+        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; });
@@ -71,12 +80,16 @@ export class VoiceController {
     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). */
+    /**
+     * 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();
+            this.voices = (await this.tts.listVoices()).filter((n) => !isBannedVoice(n));
             if (!this.voice && this.voices.length)
                 this.voice = this.voices[0];
         }
@@ -92,6 +105,12 @@ export class VoiceController {
         this.message = this.stt ? null : 'voice-in unavailable on this machine — type questions; replies are still spoken';
         this.setMode('idle');
         void this.loadVoices();
+        // task-1416: pre-load the TTS engine (Piper loads its model into a standby process) so the first
+        // reply starts speaking quickly. A no-op for engines that stream from spawn (`say`).
+        try {
+            this.tts?.warmup?.(this.rate);
+        }
+        catch { /* warm-up is best-effort; never break enabling voice */ }
     }
     disable() {
         if (!this.enabled)
@@ -100,6 +119,10 @@ export class VoiceController {
         this.stopSpeaking();
         this.enabled = false;
         this.pendingLatency = null;
+        try {
+            this.tts?.dispose?.();
+        }
+        catch { /* best-effort cleanup */ }
         this.setMode('off');
     }
     toggle() { this.enabled ? this.disable() : this.enable(); }
@@ -272,6 +295,9 @@ export class VoiceController {
     }
     /** Low-level speak: stops any current reply, then reads `text`. Muted → skip audio but update state. */
     speak(text) {
+        // Speak like a trader (task-1411): no digit-by-digit tiny prices, big numbers in human words,
+        // natural percents. Applied to EVERY spoken line so an ack or an analyst answer never reads raw.
+        text = speakable(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.
@@ -285,6 +311,7 @@ export class VoiceController {
         const handle = this.tts.speak(text, {
             voice: this.voice ?? undefined,
             rate: this.rate,
+            pitch: this.pitch,
             onFirstAudio: () => this.recordFirstAudio(),
         });
         this.speaking = handle;
@@ -362,7 +389,7 @@ export class VoiceController {
         this.stopSpeaking(); this.notify(); }
     toggleMute() { this.setMuted(!this.muted); }
     get isMuted() { return this.muted; }
-    /** Cycle to the next installed voice (macOS voices). No-op when there are none. */
+    /** Cycle to the next installed (safe) voice and persist the choice. No-op when there are none. */
     cycleVoice() {
         if (!this.voices.length) {
             this.notify();
@@ -370,10 +397,36 @@ export class VoiceController {
         }
         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(); }
+    /** The current speaking rate (words-per-minute-ish), for the status line / help. */
+    currentRate() { return this.rate; }
+    /**
+     * Nudge the speaking rate by `steps` × RATE_STEP (— for slower, + for faster), clamp it, persist it,
+     * and surface it on the status line (task-1411: the < / > keys). Takes effect on the next reply; it
+     * does not restart a line already in flight. A no-op when the rate is already at the clamp.
+     */
+    nudgeRate(steps) {
+        const next = Math.max(RATE_MIN, Math.min(RATE_MAX, this.rate + steps * RATE_STEP));
+        if (next === this.rate) {
+            this.message = `voice rate ${this.rate} wpm (${next <= RATE_MIN ? 'slowest' : 'fastest'})`;
+            this.notify();
+            return;
+        }
+        this.rate = next;
+        this.message = `voice rate ${this.rate} wpm`;
+        try {
+            this.opts.onRateChange?.(this.rate);
+        }
+        catch { /* persistence is best-effort; never break the UI */ }
+        this.notify();
+    }
     /** A compact latency report for the handoff / `--latency` demo. */
     report() {
         const paths = ['instant', 'analyst'];

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

@@ -7,22 +7,107 @@
 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 — Piper neural (the default when set up, task-1416) → macOS `say` (fallback) → text.
+    const macPiperReady = !!deps.piperPresent && !!deps.piperVoicePresent && !!deps.playerName;
+    if (macPiperReady) {
         checks.push({
-            name: 'Voice mode', status: 'warn',
-            detail: `voice mode is macOS-only for now (speech uses the built-in \`say\` and Apple Speech); on ${deps.platform} it stays off and dexterm runs as text`,
-            fix: 'Use dexterm on macOS for voice, or just use the keyboard — every voice action has a key.',
+            name: 'Voice out (Piper)', status: 'pass',
+            detail: `neural British voice is the default — en_GB-alan-medium, plays via ${deps.playerName} (local, no key); fallback: macOS \`say\``,
         });
-        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)` });
+        const role = macPiperReady ? 'the fallback if Piper is removed' : 'the default — press the voice key, then cycle the voice';
+        checks.push({ name: macPiperReady ? 'Voice out (say, fallback)' : 'Voice out (say)', status: 'pass', detail: `macOS \`say\` ready · ${deps.voiceCount} voice${deps.voiceCount === 1 ? '' : 's'} · ${role}` });
+        // Which `say` voice speaks, and why — so a machine can never silently use a novelty/odd system voice (task-1393).
+        const voiceLabel = macPiperReady ? 'Fallback voice' : 'Default voice';
+        if (deps.resolvedVoice) {
+            checks.push({ name: voiceLabel, status: 'pass', detail: `${deps.resolvedVoiceReason ?? deps.resolvedVoice} · , changes it` });
+        }
+        else if (deps.resolvedVoice === null) {
+            checks.push({
+                name: voiceLabel, 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.',
+            });
+        }
+        // Offer the higher-quality neural voice when it is not set up yet (never silent; the user decides).
+        if (!macPiperReady) {
+            checks.push({
+                name: 'Neural voice (Piper)', status: 'warn',
+                detail: 'a higher-quality neural British voice is available but not set up; `say` is speaking for now',
+                fix: 'Run `dexterm voice setup` to install it (asks first; a private Python runtime + a ~61 MB checksum-verified model; runs offline after, `dexterm voice uninstall` removes it).',
+            });
+        }
     }
-    else {
+    else if (!macPiperReady) {
         checks.push({
-            name: 'Voice out (say)', status: 'warn',
+            name: 'Voice out', 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`).',
+            fix: '`say` ships with macOS — if it is missing, reinstall the Command Line Tools (`xcode-select --install`). Or set up the neural voice: `dexterm voice setup`.',
         });
     }
     // Speech IN — Apple Speech (preferred) or whisper (fallback).
@@ -47,8 +132,8 @@ export function voiceDoctor(deps) {
             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 download base.en to '
-                + '`~/.dexterm/models/ggml-base.en.bin` (from the whisper.cpp model repo). Never use large-v3-turbo on a CPU-only Mac — it is unusably slow.',
+                + '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).

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

@@ -0,0 +1,184 @@
+// Voice model downloader (task-1408). The whisper.cpp base.en model and the Piper en_GB-alan-medium
+// voice are NOT shipped (free-forever rule: no bundled large binaries, no keys). dexterm downloads them
+// on request, and ONLY on request:
+//   - from the OFFICIAL source (the ggml-org / rhasspy repositories on Hugging Face),
+//   - after EXPLICIT user confirmation (never a silent auto-download),
+//   - and verified against a checksum pinned here from the upstream LFS pointer, so a corrupted or
+//     tampered download is rejected and never written into place.
+//
+// This module is pure logic + injected fetch/confirm/log, so it is unit-testable with a fake registry
+// and never touches the real network in tests. The CLI (`dexterm voice download …`) wires the real
+// global fetch, a readline y/N prompt, and stdout.
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { once } from 'node:events';
+/** Total download size of a spec, in whole MB (for the prompt). */
+export function specSizeMB(spec) {
+    return Math.round(spec.files.reduce((n, f) => n + (f.size ?? 0), 0) / (1024 * 1024));
+}
+/**
+ * The downloadable voice models, keyed by id. `home` is the dexterm home (~/.dexterm) so tests can
+ * point it at a temp dir. Checksums are pinned from the upstream Hugging Face LFS pointers (verified
+ * 2026-10-16): ggerganov/whisper.cpp and rhasspy/piper-voices@v1.0.0.
+ */
+export function modelRegistry(home = join(homedir(), '.dexterm')) {
+    const models = join(home, 'models');
+    return {
+        whisper: {
+            id: 'whisper',
+            label: 'whisper.cpp base.en (speech-to-text)',
+            note: 'whisper.cpp base.en — on-device speech recognition, ~141 MB, MIT (ggml-org/whisper.cpp)',
+            files: [{
+                    url: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin',
+                    dest: join(models, 'ggml-base.en.bin'),
+                    sha256: 'a03779c86df3323075f5e796cb2ce5029f00ec8869eee3fdfb897afe36c6d002',
+                    size: 147964211,
+                }],
+        },
+        'piper-voice': {
+            id: 'piper-voice',
+            label: 'Piper en_GB-alan-medium (neural voice)',
+            note: 'Piper en_GB-alan-medium — British male neural voice, ~61 MB, MIT (rhasspy/piper-voices)',
+            files: [
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx',
+                    dest: join(models, 'en_GB-alan-medium.onnx'),
+                    sha256: '0a309668932205e762801f1efc2736cd4b0120329622adf62be09e56339d3330',
+                    size: 63201294,
+                },
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx.json',
+                    dest: join(models, 'en_GB-alan-medium.onnx.json'),
+                    validateJson: true,
+                },
+            ],
+        },
+    };
+}
+/** sha256 of an existing file, or null if it cannot be read. */
+async function fileSha256(path) {
+    try {
+        const h = createHash('sha256');
+        h.update(await readFile(path));
+        return h.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `file` is already present AND valid (checksum match, or parses as JSON for config files). */
+async function isPresentAndValid(file) {
+    if (!existsSync(file.dest))
+        return false;
+    if (file.validateJson) {
+        try {
+            JSON.parse(await readFile(file.dest, 'utf8'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (file.sha256)
+        return (await fileSha256(file.dest)) === file.sha256.toLowerCase();
+    return true;
+}
+/**
+ * Download and verify one file. Streams to a `.part` temp alongside the destination (bounded memory),
+ * verifies size + sha256 (or JSON), then atomically renames into place. On ANY failure the temp is
+ * removed and nothing is written to the destination.
+ */
+async function downloadFile(file, fetchImpl, log) {
+    await mkdir(dirname(file.dest), { recursive: true });
+    const tmp = `${file.dest}.part`;
+    await rm(tmp, { force: true });
+    log(`  ↓ ${file.url}`);
+    let res;
+    try {
+        res = await fetchImpl(file.url, { redirect: 'follow' });
+    }
+    catch (e) {
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    if (!res.ok || !res.body)
+        throw new Error(`download failed (${file.url}): HTTP ${res.status}`);
+    const hash = createHash('sha256');
+    const out = createWriteStream(tmp);
+    let bytes = 0;
+    try {
+        for await (const chunk of Readable.fromWeb(res.body)) {
+            const buf = chunk;
+            bytes += buf.length;
+            hash.update(buf);
+            if (!out.write(buf))
+                await once(out, 'drain');
+        }
+        out.end();
+        await once(out, 'finish');
+    }
+    catch (e) {
+        out.destroy();
+        await rm(tmp, { force: true });
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    // Verify before anything lands at the real path.
+    try {
+        if (file.size !== undefined && bytes !== file.size) {
+            throw new Error(`size mismatch: got ${bytes} bytes, expected ${file.size}`);
+        }
+        if (file.sha256) {
+            const got = hash.digest('hex');
+            if (got !== file.sha256.toLowerCase())
+                throw new Error(`checksum mismatch: got ${got}, expected ${file.sha256}`);
+        }
+        else if (file.validateJson) {
+            JSON.parse(await readFile(tmp, 'utf8'));
+        }
+    }
+    catch (e) {
+        await rm(tmp, { force: true });
+        throw new Error(`verification failed (${file.url}): ${e.message}`);
+    }
+    await rename(tmp, file.dest);
+    const mb = (bytes / (1024 * 1024)).toFixed(1);
+    log(`  ✓ ${file.dest} (${mb} MB${file.sha256 ? ', sha256 ok' : ', json ok'})`);
+}
+/**
+ * Download a model after explicit confirmation. If every file is already present and valid, returns
+ * `already` WITHOUT prompting or touching the network. Otherwise it builds a one-prompt summary of what
+ * will be fetched and where, calls `confirm()`, and only then downloads + verifies each missing file.
+ */
+export async function downloadModel(spec, deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const log = deps.log ?? (() => { });
+    const presence = await Promise.all(spec.files.map(isPresentAndValid));
+    const missing = spec.files.filter((_, i) => !presence[i]);
+    if (missing.length === 0) {
+        log(`${spec.label} is already installed and verified.`);
+        return { status: 'already', files: spec.files.map((f) => f.dest) };
+    }
+    const dir = dirname(spec.files[0].dest);
+    const prompt = [
+        `Download ${spec.note}`,
+        `  from the official source to ${dir}`,
+        `  ${missing.length} file${missing.length === 1 ? '' : 's'}, ~${specSizeMB(spec)} MB, checksum-verified. Proceed?`,
+    ].join('\n');
+    if (!(await deps.confirm(prompt))) {
+        log('Cancelled — nothing downloaded.');
+        return { status: 'cancelled', files: spec.files.filter((_, i) => presence[i]).map((f) => f.dest) };
+    }
+    for (const f of missing)
+        await downloadFile(f, fetchImpl, log);
+    log(`${spec.label} installed.`);
+    return { status: 'ok', files: spec.files.map((f) => f.dest) };
+}
+/** Which model files exist and verify right now (for a status report; never touches the network). */
+export async function modelStatus(spec) {
+    const files = await Promise.all(spec.files.map(async (f) => ({ dest: f.dest, ok: await isPresentAndValid(f) })));
+    return { installed: files.every((f) => f.ok), files };
+}

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

@@ -5,7 +5,10 @@ import { AppleStt } from "./stt/apple.js";
 import { WhisperStt } from "./stt/whisper.js";
 import { FakeStt } from "./stt/fake.js";
 import { SayTts } from "./tts/say.js";
+import { EspeakTts, espeakVoiceFor } from "./tts/espeak.js";
+import { PiperTts } from "./tts/piper.js";
 import { FakeTts } from "./tts/fake.js";
+import { resolveVoice } from "./tts/voices.js";
 /**
  * Resolve the STT engine. `auto` prefers Apple Speech (on-device, streaming), then whisper base.en,
  * then none. An explicit choice is returned even if it later proves unavailable, so the doctor and the
@@ -29,16 +32,60 @@ export async function selectStt(choice = process.env.DEXTERM_VOICE_STT || 'auto'
         return whisper;
     return null;
 }
-/** Resolve the TTS engine. `auto` uses macOS `say` when present, else none (voice replies off). */
-export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto', defaultVoice) {
+/**
+ * Resolve the default `say` voice for this machine: the user's configured voice if it is installed and
+ * safe, else a deep British male (Daniel first), never a novelty voice and never the OS system default.
+ * Returns the full resolution (voice + why) so the controller and `dexterm doctor` can show it.
+ */
+export async function resolveSayVoice(say, configured) {
+    const installed = await say.listVoicesDetailed();
+    return resolveVoice({ configured, installed });
+}
+/**
+ * Resolve the TTS engine. `auto` uses macOS `say` when present, else none (voice replies off). When
+ * `say` is chosen, its default voice is resolved to an explicit deep British male so it can NEVER fall
+ * back to the machine's system voice (task-1393). `configuredVoice` is the user's `config.voice.name`.
+ */
+export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto', configuredVoice) {
     if (choice === 'none')
         return null;
     if (choice === 'fake')
         return new FakeTts();
-    if (choice === 'say')
-        return new SayTts(defaultVoice);
-    const say = new SayTts(defaultVoice);
-    if (await say.available())
-        return say;
-    return null;
+    // Piper and espeak are the off-macOS engines. A macOS voice name (config.voice.name is e.g.
+    // "Eddy (English (UK))") is NEVER passed to them verbatim: Piper's voice is its model, and espeak
+    // only honours a real espeak voice token (espeakVoiceFor drops a Mac name → the British default).
+    if (choice === 'piper') {
+        const p = new PiperTts();
+        return (await p.available()) ? p : null;
+    }
+    if (choice === 'espeak') {
+        const e = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+        return (await e.available()) ? e : null;
+    }
+    // On macOS, prefer Piper alan (neural) when the managed runtime is installed (task-1416:
+    // `dexterm voice setup` → venv + model + afplay), else the built-in `say`. Off macOS, `say` does not
+    // exist — use the portable engines below. An explicit `choice==='say'` always skips Piper.
+    if (choice === 'say' || (choice === 'auto' && process.platform === 'darwin')) {
+        if (choice === 'auto') {
+            const piperMac = new PiperTts();
+            if (await piperMac.available())
+                return piperMac;
+        }
+        const probe = new SayTts();
+        if (choice === 'auto' && !(await probe.available()))
+            return null;
+        const r = await resolveSayVoice(probe, configuredVoice);
+        // No safe voice installed (only novelty voices): voice-out stays OFF so `say` can never be invoked
+        // without an explicit voice and fall back to the machine's system voice (task-1393). Text still works.
+        if (r.voice === null)
+            return null;
+        return new SayTts(r.voice);
+    }
+    // auto, non-darwin: Piper (neural, higher quality) when it can speak aloud, else espeak-ng, else
+    // text-only. Neither engine is ever handed a macOS voice name (task-1408).
+    const piper = new PiperTts();
+    if (await piper.available())
+        return piper;
+    const espeak = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+    return (await espeak.available()) ? espeak : null;
 }

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

@@ -6,11 +6,17 @@
 export * from "./types.js";
 export { route, isSafe } from "./router.js";
 export { spokenSummary, splitSentences } from "./summary.js";
+export { speakable, humanizeNumber } from "./speakable.js";
 export { VoiceController } from "./controller.js";
-export { selectStt, selectTts } from "./engines.js";
+export { selectStt, selectTts, resolveSayVoice } from "./engines.js";
 export { voiceDoctor } from "./doctor.js";
-export { SayTts } from "./tts/say.js";
+export { resolveVoice, isBannedVoice, normalizeVoiceName, parseSayVoices, sanitizeSpeech, BANNED_VOICE_NAMES, BRITISH_MALE_PREFERENCE, MAX_SPEAK_CHARS, VOICE_STYLE_DEFAULTS, voiceStyleDefaults, } from "./tts/voices.js";
+export { SayTts, DEFAULT_RATE } from "./tts/say.js";
+export { EspeakTts, DEFAULT_ESPEAK_VOICE, resolveEspeakBin, espeakVoiceFor } from "./tts/espeak.js";
+export { PiperTts, DEFAULT_PIPER_VOICE, PIPER_MODEL, PIPER_PLAYERS, resolvePiperBin, resolvePiperRuntime, managedVenvPython, pickPlayer, } from "./tts/piper.js";
+export { setupPiperRuntime, uninstallPiperRuntime, piperRuntimeStatus, piperRuntimePaths, readRuntimeRecord, detectPython, parsePythonVersion, pythonVersionOk, pythonFixLine, PIPER_PYPI_VERSION, MIN_PYTHON, DEFAULT_PYTHON_CANDIDATES, } from "./tts/piper-setup.js";
 export { FakeTts } from "./tts/fake.js";
-export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR } from "./stt/whisper.js";
+export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR, pickRecorder } from "./stt/whisper.js";
+export { modelRegistry, downloadModel, modelStatus, specSizeMB, } from "./download.js";
 export { AppleStt, ensureHelper } from "./stt/apple.js";
 export { FakeStt } from "./stt/fake.js";