internal(voice): wire DebugMessage over remote-session wire#1611
Open
toubatbrian wants to merge 7 commits into
Open
internal(voice): wire DebugMessage over remote-session wire#1611toubatbrian wants to merge 7 commits into
toubatbrian wants to merge 7 commits into
Conversation
Picks up the new agent-session messages required for upcoming work: CustomEvent, AgentSessionEvent.custom_event (livekit/protocol#1588), AgentSessionEvent.FunctionToolsStarted, AgentSessionEvent.EotPrediction, and SessionRequest.UpdateIO. No runtime change in @livekit/agents itself — this only makes the new generated types resolvable. Type-check (tsc --noEmit) passes against the new version. Co-authored-by: Cursor <cursoragent@cursor.com>
🦋 Changeset detectedLatest commit: a710d41 The changes in this PR will be included in the next version bump. Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
`Struct.fromJson` expects `JsonValue`, but the helper accepts `Record<string, unknown>` which is structurally wider (unknown is broader than JsonValue). Cast at the trust boundary — the caller is contractually responsible for JSON-serializable values, and `Struct.fromJson` validates at runtime anyway. Fixes the `build:types` failure: src/voice/remote_session.ts:85:26 - error TS2345: Argument of type 'Record<string, unknown>' is not assignable to parameter of type 'JsonValue'. Co-authored-by: Cursor <cursoragent@cursor.com>
3 tasks
Mirrors the Python-side decision (livekit/agents#5855): with CustomEvent already defined in livekit/protocol, the parallel TS wrapper + dict<->Struct conversion was pure ceremony with no semantic gain. Drop the wrapper and forward the proto unchanged. - events.ts: remove `CustomEvent` type + `createCustomEvent` helper + membership in the `AgentEvent` union. Keep the `AgentSessionEventTypes.CustomEvent` enum entry so the listener topic name stays stable. - agent_session.ts: callback signature is now `(ev: pb.CustomEvent) => void` (import-as-type). - remote_session.ts: - drop `dictToStruct` / `structToDict` and the `JsonValue` import - `RemoteSessionCallbacks.custom_event` typed as `pb.CustomEvent` - `onCustomEvent` forwards the proto as-is via `emitEvent({ case: 'customEvent', value: event })` - dispatch side re-emits `ev.value` directly (no Struct->dict round-trip) User-facing emit: session.emit( 'custom_event', new pb.CustomEvent({ type: 'anomaly_detected', payload: Struct.fromJson({ score: 0.92 }), }), ); `tsc --noEmit` and lint clean (no new warnings beyond the pre-existing test-file `any` noise). Co-authored-by: Cursor <cursoragent@cursor.com>
toubatbrian
changed the title
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Sugar for the common case: build pb.CustomEvent from a JSON-like
payload and emit it, so callers don't have to import Struct +
construct the proto at the call site.
session.emitCustomEvent('anomaly_detected', { score: 0.92 });
is equivalent to:
import { Struct } from '@bufbuild/protobuf';
import { AgentSession as pb } from '@livekit/protocol';
session.emit(
AgentSessionEventTypes.CustomEvent,
new pb.CustomEvent({
type: 'anomaly_detected',
payload: Struct.fromJson({ score: 0.92 }),
}),
);
The framework layer stays proto-native (SessionHost / RemoteSession
forward pb.CustomEvent as-is); this is purely a call-site
convenience. Mirrors the python `AgentSession.emit_custom_event`
helper.
`tsc --noEmit` clean; lint clean (one pre-existing `any` warning
elsewhere in the file is unchanged).
Co-authored-by: Cursor <cursoragent@cursor.com>
3 tasks
toubatbrian
added a commit
to livekit/protocol
that referenced
this pull request
May 27, 2026
…1593) * agent_session: rename CustomEvent -> DebugMessage; drop type field Renames the agent-session event added in #1588 before any consumer ships it. Repositioned as an internal debug/trace channel surfaced only to the debugger/recorder, not to user code -- the `type` discriminator was unnecessary since callers just emit a free-form JSON payload. Wire: AgentSessionEvent.custom_event (field 21) -> AgentSessionEvent.debug_message (same field number, same type slot). No schema-compat concerns -- nothing has been built downstream against this yet (livekit/agents#5855 and livekit/agents-js#1611 are both still open). Regenerated Go (.pb.go) with protoc 25.1; JS (@livekit/protocol) regenerated via `pnpm --filter @livekit/protocol generate:proto`. Co-authored-by: Cursor <cursoragent@cursor.com> * generated protobuf * changeset: patch bump, not minor Co-authored-by: Cursor <cursoragent@cursor.com> * drop 'free-form' from DebugMessage docs Co-authored-by: Cursor <cursoragent@cursor.com> * generated protobuf --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
…otocol 1.46.4 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) - pb.CustomEvent (string type, Struct payload) -> pb.DebugMessage (Struct payload) Surface change: - AgentSession.emitCustomEvent(type, payload) -> AgentSession._emitDebugMessage(payload) - underscore prefix + `/* internal */` JSDoc signal: not for user code - type discriminator dropped; callers just emit a JSON payload - AgentSessionEventTypes.CustomEvent -> AgentSessionEventTypes.DebugMessage - RemoteSessionCallbacks.custom_event -> debug_message - SessionHost.onCustomEvent -> onDebugMessage - Dispatch oneof case 'customEvent' -> 'debugMessage' Bumps `@livekit/protocol` floor `^1.46.3` -> `^1.46.4`. tsc --noEmit clean; lint clean (only pre-existing test-file `any` warnings). Co-authored-by: Cursor <cursoragent@cursor.com>
toubatbrian
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Wires the new
AgentSessionEvent.debug_message(livekit/protocol#1593) throughSessionHost/RemoteSession, and adds an internal-onlyAgentSession._emitDebugMessage(payload)helper for the debugger/recorder (e.g.agents-cli).Not a user-facing API — the leading underscore +
/* internal */JSDoc signal that this is not intended to be called from user code. The event rides the existingAgentSessionEventwrapper on the wire; nothing else in the session lifecycle changes.Changes
pyprojectanalog: bumps@livekit/protocolfloor^1.46.3→^1.46.4(picks upDebugMessage, the renamedAgentSessionEvent.debug_messagefield,FunctionToolsStarted,EotPrediction,SessionRequest.UpdateIO).voice/events.ts—AgentSessionEventTypes.CustomEvent→DebugMessage(topic value'custom_event'→'debug_message').voice/agent_session.ts:AgentSessionCallbackstyped as(ev: pb.DebugMessage) => void_emitDebugMessage(payload: Record<string, unknown>): void— wrapsStruct.fromJson(payload)intopb.DebugMessageand emits itvoice/remote_session.ts:RemoteSessionCallbacks.debug_messagetyped aspb.DebugMessageSessionHost.onDebugMessageforwards the proto viaemitEvent({ case: 'debugMessage', value: event })ev.valuedirectlyUsage (internal only)
```ts
// debugger / recorder code only — not for user code
session._emitDebugMessage({ kind: 'anomaly_detected', score: 0.92 });
```
External listeners can subscribe to the event topic (it's discoverable on the EventEmitter), but the canonical emit path is the underscore method. There is no stable public emit API for debug events.
Test plan
Notes
_emit_debug_messageshape on the Python side).@livekit/agents; no API removed from a published version — the wrapper added in Add custom event remote session proto #1610 had not shipped yet.@livekit/protocol@1.46.4(published).