@clearlysh/beehaven 0.8.16

package/dist/tts-qwen3.js

@@ -0,0 +1,547 @@
+/**
+ * tts-qwen3.ts — the `qwen3-mlx` TTS provider: Qwen3-TTS under Apple MLX,
+ * running entirely on this machine, with 3-second voice cloning.
+ *
+ * WHY. Every other voice `beehaven speak` can use is either a network call
+ * (cloud Kokoro over the relay, ElevenLabs on the canvas) or a canned system
+ * voice (macOS `say`). So an agent in a terminal with no daemon token has no
+ * voice at all, and nobody has *their own* voice. Qwen3-TTS fixes both: it's
+ * local (no relay, no API key, no audio leaves the box) and it clones from a
+ * short reference recording.
+ *
+ * SHAPE. This file is the Node half; `python/qwen3_tts.py` is the MLX half.
+ * They talk over one JSON object on stdin and one on stdout — see that file's
+ * header for the contract. Everything that could reasonably be done in Node
+ * (path resolution, the voice registry, install) lives HERE, so the Python
+ * side stays a thin, replaceable synthesis shim.
+ *
+ * STATE ON DISK (`~/.beehaven/voice/qwen3-mlx/`):
+ *
+ *   venv/                 the Python environment (mlx-audio + mlx)
+ *   voices/<name>.json    voice profile: { name, refAudio, refText, ... }
+ *   voices/<name>.<ext>   a COPY of the reference recording
+ *
+ * The reference is copied, not linked, on purpose: a profile that points into
+ * ~/Downloads breaks the first time the user cleans that folder out, and it
+ * would break silently — mid-sentence, weeks later. Profiles are self-contained.
+ *
+ * Models themselves are NOT stored here — they land in the shared Hugging Face
+ * cache (`~/.cache/huggingface`), so a machine that already pulled Qwen3 for
+ * something else doesn't download it twice.
+ */
+import { execFileSync, spawn } from 'child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { dirname, extname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Everything this provider owns lives under one directory. */
+export const QWEN3_ROOT = join(homedir(), '.beehaven', 'voice', 'qwen3-mlx');
+const VENV_DIR = join(QWEN3_ROOT, 'venv');
+const VOICES_DIR = join(QWEN3_ROOT, 'voices');
+const VENV_PYTHON = join(VENV_DIR, 'bin', 'python');
+/**
+ * The default checkpoint. `-Base` is REQUIRED for cloning — the other two
+ * families can't take a reference recording at all (CustomVoice is fixed
+ * predefined speakers, VoiceDesign builds a voice from a text description).
+ * 0.6B-4bit is the small/fast end of the family: ~0.4 GB, roughly real-time
+ * on an M-series laptop, which is the right trade for one-line status
+ * utterances. Override with `BEEHAVEN_QWEN3_TTS_MODEL` (e.g. the 1.7B-8bit
+ * checkpoint for higher fidelity at ~2 GB and slower generation).
+ */
+export const QWEN3_DEFAULT_MODEL = process.env.BEEHAVEN_QWEN3_TTS_MODEL || 'mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit';
+/**
+ * The CustomVoice sibling — the ONLY family that honours a named speaker.
+ *
+ * ⚠⚠ THE TWO FAMILIES ARE MUTUALLY EXCLUSIVE, WHICH IS WHY THIS IS A SECOND
+ * CONSTANT RATHER THAN A NEW DEFAULT. Base takes a reference recording and ignores
+ * speaker names; CustomVoice takes speaker names and cannot clone. Switching the
+ * default outright would silently break every cloned voice on the machine.
+ *
+ * `synthesize` therefore picks the checkpoint FROM THE VOICE it was asked for. A
+ * caller who pins the model explicitly (`BEEHAVEN_QWEN3_TTS_MODEL`, or `opts.model`)
+ * keeps it — their choice is more specific than this inference.
+ */
+export const QWEN3_CUSTOMVOICE_MODEL = process.env.BEEHAVEN_QWEN3_CUSTOMVOICE_MODEL
+    || 'mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit';
+/**
+ * The model's built-in speakers.
+ *
+ * ⚠⚠ ONLY MEANINGFUL ON A CustomVoice CHECKPOINT. Base discards the name entirely —
+ * measured at **0.6% difference between two different speakers**, i.e. the same
+ * voice. Asking for a preset therefore SWITCHES THE MODEL (see `synthesize`).
+ *
+ * ⚠⚠ THIS LIST WAS WRONG ONCE AND THE MODEL IS THE AUTHORITY. An earlier version
+ * held `ethan, chelsie, cherry, nofish, jada, sunny` — names that do not exist on
+ * any checkpoint here; the real set came from the runtime error
+ * (`Speaker 'ethan' not supported. Available: [...]`). Treat this as a hint for
+ * error messages and completion, never as validation the model has not confirmed:
+ * mlx-audio raises with the true list, which is worth more than anything hardcoded.
+ *
+ * ⚠ SEPARATE NAMESPACE FROM THE CLONED REGISTRY (`~/.beehaven/voice/qwen3-mlx/
+ * voices/`). A cloned profile wins if the names collide, because it is the more
+ * specific thing the user made themselves — and on Base it is the only thing that
+ * actually pins a voice.
+ */
+export const QWEN3_PRESET_SPEAKERS = [
+    // ── measured reliable, most consistent first ──
+    'serena', 'aiden', 'vivian',
+    // ⚠⚠ THE REST PRODUCE RUNAWAY TAKES — see QWEN3_UNRELIABLE_SPEAKERS below.
+    'dylan', 'uncle_fu', 'ryan', 'sohee', 'eric', 'ono_anna',
+];
+/**
+ * ⚠⚠ SPEAKERS THAT GENERATE FOR MINUTES ON A SIX-SECOND SENTENCE.
+ *
+ * The model advertises nine speakers; only three behave. Measured, 4 runs each of a
+ * 72-character sentence that should be ~6s of speech:
+ *
+ *     serena    6.2s   aiden  5.9s   vivian  6.5s      ← usable
+ *     uncle_fu 90.7s   ryan  87.5s   eric   86.8s
+ *     sohee   167.3s   dylan 87.2s (at temp 0.3)       ← runaway
+ *     ono_anna — degenerate at every temperature tried
+ *
+ * This is not a quality difference, it is a failure mode: the decoder never stops,
+ * so a one-line status utterance blocks for minutes and plays nonsense. Worth a
+ * loud warning rather than a silent bad experience — a caller who names one of
+ * these has almost certainly not tested it.
+ *
+ * ⚠ NOT A HARD BLOCK. They may behave on another checkpoint, another quantisation
+ * or a different temperature, and refusing outright would make that untestable.
+ */
+export const QWEN3_UNRELIABLE_SPEAKERS = [
+    'uncle_fu', 'ryan', 'sohee', 'eric', 'ono_anna', 'dylan',
+];
+/**
+ * Sampling temperature when the caller has not chosen one.
+ *
+ * ⚠ NOT A STYLE KNOB — at this model's default of 0.7 the speaker itself is
+ * resampled per utterance. See the note in `synthesize`. Override per call, or with
+ * `BEEHAVEN_QWEN3_TEMPERATURE` for a machine that wants more variation.
+ */
+export const QWEN3_STABLE_TEMPERATURE = Number(process.env.BEEHAVEN_QWEN3_TEMPERATURE) || 0.01;
+/**
+ * Default temperature for a PRESET speaker — deliberately higher than the cloning
+ * default above, which is the opposite of what you would expect.
+ *
+ * ⚠⚠ ON CustomVoice, NEAR-ZERO TEMPERATURE IS WHAT *CAUSES* THE RUNAWAY TAKES.
+ * The cloning path is steadier the lower you go (a reference recording pins the
+ * timbre, so sampling only adds noise). CustomVoice has no reference, and at 0.01
+ * the decoder falls into loops — `ryan` produced an unusable take at 0.3 but so did
+ * several others at 0.01, and `dylan` was fine at 0.01 and ran away at 0.3.
+ *
+ * Measured over 4 runs each: at 0.3, `serena` spread 14.0% / 6.8% / 14.1%
+ * (zcr/centroid/duration) at a sane 6.2s. Do not "unify" the two constants —
+ * they describe different mechanisms and were measured separately.
+ */
+export const QWEN3_PRESET_TEMPERATURE = Number(process.env.BEEHAVEN_QWEN3_PRESET_TEMPERATURE) || 0.3;
+/**
+ * Per-speaker temperature, because one number does not fit them.
+ *
+ * ⚠⚠ THE RELIABLE SPEAKERS DISAGREE ABOUT WHICH REGIME SUITS THEM, and the gap is
+ * not marginal. Measured over 4 runs each (zcr / centroid / duration spread):
+ *
+ *     serena   0.3   → 14.0% /  6.8% / 14.1%      0.01 → 8.0% / 24.1% / 11.1%
+ *     vivian   0.3   → 15.3% / 12.0% /  8.7%      0.01 → 26.6% / 22.0% / 15.0%
+ *     aiden    0.01  → 15.4% /  7.3% / 12.2%      0.3  → 10.4% / 58.1% / 21.9%
+ *
+ * `aiden` at the shared 0.3 default has an EIGHT-FOLD worse spectral spread than at
+ * 0.01 — it would sound like the least consistent of the three while being, at its
+ * own setting, the joint best. A single default silently hands some speakers their
+ * worst configuration.
+ *
+ * ⚠ ONLY THE MEASURED THREE ARE LISTED. Everything else falls back to
+ * `QWEN3_PRESET_TEMPERATURE`, which is the safer regime for speakers whose failure
+ * mode is a runaway take. Add a row only with numbers behind it.
+ */
+export const QWEN3_SPEAKER_TEMPERATURE = {
+    aiden: 0.01,
+    serena: 0.3,
+    vivian: 0.3,
+};
+/** Minimum mlx-audio with the Qwen3-TTS Base + ICL cloning path. */
+export const MLX_AUDIO_SPEC = process.env.BEEHAVEN_MLX_AUDIO_SPEC || 'mlx-audio>=0.4.6';
+/** Python the venv is built with. mlx-audio needs >=3.10; 3.13 has wheels for every dep. */
+const VENV_PYTHON_VERSION = '3.13';
+// ── Capability + install ────────────────────────────────────────────────────
+/** MLX is Apple-Silicon-only; on anything else this provider can't exist. */
+export function isSupported() {
+    return process.platform === 'darwin' && process.arch === 'arm64';
+}
+export function unsupportedReason() {
+    if (process.platform !== 'darwin')
+        return `qwen3-mlx needs macOS (this is ${process.platform})`;
+    if (process.arch !== 'arm64')
+        return `qwen3-mlx needs Apple Silicon (this is ${process.arch})`;
+    return '';
+}
+export function isInstalled() {
+    return existsSync(VENV_PYTHON);
+}
+/** The bundled Python half. Resolved, not assumed — dev tree and npm tarball differ. */
+function helperScript() {
+    const candidates = [
+        // dist/cli.js → ../python/qwen3_tts.py (dev tree AND the published tarball)
+        join(__dirname, '..', 'python', 'qwen3_tts.py'),
+        // If a bundler ever flattens python/ next to the JS.
+        join(__dirname, 'python', 'qwen3_tts.py'),
+        // Running straight from src/ under tsx.
+        join(__dirname, '..', '..', 'python', 'qwen3_tts.py'),
+    ];
+    for (const p of candidates)
+        if (existsSync(p))
+            return p;
+    throw new Error('qwen3_tts.py not found — the CLI install is incomplete. Reinstall with:\n' +
+        '    cd beehaven_sdk/packages/cli && npm run build && npm link');
+}
+function which(cmd) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const out = execFileSync(probe, [cmd], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const first = out.split('\n')[0]?.trim();
+        return first || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `uv` if it's anywhere we can find it — it builds the venv in seconds, pip takes minutes. */
+function findUv() {
+    return which('uv') ?? [join(homedir(), '.local', 'bin', 'uv'), '/opt/homebrew/bin/uv'].find(existsSync) ?? null;
+}
+function run(cmd, args, onLine) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        const feed = (buf) => {
+            const s = buf.toString();
+            stderr += s;
+            if (onLine)
+                for (const l of s.split('\n'))
+                    if (l.trim())
+                        onLine(l.trim());
+        };
+        p.stdout.on('data', feed);
+        p.stderr.on('data', feed);
+        p.on('error', (e) => resolve({ code: 1, stderr: String(e?.message ?? e) }));
+        p.on('close', (code) => resolve({ code: code ?? 1, stderr }));
+    });
+}
+/**
+ * Create `~/.beehaven/voice/qwen3-mlx/venv` and install mlx-audio into it.
+ *
+ * Deliberately its OWN venv rather than the user's system Python: mlx-audio
+ * pins `transformers` and `mlx` hard, and silently upgrading those inside
+ * whatever environment happens to be active is the kind of thing that breaks
+ * an unrelated project a week later.
+ */
+export async function install(onLine) {
+    if (!isSupported())
+        throw new Error(unsupportedReason());
+    mkdirSync(QWEN3_ROOT, { recursive: true });
+    const uv = findUv();
+    if (uv) {
+        // `--python 3.13` lets uv download a managed CPython if the machine has
+        // none — so setup works on a Mac with only the Xcode python.
+        const venv = await run(uv, ['venv', '--python', VENV_PYTHON_VERSION, VENV_DIR], onLine);
+        if (venv.code !== 0)
+            throw new Error(`uv venv failed:\n${venv.stderr.trim()}`);
+        const pip = await run(uv, ['pip', 'install', '--python', VENV_PYTHON, MLX_AUDIO_SPEC], onLine);
+        if (pip.code !== 0)
+            throw new Error(`uv pip install failed:\n${pip.stderr.trim()}`);
+    }
+    else {
+        const py = ['python3.13', 'python3.12', 'python3.11'].map(which).find(Boolean) ?? which('python3');
+        if (!py) {
+            throw new Error('No suitable Python found. Install uv (https://astral.sh/uv) or Python 3.11+, then re-run `beehaven voice setup`.');
+        }
+        const venv = await run(py, ['-m', 'venv', VENV_DIR], onLine);
+        if (venv.code !== 0)
+            throw new Error(`python -m venv failed:\n${venv.stderr.trim()}`);
+        const pip = await run(VENV_PYTHON, ['-m', 'pip', 'install', '-U', MLX_AUDIO_SPEC], onLine);
+        if (pip.code !== 0)
+            throw new Error(`pip install failed:\n${pip.stderr.trim()}`);
+    }
+    if (!existsSync(VENV_PYTHON))
+        throw new Error(`venv build produced no interpreter at ${VENV_PYTHON}`);
+}
+// ── Talking to the Python half ──────────────────────────────────────────────
+/**
+ * Run one helper command. JSON in, JSON out.
+ *
+ * `stderr` is captured rather than inherited because mlx-audio writes download
+ * bars and tokenizer warnings there, and dumping those into an agent's
+ * terminal mid-`speak` is noise. On failure the tail is folded into the thrown
+ * message — that's where the real cause usually is, since mlx-audio catches
+ * model-load errors itself and only prints them.
+ */
+async function helper(command, request, opts = {}) {
+    if (!isInstalled()) {
+        throw new Error('qwen3-mlx is not installed yet — run `beehaven voice setup`');
+    }
+    const script = helperScript();
+    const timeoutMs = opts.timeoutMs ?? 10 * 60_000;
+    return new Promise((resolve, reject) => {
+        const p = spawn(VENV_PYTHON, [script, command], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // Keep HF's progress bars off; we surface our own status.
+            env: { ...process.env, HF_HUB_DISABLE_PROGRESS_BARS: '1', PYTHONUNBUFFERED: '1' },
+        });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => {
+            p.kill('SIGKILL');
+            reject(new Error(`qwen3-mlx ${command} timed out after ${Math.round(timeoutMs / 1000)}s`));
+        }, timeoutMs);
+        p.stdout.on('data', (b) => (stdout += b.toString()));
+        p.stderr.on('data', (b) => {
+            const s = b.toString();
+            // Bound the buffer — a stuck download could stream megabytes.
+            stderr = (stderr + s).slice(-8000);
+            if (opts.onLine)
+                for (const l of s.split('\n'))
+                    if (l.trim())
+                        opts.onLine(l.trim());
+        });
+        p.on('error', (e) => {
+            clearTimeout(timer);
+            reject(new Error(`could not start python: ${e?.message ?? e}`));
+        });
+        p.on('close', () => {
+            clearTimeout(timer);
+            const line = stdout.trim().split('\n').filter(Boolean).pop();
+            if (!line) {
+                reject(new Error(`qwen3-mlx ${command} produced no result.\n${stderr.trim().slice(-1200)}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                reject(new Error(`qwen3-mlx ${command} returned unparsable output: ${line.slice(0, 300)}`));
+                return;
+            }
+            if (parsed?.ok === false) {
+                reject(new Error(`${parsed.error}\n${stderr.trim().slice(-800)}`.trim()));
+                return;
+            }
+            resolve(parsed);
+        });
+        p.stdin.write(JSON.stringify(request));
+        p.stdin.end();
+    });
+}
+export function probe() {
+    return helper('probe', {}, { timeoutMs: 60_000 });
+}
+// ── Voice registry ──────────────────────────────────────────────────────────
+/** Voice names become filenames, so keep them boring. */
+function assertVoiceName(name) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(name)) {
+        throw new Error(`invalid voice name ${JSON.stringify(name)} — use letters, digits, dot, dash, underscore`);
+    }
+}
+export function listVoices() {
+    if (!existsSync(VOICES_DIR))
+        return [];
+    const out = [];
+    for (const f of readdirSync(VOICES_DIR)) {
+        if (!f.endsWith('.json'))
+            continue;
+        try {
+            out.push(JSON.parse(readFileSync(join(VOICES_DIR, f), 'utf8')));
+        }
+        catch {
+            /* a hand-mangled profile shouldn't hide the rest of the list */
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function getVoice(name) {
+    const p = join(VOICES_DIR, `${name}.json`);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function removeVoice(name) {
+    const v = getVoice(name);
+    if (!v)
+        return false;
+    rmSync(join(VOICES_DIR, `${name}.json`), { force: true });
+    // Only remove the audio we copied in — never a path outside our own dir.
+    if (v.refAudio?.startsWith(VOICES_DIR))
+        rmSync(v.refAudio, { force: true });
+    return true;
+}
+/** Transcribe a recording with whisper (via the helper). Slow — clone-time only. */
+export function transcribe(audioPath, opts = {}) {
+    return helper('transcribe', { audio: audioPath }, { timeoutMs: 15 * 60_000, onLine: opts.onLine });
+}
+/**
+ * Register a cloned voice from a reference recording.
+ *
+ * `refText` — the transcript — is not optional to Qwen3: cloning is in-context
+ * learning, so the model needs to see the reference audio AND what was said in
+ * it. We resolve it ONCE here (whisper, or the caller's `--ref-text`) and store
+ * it, so synthesis never has to load a 1.6 GB STT model again.
+ */
+export async function cloneVoice(name, sourceAudio, opts = {}) {
+    assertVoiceName(name);
+    if (!existsSync(sourceAudio))
+        throw new Error(`reference audio not found: ${sourceAudio}`);
+    if (getVoice(name) && !opts.force) {
+        throw new Error(`voice "${name}" already exists — pass --force to overwrite`);
+    }
+    mkdirSync(VOICES_DIR, { recursive: true });
+    const ext = extname(sourceAudio) || '.wav';
+    const stored = join(VOICES_DIR, `${name}${ext}`);
+    copyFileSync(sourceAudio, stored);
+    let refText = opts.refText?.trim();
+    let transcribedBy;
+    if (!refText) {
+        const t = await transcribe(stored, { onLine: opts.onLine });
+        refText = t.text;
+        transcribedBy = t.model;
+    }
+    const voice = {
+        name,
+        refAudio: stored,
+        refText: refText,
+        source: sourceAudio,
+        createdAt: Date.now(),
+        ...(transcribedBy ? { transcribedBy } : {}),
+    };
+    writeFileSync(join(VOICES_DIR, `${name}.json`), JSON.stringify(voice, null, 2));
+    return voice;
+}
+/**
+ * Synthesize `text` to a wav on disk.
+ *
+ * Returns the path rather than bytes because the consumer is `audio-play.ts`,
+ * which writes a temp file and hands it to `afplay` anyway — passing 300 KB
+ * through a pipe just to write it back out would be pure ceremony.
+ */
+export async function synthesize(text, opts = {}) {
+    const out = opts.out ?? join(tmpdir(), `beehaven-qwen3-${process.pid}-${Date.now()}.wav`);
+    const req = {
+        text,
+        out,
+        model: opts.model ?? QWEN3_DEFAULT_MODEL,
+        ...(opts.speed ? { speed: opts.speed } : {}),
+        ...(opts.temperature ? { temperature: opts.temperature } : {}),
+        // ⚠ `python/qwen3_tts.py` has forwarded this since it was written; the Node half
+        //   simply never sent it, so the single biggest expression control was
+        //   unreachable from the CLI. Same shape as preset speakers being refused here
+        //   while Python supported them.
+        ...(opts.instruct ? { instruct: opts.instruct } : {}),
+    };
+    let cloned = null;
+    if (opts.voice) {
+        cloned = getVoice(opts.voice);
+        if (cloned) {
+            req.refAudio = cloned.refAudio;
+            req.refText = cloned.refText;
+            /**
+             * ⚠ SAY SO RATHER THAN SILENTLY IGNORING IT. A style direction that measures
+             * 1–6% of movement is not a subtle effect, it is no effect — and a caller who
+             * asked for "in a whisper" and got a normal voice will blame the wording,
+             * not the checkpoint.
+             */
+            if (opts.instruct) {
+                console.error(`  ! style direction "${opts.instruct}" has almost no effect on a cloned voice — ` +
+                    'the reference recording sets the delivery. Use a CustomVoice preset ' +
+                    `(${QWEN3_PRESET_SPEAKERS.slice(0, 3).join(', ')}) to direct the style.`);
+            }
+        }
+        else if (QWEN3_PRESET_SPEAKERS.includes(opts.voice)) {
+            /**
+             * ⚠⚠ A PRESET SPEAKER SWITCHES THE CHECKPOINT, because Base cannot honour one.
+             *
+             * Measured on Base: `ethan` vs `eric` came out 0.6% apart on a speaker
+             * fingerprint — the name is discarded and the model keeps drawing a speaker
+             * per utterance. On CustomVoice the same comparison separates by 10–91%, so
+             * the name genuinely selects a voice.
+             *
+             * ⚠ AN EXPLICIT MODEL WINS. If the caller pinned one (`opts.model`, or
+             * `BEEHAVEN_QWEN3_TTS_MODEL`), respect it and let mlx-audio raise its own
+             * "Speaker 'x' not supported. Available: [...]" — that error names the true
+             * set, which is more useful than anything this file could assert.
+             */
+            const modelWasChosen = !!opts.model || !!process.env.BEEHAVEN_QWEN3_TTS_MODEL;
+            if (!modelWasChosen)
+                req.model = QWEN3_CUSTOMVOICE_MODEL;
+            /**
+             * ⚠ STILL REFUSE IF THE RESOLVED MODEL IS A Base ONE — which now only happens
+             * when the caller pinned it themselves. Accepting the name there would report
+             * `voice "x"` while the model kept drawing a speaker per utterance: a label
+             * that agrees with the request and disagrees with the audio. That combination
+             * is why "the voice still switches" survived the first fix, and it is worth a
+             * loud refusal rather than a silent no-op.
+             */
+            if (/-Base(-|$)/i.test(String(req.model))) {
+                throw new Error(`speaker "${opts.voice}" is ignored by this model (${req.model}) — Base checkpoints take a timbre only from a reference recording. ` +
+                    `Unset BEEHAVEN_QWEN3_TTS_MODEL to use ${QWEN3_CUSTOMVOICE_MODEL}, or clone a voice with \`beehaven voice clone <name> <audio>\`.`);
+            }
+            req.voice = opts.voice;
+            // ⚠ WARN, DO NOT REFUSE — see QWEN3_UNRELIABLE_SPEAKERS. Someone naming one
+            //   of these has almost certainly not heard it; someone testing one needs it
+            //   to still run.
+            if (QWEN3_UNRELIABLE_SPEAKERS.includes(opts.voice)) {
+                const msg = `  ! speaker "${opts.voice}" measured unreliable — it can generate for minutes on a short sentence. ` +
+                    `Reliable: ${QWEN3_PRESET_SPEAKERS.slice(0, 3).join(', ')}.`;
+                /**
+                 * ⚠ STDERR DIRECTLY, NOT ONLY `onLine`. The speak ladder calls `synthesize`
+                 * without an `onLine` handler, so routing this through the callback alone
+                 * put the warning nowhere — the exact failure it exists to prevent, one
+                 * layer up. Verified by running it: the callback version printed nothing.
+                 */
+                console.error(msg);
+                opts.onLine?.(msg);
+            }
+        }
+        else {
+            const known = listVoices().map((v) => v.name);
+            throw new Error(`unknown voice "${opts.voice}" — presets: ${QWEN3_PRESET_SPEAKERS.join(', ')}` +
+                (known.length ? `; cloned: ${known.join(', ')}` : '; clone one with `beehaven voice clone <name> <audio>`'));
+        }
+    }
+    /**
+     * ⚠⚠ TEMPERATURE IS A VOICE-IDENTITY SETTING HERE, NOT A STYLE KNOB — AND ITS
+     * DEFAULT WAS WHY "THE VOICE CHANGED RANDOMLY".
+     *
+     * With no reference audio the model SAMPLES a speaker, so at the Python half's
+     * default of 0.7 every utterance is a different person. Measured over 3 runs of
+     * one sentence, spread of a crude speaker fingerprint (zero-crossing rate /
+     * spectral centroid):
+     *
+     *     base voice, temp 0.7   →  75% / 81%     a different voice each time
+     *     "ethan",    temp 0.01  →  16% / 14%     recognisably one voice
+     *
+     * So the fix is BOTH: name a speaker, and stop sampling. This pins the low
+     * temperature whenever the caller has not asked for one, and leaves an explicit
+     * `--tts-voice`-style override alone.
+     *
+     * ⚠ n=3 per cell and the fingerprint is crude, so do not read the exact numbers
+     * as precise — the property that matters is that ≪0.7 is dramatically steadier.
+     * Raise it deliberately if the delivery starts sounding flat.
+     */
+    if (opts.temperature === undefined) {
+        // ⚠ WHICH DEFAULT DEPENDS ON WHICH MECHANISM IS PINNING THE VOICE. A preset
+        //   (CustomVoice) needs the HIGHER value; a reference recording (Base) needs
+        //   the lower one. See both constants — this was measured, not assumed, and
+        //   getting it backwards is what produces minutes-long runaway takes.
+        req.temperature = req.voice
+            ? (QWEN3_SPEAKER_TEMPERATURE[String(req.voice)] ?? QWEN3_PRESET_TEMPERATURE)
+            : QWEN3_STABLE_TEMPERATURE;
+    }
+    const res = await helper('speak', req, {
+        timeoutMs: opts.timeoutMs ?? 10 * 60_000,
+        onLine: opts.onLine,
+    });
+    return { ...res, ...(cloned ? { voice: cloned.name } : {}) };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Beehaven Daemon — Type Definitions
+// ============================================================================
+export {};

package/dist/utm.js

@@ -0,0 +1,38 @@
+// ============================================================================
+// UTM tagging for browser-opened clearly.sh URLs
+// ----------------------------------------------------------------------------
+// When the CLI opens a clearly.sh URL in the user's default browser (login,
+// signup, admin console, canvas), the navigation carries no web referrer — so
+// GA4 buckets the session as "(direct)", inflating direct traffic and hiding
+// real attribution. `withUtm()` stamps utm_source/utm_medium so those hits are
+// attributable to the CLI.
+//
+// ONLY clearly.sh / *.clearly.sh hosts are tagged. OAuth provider URLs
+// (accounts.google.com), Stripe, localhost dev servers, staging *.pages.dev,
+// and any other third-party URL pass through untouched. Existing query strings
+// are preserved and existing utm_* params are never overwritten (idempotent).
+// ============================================================================
+const DEFAULT_SOURCE = 'cli';
+const DEFAULT_MEDIUM = 'cli';
+function isClearlyHost(hostname) {
+    const h = hostname.toLowerCase();
+    return h === 'clearly.sh' || h.endsWith('.clearly.sh');
+}
+export function withUtm(rawUrl, source = DEFAULT_SOURCE, medium = DEFAULT_MEDIUM) {
+    try {
+        const u = new URL(rawUrl);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:')
+            return rawUrl;
+        if (!isClearlyHost(u.hostname))
+            return rawUrl;
+        if (!u.searchParams.has('utm_source'))
+            u.searchParams.set('utm_source', source);
+        if (!u.searchParams.has('utm_medium'))
+            u.searchParams.set('utm_medium', medium);
+        return u.toString();
+    }
+    catch {
+        // Non-absolute or malformed URL — leave it exactly as-is.
+        return rawUrl;
+    }
+}