dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,206 @@
+// Piper neural TTS engine (task-1408). Piper is a free, local, no-key neural text-to-speech engine
+// (rhasspy/piper, MIT) that sounds markedly better than espeak-ng. Off macOS it is the PREFERRED
+// speech-out engine; espeak-ng stays the last-resort baseline (see engines.ts). Verified in Docker
+// (task-1397/task-1408): the prebuilt Linux binary + the en_GB-alan-medium voice write a valid,
+// non-silent 22.05 kHz WAV that whisper.cpp transcribes almost word-for-word.
+//
+// It carries the SAME contract as the macOS `say` and espeak engines:
+//   - text is SANITISED (sanitizeSpeech strips `[[…]]`, control chars, a leading `-`, caps length)
+//   - text is delivered on STDIN, never as an argv word
+//   - a new speak() cleanly INTERRUPTS the current one — one queue, never two voices at once
+//   - the voice is fixed by the downloaded MODEL, never by a macOS voice name (so config.voice.name,
+//     which on a Mac is e.g. "Eddy (English (UK))", is NEVER passed verbatim to Piper)
+//
+// Piper has no audio output of its own: it synthesises to a WAV, which we then play through the
+// platform player (aplay / paplay / ffplay — detected and reported by the doctor). Containers have no
+// audio device, so real playback is unverified; synthesis-to-file IS verified (synthToFile + whisper).
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sanitizeSpeech } from "./voices.js";
+/** The Piper voice dexterm defaults to off macOS: a British male, medium quality (local, no key). */
+export const DEFAULT_PIPER_VOICE = 'en_GB-alan-medium';
+/** Where the downloaded Piper voice model lives (see `dexterm voice download piper-voice`). */
+export const PIPER_MODEL = process.env.DEXTERM_PIPER_MODEL
+    || join(homedir(), '.dexterm', 'models', `${DEFAULT_PIPER_VOICE}.onnx`);
+/** Audio players we can hand a WAV to, best-first. Reported by the doctor so the user knows which plays. */
+export const PIPER_PLAYERS = ['aplay', 'paplay', 'ffplay'];
+function which(bin) {
+    if (!bin)
+        return null;
+    if (bin.includes('/') || bin.includes('\\'))
+        return existsSync(bin) ? bin : null;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const p of (process.env.PATH ?? '').split(sep)) {
+        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 Piper binary. We look at an explicit override, then the dexterm-local install
+ * (`~/.dexterm/piper/piper`, where the prebuilt release is extracted), then PATH. NOTE: Debian's
+ * `apt install piper` is an UNRELATED gaming-mouse tool, so the doctor steers users to the rhasspy
+ * prebuilt release rather than apt; a wrong `piper` on PATH simply fails to synth and voice degrades
+ * to text (it never crashes).
+ */
+export function resolvePiperBin() {
+    return which(process.env.DEXTERM_PIPER_BIN || '')
+        || which(join(homedir(), '.dexterm', 'piper', 'piper'))
+        || which('piper');
+}
+/** The player that will play Piper's WAV, or null when none is installed. */
+export function pickPlayer() {
+    const override = process.env.DEXTERM_AUDIO_PLAYER;
+    if (override)
+        return which(override) ? override : null;
+    for (const p of PIPER_PLAYERS)
+        if (which(p))
+            return p;
+    return null;
+}
+/** Argv to play a finished WAV through the given player (quiet, exits on end, no window). */
+function playerArgs(player, wav) {
+    switch (player) {
+        case 'ffplay': return ['-nodisp', '-autoexit', '-loglevel', 'quiet', wav];
+        case 'paplay': return [wav];
+        case 'aplay':
+        default: return ['-q', wav];
+    }
+}
+export class PiperTts {
+    name = 'piper';
+    label = 'Piper (neural, local, no key)';
+    model;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
+    constructor(model = PIPER_MODEL) { this.model = model; }
+    /** The voice id this engine speaks with (the model basename), for the status line. */
+    get voiceName() { return DEFAULT_PIPER_VOICE; }
+    /** True when Piper can speak ALOUD here: the binary, the voice model and a player are all present. */
+    async available() {
+        return resolvePiperBin() !== null && existsSync(this.model) && pickPlayer() !== null;
+    }
+    /** True when Piper can SYNTHESISE here (binary + model) even with no audio device (used for the proof). */
+    canSynth() {
+        return resolvePiperBin() !== null && existsSync(this.model);
+    }
+    /** Piper's voice is the model; there is no per-machine installed-voice list to cycle. */
+    async listVoices() { return [DEFAULT_PIPER_VOICE]; }
+    /**
+     * Synthesise `text` to a WAV at `outPath`. Resolves on success, rejects on a missing binary/model or a
+     * non-zero exit. This is the engine's testable, audio-device-free core — the Docker proof and the unit
+     * tests drive it directly. The text is sanitised and delivered on stdin, exactly as speak() does.
+     */
+    synthToFile(text, outPath, opts = {}) {
+        const bin = resolvePiperBin();
+        const safe = sanitizeSpeech(text);
+        return new Promise((resolve, reject) => {
+            if (!bin) {
+                reject(new Error('piper binary not found'));
+                return;
+            }
+            const args = ['--model', this.model, '--output_file', outPath];
+            if (typeof opts.lengthScale === 'number' && Number.isFinite(opts.lengthScale)) {
+                args.push('--length_scale', String(opts.lengthScale)); // >1 = slower speech
+            }
+            let child;
+            try {
+                child = spawn(bin, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+            }
+            catch (e) {
+                reject(e);
+                return;
+            }
+            let err = '';
+            child.stderr?.on('data', (d) => { err += d; });
+            child.stdin?.on('error', () => { });
+            // Piper reads one line of text from stdin; the sanitiser already collapsed newlines to one line.
+            try {
+                child.stdin?.end(safe + '\n');
+            }
+            catch { /* child gone */ }
+            child.on('error', reject);
+            child.on('close', (code) => code === 0
+                ? resolve()
+                : reject(new Error(`piper exit ${code}: ${err.slice(-200)}`)));
+        });
+    }
+    speak(text, opts = {}) {
+        this.stopCurrent(); // single queue: never two speakers at once
+        const player = pickPlayer();
+        // rate: map the words-per-minute feel to Piper's length_scale (lower rate → slower → larger scale).
+        const lengthScale = typeof opts.rate === 'number' && opts.rate > 0 ? Math.max(0.5, Math.min(2, 190 / opts.rate)) : undefined;
+        let child = null;
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        const dir = mkdtempSync(join(tmpdir(), 'dexterm-piper-'));
+        const wav = join(dir, 'speech.wav');
+        const cleanup = () => { try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ } };
+        const finish = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            cleanup();
+            resolve();
+        };
+        const handle = {
+            done,
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                if (this.current === handle)
+                    this.current = null;
+                try {
+                    child?.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                cleanup();
+                resolve();
+            },
+        };
+        this.current = handle;
+        if (!player) {
+            queueMicrotask(finish);
+            return handle;
+        } // no player → can't speak aloud; degrade to text
+        // Synthesise, then play. Piper's RTF is ~0.16, so synth is fast; first audio is the player spawn.
+        this.synthToFile(text, wav, lengthScale !== undefined ? { lengthScale } : {}).then(() => {
+            if (stopped)
+                return;
+            try {
+                child = spawn(player, playerArgs(player, wav), { stdio: 'ignore' });
+                child.on('spawn', () => { if (!stopped)
+                    opts.onFirstAudio?.(); });
+                child.on('error', finish);
+                child.on('close', finish);
+            }
+            catch {
+                finish();
+            }
+        }).catch(finish); // synth failed (bad binary/model) → degrade to text
+        return handle;
+    }
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

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

@@ -0,0 +1,132 @@
+// macOS `say` TTS engine (task-1282, hardened task-1393). `say` ships with macOS, needs no key and no
+// network, so it is the free/portable default (SPEC: macOS say first). It streams to the audio device,
+// so time-to-first-audio is close to process spawn. speak() is interruptible via stop() (SIGTERM to the
+// child), which is how a key or the user starting to talk cuts a reply short.
+//
+// task-1393 hardening:
+//   - text is SANITISED (no `[[…]]` embedded commands, no leading-`-` flag, addresses shortened, capped)
+//   - text is delivered on STDIN (`say -f -`), never as the last argv word
+//   - a new speak() cleanly INTERRUPTS the current one, so two `say` processes never overlap (one queue)
+//   - the voice is always EXPLICIT (resolved to a deep British male upstream); it never falls back to the
+//     machine's system voice
+import { spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { parseSayVoices, sanitizeSpeech } from "./voices.js";
+export const SAY_BIN = process.env.DEXTERM_SAY_BIN || 'say';
+/** Consistent speaking rate (words-per-minute-ish) for every reply path. */
+export const DEFAULT_RATE = 190;
+export class SayTts {
+    name = 'say';
+    label = 'macOS say (built-in, no key)';
+    defaultVoice;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
+    constructor(defaultVoice) { this.defaultVoice = defaultVoice; }
+    /** The resolved default voice this engine speaks with — used to seed the controller / status line. */
+    get voiceName() { return this.defaultVoice; }
+    async available() {
+        if (process.platform !== 'darwin')
+            return false;
+        return new Promise((resolve) => {
+            try {
+                const child = execFile(SAY_BIN, ['-v', '?'], { timeout: 4000 }, (err) => resolve(!err || err.code !== 'ENOENT'));
+                child.on('error', () => resolve(false));
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    }
+    /** Installed voices with their locale. Robust against the single-space padding on long voice names. */
+    async listVoicesDetailed() {
+        return new Promise((resolve) => {
+            try {
+                execFile(SAY_BIN, ['-v', '?'], { timeout: 5000, maxBuffer: 1 << 20 }, (err, stdout) => {
+                    resolve(err || !stdout ? [] : parseSayVoices(stdout));
+                });
+            }
+            catch {
+                resolve([]);
+            }
+        });
+    }
+    /** Selectable voice names (the TtsEngine contract). */
+    async listVoices() {
+        return (await this.listVoicesDetailed()).map((v) => v.name);
+    }
+    speak(text, opts = {}) {
+        // One queue: cut off whatever is playing so two `say` processes never overlap (clean interrupt).
+        this.stopCurrent();
+        const voice = opts.voice ?? this.defaultVoice;
+        const rate = opts.rate ?? DEFAULT_RATE;
+        // Sanitise the UNTRUSTED text first, then prepend our own TRUSTED pitch command. Order matters: the
+        // sanitiser strips any `[[…]]` the text tried to smuggle, so only our validated `[[pbas N]]` survives.
+        let safe = sanitizeSpeech(text);
+        if (typeof opts.pitch === 'number' && Number.isFinite(opts.pitch)) {
+            const pbas = Math.max(0, Math.min(100, Math.round(opts.pitch)));
+            safe = `[[pbas ${pbas}]] ${safe}`;
+        }
+        const args = [];
+        if (voice)
+            args.push('-v', voice);
+        args.push('-r', String(rate));
+        args.push('-f', '-'); // read the utterance from stdin — the text is 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 {
+            child = spawn(SAY_BIN, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            // Nothing is spoken until stdin is closed; write the sanitised text and end it.
+            child.stdin?.on('error', () => { });
+            try {
+                child.stdin?.end(safe);
+            }
+            catch { /* child gone */ }
+            // `say` has no first-sample hook; the spawn event is the closest honest lower bound and is what the
+            // latency table reports as "first spoken word" for this engine.
+            child.on('spawn', () => { if (!stopped)
+                opts.onFirstAudio?.(); });
+            child.on('error', finish);
+            child.on('close', finish);
+        }
+        catch {
+            // No `say` on this machine: resolve immediately so the caller degrades to text.
+            queueMicrotask(finish);
+        }
+        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;
+    }
+    /** Stop the currently-playing utterance, if any. */
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

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

@@ -0,0 +1,206 @@
+// Voice resolution, the novelty ban-list, and speech-text sanitisation (task-1393). All pure and
+// dependency-free so every rule is unit-testable without spawning `say`.
+//
+// Why this exists: SayTts used to be constructed with NO default voice, so macOS fell back to the
+// machine's *system* voice — which differs per machine and can be a novelty/odd voice (a maintainer heard a
+// "terrifying" one). This module makes the default an EXPLICIT deep British male and guarantees a
+// novelty voice (Zarvox, Bad News, …) can never be auto-selected and the system default is never used
+// silently: if nothing safe is installed, voice degrades to text (voice === null), never to "whatever
+// the OS picks".
+/**
+ * Novelty / "scary" voices that must never be auto-selected, normalised to lowercase base names (the
+ * locale qualifier like " (English (UK))" is stripped first — see normalizeVoiceName). The list is the
+ * classic MacinTalk novelty set plus the names the task named explicitly ("and similar"). The resolver
+ * also uses POSITIVE allow-lists, so this is defence in depth; the ban test asserts no resolved voice
+ * is ever on it.
+ */
+export const BANNED_VOICE_NAMES = new Set([
+    'albert', 'bad news', 'bahh', 'bells', 'boing', 'bubbles', 'cellos', 'deranged', 'fred',
+    'good news', 'hysterical', 'jester', 'junior', 'organ', 'pipe organ', 'princess', 'ralph',
+    'superstar', 'trinoids', 'whisper', 'wobble', 'zarvox',
+]);
+/**
+ * Strip the locale qualifier macOS appends to the newer voices ("Eddy (English (UK))" → "Eddy"),
+ * collapse whitespace, lowercase. Used for ban/allow matching so "Eddy (English (US))" and
+ * "Eddy (English (UK))" share one base name.
+ */
+export function normalizeVoiceName(name) {
+    return name.replace(/\s*\(.*\)\s*$/, '').trim().toLowerCase();
+}
+/** True when a voice is on the novelty ban-list (matched on its normalised base name). */
+export function isBannedVoice(name) {
+    return BANNED_VOICE_NAMES.has(normalizeVoiceName(name));
+}
+/**
+ * Parse the output of `say -v '?'`. Each line is `<name>  <locale>  # <sample sentence>`, but the name
+ * column is only padded to a fixed width, so a LONG name ("Eddy (English (UK))") leaves a SINGLE space
+ * before the locale — the old regex required two and silently dropped exactly the en_GB voices we care
+ * about. This parser anchors on the trailing locale token instead, so it never loses a voice.
+ */
+export function parseSayVoices(stdout) {
+    const voices = [];
+    for (const raw of stdout.split('\n')) {
+        if (!raw.trim())
+            continue;
+        const hash = raw.indexOf('#');
+        const left = (hash >= 0 ? raw.slice(0, hash) : raw).trimEnd();
+        // name = everything up to the last whitespace run; locale = the final token (en, en_GB, zh-CN…).
+        const m = left.match(/^(.*\S)\s+([a-z]{2}(?:[_-][A-Za-z0-9]+)?)$/);
+        if (m)
+            voices.push({ name: m[1].trim(), locale: m[2] });
+    }
+    return voices;
+}
+/**
+ * Deep British male voices, best-to-worst. Eddy (the maintainers' pick, 2026-10-15) is the dexterm default; Daniel is the canonical deep British male that
+ * ships with every macOS and is the next fallback. Oliver/Arthur are the newer en_GB male voices (present only if the
+ * user downloaded them). Matched on normalised base name.
+ */
+export const BRITISH_MALE_PREFERENCE = ['eddy', 'daniel', 'oliver', 'arthur'];
+/**
+ * Per-voice delivery defaults, applied only when the user has not saved their own rate/pitch. Eddy's are
+ * the values of the audition sample chosen (2026-10-15: 06-eddy-uk-deep-slow = rate 168, pbas 30).
+ */
+export const VOICE_STYLE_DEFAULTS = {
+    eddy: { rate: 168, pitch: 30 },
+};
+/** The delivery defaults for a resolved voice name, or undefined to use the engine-wide defaults. */
+export function voiceStyleDefaults(name) {
+    return name ? VOICE_STYLE_DEFAULTS[normalizeVoiceName(name)] : undefined;
+}
+/**
+ * en_GB voices that read masculine / neutral and are acceptable British fallbacks when no first-class
+ * British male is installed (Grandpa is explicitly a male voice; Eddy/Reed/Rocko are the modern
+ * expressive voices under audition). Matched on normalised base name, en_GB locale only.
+ */
+export const BRITISH_FALLBACK = ['grandpa', 'eddy', 'reed', 'rocko'];
+/** Safe English male voices in any English locale, used only when nothing British is installed. */
+export const ENGLISH_MALE_ALLOW = ['daniel', 'oliver', 'arthur', 'alex', 'tom', 'aaron', 'rishi'];
+const isEnglish = (locale) => /^en([_-]|$)/i.test(locale);
+const isBritish = (locale) => /^en[_-]gb$/i.test(locale);
+/** Pick the best installed match for a base name, preferring an Enhanced/Premium variant and the given locale. */
+function bestMatch(installed, base, preferLocale) {
+    const matches = installed.filter((v) => normalizeVoiceName(v.name) === base && !isBannedVoice(v.name));
+    if (!matches.length)
+        return null;
+    const score = (v) => {
+        let s = 0;
+        if (/\((enhanced|premium)\)/i.test(v.name))
+            s += 4; // higher-quality download, if present
+        if (preferLocale?.(v.locale))
+            s += 2;
+        return s;
+    };
+    return matches.slice().sort((a, b) => score(b) - score(a))[0];
+}
+/**
+ * Find the installed voice a saved name refers to. The `,` key saves the FULL name ("Eddy (English (UK))"),
+ * and Eddy/Reed/Rocko each exist in many languages, so an exact full-name match must win. Only when the
+ * saved name is a bare base name ("Eddy") do we choose among same-base voices: en_GB first, then any
+ * English, then anything else (a verifier found "Reed (English (UK))" resolving to the German Reed).
+ */
+function findConfiguredVoice(installed, configured) {
+    const exact = installed.find((v) => v.name === configured && !isBannedVoice(v.name));
+    if (exact)
+        return exact;
+    const folded = configured.toLowerCase();
+    const ci = installed.find((v) => v.name.toLowerCase() === folded && !isBannedVoice(v.name));
+    if (ci)
+        return ci;
+    const base = normalizeVoiceName(configured);
+    const rank = (v) => (isBritish(v.locale) ? 0 : isEnglish(v.locale) ? 1 : 2);
+    return installed
+        .filter((v) => normalizeVoiceName(v.name) === base && !isBannedVoice(v.name))
+        .sort((a, b) => rank(a) - rank(b))[0];
+}
+/**
+ * Resolve the voice `say` should use. The fallback chain, in order:
+ *   1. the user's configured voice (if installed and not banned)
+ *   2. the chosen default: a British male (Eddy → Daniel → Oliver → Arthur), Enhanced/Premium preferred
+ *   3. the next British voice (en_GB Grandpa/Eddy/Reed/Rocko)
+ *   4. any safe English male voice (Alex/Tom/…)
+ *   5. null → replies stay text-only
+ * A banned (novelty) voice is NEVER returned, and the OS system default is NEVER used silently.
+ */
+export function resolveVoice(opts) {
+    const installed = opts.installed ?? [];
+    const configured = opts.configured?.trim();
+    // 1. Configured voice wins when it is actually installed and safe.
+    if (configured) {
+        const hit = findConfiguredVoice(installed, configured);
+        if (hit && !isBannedVoice(hit.name)) {
+            return { voice: hit.name, source: 'config', reason: `your configured voice (${hit.name})` };
+        }
+        // Configured but missing or banned: fall through to the safe default rather than honour a bad value.
+    }
+    // 2. Chosen default: British male (Eddy → Daniel → …). en_GB only: Eddy also exists in other locales.
+    const britishInstalled = installed.filter((v) => isBritish(v.locale));
+    for (const base of BRITISH_MALE_PREFERENCE) {
+        const v = bestMatch(britishInstalled, base, isBritish);
+        if (v) {
+            const isDefault = base === BRITISH_MALE_PREFERENCE[0];
+            return {
+                voice: v.name,
+                source: 'default',
+                reason: isDefault ? `${v.name} — deep British male (dexterm default)` : `${v.name} — British male voice`,
+            };
+        }
+    }
+    // 3. Next British voice (en_GB, masculine/neutral).
+    for (const base of BRITISH_FALLBACK) {
+        const v = installed.find((x) => normalizeVoiceName(x.name) === base && isBritish(x.locale) && !isBannedVoice(x.name));
+        if (v)
+            return { voice: v.name, source: 'british', reason: `${v.name} — British voice (no Daniel installed)` };
+    }
+    // 4. Any safe English male voice, any English locale.
+    for (const base of ENGLISH_MALE_ALLOW) {
+        const v = installed.find((x) => normalizeVoiceName(x.name) === base && isEnglish(x.locale) && !isBannedVoice(x.name));
+        if (v)
+            return { voice: v.name, source: 'english', reason: `${v.name} — English voice (no British male installed)` };
+    }
+    // 5. Nothing safe: text only. Never the system default.
+    return { voice: null, source: 'none', reason: 'no safe voice installed — spoken replies are off (text still works)' };
+}
+// ------------------------------------------------------------------ speech-text sanitisation
+/** Default cap on spoken length. Long analyst answers are summarised upstream; this is a hard backstop. */
+export const MAX_SPEAK_CHARS = 600;
+const BASE58 = '1-9A-HJ-NP-Za-km-z';
+/** A Solana mint / base58 address (32-44 chars) or a 0x… EVM address — never read 44 characters aloud. */
+const ADDRESS_RE = new RegExp(`\\b(?:0x[0-9a-fA-F]{40}|[${BASE58}]{32,44})\\b`, 'g');
+/** Short, speakable form of an address: "7xKX…Dgkp" reads as a few characters, not forty-four. */
+function shortAddress(addr) {
+    const body = addr.startsWith('0x') ? addr.slice(2) : addr;
+    return `${body.slice(0, 4)}…${body.slice(-4)}`;
+}
+/**
+ * Make arbitrary text safe to hand to `say`. Untrusted text (token names, socials, analyst output) can
+ * contain `say`'s own `[[…]]` embedded speech commands — `[[slnc 5000]]`, `[[rate 10]]`, even a voice
+ * switch — which `say` INTERPRETS whether the text arrives on argv or stdin. We also never want a
+ * leading `-` parsed as a flag. This:
+ *   - defuses `[[` / `]]` so no embedded command is ever executed (kept readable, not deleted)
+ *   - neutralises a leading `-`/`+` (defence in depth; we also deliver via stdin, not argv)
+ *   - collapses control characters and whitespace
+ *   - shortens contract addresses to a 4…4 form instead of reading 44 characters
+ *   - caps the length on a word boundary
+ */
+export function sanitizeSpeech(text, opts = {}) {
+    const maxChars = opts.maxChars ?? MAX_SPEAK_CHARS;
+    let s = String(text ?? '');
+    // Defuse `say` embedded commands: a split `[ [` / `] ]` is no longer a command token.
+    s = s.replace(/\[\[/g, '[ [').replace(/\]\]/g, '] ]');
+    // Strip control characters (NUL, ESC, etc.) that could confuse the child or the terminal.
+    s = s.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, ' ');
+    // Shorten addresses so we don't read 44 characters aloud.
+    s = s.replace(ADDRESS_RE, (m) => shortAddress(m));
+    // Collapse whitespace.
+    s = s.replace(/\s+/g, ' ').trim();
+    // A leading dash/plus could be read as a flag if it ever reached argv; neutralise it.
+    s = s.replace(/^[-+]+\s*/, '');
+    // Cap length on a word boundary.
+    if (s.length > maxChars) {
+        const cut = s.slice(0, maxChars);
+        const sp = cut.lastIndexOf(' ');
+        s = (sp > maxChars * 0.6 ? cut.slice(0, sp) : cut).trim();
+    }
+    return s;
+}

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

@@ -0,0 +1,3 @@
+// Shared types for @dexterm/voice (task-1282). Everything here is UI- and engine-agnostic so the
+// controller can be driven headlessly with fakes in tests and with the real macOS engines in the app.
+export {};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "dexterm-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "dexterm: terminal DEX screener with a local Claude CLI analyst",
+  "author": "The dexterm authors",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dexterm-xyz/dexterm.git"
+  },
+  "type": "module",
+  "bin": {
+    "dexterm": "./dist/packages/cli/bin/dexterm.mjs"
+  },
+  "exports": {
+    ".": "./dist/packages/cli/src/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "node scripts/build-dist.mjs"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@dexterm/agents": "0.0.1",
+    "@dexterm/custom": "0.0.1",
+    "@dexterm/data": "0.0.1",
+    "@dexterm/mcp": "0.0.1",
+    "@dexterm/packs": "0.0.1",
+    "@dexterm/popup": "0.0.1",
+    "@dexterm/recorder": "0.0.1",
+    "@dexterm/tui": "0.0.1",
+    "@dexterm/voice": "0.0.1"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.