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..77c6d32c8 --- /dev/null +++ b/.changeset/rename-custom-event-to-debug-message.md @@ -0,0 +1,14 @@ +--- +"@livekit/protocol": patch +--- + +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 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..b12a44773 100644 --- a/livekit/agent/livekit_agent_session.pb.go +++ b/livekit/agent/livekit_agent_session.pb.go @@ -1473,29 +1473,29 @@ func (x *AgentSessionUsage) GetModelUsage() []*ModelUsage { return nil } -// Application-defined event carried over the remote session wire. -type CustomEvent struct { +// 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..ed74a7c74 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; +// 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; } }