Refactor: extract sub-hooks from packages/sdk/src/voice/use-voice.ts (1127 LOC)

[serge-ivo]

Follow-up to the largest-files audit (#125). packages/sdk/src/voice/use-voice.ts (1127 LOC) packs STT/TTS/VAD/modes/commands/timers/echo-guard into one hook.

Task

Extract sub-hooks useVoice composes: useStt, useTurnTimers, useVoiceCommands; keep the pure modules (vad/convo/config) as-is.

Constraints

• Behavior-preserving; keep SDK voice tests green; no change to the useVoice public return shape.

[serge-ivo]

Recheck 2026-08-06 — the file has grown since this was filed.

Ticket says 1127 LOC. Actual today: 1341 (+214) — the largest drift of the two refactor tickets (#136 went 1298 → 1383).

Recent voice work landed straight into the monolith rather than into the sub-hooks this issue proposes: the trailing-command split, the three-mode control, and the speech gate (#233) all added to useVoice directly. Each was reasonable in isolation; together they are why the number moved 19% in the wrong direction.

The extraction targets named here (useStt, useTurnTimers, useVoiceCommands) are still right, and the pure modules (vad/convo/config) have held up well — which is the evidence that the split works when it is done.

[serge-ivo]

Done in f194a72 — but smaller than the ticket proposed, deliberately.

The ticket was stale on both size and shape. The file is 1393 LOC, not 1127. More importantly, the pure decisions it wanted separated were already extracted into ten tested modules (machine/convo/vad/audio/gate/config/stt/tts/transcript/prompt). What remains in the hook is the imperative remainder those modules deliberately don't own: sequencing side effects over mutable state several of them read at once.

Why useStt/useTts/useVoiceCommands/useTurnTimers were rejected. Each fails the test that matters — that an extracted hook owns its refs and exposes a narrow surface:

• ttsRef is touched at ~20 sites across the whole file, because "is the agent speaking" is an input to the guard model (readGuard). A useTts would have to hand ttsRef straight back out, plus speakEndedAtRef (written from six places) and setSpeaking.
• startAudioMonitor reads ~24 refs including the command effects — the gate's onInterim is where a "mute" said mid-recording is caught (Voice: mute is unreachable while the user is speaking in Whisper STT mode — works in dictation, silently not in OpenAI #228).
• The timers' callbacks close over finalize, which is built inside handleResult.

Threading twenty-odd refs through parameter bags doesn't remove that coupling, it hides it — and the sequencing is exactly what this week's bugs were made of (#175 late-transcript classification, the unmute stale-ref trap, the echo guard, the speech gate).

What was extracted (the seams that genuinely exist):

• cues.ts — chimes, start cue, iOS SpeechSynthesis unlock. Module-level already, closes over nothing from the hook.
• voice-audio.ts — the replay upload. Three primitives in, no refs, no React. Its skip/retry rules were unreachable by any test while inline; 6 new tests now cover them (empty blob, 5MB cap, no keepalive, 4xx no-retry, 5xx retry, dropped-connection recovery).
• The 14-line settings-to-refs copy existed twice, byte-identical, kept in sync by hand — a setting added to one behaved differently depending on whether you'd opened the mic yet. Now one applyConfig.
• A header comment recording why the file is one hook, so this doesn't get re-opened.

Safety. All seven moved function bodies verified byte-identical to the removed versions by script; only signatures changed (export, one explicit : void). Public return shape untouched — store/console and agents/coder/web unaffected. Voice suites pass unchanged (219 → 225 tests). Full suite 3199 passed, typecheck green.

1393 → 1315 LOC, 44 of which are the new header. Closing as delivered; if the remaining size is still a concern, the honest next move is more test coverage of the orchestration, not more files.