Files
CyberGril/scripts/gen_subtitle_samples_hel879.py
T
zonggongandmultica-agent 3228b1e0d7 HEL-879 remaining closure: auto-expiry cleanup ownership, exact SDK speech-turn attribution, and the versioned v2 subtitle contract for HEL-898
A. Room lifecycle (总管 review items A-1/A-2): the single cleanup owner now watches
   ACTIVE session deadlines as well as debts - a session nobody touches expires into
   the ledger and has its room really deleted with zero further requests (old code:
   _cleanup_loop only scanned debts, expired rooms were never deleted until some
   request ran _prune). Explicit end and the background sweep share ONE persisted
   attempt/age cap and abandoned state - _sessions no longer bypasses it (the
   manager measured 2 background attempts + 3 more interactive deletes = 5); an
   abandoned debt raises CleanupAbandoned -> 503 with room/attempts/reason instead
   of pretending done-404, success clears both _sessions and _debts, restart
   continues the same persisted cap, close/cancel leaves no dangling coroutine, and
   only this instance's own rooms are ever touched. New wake event makes a fresh
   debt retry immediately instead of waiting out a deadline sleep.

B. Queued speech turns bind EXACTLY (总管 interleaving note_handle(H1)->H2->
   note_stream(S1)->S2 gave H1=None, H2='turn-one'): CyberGrillLLM.chat now reads
   the SDK's own agents_speech_handle ContextVar (livekit-agents 1.8.8 sets it in
   _create_speech_task around every speech pipeline; source-verified on .12 and
   asserted at runtime) so each ChatApiLLMStream carries speech_handle/speech_id of
   the very handle whose generation created it. TurnLedger binds only on that exact
   attribution - a newer speech NEVER retires an older pending handle, say/proactive
   generations bind nobody, missing attribution fails closed (no ack, no subtitle
   turn), interrupt/failure discards only its own binding.

C. Versioned subtitle contract v2 for the visual author's wiring card (HEL-898):
   every cg.subtitle payload gains {v:2, seq} (session-monotonic), turn identity
   (speech_id, turn_id, same-source message_id for proactive rows) and explicit
   lifecycle events - turn_start/assistant_interim/assistant_final/turn_end/
   turn_cancel(reason) plus proactive_start/proactive_end/proactive_cancel that
   ride the say SpeechHandle instead of the receipt branch. Accumulators are
   isolated per speech_id (a late delta after cancel is dropped producer-side);
   seq + speech_id give the frontend two independent stale-rejection rules. Full
   executable contract: docs/voice-subtitle-contract-v2.md with recorded samples in
   docs/rework/hel879/subtitle-samples/ (scripts/gen_subtitle_samples_hel879.py).
   web/src untouched.

Verification: the .12 real-SDK check now LOADS THE ACTUAL WORKER MODULE and drives
the callbacks IT registered on a real AgentSession (no hand-copied functions) -
both-queued delayed generations bind exactly, a say sandwiched between user turns
steals nothing, unattributed generations fail closed, interrupted turns cancel
without final/receipt (11/11 ALL PASS, source-level proof of the ContextVar wiring
included; evidence docs/rework/hel879/sdk-check-hel879-remaining.log). The old r2
lifespan test flake is root-caused (clock freeze and block were two separate portal
calls; a 10ms life tick could slip between them and claim the frozen day unblocked)
and fixed atomically without raising timeouts or dropping assertions - 12/12 solo,
full suite 350/350 three times in a row on .venv311; ruff back to the single
pre-existing error; voice chain 8/8; release offline R1-R7 with zero failures;
requirement checks 4/4 (origin/main and c121c42, each with/without handoff).
Zero real LLM/embed/ASR/TTS calls, zero downloads/installs, nothing deployed or
merged, real caps stay 0.

Co-authored-by: multica-agent <github@multica.ai>
2026-10-27 05:10:52 +08:00

102 lines
3.8 KiB
Python

#!/usr/bin/env python3
"""Generate the v2 subtitle contract sample recordings (HEL-879).
Drives the REAL seam implementation (seam.SubtitleBus / AssistantInterimPublisher
/ speak_proactive_row's event shape) offline — zero livekit imports, zero model
calls — and writes the JSONL sequences the visual author wires against:
docs/rework/hel879/subtitle-samples/normal-turn.jsonl
docs/rework/hel879/subtitle-samples/interrupt.jsonl
docs/rework/hel879/subtitle-samples/proactive.jsonl
Each line is exactly one cg.subtitle payload as it would be published on the
room topic (see docs/voice-subtitle-contract-v2.md).
"""
from __future__ import annotations
import json
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "src"))
from cybergril.voice.seam import ( # noqa: E402
AssistantInterimPublisher,
SubtitleBus,
)
OUT = ROOT / "docs/rework/hel879/subtitle-samples"
def record(name: str, payloads: list[dict]) -> Path:
OUT.mkdir(parents=True, exist_ok=True)
path = OUT / name
path.write_text(
"".join(json.dumps(p, ensure_ascii=False) + "\n" for p in payloads),
encoding="utf-8")
return path
def normal_turn() -> list[dict]:
payloads: list[dict] = []
bus = SubtitleBus(payloads.append)
interim = AssistantInterimPublisher(bus)
bus.emit("interim", role="user", text="你在听的")
bus.emit("user_final", role="user", text="你在听吗?")
interim.begin("speech_normal")
interim.feed("speech_normal", "在听呢,")
interim.feed("speech_normal", "在听呢,你刚才说到一半的那件事我还在想。")
interim.finish("speech_normal", turn_id="0e2f-demo-turn",
text="在听呢,你刚才说到一半的那件事我还在想。",
message_id=None)
return payloads
def interrupt_turn() -> list[dict]:
payloads: list[dict] = []
bus = SubtitleBus(payloads.append)
interim = AssistantInterimPublisher(bus)
interim.begin("speech_cut")
interim.feed("speech_cut", "我正想跟你说,今天下午")
# barge-in: the turn dies without a final; the next user turn starts clean
interim.cancel("speech_cut", "interrupted")
bus.emit("interim", role="user", text="等一下")
bus.emit("user_final", role="user", text="等一下,先听我说。")
interim.begin("speech_next")
interim.feed("speech_next", "好,你先说。")
interim.finish("speech_next", turn_id="0e2f-demo-next", text="好,你先说。")
return payloads
def proactive() -> list[dict]:
payloads: list[dict] = []
bus = SubtitleBus(payloads.append)
# spoken to the end (same-source message_id 17)
bus.emit("proactive_start", role="assistant", speech_id="speech_pro1",
text="我看到一句很适合现在的话,先念给你听。", message_id=17)
bus.emit("proactive_end", role="assistant", speech_id="speech_pro1",
message_id=17)
# interrupted variant (message_id 18)
bus.emit("proactive_start", role="assistant", speech_id="speech_pro2",
text="还有一件事想告诉你——", message_id=18)
bus.emit("proactive_cancel", role="assistant", speech_id="speech_pro2",
message_id=18, reason="interrupted")
return payloads
def main() -> int:
for name, fn in (("normal-turn.jsonl", normal_turn),
("interrupt.jsonl", interrupt_turn),
("proactive.jsonl", proactive)):
path = record(name, fn())
seqs = [json.loads(line)["seq"] for line in
path.read_text(encoding="utf-8").splitlines()]
assert seqs == sorted(seqs) and len(set(seqs)) == len(seqs), (name, seqs)
print(f"{path} ({len(seqs)} payloads, seq 1..{seqs[-1]})")
return 0
if __name__ == "__main__":
sys.exit(main())