fix(proto): one ChatItem serializer that carries every declared field

[u9g]

_chat_item_to_proto in voice/remote_session.py dropped FunctionCallOutput.id. The proto declares the field, the sibling serializer in telemetry/traces.py set it, agents-js set it, and every other branch of the same function set id. The identical omission of name from this constructor was fixed once already in #6491.

Nothing reads that id today — livekit-cli renders function call outputs by name/output/is_error — so it was silent data loss rather than a visible break.

Why there was a second copy to disagree with

Rather than add the one field, I measured both serializers: saturate every ChatItem field with a non-default value, serialize, then walk the proto descriptor for whatever came back unset. On main:

remote_session
  message               transcript_confidence, extra, metrics.started_speaking_at,
                        metrics.stopped_speaking_at, created_at
  function_call         created_at
  function_call_output  id, created_at
  agent_handoff         created_at
  agent_config_update   created_at

telemetry/traces
  message               metrics.llm_node_tps, metrics.llm_node_ttfs

Each copy was missing a different subset. remote_session never got the speaking-at timestamps because its _metrics_to_proto splatted scalars only and those two are Timestamps; traces.py never got tps/ttfs because #6373 added them to the other list. Neither author was wrong — the mapping was written twice and drifted wherever the other one didn't.

The three commits

refactor: move proto serialization into its own module — both copies into livekit/agents/_proto.py, otherwise verbatim. A leaf: it imports neither llm, voice nor telemetry at module scope, so anything that puts a ChatItem on the wire can share it. The one non-mechanical part is that the voice copy now dispatches on ChatItem's discriminator rather than isinstance; importing the classes pulls in llm, llm reaches telemetry, and the import cycles.

fix(proto): carry every field the wire format declares — encode_by_name reads the fields the proto declares off the source object, so one implementation serves both paths and a field added to the schema is carried without editing a call site. _session_usage_to_proto's five variants collapse to a table over the same helper.

test(proto): fail when a declared field is dropped — the guard, below.

Behavior changes

• Every field in the table above now reaches the wire.
• Chat item timestamps move from FromMilliseconds to FromNanoseconds. created_at is time.time(), so sub-millisecond components were being truncated.
• Message content is one entry per part rather than the parts joined with \n. The proto field is repeated; joining collapsed them. This is what traces.py and agents-js already sent — the RemoteSession path is the one that changes.

Tests

tests/test_chat_item_proto_coverage.py saturates every ChatItem, model usage and metrics source, encodes it, then walks the result against the proto descriptor; anything left unset is a drop. That is what makes encode_by_name safe, since a field it cannot find on the source is skipped rather than raised — verified against a deliberately stale source, which the guard reports field by field.

Fixture timestamps are sub-millisecond and message content is multi-part, so a serializer that truncates or joins fails rather than passing on a value that hides the difference.

1885 passed. The 15 failures in test_realtime/test_openai_realtime_model.py and test_realtime/test_xai_realtime_model.py are pre-existing: a pristine origin/main checkout in the same environment fails the same 15.

encode_by_name costs mypy coverage on the copied assignments, which is the deliberate trade — the guard covers the same ground at test time rather than in the editor. Where it collided with typing outright, at ModelUsage's oneof, the code uses CopyFrom rather than a dict splat, so scripts/check_types.py still passes clean.

agents-js

livekit/agents-js#2247 does the same there, and its telemetry log now matches this one field for field — verified by encoding the same five items through both SDKs and diffing the JSON.

Follow-ups, not in this PR

MetricsReport has no playback_latency, so neither SDK can carry it; agents-js was emitting it into telemetry only because its hand-written types had no link to the schema. It needs a field in livekit/protocol.

The function_tools_executed handler still builds FunctionCallOutput without id (remote_session.py:528), as does the agents-js equivalent. Consistent across SDKs, so left alone.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.