From d7a2071d5e02c1b9672b48f5988160448720effb Mon Sep 17 00:00:00 2001 From: mintaka Date: Thu, 27 Aug 2026 19:54:07 -0400 Subject: [PATCH] feat(proto): add traceparent to SteerControl/DeliverControl for trace continuity (RIG-2508) T4 (partial) of the message->turn trace-continuity record: the agent.proto half of the cross-lane wire contract. Adds an additive proto3 `string traceparent` to SteerControl (field 3) and DeliverControl (field 4) so the Server can denormalize its active-span W3C traceparent onto the inbound control, letting the agent join its turn to the message's server-side trace (creation -> routing -> delivery -> turn -> tool calls, one connected trace) -- mirroring the from_handle denorm (RIG-2486 T1). W3C format; empty when the Server has no active span (trace machinery never blocks a delivery). Buf-breaking-safe additive fields, internal-only (gen-fence clean). Regenerates the internal Go and agent TS lanes. Server-side stamping + the compass.proto SessionInjection / agent_gateway.proto trigger_traceparent seam land as a follow-up. Unblocks compass-agent T3 (RIG-2871) wire decode. Record: docs/designs/platform/compass-agent-message-trace-continuity/design.md Co-authored-by: Matt Wilkinson --- go/internal/gen/compass/v1/agent.pb.go | 44 ++++++++++++++++--- .../src/gen/compass/v1/agent_pb.ts | 28 +++++++++++- proto/compass/v1/agent.proto | 16 +++++++ 3 files changed, 81 insertions(+), 7 deletions(-) diff --git a/go/internal/gen/compass/v1/agent.pb.go b/go/internal/gen/compass/v1/agent.pb.go index 615367ac5..749b89fe0 100644 --- a/go/internal/gen/compass/v1/agent.pb.go +++ b/go/internal/gen/compass/v1/agent.pb.go @@ -688,7 +688,15 @@ type SteerControl struct { // topic_name denorm rationale below. The comms Message carries only // `author_account_id` (an id, not a handle), so the handle is denormalized // here; the Server resolves it once when wrapping the AgentControl. - FromHandle string `protobuf:"bytes,2,opt,name=from_handle,json=fromHandle,proto3" json:"from_handle,omitempty"` + FromHandle string `protobuf:"bytes,2,opt,name=from_handle,json=fromHandle,proto3" json:"from_handle,omitempty"` + // The W3C `traceparent` of the Server's active span when it wrapped this + // control, denormalized so the agent joins its turn to the message's + // server-side trace (creation → routing → delivery → turn → tool calls, one + // connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + // flags>`; EMPTY when the Server had no active span (trace machinery never + // blocks or fails a delivery). Server-side stamping per + // docs/designs/platform/compass-agent-message-trace-continuity/design.md. + Traceparent string `protobuf:"bytes,3,opt,name=traceparent,proto3" json:"traceparent,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -737,6 +745,13 @@ func (x *SteerControl) GetFromHandle() string { return "" } +func (x *SteerControl) GetTraceparent() string { + if x != nil { + return x.Traceparent + } + return "" +} + // Empty shells — payload fields parked (SEA-1310). Present so the AgentControl // oneof is complete on the wire; populated by a stacked PR. // @@ -835,7 +850,15 @@ type DeliverControl struct { // above. The comms Message carries only `author_account_id` (an id, not a // handle), so the handle is denormalized here; the Server resolves it once // when wrapping the AgentControl. - FromHandle string `protobuf:"bytes,3,opt,name=from_handle,json=fromHandle,proto3" json:"from_handle,omitempty"` + FromHandle string `protobuf:"bytes,3,opt,name=from_handle,json=fromHandle,proto3" json:"from_handle,omitempty"` + // The W3C `traceparent` of the Server's active span when it wrapped this + // control, denormalized so the agent joins its turn to the message's + // server-side trace (creation → routing → delivery → turn → tool calls, one + // connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + // flags>`; EMPTY when the Server had no active span (trace machinery never + // blocks or fails a delivery). Server-side stamping per + // docs/designs/platform/compass-agent-message-trace-continuity/design.md. + Traceparent string `protobuf:"bytes,4,opt,name=traceparent,proto3" json:"traceparent,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -891,6 +914,13 @@ func (x *DeliverControl) GetFromHandle() string { return "" } +func (x *DeliverControl) GetTraceparent() string { + if x != nil { + return x.Traceparent + } + return "" +} + // DeliveryAck — the agent's per-message delivery receipt (SEA-1569), an // AgentFrame oneof variant riding the Publish spine. Correlates to the // delivered message by id; on receipt the Server advances the delivery cursor @@ -1134,19 +1164,21 @@ const file_compass_v1_agent_proto_rawDesc = "" + "\acontrol\"%\n" + "\rPromptControl\x12\x14\n" + "\x05input\x18\x01 \x01(\tR\x05input\"\x10\n" + - "\x0eReplayComplete\"^\n" + + "\x0eReplayComplete\"\x80\x01\n" + "\fSteerControl\x12-\n" + "\amessage\x18\x01 \x01(\v2\x13.compass.v1.MessageR\amessage\x12\x1f\n" + "\vfrom_handle\x18\x02 \x01(\tR\n" + - "fromHandle\"\x12\n" + + "fromHandle\x12 \n" + + "\vtraceparent\x18\x03 \x01(\tR\vtraceparent\"\x12\n" + "\x10TranscriptReplay\"\x0f\n" + - "\rConfigControl\"\x7f\n" + + "\rConfigControl\"\xa1\x01\n" + "\x0eDeliverControl\x12-\n" + "\amessage\x18\x01 \x01(\v2\x13.compass.v1.MessageR\amessage\x12\x1d\n" + "\n" + "topic_name\x18\x02 \x01(\tR\ttopicName\x12\x1f\n" + "\vfrom_handle\x18\x03 \x01(\tR\n" + - "fromHandle\",\n" + + "fromHandle\x12 \n" + + "\vtraceparent\x18\x04 \x01(\tR\vtraceparent\",\n" + "\vDeliveryAck\x12\x1d\n" + "\n" + "message_id\x18\x01 \x01(\tR\tmessageId\"[\n" + diff --git a/packages/compass-agent/src/gen/compass/v1/agent_pb.ts b/packages/compass-agent/src/gen/compass/v1/agent_pb.ts index b2a636296..3ac0d29c5 100644 --- a/packages/compass-agent/src/gen/compass/v1/agent_pb.ts +++ b/packages/compass-agent/src/gen/compass/v1/agent_pb.ts @@ -35,7 +35,7 @@ import type { Message } from "@bufbuild/protobuf"; * Describes the file compass/v1/agent.proto. */ export const file_compass_v1_agent: GenFile = /*@__PURE__*/ - fileDesc("ChZjb21wYXNzL3YxL2FnZW50LnByb3RvEgpjb21wYXNzLnYxIt0CCgpBZ2VudEZyYW1lEisKB3Nlc3Npb24YAyABKAsyGC5jb21wYXNzLnYxLlNlc3Npb25GcmFtZUgAEjwKE3JlcGxheV9jb21wbGV0ZV9hY2sYBCABKAsyHS5jb21wYXNzLnYxLlJlcGxheUNvbXBsZXRlQWNrSAASLQoLY29udHJvbF9hY2sYBSABKAsyFi5jb21wYXNzLnYxLkNvbnRyb2xBY2tIABIvCgxkZWxpdmVyeV9hY2sYBiABKAsyFy5jb21wYXNzLnYxLkRlbGl2ZXJ5QWNrSAASNwoQdHJhbnNjcmlwdF9lbnRyeRgHIAEoCzIbLmNvbXBhc3MudjEuVHJhbnNjcmlwdEVudHJ5SAASQgoWZm9yZ2Vfbm90aWZpY2F0aW9uX2FjaxgIIAEoCzIgLmNvbXBhc3MudjEuRm9yZ2VOb3RpZmljYXRpb25BY2tIAEIHCgVmcmFtZSJMCg9UcmFuc2NyaXB0RW50cnkSEgoKZW50cnlfanNvbhgBIAEoCRISCgpjaGVja3BvaW50GAIgASgIEhEKCWVudHJ5X3NlcRgDIAEoBCJrCgxTZXNzaW9uRnJhbWUSLAoFc3RhdGUYASABKA4yHS5jb21wYXNzLnYxLkFnZW50U2Vzc2lvblN0YXRlEi0KC3R5cGVkX2V2ZW50GAIgASgLMhguY29tcGFzcy52MS5TZXNzaW9uRXZlbnQihgMKDEFnZW50Q29udHJvbBITCgtjb250cm9sX3NlcRgIIAEoBBIrCgZwcm9tcHQYASABKAsyGS5jb21wYXNzLnYxLlByb21wdENvbnRyb2xIABIpCgVzdGVlchgCIAEoCzIYLmNvbXBhc3MudjEuU3RlZXJDb250cm9sSAASLQoHZGVsaXZlchgDIAEoCzIaLmNvbXBhc3MudjEuRGVsaXZlckNvbnRyb2xIABIrCgZjb25maWcYBSABKAsyGS5jb21wYXNzLnYxLkNvbmZpZ0NvbnRyb2xIABIuCgZyZXBsYXkYBiABKAsyHC5jb21wYXNzLnYxLlRyYW5zY3JpcHRSZXBsYXlIABI1Cg9yZXBsYXlfY29tcGxldGUYByABKAsyGi5jb21wYXNzLnYxLlJlcGxheUNvbXBsZXRlSAASOwoSZm9yZ2Vfbm90aWZpY2F0aW9uGAkgASgLMh0uY29tcGFzcy52MS5Gb3JnZU5vdGlmaWNhdGlvbkgAQgkKB2NvbnRyb2wiHgoNUHJvbXB0Q29udHJvbBINCgVpbnB1dBgBIAEoCSIQCg5SZXBsYXlDb21wbGV0ZSJJCgxTdGVlckNvbnRyb2wSJAoHbWVzc2FnZRgBIAEoCzITLmNvbXBhc3MudjEuTWVzc2FnZRITCgtmcm9tX2hhbmRsZRgCIAEoCSISChBUcmFuc2NyaXB0UmVwbGF5Ig8KDUNvbmZpZ0NvbnRyb2wiXwoORGVsaXZlckNvbnRyb2wSJAoHbWVzc2FnZRgBIAEoCzITLmNvbXBhc3MudjEuTWVzc2FnZRISCgp0b3BpY19uYW1lGAIgASgJEhMKC2Zyb21faGFuZGxlGAMgASgJIiEKC0RlbGl2ZXJ5QWNrEhIKCm1lc3NhZ2VfaWQYASABKAkiQQoURm9yZ2VOb3RpZmljYXRpb25BY2sSFwoPc3Vic2NyaXB0aW9uX2lkGAEgASgJEhAKCHJldmlzaW9uGAIgASgJIhMKEVJlcGxheUNvbXBsZXRlQWNrIjYKCkNvbnRyb2xBY2sSEQoJYWNrZWRfc2VxGAEgASgEEhUKDWFwcGxpZWRfYWJvdmUYAiADKARiBnByb3RvMw", [file_compass_v1_comms, file_compass_v1_compass, file_compass_v1_forge]); + fileDesc("ChZjb21wYXNzL3YxL2FnZW50LnByb3RvEgpjb21wYXNzLnYxIt0CCgpBZ2VudEZyYW1lEisKB3Nlc3Npb24YAyABKAsyGC5jb21wYXNzLnYxLlNlc3Npb25GcmFtZUgAEjwKE3JlcGxheV9jb21wbGV0ZV9hY2sYBCABKAsyHS5jb21wYXNzLnYxLlJlcGxheUNvbXBsZXRlQWNrSAASLQoLY29udHJvbF9hY2sYBSABKAsyFi5jb21wYXNzLnYxLkNvbnRyb2xBY2tIABIvCgxkZWxpdmVyeV9hY2sYBiABKAsyFy5jb21wYXNzLnYxLkRlbGl2ZXJ5QWNrSAASNwoQdHJhbnNjcmlwdF9lbnRyeRgHIAEoCzIbLmNvbXBhc3MudjEuVHJhbnNjcmlwdEVudHJ5SAASQgoWZm9yZ2Vfbm90aWZpY2F0aW9uX2FjaxgIIAEoCzIgLmNvbXBhc3MudjEuRm9yZ2VOb3RpZmljYXRpb25BY2tIAEIHCgVmcmFtZSJMCg9UcmFuc2NyaXB0RW50cnkSEgoKZW50cnlfanNvbhgBIAEoCRISCgpjaGVja3BvaW50GAIgASgIEhEKCWVudHJ5X3NlcRgDIAEoBCJrCgxTZXNzaW9uRnJhbWUSLAoFc3RhdGUYASABKA4yHS5jb21wYXNzLnYxLkFnZW50U2Vzc2lvblN0YXRlEi0KC3R5cGVkX2V2ZW50GAIgASgLMhguY29tcGFzcy52MS5TZXNzaW9uRXZlbnQihgMKDEFnZW50Q29udHJvbBITCgtjb250cm9sX3NlcRgIIAEoBBIrCgZwcm9tcHQYASABKAsyGS5jb21wYXNzLnYxLlByb21wdENvbnRyb2xIABIpCgVzdGVlchgCIAEoCzIYLmNvbXBhc3MudjEuU3RlZXJDb250cm9sSAASLQoHZGVsaXZlchgDIAEoCzIaLmNvbXBhc3MudjEuRGVsaXZlckNvbnRyb2xIABIrCgZjb25maWcYBSABKAsyGS5jb21wYXNzLnYxLkNvbmZpZ0NvbnRyb2xIABIuCgZyZXBsYXkYBiABKAsyHC5jb21wYXNzLnYxLlRyYW5zY3JpcHRSZXBsYXlIABI1Cg9yZXBsYXlfY29tcGxldGUYByABKAsyGi5jb21wYXNzLnYxLlJlcGxheUNvbXBsZXRlSAASOwoSZm9yZ2Vfbm90aWZpY2F0aW9uGAkgASgLMh0uY29tcGFzcy52MS5Gb3JnZU5vdGlmaWNhdGlvbkgAQgkKB2NvbnRyb2wiHgoNUHJvbXB0Q29udHJvbBINCgVpbnB1dBgBIAEoCSIQCg5SZXBsYXlDb21wbGV0ZSJeCgxTdGVlckNvbnRyb2wSJAoHbWVzc2FnZRgBIAEoCzITLmNvbXBhc3MudjEuTWVzc2FnZRITCgtmcm9tX2hhbmRsZRgCIAEoCRITCgt0cmFjZXBhcmVudBgDIAEoCSISChBUcmFuc2NyaXB0UmVwbGF5Ig8KDUNvbmZpZ0NvbnRyb2widAoORGVsaXZlckNvbnRyb2wSJAoHbWVzc2FnZRgBIAEoCzITLmNvbXBhc3MudjEuTWVzc2FnZRISCgp0b3BpY19uYW1lGAIgASgJEhMKC2Zyb21faGFuZGxlGAMgASgJEhMKC3RyYWNlcGFyZW50GAQgASgJIiEKC0RlbGl2ZXJ5QWNrEhIKCm1lc3NhZ2VfaWQYASABKAkiQQoURm9yZ2VOb3RpZmljYXRpb25BY2sSFwoPc3Vic2NyaXB0aW9uX2lkGAEgASgJEhAKCHJldmlzaW9uGAIgASgJIhMKEVJlcGxheUNvbXBsZXRlQWNrIjYKCkNvbnRyb2xBY2sSEQoJYWNrZWRfc2VxGAEgASgEEhUKDWFwcGxpZWRfYWJvdmUYAiADKARiBnByb3RvMw", [file_compass_v1_comms, file_compass_v1_compass, file_compass_v1_forge]); /** * The agent's stdout envelope: one discriminated frame per newline-delimited @@ -398,6 +398,19 @@ export type SteerControl = Message<"compass.v1.SteerControl"> & { * @generated from field: string from_handle = 2; */ fromHandle: string; + + /** + * The W3C `traceparent` of the Server's active span when it wrapped this + * control, denormalized so the agent joins its turn to the message's + * server-side trace (creation → routing → delivery → turn → tool calls, one + * connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + * flags>`; EMPTY when the Server had no active span (trace machinery never + * blocks or fails a delivery). Server-side stamping per + * docs/designs/platform/compass-agent-message-trace-continuity/design.md. + * + * @generated from field: string traceparent = 3; + */ + traceparent: string; }; /** @@ -477,6 +490,19 @@ export type DeliverControl = Message<"compass.v1.DeliverControl"> & { * @generated from field: string from_handle = 3; */ fromHandle: string; + + /** + * The W3C `traceparent` of the Server's active span when it wrapped this + * control, denormalized so the agent joins its turn to the message's + * server-side trace (creation → routing → delivery → turn → tool calls, one + * connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + * flags>`; EMPTY when the Server had no active span (trace machinery never + * blocks or fails a delivery). Server-side stamping per + * docs/designs/platform/compass-agent-message-trace-continuity/design.md. + * + * @generated from field: string traceparent = 4; + */ + traceparent: string; }; /** diff --git a/proto/compass/v1/agent.proto b/proto/compass/v1/agent.proto index 02deefc25..37e586411 100644 --- a/proto/compass/v1/agent.proto +++ b/proto/compass/v1/agent.proto @@ -203,6 +203,14 @@ message SteerControl { // `author_account_id` (an id, not a handle), so the handle is denormalized // here; the Server resolves it once when wrapping the AgentControl. string from_handle = 2; + // The W3C `traceparent` of the Server's active span when it wrapped this + // control, denormalized so the agent joins its turn to the message's + // server-side trace (creation → routing → delivery → turn → tool calls, one + // connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + // flags>`; EMPTY when the Server had no active span (trace machinery never + // blocks or fails a delivery). Server-side stamping per + // docs/designs/platform/compass-agent-message-trace-continuity/design.md. + string traceparent = 3; } // Empty shells — payload fields parked (SEA-1310). Present so the AgentControl @@ -233,6 +241,14 @@ message DeliverControl { // handle), so the handle is denormalized here; the Server resolves it once // when wrapping the AgentControl. string from_handle = 3; + // The W3C `traceparent` of the Server's active span when it wrapped this + // control, denormalized so the agent joins its turn to the message's + // server-side trace (creation → routing → delivery → turn → tool calls, one + // connected trace). W3C format `00-<32hex trace-id>-<16hex span-id>-<2hex + // flags>`; EMPTY when the Server had no active span (trace machinery never + // blocks or fails a delivery). Server-side stamping per + // docs/designs/platform/compass-agent-message-trace-continuity/design.md. + string traceparent = 4; } // DeliveryAck — the agent's per-message delivery receipt (SEA-1569), an