mouth: render chunks ahead of playback (no gap between lines); brain: print tool calls

[FryD420]

Two quality-of-life changes from daily use of backtalk as a voice line for my agent.

1. Lookahead synthesis in the mouth

Mouth was one worker thread doing render, play, render, play. Every chunk boundary paid the synth latency plus the 0.75 s prebuffer in series, which on my machine is about a second of dead air between lines while the text had already streamed to the screen.

This splits it into a synth thread and a player thread. The synth renders LOOKAHEAD (2) chunks ahead of the one playing, so when a chunk ends, the next one's audio is already finished and starts with no gap. Both hard-won audio laws still hold: one long-lived OutputStream, and the prebuffer (which is satisfied instantly for chunks that finished rendering while the previous one played).

Barge-in: a generation counter ties the two threads together. shut_up() bumps it, and anything ordered under the old generation is dropped wherever it turns up (text queue, ready queue, mid-render, or in the player), so nothing stale ever plays. A pending counter replaces "queue empty" for the speaking flag and wait_done(), since the text queue is no longer the whole story once rendering runs ahead.

2. [tool] lines from the brain

ask_stream now logs one line per tool call from the AssistantMessage that lands as the call runs:

[tool] Read: E:\my-agent\backtalk\LICENSE
[tool] Bash: Check git remote and status
[tool] Grep: say_chunk in backtalk/

So the terminal shows what the agent is doing during a long quiet stretch instead of just the thinking sound.

Test

tests/test_mouth_lookahead.py drives the mouth with a fake synth (0.3 s to first audio, streamed blocks) and a fake real-time output device, no speakers needed:

• boundary gaps under 80 ms (measured 0 to 1 ms; the old mouth would have been ~1 s)
• a chunk shorter than the prebuffer still completes
• barge-in cuts mid-chunk, plays nothing stale, and the mouth speaks fresh text afterwards

Run with .venv/Scripts/python tests/test_mouth_lookahead.py (or the posix equivalent). Also verified live: Kokoro voice, Windows 11, and the [tool] lines against a real session.

Happy to adjust naming or fold the lookahead depth into backtalk.json if you would rather have it configurable.

🤖 Generated with Claude Code

[rhuitt]

Independent confirmation from macOS (M1, 8 GB, Kokoro in-process, voice bm_lewis), where this bug is much bigger than the ~1 s described above.

Measurements on the unpatched mouth:

• Kokoro's pipeline yields a chunk's audio as one segment, so synth_stream never actually streams — first PCM arrives only when the whole chunk is rendered, and the 0.75 s prebuffer never gets a head start.
• Render cost is ~0.25–0.3× real-time here: ~0.5 s for a short sentence, ~2.3 s for a typical one, ~3.3 s for the 2-sentence batches speak_reply builds.
• Because render and play were serial, every chunk boundary was dead air equal to the next chunk's full render. On a realistic 4-chunk reply (~40 s of speech) I measured gaps of 4.3 s, 3.6 s, 0.9 s with a fake real-time output device.

I wrote a lookahead fix before finding this PR and it converged on the same shape (synth thread + player thread, generation counter on barge-in, pending counter for speaking/wait_done, render handed over before it fills). Same harness after the change: no measurable gap at any boundary, reply wall time 49.6 s → 40.6 s, time-to-first-audio unchanged (~1.5 s); barge-in cuts within one block, drops the rendered-ahead and in-flight chunks, and the next turn plays clean. Both audio laws intact.

So +1 on this PR — on CPU-only Macs it turns "statement… pause… statement" into continuous speech. Happy to share the harness or numbers if useful.

[jaredrhod]

Closing this because #10 contains all eight of these commits plus the warm gate, so merging #10 takes this with it. Not a rejection, the lookahead work is going in, it is just travelling in the other PR. Thanks for both.