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>
102 lines
3.8 KiB
Python
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())
|