From adaed5f3bd51acbf0b24944bdb2f8c16525191d1 Mon Sep 17 00:00:00 2001 From: Brian Yin Date: Tue, 26 May 2026 20:34:56 -0400 Subject: [PATCH 1/5] 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 --- .../rename-custom-event-to-debug-message.md | 14 ++++ livekit/agent/livekit_agent_session.pb.go | 68 ++++++++----------- protobufs/agent/livekit_agent_session.proto | 10 +-- 3 files changed, 49 insertions(+), 43 deletions(-) create mode 100644 .changeset/rename-custom-event-to-debug-message.md diff --git a/.changeset/rename-custom-event-to-debug-message.md b/.changeset/rename-custom-event-to-debug-message.md new file mode 100644 index 000000000..f835fa777 --- /dev/null +++ b/.changeset/rename-custom-event-to-debug-message.md @@ -0,0 +1,14 @@ +--- +"@livekit/protocol": minor +--- + +agent_session: rename `CustomEvent` → `DebugMessage`; drop `type` field, keep only `payload` + +Renames the agent-session event added in #1588 before any consumer ships it. The +message is repositioned as an internal debug/trace channel surfaced only to the +debugger/recorder, not to user code, so the `type` discriminator was unnecessary +— callers just emit a free-form JSON `payload`. + +Wire-level: `AgentSessionEvent.custom_event` (field 21) → `AgentSessionEvent.debug_message` +(same field number 21, same type slot, no schema-compat concerns since nothing +has been built against it yet downstream). diff --git a/livekit/agent/livekit_agent_session.pb.go b/livekit/agent/livekit_agent_session.pb.go index 95874e032..4ffdcbe81 100644 --- a/livekit/agent/livekit_agent_session.pb.go +++ b/livekit/agent/livekit_agent_session.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.36.11 -// protoc v4.23.4 +// protoc-gen-go v1.36.6 +// protoc v5.29.3 // source: agent/livekit_agent_session.proto package agent @@ -1473,29 +1473,29 @@ func (x *AgentSessionUsage) GetModelUsage() []*ModelUsage { return nil } -// Application-defined event carried over the remote session wire. -type CustomEvent struct { +// Free-form debug/trace payload carried over the remote session wire. +// Internal: surfaced only to the debugger/recorder, not to user code. +type DebugMessage struct { state protoimpl.MessageState `protogen:"open.v1"` - Type string `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"` - Payload *structpb.Struct `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"` + Payload *structpb.Struct `protobuf:"bytes,1,opt,name=payload,proto3" json:"payload,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } -func (x *CustomEvent) Reset() { - *x = CustomEvent{} +func (x *DebugMessage) Reset() { + *x = DebugMessage{} mi := &file_agent_livekit_agent_session_proto_msgTypes[15] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } -func (x *CustomEvent) String() string { +func (x *DebugMessage) String() string { return protoimpl.X.MessageStringOf(x) } -func (*CustomEvent) ProtoMessage() {} +func (*DebugMessage) ProtoMessage() {} -func (x *CustomEvent) ProtoReflect() protoreflect.Message { +func (x *DebugMessage) ProtoReflect() protoreflect.Message { mi := &file_agent_livekit_agent_session_proto_msgTypes[15] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) @@ -1507,19 +1507,12 @@ func (x *CustomEvent) ProtoReflect() protoreflect.Message { return mi.MessageOf(x) } -// Deprecated: Use CustomEvent.ProtoReflect.Descriptor instead. -func (*CustomEvent) Descriptor() ([]byte, []int) { +// Deprecated: Use DebugMessage.ProtoReflect.Descriptor instead. +func (*DebugMessage) Descriptor() ([]byte, []int) { return file_agent_livekit_agent_session_proto_rawDescGZIP(), []int{15} } -func (x *CustomEvent) GetType() string { - if x != nil { - return x.Type - } - return "" -} - -func (x *CustomEvent) GetPayload() *structpb.Struct { +func (x *DebugMessage) GetPayload() *structpb.Struct { if x != nil { return x.Payload } @@ -1542,7 +1535,7 @@ type AgentSessionEvent struct { // *AgentSessionEvent_AmdPrediction_ // *AgentSessionEvent_EotPrediction_ // *AgentSessionEvent_FunctionToolsStarted_ - // *AgentSessionEvent_CustomEvent + // *AgentSessionEvent_DebugMessage Event isAgentSessionEvent_Event `protobuf_oneof:"event"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -1691,10 +1684,10 @@ func (x *AgentSessionEvent) GetFunctionToolsStarted() *AgentSessionEvent_Functio return nil } -func (x *AgentSessionEvent) GetCustomEvent() *CustomEvent { +func (x *AgentSessionEvent) GetDebugMessage() *DebugMessage { if x != nil { - if x, ok := x.Event.(*AgentSessionEvent_CustomEvent); ok { - return x.CustomEvent + if x, ok := x.Event.(*AgentSessionEvent_DebugMessage); ok { + return x.DebugMessage } } return nil @@ -1748,8 +1741,8 @@ type AgentSessionEvent_FunctionToolsStarted_ struct { FunctionToolsStarted *AgentSessionEvent_FunctionToolsStarted `protobuf:"bytes,20,opt,name=function_tools_started,json=functionToolsStarted,proto3,oneof"` } -type AgentSessionEvent_CustomEvent struct { - CustomEvent *CustomEvent `protobuf:"bytes,21,opt,name=custom_event,json=customEvent,proto3,oneof"` +type AgentSessionEvent_DebugMessage struct { + DebugMessage *DebugMessage `protobuf:"bytes,21,opt,name=debug_message,json=debugMessage,proto3,oneof"` } func (*AgentSessionEvent_AgentStateChanged_) isAgentSessionEvent_Event() {} @@ -1774,7 +1767,7 @@ func (*AgentSessionEvent_EotPrediction_) isAgentSessionEvent_Event() {} func (*AgentSessionEvent_FunctionToolsStarted_) isAgentSessionEvent_Event() {} -func (*AgentSessionEvent_CustomEvent) isAgentSessionEvent_Event() {} +func (*AgentSessionEvent_DebugMessage) isAgentSessionEvent_Event() {} type SessionRequest struct { state protoimpl.MessageState `protogen:"open.v1"` @@ -4444,10 +4437,9 @@ const file_agent_livekit_agent_session_proto_rawDesc = "" + "\x05usage\"O\n" + "\x11AgentSessionUsage\x12:\n" + "\vmodel_usage\x18\x01 \x03(\v2\x19.livekit.agent.ModelUsageR\n" + - "modelUsage\"T\n" + - "\vCustomEvent\x12\x12\n" + - "\x04type\x18\x01 \x01(\tR\x04type\x121\n" + - "\apayload\x18\x02 \x01(\v2\x17.google.protobuf.StructR\apayload\"\x94\x16\n" + + "modelUsage\"A\n" + + "\fDebugMessage\x121\n" + + "\apayload\x18\x01 \x01(\v2\x17.google.protobuf.StructR\apayload\"\x97\x16\n" + "\x11AgentSessionEvent\x129\n" + "\n" + "created_at\x18\x01 \x01(\v2\x1a.google.protobuf.TimestampR\tcreatedAt\x12d\n" + @@ -4462,8 +4454,8 @@ const file_agent_livekit_agent_session_proto_rawDesc = "" + "\x15session_usage_updated\x18\x11 \x01(\v24.livekit.agent.AgentSessionEvent.SessionUsageUpdatedH\x00R\x13sessionUsageUpdated\x12W\n" + "\x0eamd_prediction\x18\x12 \x01(\v2..livekit.agent.AgentSessionEvent.AmdPredictionH\x00R\ramdPrediction\x12W\n" + "\x0eeot_prediction\x18\x13 \x01(\v2..livekit.agent.AgentSessionEvent.EotPredictionH\x00R\reotPrediction\x12m\n" + - "\x16function_tools_started\x18\x14 \x01(\v25.livekit.agent.AgentSessionEvent.FunctionToolsStartedH\x00R\x14functionToolsStarted\x12?\n" + - "\fcustom_event\x18\x15 \x01(\v2\x1a.livekit.agent.CustomEventH\x00R\vcustomEvent\x1a\x83\x01\n" + + "\x16function_tools_started\x18\x14 \x01(\v25.livekit.agent.AgentSessionEvent.FunctionToolsStartedH\x00R\x14functionToolsStarted\x12B\n" + + "\rdebug_message\x18\x15 \x01(\v2\x1b.livekit.agent.DebugMessageH\x00R\fdebugMessage\x1a\x83\x01\n" + "\x11AgentStateChanged\x126\n" + "\told_state\x18\x01 \x01(\x0e2\x19.livekit.agent.AgentStateR\boldState\x126\n" + "\tnew_state\x18\x02 \x01(\x0e2\x19.livekit.agent.AgentStateR\bnewState\x1a\x80\x01\n" + @@ -4682,7 +4674,7 @@ var file_agent_livekit_agent_session_proto_goTypes = []any{ (*EotModelUsage)(nil), // 16: livekit.agent.EotModelUsage (*ModelUsage)(nil), // 17: livekit.agent.ModelUsage (*AgentSessionUsage)(nil), // 18: livekit.agent.AgentSessionUsage - (*CustomEvent)(nil), // 19: livekit.agent.CustomEvent + (*DebugMessage)(nil), // 19: livekit.agent.DebugMessage (*AgentSessionEvent)(nil), // 20: livekit.agent.AgentSessionEvent (*SessionRequest)(nil), // 21: livekit.agent.SessionRequest (*SessionResponse)(nil), // 22: livekit.agent.SessionResponse @@ -4750,7 +4742,7 @@ var file_agent_livekit_agent_session_proto_depIdxs = []int32{ 15, // 15: livekit.agent.ModelUsage.interruption:type_name -> livekit.agent.InterruptionModelUsage 16, // 16: livekit.agent.ModelUsage.eot:type_name -> livekit.agent.EotModelUsage 17, // 17: livekit.agent.AgentSessionUsage.model_usage:type_name -> livekit.agent.ModelUsage - 65, // 18: livekit.agent.CustomEvent.payload:type_name -> google.protobuf.Struct + 65, // 18: livekit.agent.DebugMessage.payload:type_name -> google.protobuf.Struct 64, // 19: livekit.agent.AgentSessionEvent.created_at:type_name -> google.protobuf.Timestamp 27, // 20: livekit.agent.AgentSessionEvent.agent_state_changed:type_name -> livekit.agent.AgentSessionEvent.AgentStateChanged 28, // 21: livekit.agent.AgentSessionEvent.user_state_changed:type_name -> livekit.agent.AgentSessionEvent.UserStateChanged @@ -4763,7 +4755,7 @@ var file_agent_livekit_agent_session_proto_depIdxs = []int32{ 35, // 28: livekit.agent.AgentSessionEvent.amd_prediction:type_name -> livekit.agent.AgentSessionEvent.AmdPrediction 36, // 29: livekit.agent.AgentSessionEvent.eot_prediction:type_name -> livekit.agent.AgentSessionEvent.EotPrediction 31, // 30: livekit.agent.AgentSessionEvent.function_tools_started:type_name -> livekit.agent.AgentSessionEvent.FunctionToolsStarted - 19, // 31: livekit.agent.AgentSessionEvent.custom_event:type_name -> livekit.agent.CustomEvent + 19, // 31: livekit.agent.AgentSessionEvent.debug_message:type_name -> livekit.agent.DebugMessage 38, // 32: livekit.agent.SessionRequest.ping:type_name -> livekit.agent.SessionRequest.Ping 39, // 33: livekit.agent.SessionRequest.get_chat_history:type_name -> livekit.agent.SessionRequest.GetChatHistory 40, // 34: livekit.agent.SessionRequest.run_input:type_name -> livekit.agent.SessionRequest.RunInput @@ -4860,7 +4852,7 @@ func file_agent_livekit_agent_session_proto_init() { (*AgentSessionEvent_AmdPrediction_)(nil), (*AgentSessionEvent_EotPrediction_)(nil), (*AgentSessionEvent_FunctionToolsStarted_)(nil), - (*AgentSessionEvent_CustomEvent)(nil), + (*AgentSessionEvent_DebugMessage)(nil), } file_agent_livekit_agent_session_proto_msgTypes[17].OneofWrappers = []any{ (*SessionRequest_Ping_)(nil), diff --git a/protobufs/agent/livekit_agent_session.proto b/protobufs/agent/livekit_agent_session.proto index aaf82df81..257841ba1 100644 --- a/protobufs/agent/livekit_agent_session.proto +++ b/protobufs/agent/livekit_agent_session.proto @@ -183,10 +183,10 @@ message AgentSessionUsage { repeated ModelUsage model_usage = 1; } -// Application-defined event carried over the remote session wire. -message CustomEvent { - string type = 1; - google.protobuf.Struct payload = 2; +// Free-form debug/trace payload carried over the remote session wire. +// Internal: surfaced only to the debugger/recorder, not to user code. +message DebugMessage { + google.protobuf.Struct payload = 1; } message AgentSessionEvent { @@ -262,7 +262,7 @@ message AgentSessionEvent { AmdPrediction amd_prediction = 18; EotPrediction eot_prediction = 19; FunctionToolsStarted function_tools_started = 20; - CustomEvent custom_event = 21; + DebugMessage debug_message = 21; } } From 9deddddf86cdbb9200aea166af91874e979ad2e0 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 00:36:05 +0000 Subject: [PATCH 2/5] generated protobuf --- livekit/agent/livekit_agent_session.pb.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/livekit/agent/livekit_agent_session.pb.go b/livekit/agent/livekit_agent_session.pb.go index 4ffdcbe81..151627dd9 100644 --- a/livekit/agent/livekit_agent_session.pb.go +++ b/livekit/agent/livekit_agent_session.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.36.6 -// protoc v5.29.3 +// protoc-gen-go v1.36.11 +// protoc v4.23.4 // source: agent/livekit_agent_session.proto package agent From 5061facfe6935c19753cc39dde77cc4d62496384 Mon Sep 17 00:00:00 2001 From: Brian Yin Date: Tue, 26 May 2026 20:38:15 -0400 Subject: [PATCH 3/5] changeset: patch bump, not minor Co-authored-by: Cursor --- .changeset/rename-custom-event-to-debug-message.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/rename-custom-event-to-debug-message.md b/.changeset/rename-custom-event-to-debug-message.md index f835fa777..e2e00bc79 100644 --- a/.changeset/rename-custom-event-to-debug-message.md +++ b/.changeset/rename-custom-event-to-debug-message.md @@ -1,5 +1,5 @@ --- -"@livekit/protocol": minor +"@livekit/protocol": patch --- agent_session: rename `CustomEvent` → `DebugMessage`; drop `type` field, keep only `payload` From acd2ff11c58037a99ad03efd4e72ed59e493feff Mon Sep 17 00:00:00 2001 From: Brian Yin Date: Tue, 26 May 2026 20:40:23 -0400 Subject: [PATCH 4/5] drop 'free-form' from DebugMessage docs Co-authored-by: Cursor --- .changeset/rename-custom-event-to-debug-message.md | 2 +- livekit/agent/livekit_agent_session.pb.go | 6 +++--- protobufs/agent/livekit_agent_session.proto | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.changeset/rename-custom-event-to-debug-message.md b/.changeset/rename-custom-event-to-debug-message.md index e2e00bc79..77c6d32c8 100644 --- a/.changeset/rename-custom-event-to-debug-message.md +++ b/.changeset/rename-custom-event-to-debug-message.md @@ -7,7 +7,7 @@ agent_session: rename `CustomEvent` → `DebugMessage`; drop `type` field, keep Renames the agent-session event added in #1588 before any consumer ships it. The message is repositioned as an internal debug/trace channel surfaced only to the debugger/recorder, not to user code, so the `type` discriminator was unnecessary -— callers just emit a free-form JSON `payload`. +— callers just emit a JSON `payload`. Wire-level: `AgentSessionEvent.custom_event` (field 21) → `AgentSessionEvent.debug_message` (same field number 21, same type slot, no schema-compat concerns since nothing diff --git a/livekit/agent/livekit_agent_session.pb.go b/livekit/agent/livekit_agent_session.pb.go index 151627dd9..e3935c82f 100644 --- a/livekit/agent/livekit_agent_session.pb.go +++ b/livekit/agent/livekit_agent_session.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.36.11 -// protoc v4.23.4 +// protoc-gen-go v1.36.6 +// protoc v5.29.3 // source: agent/livekit_agent_session.proto package agent @@ -1473,7 +1473,7 @@ func (x *AgentSessionUsage) GetModelUsage() []*ModelUsage { return nil } -// Free-form debug/trace payload carried over the remote session wire. +// Debug/trace payload carried over the remote session wire. // Internal: surfaced only to the debugger/recorder, not to user code. type DebugMessage struct { state protoimpl.MessageState `protogen:"open.v1"` diff --git a/protobufs/agent/livekit_agent_session.proto b/protobufs/agent/livekit_agent_session.proto index 257841ba1..ed74a7c74 100644 --- a/protobufs/agent/livekit_agent_session.proto +++ b/protobufs/agent/livekit_agent_session.proto @@ -183,7 +183,7 @@ message AgentSessionUsage { repeated ModelUsage model_usage = 1; } -// Free-form debug/trace payload carried over the remote session wire. +// Debug/trace payload carried over the remote session wire. // Internal: surfaced only to the debugger/recorder, not to user code. message DebugMessage { google.protobuf.Struct payload = 1; From 54ce680776bee699fb2fe0a8df0ef6a259be1a47 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 00:41:28 +0000 Subject: [PATCH 5/5] generated protobuf --- livekit/agent/livekit_agent_session.pb.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/livekit/agent/livekit_agent_session.pb.go b/livekit/agent/livekit_agent_session.pb.go index e3935c82f..b12a44773 100644 --- a/livekit/agent/livekit_agent_session.pb.go +++ b/livekit/agent/livekit_agent_session.pb.go @@ -1,7 +1,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.36.6 -// protoc v5.29.3 +// protoc-gen-go v1.36.11 +// protoc v4.23.4 // source: agent/livekit_agent_session.proto package agent