refactor(voice): rename CustomEvent -> DebugMessage; expose internal _emit_debug_message

Picks up livekit/protocol#1593 which renamed the agent-session event
before any consumer shipped it. The message is repositioned as an
internal debug/trace channel surfaced only to the debugger/recorder
(e.g. agents-cli), not to user code.

Proto change (mechanical rename):
- AgentSessionEvent.custom_event -> AgentSessionEvent.debug_message (field 21)
- agent_pb.CustomEvent (str type, Struct payload) -> agent_pb.DebugMessage (Struct payload)

Surface change:
- AgentSession.emit_custom_event(event_type, payload) ->
  AgentSession._emit_debug_message(payload)
  - underscore prefix + `:meta private:` docstring marker signal: not for user code
  - type discriminator dropped; callers just emit a JSON payload
- EventTypes literal "custom_event" -> "debug_message"
- SessionHost._on_custom_event -> _on_debug_message

Pin bump: `livekit-protocol>=1.1.9` -> `>=1.1.10` to pick up DebugMessage.
(CI type-check is blocked until livekit/python-sdks#689 merges and a new
livekit-protocol release is cut to PyPI.)

Drive-by deslop on the helper body:
- `from google.protobuf...` imports lifted to module scope (avoids the
  no-inline-imports convention warning).
- Dropped the defensive `if payload:` + `dict(payload)` cast and the
  `ignore_unknown_fields=True` kwarg (Struct fields aren't user fields).
- Trimmed the 12-line docstring + 3-line inline comment down to the one
  non-obvious line that documents *why* we use `super().emit`.

ruff check + ruff format --check clean.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: toubatbrian

livekit-agents/livekit/agents/voice/agent_session.py

@@ -19,6 +19,8 @@
     runtime_checkable,
 )
 
+from google.protobuf.json_format import ParseDict
+from google.protobuf.struct_pb2 import Struct
 from opentelemetry import context as otel_context, trace
 from typing_extensions import TypedDict
 
@@ -1222,30 +1224,13 @@ def interrupt(self, *, force: bool = False) -> asyncio.Future[None]:
 
         return self._activity.interrupt(force=force)
 
-    def emit_custom_event(self, event_type: str, payload: Mapping[str, Any] | None = None) -> None:
-        """Emit an application-defined ``custom_event`` over the remote-session wire.
-
-        Sugar over constructing ``agent_pb.CustomEvent`` and emitting it: wraps
-        ``payload`` (a JSON-compatible mapping) into a ``google.protobuf.Struct`` and
-        emits the proto. Listeners registered via
-        ``session.on("custom_event", handler)`` receive the same
-        ``agent_pb.CustomEvent``.
-
-        Args:
-            event_type: Application-defined type tag (maps to ``CustomEvent.type``).
-            payload: JSON-compatible mapping (maps to ``CustomEvent.payload``). Defaults
-                to an empty struct.
-        """
-        from google.protobuf.json_format import ParseDict
-        from google.protobuf.struct_pb2 import Struct
-
+    def _emit_debug_message(self, payload: Mapping[str, Any]) -> None:
+        """:meta private: internal — emit a debug/trace payload to the debugger/recorder."""
         st = Struct()
-        if payload:
-            ParseDict(dict(payload), st, ignore_unknown_fields=True)
-        # bypass the typed `AgentSession.emit` override (which narrows to AgentEvent
-        # for the event-trace report): custom events ride the proto, not the
-        # Pydantic union, and aren't part of the typed report.
-        super().emit("custom_event", agent_pb.CustomEvent(type=event_type, payload=st))
+        ParseDict(payload, st)
+        # super().emit bypasses AgentSession.emit's narrowed AgentEvent type;
+        # debug messages ride the proto, not the Pydantic event union.
+        super().emit("debug_message", agent_pb.DebugMessage(payload=st))
 
     def clear_user_turn(self) -> None:
         # clear the transcription or input audio buffer of the user turn

livekit-agents/livekit/agents/voice/events.py

@@ -101,7 +101,7 @@ async def wait_for_playout(self) -> None:
     "speech_created",
     "error",
     "close",
-    "custom_event",
+    "debug_message",
 ]
 
 UserState = Literal["speaking", "listening", "away"]

livekit-agents/livekit/agents/voice/remote_session.py

@@ -375,7 +375,7 @@ def register_session(self, session: AgentSession) -> None:
             session.on("session_usage_updated", self._on_session_usage_updated)
             session.on("overlapping_speech", self._on_overlapping_speech)
             session.on("error", self._on_error)
-            session.on("custom_event", self._on_custom_event)
+            session.on("debug_message", self._on_debug_message)
 
     def register_text_input(self, text_input_cb: TextInputCallback) -> None:
         self._text_input_cb = text_input_cb
@@ -402,7 +402,7 @@ async def aclose(self) -> None:
             self._session.off("session_usage_updated", self._on_session_usage_updated)
             self._session.off("overlapping_speech", self._on_overlapping_speech)
             self._session.off("error", self._on_error)
-            self._session.off("custom_event", self._on_custom_event)
+            self._session.off("debug_message", self._on_debug_message)
 
         if self._recv_task:
             await utils.aio.cancel_and_wait(self._recv_task)
@@ -576,8 +576,8 @@ def _on_error(self, event: ErrorEvent) -> None:
             )
         )
 
-    def _on_custom_event(self, event: agent_pb.CustomEvent) -> None:
-        self._send_event(agent_pb.AgentSessionEvent(custom_event=event))
+    def _on_debug_message(self, event: agent_pb.DebugMessage) -> None:
+        self._send_event(agent_pb.AgentSessionEvent(debug_message=event))
 
     async def _handle_request_safe(self, req: agent_pb.SessionRequest) -> None:
         try:

livekit-agents/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "certifi>=2025.6.15",
     "livekit==1.1.8",
     "livekit-api>=1.0.7,<2",
-    "livekit-protocol>=1.1.9,<2",
+    "livekit-protocol>=1.1.10,<2",
     "livekit-blingfire~=1.1,<2",
     "protobuf>=3",
     "pyjwt>=2.0",