docs(voice): TODO for stream-mode ui_op aggregator flush (colon-tail leak)

[swaroopvarma1]

What

Documents a known, low-severity issue in the widget stream-mode voice bridge as a deferred TODO (no behavior change).

In chat/voice_bridge.py _consume_events, the ui_op branch emits the ui-op RTVI event without flushing the _SentenceAggregator first — unlike function_call_started / function_approval_requested / turn_end, which all agg.flush() before their boundary event. A <ui_stream> block is a hard turn boundary (the widget finalizes the open transcript bubble on ui-op), so if the prose before the marker ends mid-sentence (e.g. a trailing colon, "...best options:"), that buffered tail leaks into the post-carousel bubble.

Why deferred

Low severity — the <ui_stream> marker is normally newline-led, so the aggregator is usually empty at the boundary; the leak only surfaces on a mid-sentence cutover. Captured now (right after the voice-as-chat release) so it isn't lost.

Changes

• Inline TODO(voice-as-chat) at the ui_op branch with the exact one-line fix.
• Matching note in docs/widget/VOICE_GENERATIVE_UI_TODO.md.

Fix (for the follow-up): for chunk in agg.flush(): await self._speak(chunk, gen) immediately before the _emit_rtvi(_RTVI_UI_OP, ...) call.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added notes documenting a known issue in voice-generative UI where buffered text can be incorrectly carried into subsequent content during certain operations.

• Chores

  • Added tracking comment for the deferred fix with detailed description of the intended resolution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c51661e4-9c87-45fd-ac02-278340cb588a

📥 Commits

Reviewing files that changed from the base of the PR and between 39fdbef and e5f814b.

📒 Files selected for processing (2)

• app/ai/voice/agents/breeze_buddy/chat/voice_bridge.py
• docs/widget/VOICE_GENERATIVE_UI_TODO.md

---

Walkthrough

Adds a TODO comment in the ui_op handling branch of WidgetVoiceBridge._consume_events and a new section in docs/widget/VOICE_GENERATIVE_UI_TODO.md, both documenting the missing _SentenceAggregator flush before ui_op emission and specifying the intended fix.

Changes

Aggregator flush TODO documentation

Layer / File(s)	Summary
Inline TODO and doc section for aggregator flush gap app/ai/voice/agents/breeze_buddy/chat/voice_bridge.py, docs/widget/VOICE_GENERATIVE_UI_TODO.md	Adds a detailed TODO comment in the ui_op branch of _consume_events and a matching markdown section in the generative UI TODO doc, both describing the boundary-condition bug where _SentenceAggregator is not flushed before emitting ui-op, and specifying for chunk in agg.flush(): await self._speak(chunk, gen) as the fix to insert before the _emit_rtvi(... _RTVI_UI_OP, ...) call.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 A buffer untouched, a sentence half-said,
The carousel spins with old words in its head.
I've left a small note — a TODO, a sign —
"Please flush me before you cross that bright line!"
The fix is right there, just waiting to hop,
agg.flush() before the ui_op. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically references the main change: documenting a TODO for the stream-mode ui_op aggregator flush issue (colon-tail leak) in the voice bridge. It directly summarizes the primary purpose of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/voice-ui-op-flush-todo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Tara-ag]

Review Summary

Files reviewed: 2

• app/ai/voice/agents/breeze_buddy/chat/voice_bridge.py - TODO comment added
• docs/widget/VOICE_GENERATIVE_UI_TODO.md - Documentation update

Issues found: 0 (none)

New issues by severity:

• 🔒 CRITICAL: 0
• ⚠️ MAJOR: 0
• 💡 MINOR: 0
• 💬 SUGGESTION: 0

Assessment:
This is a clean documentation-only PR that accurately documents a known low-severity issue. The TODO correctly identifies that the ui_op branch in _consume_events doesn't flush the _SentenceAggregator before emitting the ui-op RTVI event, unlike the function_call_started, function_approval_requested, and turn_end branches which all call agg.flush() before their boundary events.

No blocking criteria met. The PR is safe to merge.