Voice provider abstraction: swappable engines + fully local STT/TTS (#36, #37)

[noisy]

What

A provider seam between the daemon and its voice engines (#36), and the first alternative provider: fully local, offline STT + TTS (#37).

• providers/ package: TTSProvider/STTProvider protocols with capability flags; the registry re-reads providers.json (config dir) on every call, so switching engines is a file write - live immediately, no restart. Unknown names fall back to Grok.
• Grok becomes a thin adapter over the existing clients; its exceptions subclass the new provider errors. Voice identity stays in the daemon - providers only receive a voice_id.
• Local provider: STT via faster-whisper (model size configurable), TTS via Kokoro (kokoro-onnx) with natural offline voices; macOS say remains a zero-dependency fallback (local.tts_engine: "say"). Both report $0 cost. Batch-only providers automatically fall back to the daemon's batch paths.
• Switching UI: GET/POST /providers (purely additive; /status, static serving and /shutdown untouched) + ProviderSettings.vue in SETTINGS -> SYSTEM, generated from per-provider catalog metadata (providers/manifest.py) - a future provider (OpenAI, Provider abstraction: support OpenAI voice APIs (STT + TTS) alongside Grok #36) needs no new frontend code, just fields in its manifest entry.
• Model downloads: picking a local engine prefetches weights in a background thread; the UI polls during a download and draws byte-accurate progress for Kokoro, coarse state for whisper (huggingface_hub exposes no byte callback), checkmarks with sizes for what's on disk, and keeps failures visible.
• Storybook: ProviderSettings.stories.ts with nine states (grok/local/mixed/not-ready, downloading, downloaded, failed, old daemon without the endpoint).

Heads-up for reviewers

• First local use downloads ~340 MB (Kokoro model + voices) into CONFIG_DIR/models/kokoro/, plus the whisper model into the HF cache. The prefetch + progress bar make this visible, never dead air on the first utterance.
• uv.lock was regenerated with --no-config (a machine-global uv index required credentials); the diff only adds the optional local extra: faster-whisper, kokoro-onnx.
• SynthesizedAudio moved to providers/base.py; tts.py re-exports it, so existing imports keep working.
• New deps are behind the optional extra: uv sync --extra local.

Testing

• 179 Python unit tests (18 new) and 179 dashboard tests green; ruff clean.
• Live-verified against a scratch daemon: runtime switching, repeated GET /providers (regression test for a catalog-shadowing bug the live check caught), and a spoken utterance rendered by Kokoro through /speak.
• Offline round-trip: Kokoro synthesis -> faster-whisper transcription reproduces the sentence exactly.

Closes #37, groundwork for #36 (OpenAI provider intentionally not registered yet - no keys).

🤖 Generated with Claude Code

[noisy]

User-perspective review, as requested (flow: first contact -> switching -> downloads -> failure states).

HIGH - first contact still hardwires the xAI key. The full-screen FIRST CONTACT gate (App.vue, unconfigured = !api_key_set) demands a key before anything works, so the local/offline promise of this PR is unreachable for exactly the user it targets. manifest.py's own docstring names the fix: ask "which engine?" first. Suggested shape: the gate shows two cards driven by the catalog - "Cloud (Grok)": paste key, as today; "Local (offline)": no key, kicks the prefetch and shows the existing progress bars. unconfigured then becomes "no ready provider selected" rather than "no key". Can be a follow-up PR, but v3.0-beta first-run should not dead-end local users.

MED - NOT READY is a label, not a path. The chooser badges an engine "NOT READY" but never says why or how to fix it, and still lets you select it. The catalog already knows the reason (missing secret vs missing install). When the picked engine is not ready, render its fields/hint inline: for grok the key field, for local the install one-liner (uv sync --extra local).

MED - _local_ready() doesn't check what the default engine needs. It requires faster_whisper + say, but the default TTS engine is kokoro, which needs kokoro-onnx. Result: catalog says ready, user switches, and the failure surfaces only at first speak, in daemon logs. Either include find_spec("kokoro_onnx") when tts_engine != "say", or report per-direction readiness.

LOW - failed downloads have no retry. The FAILED row shows the detail (good), but recovery is re-picking the engine, which nothing suggests. A small RETRY on the error row, or even a hint in the text block, closes the loop.

LOW - stale field label. "System voice (empty = default)" only applies to the say engine, while the default is kokoro - as-is it reads like it configures the voice you actually hear. Label it "say voice" and show it only when `tts_engine = say", or add a kokoro voice choice instead.

Everything else held up nicely in reading: the additive routes, the self-contained component, download visibility rules ("never hide an error"), and the catalog-driven form. Nice work.

[noisy]

Round 2. The engine-first gate is the right shape - cloud path untouched, local is genuinely one click, remedies render inline, RETRY and the engine-conditional voice field are in. Three findings, then I expect to be done:

MED - the gate closes while the weights are still downloading. voice_ready() is true the moment the selected providers' deps are in place - it ignores whether the models are on disk. Picking LOCAL flips it true, the overlay unmounts on the next status poll, and the in-gate progress bars the card promises ("download while you watch") vanish mid-flight. Worse, a user who speaks right away gets minutes of silence while _ensure_downloaded blocks the first utterance. Fix: for the local provider, voice_ready should also require the weights to be present (downloads registry shows no missing/downloading/error for the selected engine) - that matches its own docstring, "can the daemon hear AND speak RIGHT NOW". Then the ok-line's "this gate closes by itself" becomes true at the right moment: when the last bar completes.

LOW - the poll fights the user's card choice. refresh() runs every second while downloading and calls setChosen("local") whenever localActive - so a user who picked LOCAL, saw 340 MB, and clicked CLOUD to paste a key instead is yanked back to the local card on the next tick. Force the choice once (first load), not on every refresh.

LOW - raw String(error) in user-facing notes (both EngineChoice and ProviderSettings). An axios failure prints as Error: Request failed with status code 500. One tiny helper that prefers the daemon's error body and falls back to a generic "the daemon refused - check its log" would read much better.

Nothing else - the catalog-driven fields, per-engine readiness with kokoro_onnx, story coverage and the additive /status key all look right.

[noisy]

Round 3. All three round-2 fixes verified in the diff and by running the provider tests here (14 passed). One genuine edge left, then I'm done:

MED (last one) - models_present() is not direction-aware. voice_ready() calls it when EITHER direction is local, but it always demands BOTH the kokoro weights (unless say) AND the whisper cache. A mixed setup - tts=local + stt=grok with a valid key, kokoro weights on disk - is fully able to hear and speak, yet voice_ready returns false because whisper isn't cached, and the first-contact gate locks the user out of a working configuration. Mirror the split: require kokoro weights only when TTS is local, the whisper cache only when STT is local.

The friendly() regex over the error text is mildly fragile, but it has a human fallback - not blocking, just noting it.

Fix the direction split and, from my side, this is merge-ready.

[noisy]

Round 4: verified the direction-aware fix in the diff and ran the full unit suite here - 181 passed. No findings left. Merge-ready from my side. Nice iteration - five findings to zero in three rounds, with each fix pinned by a test.

[noisy]

Post-approval notes from review (non-blocking, for a future pass — recording them so they survive the stream session):

1. downloadsFor() in SignalPath.vue routes weights to pills by name prefix (whisper/kokoro/voices); a third provider's weights would silently route nowhere. A direction field on the download record is the sturdier shape.
2. flip() hardcodes grok as the only cloud engine — needs to consult the catalog once OpenAI lands (Provider abstraction: support OpenAI voice APIs (STT + TTS) alongside Grok #36).
3. One timing-sensitive Python test flaked once under heavy machine load (204 s run) and passed on every normal run since; if it flakes again, capture the name and pin it.

🤖 Generated with Claude Code