| name | data-channel-contract |
| description | Use when adding, changing, or debugging data-channel messages between the client and the agent — topic agent.events. The contract lives in THREE places that must stay in sync: server/agent.py, app/lib/state/call_state.dart, and voice_forge (packages/voice_forge/lib/src/session/agent_session.dart + examples/poc_server). |
agent.events data-channel contract
One shared contract across ClinicGuard (LiveKit) and voice_forge (WebRTC). Topic: agent.events. Messages are JSON. Keep all three implementations in sync — they already drift once (summary_error).
Server → client events
| type | payload | ClinicGuard server | voice_forge | Flutter app (call_state.dart) |
|---|
user_transcript | {text, is_final, language} | agent.py ~203 | agent_session.dart ~129 | handled ~185 |
assistant_text | {text, item_id} | agent.py ~224 | agent_session.dart ~139 | handled ~193 |
agent_state | {state} idle/listening/thinking/speaking | agent.py ~229 | agent_session.dart ~82 | handled ~200 |
summary | {summary} | agent.py (event relay) | — (not in voice_forge yet) | handled ~203 |
summary_error | {error} | agent.py ~309 | — | NOT handled — known drift |
Client → server
{"event":"barge_in"} on the same topic for instant interrupt:
- ClinicGuard app:
app/lib/vad/barge_in_controller.dart (~line 90); server side: agent.py _on_data_received (~line 240).
- voice_forge:
packages/voice_forge_flutter/lib/src/voice_call_controller.dart sendBargeIn(); server side examples/poc_server/bin/agent_server.dart (~line 67).
When changing the contract
- Update the table's row in ALL three places (add
summary_error handling to call_state.dart first if you touch summaries).
- ClinicGuard: app switch at
app/lib/state/call_state.dart ~184-206; server publish points in agent.py EventRelay.
- voice_forge:
agent_session.dart publish points + agent_server.dart/agent_self_test.dart if the loop or test asserts on events.
- Extend
agent_self_test.dart event assertions if the new event should be asserted.
- Verify with the
verify-stack skill (voice_forge self-test asserts user_transcript/assistant_text/agent_state counts and states).
