fix(calls): retire first clause window after short replies

[rudycelekli]

Summary

A short first reply such as Hello! empties the buffer but leaves the first-clause window active. In the aggressive call-agent mode, a later clause is then emitted early as though it were still the first clause.

Changes

• Retire the first-clause window when the short sentence is emitted. Preserve the minimum-word guard and reset the window for the next turn.
• Add focused regressions and update the relevant documentation and changelog.

Type

• 🐛 Bug fix

Testing

• Hosted CI audit at 2026-10-06T12:35:20.584679+00:00: no failing latest checks; required CLA passes. All latest reported checks completed successfully. No upstream merge performed.

• Existing sentence-chunker tests cover the short reply, buffering of the next clause, a new-turn reset and the non-emitting minimum-word control.

• Regression against unchanged main production source: 1 failed, 65 passed. After the fix: 66 passed; 79 with changelog gate.

• Python 3.13 with HF_HUB_OFFLINE=1 and an empty Hugging Face cache. No model download or inference calls.

• Diff check and Python compilation pass.

• Full backend/Electron suites were not run locally; focused tests alone do not establish hosted security or platform gates. Hosted results are reported separately below.

Checklist

• I've tested this locally
• Every commit author has signed the CLA — registered signature and required CLA status verified
• I've updated relevant documentation
• No local machine paths, logs, or personal env details in this PR
• Maintained version files are in sync — no version bump
• Runtime regression fixture still loads green on smoke-matrix CI — not run locally

Closes #2628

Short replies now retire the first-clause window, so later clauses wait for normal sentence boundaries; regression tests cover the next clause, turn reset, and minimum-word guard. This prevents later speech from being emitted early in aggressive call-agent mode. Full backend, Electron, hosted security, and platform-matrix gates were not run.

[github-actions]

All contributors on this pull request have signed the VoiceStudio CLA. Thank you!

[greptile-apps]

[Medium risk] Adjusts when speech output waits for sentence boundaries in calls.

The PR appears safe to merge; no merge-changing defect was identified.

Summary

The PR retires aggressive first-clause flushing after a short sentence is emitted.

• Adds regressions for follow-up buffering, turn reset, and the minimum-word guard.
• Updates call behavior documentation and the changelog.

_{Reviews (1) · Last reviewed commit: "docs: link short-flush regression report..."}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: debpalash/VoiceStudio/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 584e0b92-fabe-4917-acaa-ee37841dc9a9

📥 Commits

Reviewing files that changed from the base of the PR and between 286f46b and c99a752.

📒 Files selected for processing (4)

• CHANGELOG.md
• backend/services/sentence_chunker.py
• docs/integrations/calls.md
• tests/test_sentence_chunker.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The sentence chunker now clears its first-flush state after emitting a short sentence. Tests, the call integration documentation, and the changelog cover the updated boundary behavior.

Changes

Short reply flush behavior

Layer / File(s)	Summary
Short-flush state and validation backend/services/sentence_chunker.py, tests/test_sentence_chunker.py, docs/integrations/calls.md, CHANGELOG.md	The short-flush path clears _is_first_flush after emitting a sentence. Tests cover later text and the minimum-word threshold. The call documentation and changelog describe the sentence-boundary behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Bug fix

Suggested reviewers: debpalash

Fixed issue severity: <fixed_issue_severity>Low</fixed_issue_severity>

Merge Risk: ⚪ Minimal · up to c99a7

The change prevents later clauses from using the first-clause shortcut after a short reply. No actionable merge-blocking risk is established.

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	[#2628] backend/services/sentence_chunker.py retires _is_first_flush when _maybe_short_flush emits a short sentence. The added tests cover follow-up buffering, next-turn behavior, and the minimu…
Out of Scope Changes check	✅ Passed	The sentence-chunker tests, call documentation, and changelog entry all support the fix requested by [#2628]. No unrelated change is present in the reviewed diff.
Cross-Platform Default Parity	✅ Passed	The changed short-flush path uses only the chunker's buffer and state: after emitting a short reply, it clears _is_first_flush in backend/services/sentence_chunker.py:480-482. The same Python logi…
I18n Completeness (21 Locales)	✅ Passed	The changed-file inventory contains only changelog, backend, docs, and tests files. The diff adds no Electron UI code, translation keys, or hardcoded UI strings, so the 21-locale check does not apply.
Local-First Guarantee	✅ Passed	The PR adds no outbound-call, credential, account, or analytics code. Its only production change sets local SentenceChunker state after a short flush (backend/services/sentence_chunker.py:480-482)…
Backward Compatibility	✅ Passed	The pull request changes only sentence chunking, its tests, the calls guide, and the changelog. The code change updates in-memory _is_first_flush state in backend/services/sentence_chunker.py; it …
Title check	✅ Passed	The title uses the required conventional-commit format with a scope, and the PR description references issue #2628.
Description check	✅ Passed	The description includes the summary, changes, type, testing, and checklist sections. It states that the runtime regression fixture was not run locally.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[rudycelekli]

recheck

[debpalash]

Thanks for the report and the work on this, @rudycelekli. The problem in #2628 is fixed on main by 2db77302 (merged in #2673), so I'm closing this pull request as already fixed. It will ship in v0.5.7. Reporter credit stays in the changelog.