#!/usr/bin/env python3 """Generate the HEL-877/879 real-SDK compatibility check for the .12 agent venv. Embeds the repo voice-module sources in a self-contained stdin script (no files written to .12, no network, no service touched) and runs it with /opt/voice-agent/agent/venv/bin/python (livekit-agents 1.8.8, livekit 1.1.20). HEL-879 remaining closure: the check LOADS THE ACTUAL WORKER MODULE (cybergril.voice.worker, wiring included — no hand-copied callbacks) and drives the callbacks IT registered on a real AgentSession with real SpeechHandle/SpeechCreatedEvent objects. Attribution is proven two ways: (a) source-level — the installed SDK's _create_speech_task sets the private agents_speech_handle ContextVar around every speech task and speech_created is emitted before the task starts; (b) runtime — generations started inside that ContextVar bind exactly, including the manager's both-queued-then-delayed interleaving, a say speech sandwiched between user turns, an unattributed generation (fail-closed) and an interrupted turn (cancel, no receipt). HEL-879 timing closure (contract-approval round): the real SDK's AgentSession.say is a SYNC method returning an awaitable SpeechHandle (awaiting it awaits the whole playout) — speak_proactive_row must publish proactive_start DURING the playout with end/cancel on the handle's done callback; and a clearly-attributed but incomplete/no-receipt stream must close the subtitle turn with turn_cancel ONLY (contract v2: no complete same-turn receipt means no assistant_final), while the complete+receipt path keeps final AND the ack. """ from __future__ import annotations import base64 import sys from pathlib import Path ROOT = Path(__file__).resolve().parents[1] MODULES = ["chat_api_client", "receipt", "seam", "llm_chat_api", "stt_funasr", "tts_cosyvoice", "worker"] TEMPLATE = r''' import asyncio, base64, inspect, json, sys, types SOURCES = json.loads(base64.b64decode("__B64__")) pkg = types.ModuleType("cybergril"); pkg.__path__ = [] voice = types.ModuleType("cybergril.voice"); voice.__path__ = [] sys.modules["cybergril"] = pkg sys.modules["cybergril.voice"] = voice for name, src in SOURCES.items(): mod = types.ModuleType(f"cybergril.voice.{name}") mod.__package__ = "cybergril.voice" sys.modules[f"cybergril.voice.{name}"] = mod exec(compile(src, f"", "exec"), mod.__dict__) setattr(voice, name, mod) import httpx from livekit.agents import llm as lk_llm from livekit.agents.llm import LLM, LLMStream, ChatChunk, ChoiceDelta ok = [] # 1. real-SDK subclass contracts llm_mod = sys.modules["cybergril.voice.llm_chat_api"] assert issubclass(llm_mod.CyberGrillLLM, LLM), "CyberGrillLLM must subclass the real llm.LLM" assert issubclass(llm_mod.ChatApiLLMStream, LLMStream) ok.append("CyberGrillLLM/ChatApiLLMStream subclass real livekit-agents 1.8.8 LLM/LLMStream") # 2. real ChatContext -> latest_user_text ctx = lk_llm.ChatContext() ctx.add_message(role="assistant", content="早些的一句") ctx.add_message(role="user", content="真实SDK链路你好") assert llm_mod.latest_user_text(ctx) == "真实SDK链路你好" ok.append("latest_user_text reads a real ChatContext (items/role/text_content)") # 3. full turn through the real LLMStream machinery with fake SSE FINAL = "真实链路上的一句完整回复。" sse = ( 'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"真实链路上"}\n\n' 'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"的一句完整回复。"}\n\n' 'data: {"t":"chat.final","epoch":1,"turn_id":null,"utterance":{"text":"' + FINAL + '"},' '"receipt":{"message_id":9,"turn_id":null,"epoch":1,"token":"' + "k" * 48 + '","text_hash":"' + "h" * 64 + '"}}\n\n' ).encode() def handler(request: httpx.Request) -> httpx.Response: if request.url.path == "/api/health": return httpx.Response(200, json={"epoch": 1}) return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=sse) receipt_ok = {} async def round_trip(): client = llm_mod.ChatApiClient("http://x", transport=httpx.MockTransport(handler)) adapter = llm_mod.CyberGrillLLM("http://x", client=client) stream = adapter.chat(chat_ctx=ctx) chunks = [] async for chunk in stream: assert isinstance(chunk, ChatChunk) and chunk.delta and chunk.delta.content chunks.append(chunk.delta.content) assert "".join(chunks) == FINAL, chunks assert stream.completed and stream.receipt and stream.receipt["message_id"] == 9 receipt_ok["text"] = stream.text receipt_ok["receipt"] = stream.receipt asyncio.run(round_trip()) assert receipt_ok["text"] == FINAL ok.append("fake-SSE turn through real LLMStream emits ChatChunks, final text and receipt") # 4. phi error turn: spoken verbatim, no receipt phi_sse = ( 'data: {"t":"chat.error","epoch":1,"turn_id":null,"phi":"她这会儿没接上话,稍后再试试。你写的话还在。","retryable":true}\n\n' ).encode() def phi_handler(request: httpx.Request) -> httpx.Response: if request.url.path == "/api/health": return httpx.Response(200, json={"epoch": 1}) return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=phi_sse) async def phi_turn(): adapter = llm_mod.CyberGrillLLM("http://x", client=llm_mod.ChatApiClient("http://x", transport=httpx.MockTransport(phi_handler))) stream = adapter.chat(chat_ctx=ctx) spoken = [] async for chunk in stream: spoken.append(chunk.delta.content) assert "".join(spoken) == "她这会儿没接上话,稍后再试试。你写的话还在。" assert stream.error_phi and not stream.completed and stream.receipt is None asyncio.run(phi_turn()) ok.append("chat.error phi is spoken verbatim via ChatChunk and carries no receipt") # 5. token claims parity with the real livekit.api.AccessToken from livekit import api import jwt as pyjwt wire = sys.modules["cybergril.voice.livekit_wire"] mine = wire.mint_token("devkey", "s3cret", identity="user-ab", name="用户", room="cg-voice-test", room_join=True, ttl_seconds=300, now=1700000000.0) sdk_token = (api.AccessToken("devkey", "s3cret").with_identity("user-ab").with_name("用户") .with_grants(api.VideoGrants(room_join=True, room="cg-voice-test", can_publish=True, can_subscribe=True)) .to_jwt()) mine_claims = pyjwt.decode(mine, "s3cret", algorithms=["HS256"], options={"verify_exp": False}) sdk_claims = pyjwt.decode(sdk_token, "s3cret", algorithms=["HS256"], options={"verify_exp": False}) assert mine_claims["video"] == sdk_claims["video"], (mine_claims["video"], sdk_claims["video"]) assert mine_claims["iss"] == sdk_claims["iss"] and mine_claims["sub"] == sdk_claims["sub"] assert set(mine_claims) == set(sdk_claims), (sorted(mine_claims), sorted(sdk_claims)) ok.append("mint_token claims byte-parity with livekit.api.AccessToken (video/iss/sub/keys)") # 6. server token decodes as the SDK Service._auth_header shape server_tok = wire.mint_server_token("devkey", "s3cret", ttl_seconds=60, now=1700000000.0) sc = pyjwt.decode(server_tok, "s3cret", algorithms=["HS256"], options={"verify_exp": False}) assert sc["iss"] == "devkey" and sc["sub"] == "" and "video" not in sc ok.append("mint_server_token matches SDK no-grant auth header claims") # 7. SpeechHandle/worker API surface used by worker.py exists on the real SDK from livekit.agents.voice.speech_handle import SpeechHandle for attr in ("wait_for_playout", "interrupted", "exception", "add_done_callback"): assert hasattr(SpeechHandle, attr), attr from livekit.agents.voice.events import UserInputTranscribedEvent assert "is_final" in UserInputTranscribedEvent.model_fields ok.append("worker.py SDK surface (SpeechHandle, UserInputTranscribedEvent.is_final) present") # 8. barge-in cancellation closes the SSE response immediately state = {"response": None} async def slow_body(): yield 'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"开头"}\n\n'.encode() await asyncio.sleep(30) yield 'data: {"t":"chat.final","epoch":1,"turn_id":null}\n\n'.encode() class TrackingTransport(httpx.MockTransport): async def handle_async_request(self, request): response = await super().handle_async_request(request) if request.url.path == "/api/chat": state["response"] = response return response def slow_handler(request: httpx.Request) -> httpx.Response: if request.url.path == "/api/health": return httpx.Response(200, json={"epoch": 1}) return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=slow_body()) async def cancel_case(): adapter = llm_mod.CyberGrillLLM("http://x", client=llm_mod.ChatApiClient("http://x", transport=TrackingTransport(slow_handler))) stream = adapter.chat(chat_ctx=ctx) task = asyncio.create_task(stream._run()) await asyncio.sleep(0.2) # first delta consumed assert state["response"] is not None and not state["response"].is_closed task.cancel() try: await task except asyncio.CancelledError: pass assert state["response"].is_closed, "adapter must close the HTTP stream on barge-in" asyncio.run(cancel_case()) ok.append("barge-in task cancel closes the in-flight HTTP stream immediately") # 9. HEL-879 remaining closure: THE ACTUAL WORKER MODULE's registered callbacks # on a real AgentSession — exact attribution from the SDK generation context. from livekit.agents import AgentSession from livekit.agents.voice import agent_activity from livekit.agents.voice.speech_handle import SpeechHandle from livekit.agents.voice.events import SpeechCreatedEvent # 9a. source-level proof on the INSTALLED SDK: every speech task runs inside # the private agents_speech_handle ContextVar, and speech_created is # emitted BEFORE the pipeline task is created (so note_handle always # happens-before its generation's llm.chat). create_src = inspect.getsource(agent_activity.AgentActivity._create_speech_task) assert "_SpeechHandleContextVar.set(speech_handle)" in create_src, create_src gen_src = inspect.getsource(agent_activity.AgentActivity._generate_reply) assert gen_src.index("speech_created") < gen_src.index("_pipeline_reply_task"), gen_src say_src = inspect.getsource(agent_activity.AgentActivity.say) assert say_src.index("speech_created") < say_src.index("_create_speech_task"), say_src llm_call_src = inspect.getsource( __import__("livekit.agents.voice.agent", fromlist=["Agent"]).Agent.default.llm_node) assert "self.llm.chat(" in llm_call_src or "activity_llm.chat(" in llm_call_src ok.append("installed-SDK source verified: speech tasks set agents_speech_handle around " "the pipeline; speech_created precedes the task; llm_node calls llm.chat inside it") worker_mod = sys.modules["cybergril.voice.worker"] receipt_mod = sys.modules["cybergril.voice.receipt"] seam_mod = sys.modules["cybergril.voice.seam"] def receipt_echo_handler(request: httpx.Request) -> httpx.Response: if request.url.path == "/api/health": return httpx.Response(200, json={"epoch": 1}) if request.url.path == "/api/chat/received": return httpx.Response(200, json={"accepted": True}) body = json.loads(request.content) turn_id = body["turn_id"] payload = ( 'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"这句是"}\n\n' 'data: {"t":"chat.final","epoch":1,"turn_id":null,"utterance":{"text":"这句是她的完整回复。"},' '"receipt":{"message_id":42,"turn_id":"' + turn_id + '","epoch":1,' '"token":"' + "t" * 48 + '","text_hash":"' + "z" * 64 + '"}}\n\n' ).encode() return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=payload) confirmed: list[str] = [] subtitle_payloads: list[dict] = [] class RecordingReceipts: async def confirm(self, turn_id, receipt): confirmed.append(turn_id) return True async def worker_callback_path(): session = AgentSession() # real SDK session object ledger = receipt_mod.TurnLedger() bus = seam_mod.SubtitleBus(subtitle_payloads.append) interim = seam_mod.AssistantInterimPublisher(bus) stt = types.SimpleNamespace(agent_speaking=False, agent_recent_text="") client = llm_mod.ChatApiClient("http://x", transport=httpx.MockTransport(receipt_echo_handler)) llm = worker_mod.make_voice_llm("http://x", ledger=ledger, interim=interim, client=client) # the ACTUAL worker wiring registers every callback on the real session worker_mod.bind_voice_session(session, llm=llm, ledger=ledger, interim=interim, bus=bus, stt=stt, receipts=RecordingReceipts()) def speech(hid_source): handle = SpeechHandle.create() session.emit("speech_created", SpeechCreatedEvent( user_initiated=True, source=hid_source, speech_handle=handle, created_at=1.0)) return handle async def generation_for(handle): # EXACTLY what _create_speech_task does (source-verified in 9a): the # pipeline task runs with the SDK's own ContextVar set to its handle. tk = agent_activity._SpeechHandleContextVar.set(handle) try: stream = llm.chat(chat_ctx=ctx) async for _ in stream: pass return stream finally: agent_activity._SpeechHandleContextVar.reset(tk) # the manager's exact interleaving: BOTH speech events queued first, the # generations only start afterwards (delayed, in queue order). h1 = speech("generate_reply") h2 = speech("generate_reply") s1, s2 = await asyncio.gather(generation_for(h1), generation_for(h2)) h1._mark_done() h2._mark_done() await asyncio.sleep(0.1) # let the scheduled done callbacks (_after_playout) run assert ledger.stream_for(h1) is None and ledger.stream_for(h2) is None # consumed assert s1.speech_handle is h1 and s2.speech_handle is h2, "exact attribution" # both completed turns acked exactly once, each with its own turn_id assert sorted(confirmed) == sorted([s1.turn_id, s2.turn_id]), confirmed # v2 subtitle lifecycle per speech_id, seq monotonic, interleaved correctly kinds = [(p["kind"], p.get("speech_id")) for p in subtitle_payloads] assert kinds[0] == ("turn_start", h1.id) for sid in (h1.id, h2.id): seq = [p["kind"] for p in subtitle_payloads if p.get("speech_id") == sid] assert seq == ["turn_start", "assistant_interim", "assistant_final", "turn_end"], seq seqs = [p["seq"] for p in subtitle_payloads] assert seqs == sorted(seqs) and len(set(seqs)) == len(seqs) # no payload without a speech_id ever opened a turn assert all(p.get("speech_id") for p in subtitle_payloads if p["kind"] in ("turn_start", "assistant_interim")), subtitle_payloads # a say speech sandwiched between user turns never takes a user stream before = len(confirmed) h_user = speech("generate_reply") h_say = speech("say") # proactive/programmatic say: user_initiated but no LLM stream stream_user = await generation_for(h_user) h_say._mark_done() # say finishes without any generation h_user._mark_done() await asyncio.sleep(0.1) assert stream_user.speech_handle is h_user assert confirmed.count(stream_user.turn_id) == 1 and len(confirmed) == before + 1 say_events = [p for p in subtitle_payloads if p.get("speech_id") == h_say.id] assert say_events == [], "say without an LLM stream opens/closes no subtitle turn" # an UNATTRIBUTED generation (no speech task context) binds nobody h_late = speech("generate_reply") async def unattributed(): assert agent_activity._SpeechHandleContextVar.get(None) is None return llm.chat(chat_ctx=ctx) # proactive background generation shape stray = await unattributed() await generation_for(h_late) assert stray.speech_handle is None and stray.speech_id == "" assert ledger.stream_for(h_late).speech_handle is h_late assert stray in ledger.unattributed assert not [p for p in subtitle_payloads if p["kind"] == "turn_start" and not p.get("speech_id")], "unattributed generation must not open a subtitle turn" # interrupted turn: cancel event, no final, no receipt before = len(confirmed) h3 = speech("generate_reply") await generation_for(h3) h3.interrupt() h3._mark_done() await asyncio.sleep(0.1) assert len(confirmed) == before ev3 = [p["kind"] for p in subtitle_payloads if p.get("speech_id") == h3.id] assert ev3 == ["turn_start", "assistant_interim", "turn_cancel"], ev3 asyncio.run(worker_callback_path()) ok.append("ACTUAL worker module loaded; its registered callbacks driven on a real " "AgentSession: both-queued delayed generations bind exactly (manager " "interleaving), say never steals a stream, unattributed fails closed, " "interrupt cancels without final/receipt") # 10. HEL-879: assistant_interim seam through the REAL LLMStream machinery, # per-speech_id accumulators (stream-passing delta callback). interim_payloads = [] async def interim_seam(): from livekit.agents.voice import agent_activity bus = seam_mod.SubtitleBus(interim_payloads.append) publisher = seam_mod.AssistantInterimPublisher(bus) adapter = llm_mod.CyberGrillLLM("http://x", client=llm_mod.ChatApiClient( "http://x", transport=httpx.MockTransport(handler)), on_assistant_delta=lambda stream, delta: publisher.feed(stream.speech_id, delta)) publisher.begin("speech_seam") # attribute the stream exactly like the SDK would (a speech task setting # its own handle): the deltas then feed THIS turn's accumulator fake_handle = types.SimpleNamespace(id="speech_seam") tk = agent_activity._SpeechHandleContextVar.set(fake_handle) stream = adapter.chat(chat_ctx=ctx) async for _ in stream: pass agent_activity._SpeechHandleContextVar.reset(tk) assert stream.speech_handle is fake_handle and stream.speech_id == "speech_seam" interims = [p for p in interim_payloads if p["kind"] == "assistant_interim"] assert [p["text"] for p in interims] == ["真实链路上", "真实链路上的一句完整回复。"] assert all(p["role"] == "assistant" and p["v"] == 2 and p["speech_id"] == "speech_seam" for p in interims) assert interim_payloads[0]["kind"] == "turn_start" # begin opened the turn # a stream without attribution feeds no open turn (fail-closed, no leak) stray = adapter.chat(chat_ctx=ctx) # no ctxvar set here async for _ in stray: pass assert stray.speech_handle is None and stray.speech_id == "" assert len(interim_payloads) == 3, interim_payloads # turn_start + 2 interims only asyncio.run(interim_seam()) ok.append("assistant_interim seam: real LLMStream deltas feed per-speech_id v2 " "payloads (replace semantics); unattributed streams feed nothing") # 11. HEL-879 timing closure: proactive_start DURING the playout on the real # sync-say shape (a bare handle.__await__ would wait out the whole play). async def proactive_timing_case(): events: list[dict] = [] h = SpeechHandle.create() class SyncSay: def say(self, *args, **kwargs): # real SDK shape: sync -> handle asyncio.get_running_loop().call_later(.06, h._mark_done) return h task = asyncio.create_task(worker_mod.speak_proactive_row( SyncSay(), seam_mod.SubtitleBus(events.append), {"id": 7, "text": "offline sample"})) await asyncio.sleep(.015) assert h.done() is False assert [e["kind"] for e in events] == ["proactive_start"], events await task await asyncio.sleep(.015) assert [e["kind"] for e in events] == ["proactive_start", "proactive_end"] start = events[0] assert (start["v"], start["role"], start["message_id"], start["text"]) == \ (2, "assistant", 7, "offline sample") assert start["speech_id"] == h.id asyncio.run(proactive_timing_case()) ok.append("speak_proactive_row publishes proactive_start while the real " "SpeechHandle is still playing (sync-say shape), end/cancel on the " "handle's done callback") # 11b. an interrupted proactive row closes with cancel, never end async def proactive_interrupt_case(): events: list[dict] = [] h = SpeechHandle.create() class SyncSay: def say(self, *args, **kwargs): return h task = asyncio.create_task(worker_mod.speak_proactive_row( SyncSay(), seam_mod.SubtitleBus(events.append), {"id": 8, "text": "被打断的主动留言"})) await asyncio.sleep(.005) # start emitted, done callback registered h.interrupt() h._mark_done() await task await asyncio.sleep(.02) assert [e["kind"] for e in events] == ["proactive_start", "proactive_cancel"], events assert events[-1]["reason"] == "interrupted" asyncio.run(proactive_interrupt_case()) ok.append("interrupted proactive row emits proactive_cancel(reason=interrupted), " "never proactive_end") # 12. HEL-879 timing closure: a clearly-attributed but INCOMPLETE/no-receipt # stream through the ACTUAL bind_voice_session callbacks must close the # subtitle turn with turn_cancel ONLY — no assistant_final, no ack (v2). async def no_receipt_incomplete_case(): events: list[dict] = [] session = AgentSession() ledger = receipt_mod.TurnLedger() bus = seam_mod.SubtitleBus(events.append) interim = seam_mod.AssistantInterimPublisher(bus) confirmed: list[str] = [] async def epoch(): return 1 class Receipts: async def confirm(self, *args): confirmed.append(args[0]) return True llm = types.SimpleNamespace(client=types.SimpleNamespace(current_epoch=epoch)) worker_mod.bind_voice_session(session, llm=llm, ledger=ledger, interim=interim, bus=bus, stt=types.SimpleNamespace(), receipts=Receipts()) h = SpeechHandle.create() session.emit("speech_created", SpeechCreatedEvent( user_initiated=True, source="generate_reply", speech_handle=h, created_at=1.0)) stream = types.SimpleNamespace( speech_id=h.id, error_phi=None, text="partial without receipt", turn_id="incomplete", receipt=None, completed=False) ledger.note_stream(stream, h) interim.begin(h.id) h._mark_done() await asyncio.sleep(.06) assert [e["kind"] for e in events] == ["turn_start", "turn_cancel"], events assert events[-1]["reason"] == "incomplete" assert confirmed == [] asyncio.run(no_receipt_incomplete_case()) ok.append("incomplete/no-receipt attributed stream: actual worker callbacks emit " "turn_start -> turn_cancel only, no assistant_final, no ack") print("HEL-877/879 real-SDK check on livekit-agents", end=" ") import importlib.metadata as md print(md.version("livekit-agents") + ":", "ALL PASS") for line in ok: print(" OK", line) ''' def main() -> int: sources = {} for name in MODULES + ["livekit_wire"]: path = ROOT / "src/cybergril/voice" / f"{name}.py" sources[name] = path.read_text(encoding="utf-8") payload = base64.b64encode(json.dumps(sources).encode()).decode() script = TEMPLATE.replace("__B64__", payload) out = ROOT / "scripts/_hel877_sdk_check_payload.py" out.write_text(script, encoding="utf-8") print(out) return 0 if __name__ == "__main__": import json sys.exit(main())