The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
WS1 — Event Identity: promote native tool call IDs and derive event IDs
Claude2316d655ed22
diff --git a/CLAUDE.md b/CLAUDE.mdindex 1b95d32c..7236107c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -353,6 +353,7 @@ Use these npm trusted publisher values:- For macOS-only behavior, gate tests with `runtime.GOOS == "darwin"` or assert the non-Darwin contract explicitly.- Keep endpoint event schema fields stable: `vendor`, `product`, `schema_version`, required event fields, and Wazuh-compatible JSONL output are release contracts.- Preserve optional event fields for agent-native metadata (`session`, `trace`, `tool`, `file`, `command`, `mcp`, `approval`, `content`, `model`, `repository`, and `branch`) without changing existing required field semantics.+- Keep event identity derivable rather than asserted. `gen_ai.tool.call.id` carries the runtime's own name for one tool invocation, promoted on every capture path from the shared alias list in `pkg/asymptoteobserve.ToolCallIDKeys`; a new runtime adds its spelling there rather than in a mapper. `event.id` is a deterministic UUID derived by `EventIDForLine` from the event about to be written, so both capture paths name one action the same way. Its namespace constant and derivation are a contract: changing either renames every event ID Beacon has written, and a test pins the value.- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cost_usd` carries runtime-reported cost only; do not derive cost from local pricing tables.- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.diff --git a/beacon-sandbox/check/check_test.go b/beacon-sandbox/check/check_test.goindex b0fcae50..8c287a50 100644--- a/beacon-sandbox/check/check_test.go+++ b/beacon-sandbox/check/check_test.go@@ -275,9 +275,14 @@ func TestSameHarnessRepeatsSurviveWithoutMatchingCallIDs(t *testing.T) {}}-// An equal, non-empty call ID inside the window is the one case the writer does collapse, so-// requiring two would be a guaranteed false failure.-func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {+// An equal, non-empty call ID is the one case the writer really does collapse, so requiring two+// would be a guaranteed false failure.+//+// No window applies to it, which is the whole point: a hook writes when the tool runs and the+// collector writes when its batch flushes, so the two reports of one call land further apart than+// any window worth having. Both distances are pinned here because the near one used to be the only+// one that collapsed.+func TestMatchingCallIDsCollapseAtAnyDistance(t *testing.T) {base := goodLog()withID := func(line, ts, id string) string {line = strings.Replace(line, "18:00:01Z", ts, 1)@@ -286,7 +291,7 @@ func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {}first := withID(base[1], "18:00:01Z", "call-1")same := withID(base[1], "18:00:02Z", "call-1") // 1s apart, identical call id- later := withID(base[1], "18:00:11Z", "call-1") // 10s apart, outside the 2s window+ later := withID(base[1], "18:00:11Z", "call-1") // 10s apart, well past the 2s windowsc := demoScenario()sc.Expect = []scenario.Expect{{@@ -301,8 +306,9 @@ func TestMatchingCallIDsInsideTheWindowCollapse(t *testing.T) {}outside := run(t, []string{base[0], first, later}, sc, presentSentinel(), nil)- if outside.Outcome != Pass {- t.Errorf("10s apart is outside the 2s window, so both survive:\n%s", outside.Report())+ if outside.Outcome != Fail {+ t.Errorf("equal call IDs are collapsed however far apart they are, so min_count 2 must "++ "fail at 10s too:\n%s", outside.Report())}}diff --git a/beacon-sandbox/check/expect.go b/beacon-sandbox/check/expect.goindex adfc9b53..999577d5 100644--- a/beacon-sandbox/check/expect.go+++ b/beacon-sandbox/check/expect.go@@ -231,8 +231,8 @@ func evaluate(v *Verdict, log Log, exp scenario.Expect, idx int, canary string)// Three rules matter, all taken from pkg/asymptoteobserve/dedupe.go://// - only dedupeActions are candidates at all; every other action is preserved verbatim-// - same harness collapses only on equal non-empty call IDs; different harness collapses on-// the window alone+// - equal non-empty call IDs collapse on their own, with no window and regardless of harness;+// otherwise a different harness collapses on the window alone and the same harness never does// - the window is 2s, except tool.completed which uses 10sfunc collapseDuplicates(events []Event) []Event {if len(events) < 2 {@@ -254,12 +254,16 @@ func collapseDuplicates(events []Event) []Event {if prev.Action() != e.Action() || identity(prev) != identity(e) {continue}- // Same harness needs matching, non-empty call IDs before the writer collapses.+ // An equal, non-empty call ID settles it on its own: the writer applies no window+ // there, because the hook and the collector report one call seconds apart.+ if a, b := callIDOf(prev), callIDOf(e); a != "" && a == b {+ suppressed = true+ break+ }+ // Without that, the same harness never collapses: two adjacent calls can+ // legitimately touch the same file or command.if harnessOf(prev) == harnessOf(e) {- a, b := callIDOf(prev), callIDOf(e)- if a == "" || b == "" || a != b {- continue- }+ continue}pts, err := time.Parse(time.RFC3339, prev.Typed.Timestamp)if err != nil {diff --git a/cli/beacon-hooks/cmd/cline_event.go b/cli/beacon-hooks/cmd/cline_event.goindex 0c483e2c..58933b63 100644--- a/cli/beacon-hooks/cmd/cline_event.go+++ b/cli/beacon-hooks/cmd/cline_event.go@@ -574,7 +574,7 @@ func clineToolFields(input map[string]interface{}, completed bool) map[string]incall["result"] = toolResponse}}- if callID := getFirstStr(input, "callId", "call_id", "toolCallId", "tool_call_id"); callID != "" {+ if callID := toolCallIDIn(input); callID != "" {call["id"] = callID}fields["gen_ai"] = map[string]interface{}{diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.goindex e940bfce..f6b74301 100644--- a/cli/beacon-hooks/cmd/endpoint_events.go+++ b/cli/beacon-hooks/cmd/endpoint_events.go@@ -15,6 +15,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/cloudshuttle""github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/git""github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve")var runInventoryHeartbeatCommand = exec.CommandContext@@ -36,6 +37,7 @@ func emitHookEvent(logger *logging.Logger, action, category, severity, message sif isCascadePlatform(platformFlag) {fields["raw"] = mergeNested(fields["raw"], map[string]interface{}{"cascade": input})}+ applyToolCallID(fields, input)if model := getFirstStr(input, "model"); model != "" {fields["model"] = model}@@ -257,9 +259,83 @@ func toolFieldsWithResponse(toolName string, toolInput, toolResponse map[string]fields[key] = value}}+ // The call ID goes on every tool event, not just the MCP ones that happened+ // to build a gen_ai object for their arguments. It is the join key: without+ // it nothing links this call to its result, or to the OTLP record of the+ // same action. Only the ID is promoted here -- arguments and results are a+ // separate question about what Beacon retains, not about identity.+ if callID := toolCallIDIn(toolInput, toolResponse); callID != "" {+ setToolCallID(fields, callID)+ }return fields}+// toolCallIDIn reads the runtime's own identifier for one tool invocation out of+// the payload maps a hook mapper has to hand.+//+// The alias list is shared with the OTLP path so both capture paths promote the+// same value to the same field, which is what lets duplicate suppression+// recognise the two reports of one action as one action.+func toolCallIDIn(inputs ...map[string]interface{}) string {+ return firstToolStringAcross(inputs, asymptoteobserve.ToolCallIDKeys...)+}++// applyToolCallID promotes a call ID carried at the top level of a hook payload,+// which is where Claude Code puts tool_use_id -- outside tool_input, so no+// amount of reading the tool arguments would ever have found it.+//+// Only an event that already describes a tool action takes one. A session+// lifecycle payload that happens to echo an ID is not a tool call, and giving it+// the join key of one would join it to work it did not do.+func applyToolCallID(fields, input map[string]interface{}) {+ if fields == nil || toolCallIDOf(fields) != "" || !describesToolAction(fields) {+ return+ }+ if callID := toolCallIDIn(input); callID != "" {+ setToolCallID(fields, callID)+ }+}++func describesToolAction(fields map[string]interface{}) bool {+ for _, key := range []string{"tool", "command", "file", "mcp"} {+ if value, ok := fields[key].(map[string]interface{}); ok && len(value) > 0 {+ return true+ }+ }+ return false+}++// toolCallIDOf reads back what setToolCallID wrote, so a mapper that already+// found the ID somewhere better is not overwritten by a weaker source.+func toolCallIDOf(fields map[string]interface{}) string {+ genAI, _ := fields["gen_ai"].(map[string]interface{})+ tool, _ := genAI["tool"].(map[string]interface{})+ call, _ := tool["call"].(map[string]interface{})+ id, _ := call["id"].(string)+ return strings.TrimSpace(id)+}++// setToolCallID writes gen_ai.tool.call.id, creating the objects on the way down+// and leaving whatever is already in them alone. mergeNested cannot do this: it+// is a one-level merge, so writing the call through it would replace the whole+// tool object and drop the name and arguments an MCP event puts there.+func setToolCallID(fields map[string]interface{}, callID string) {+ genAI := mutableChild(fields["gen_ai"])+ tool := mutableChild(genAI["tool"])+ call := mutableChild(tool["call"])+ call["id"] = callID+ tool["call"] = call+ genAI["tool"] = tool+ fields["gen_ai"] = genAI+}++func mutableChild(value interface{}) map[string]interface{} {+ if existing, ok := value.(map[string]interface{}); ok && existing != nil {+ return existing+ }+ return map[string]interface{}{}+}+func mcpToolFields(toolName string, toolInput, toolResponse map[string]interface{}) map[string]interface{} {maps := []map[string]interface{}{toolInput, toolResponse}mcpServer := firstToolStringAcross(maps, "mcp_server", "mcp_server_name", "mcp.server", "mcp.server.name")diff --git a/cli/beacon-hooks/cmd/opencode_event.go b/cli/beacon-hooks/cmd/opencode_event.goindex ef54dd50..de0b99bc 100644--- a/cli/beacon-hooks/cmd/opencode_event.go+++ b/cli/beacon-hooks/cmd/opencode_event.go@@ -266,7 +266,7 @@ func opencodeToolFields(input map[string]interface{}, completed bool) map[stringtoolInput := firstMap(input, "tool_input", "toolInput")toolResponse := firstMap(input, "tool_response", "toolResponse")fields := toolFieldsWithResponse(toolName, toolInput, toolResponse)- callID := getFirstStr(input, "call_id", "callID")+ callID := toolCallIDIn(input)call := map[string]interface{}{}if len(toolInput) > 0 {call["arguments"] = toolInputdiff --git a/cli/beacon-hooks/cmd/post_tool.go b/cli/beacon-hooks/cmd/post_tool.goindex b0ccd7c8..b75ba52c 100644--- a/cli/beacon-hooks/cmd/post_tool.go+++ b/cli/beacon-hooks/cmd/post_tool.go@@ -206,6 +206,11 @@ func recordLocalEdit(params *evaluationParams, input map[string]interface{}, logfields["session"] = mergeNested(fields["session"], map[string]interface{}{"id": params.sessionID})}applyWorkspaceFields(fields, input, filepath.Dir(params.filePath))+ // This emitter writes its event without going through emitHookEvent, so it+ // has to promote the call ID itself. Every file edit in the log is recorded+ // twice -- once here, once from OTLP -- and this is the field that lets the+ // writer tell that the two are one edit.+ applyToolCallID(fields, input)logger.EndpointEvent("file.modified", "file", "info", "File edit observed", fields)}diff --git a/cli/beacon-hooks/cmd/tool_call_id_test.go b/cli/beacon-hooks/cmd/tool_call_id_test.gonew file mode 100644index 00000000..b6fc585c--- /dev/null+++ b/cli/beacon-hooks/cmd/tool_call_id_test.go@@ -0,0 +1,153 @@+package cmd++import (+ "path/filepath"+ "regexp"+ "testing"+)++// leaf reads a string at a dotted path, returning "" for anything missing along+// the way. nested is the fatal-on-missing variant and is the wrong tool here:+// half these assertions are about a field legitimately not being there.+func leaf(event map[string]interface{}, keys ...string) string {+ var current interface{} = event+ for _, key := range keys {+ next, ok := current.(map[string]interface{})+ if !ok {+ return ""+ }+ current = next[key]+ }+ value, _ := current.(string)+ return value+}++func callIDOfEvent(event map[string]interface{}) string {+ return leaf(event, "gen_ai", "tool", "call", "id")+}++// Claude Code puts tool_use_id at the top level of the hook payload, outside+// tool_input, so no amount of reading the tool arguments would ever have found+// it. It is the only value that links this event to the tool's result, to the+// approval that allowed it, and to the OTLP record of the same command.+func TestRunPostToolPromotesClaudeToolUseID(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "claude"+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ runHookWithInput(t, runPostTool, map[string]interface{}{+ "session_id": "claude-session",+ "cwd": "/repo",+ "hook_event_name": "PostToolUse",+ "tool_name": "Bash",+ "tool_use_id": "toolu_01abc",+ "tool_input": map[string]interface{}{"command": "echo hi"},+ "tool_response": map[string]interface{}{"stdout": "hi"},+ })++ events := endpointEvents(t, logPath)+ if len(events) != 1 {+ t.Fatalf("event count = %d, want one command event: %#v", len(events), events)+ }+ if got := leaf(events[0], "event", "action"); got != "command.executed" {+ t.Fatalf("event.action = %q, want command.executed", got)+ }+ if got := callIDOfEvent(events[0]); got != "toolu_01abc" {+ t.Fatalf("gen_ai.tool.call.id = %q, want the tool_use_id Claude Code assigned", got)+ }+}++// A Claude Edit reaches the log through recordLocalEdit, which writes its event+// without going through emitHookEvent. Every file edit is recorded twice --+// once here, once from OTLP -- so this is the path that most needs the join key.+func TestRunPostToolPromotesToolUseIDOnFileEdits(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "claude"+ dir := t.TempDir()+ logPath := filepath.Join(dir, "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ runHookWithInput(t, runPostTool, map[string]interface{}{+ "session_id": "claude-session",+ "cwd": dir,+ "hook_event_name": "PostToolUse",+ "tool_name": "Write",+ "tool_use_id": "toolu_01write",+ "tool_input": map[string]interface{}{+ "file_path": filepath.Join(dir, "notes.md"),+ "content": "hello",+ },+ })++ events := endpointEvents(t, logPath)+ edits := 0+ for _, event := range events {+ if leaf(event, "event", "action") != "file.modified" {+ continue+ }+ edits+++ if got := callIDOfEvent(event); got != "toolu_01write" {+ t.Fatalf("file.modified call ID = %q, want the tool_use_id Claude Code assigned", got)+ }+ }+ if edits == 0 {+ t.Fatalf("no file.modified event was written: %#v", events)+ }+}++// A session lifecycle payload that happens to echo an ID is not a tool call.+// Giving it the join key of one would join it to work it did not do.+func TestSessionEventsDoNotTakeAToolCallID(t *testing.T) {+ fields := map[string]interface{}{"session": map[string]interface{}{"id": "s1"}}+ applyToolCallID(fields, map[string]interface{}{"tool_use_id": "toolu_01abc"})+ if _, ok := fields["gen_ai"]; ok {+ t.Fatalf("a session event took a tool call ID: %#v", fields)+ }+}++// An MCP event already builds a gen_ai object for its arguments, so the call ID+// has to be written into it rather than over it.+func TestToolCallIDDoesNotDisplaceMCPToolFields(t *testing.T) {+ fields := toolFieldsWithResponse("mcp__linear__list_issues", map[string]interface{}{+ "mcp_server": "linear",+ "call_id": "call_42",+ "team": "beacon",+ }, nil)+ if got := callIDOfEvent(fields); got != "call_42" {+ t.Fatalf("gen_ai.tool.call.id = %q, want call_42", got)+ }+ if got := leaf(fields, "gen_ai", "tool", "name"); got != "list_issues" {+ t.Fatalf("gen_ai.tool.name = %q, want the MCP tool name to survive", got)+ }+ if got := nested(t, fields, "gen_ai", "tool", "call")["arguments"]; got == nil {+ t.Fatal("gen_ai.tool.call.arguments was dropped when the call ID was written")+ }+}++var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)++// Every event the hook writer emits carries an identity, whether or not the+// runtime named the action itself.+func TestHookEventsCarryAnEventID(t *testing.T) {+ setupHookConfigDirs(t)+ platformFlag = "claude"+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ runHookWithInput(t, runPostTool, map[string]interface{}{+ "session_id": "claude-session",+ "cwd": "/repo",+ "hook_event_name": "PostToolUse",+ "tool_name": "Bash",+ "tool_use_id": "toolu_01abc",+ "tool_input": map[string]interface{}{"command": "echo hi"},+ })++ for _, event := range endpointEvents(t, logPath) {+ id := leaf(event, "event", "id")+ if !uuidV5Pattern.MatchString(id) {+ t.Fatalf("event.id = %q, want an RFC 4122 version 5 UUID: %#v", id, event)+ }+ }+}diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.goindex ff018796..5ddeefd4 100644--- a/cli/beacon-hooks/internal/logging/logging.go+++ b/cli/beacon-hooks/internal/logging/logging.go@@ -252,9 +252,40 @@ func writeEndpointJSON(path string, event map[string]interface{}) error {if len(data) > 64*1024 {return fmt.Errorf("endpoint event exceeds 64 KiB after metadata fallback")}+ // Stamped last, over the bytes that are actually about to be written, so+ // none of the size fallbacks above can leave the ID describing an event that+ // no longer exists.+ if data, err = withEndpointEventID(event, data); err != nil {+ return err+ }return appendEndpointJSONL(path, append(data, '\n'), defaultEndpointRotateBytes, defaultEndpointRotateArchives)}+// withEndpointEventID fills event.id on an event assembled as a map and returns+// its re-marshalled line. line must be the marshalled form of event with no ID+// on it, which is what EventIDForLine is derived from.+func withEndpointEventID(event map[string]interface{}, line []byte) ([]byte, error) {+ info, ok := event["event"].(map[string]interface{})+ if !ok {+ return line, nil+ }+ if id, _ := info["id"].(string); strings.TrimSpace(id) != "" {+ return line, nil+ }+ info["id"] = asymptoteobserve.EventIDForLine(line)+ data, err := json.Marshal(sanitizeEndpointMap(event))+ if err != nil {+ return nil, err+ }+ // An event already at the size limit keeps its bytes and goes without an ID:+ // the limit is a hard contract, and refusing to write an event over forty+ // bytes of identity would be the worse trade.+ if len(data) > 64*1024 {+ return line, nil+ }+ return data, nil+}+func compactEndpointContent(event map[string]interface{}) {if file, ok := event["file"].(map[string]interface{}); ok {delete(file, "diff")diff --git a/cli/beacon/internal/endpoint/writer/writer.go b/cli/beacon/internal/endpoint/writer/writer.goindex 3c18f86f..1d6fd85a 100644--- a/cli/beacon/internal/endpoint/writer/writer.go+++ b/cli/beacon/internal/endpoint/writer/writer.go@@ -82,6 +82,21 @@ func AppendEvent(event schema.Event, opts Options) (string, error) {if len(data) > opts.MaxBytes {return "", fmt.Errorf("event exceeds maximum size after truncation: %d bytes", len(data))}+ // Stamped last, over the bytes that are actually about to be written, so the+ // truncation fallback above cannot leave the ID describing an event that no+ // longer exists. An event already at the size limit keeps its bytes and goes+ // without one: the limit is a hard contract, and refusing to write an event+ // over forty bytes of identity would be the worse trade.+ if event.Event.ID == "" {+ event.Event.ID = asymptoteobserve.EventIDForLine(data)+ stamped, err := json.Marshal(event)+ if err != nil {+ return "", err+ }+ if len(stamped) <= opts.MaxBytes {+ data = stamped+ }+ }if err := appendJSONL(opts.Path, append(data, '\n'), opts.RotateSize, opts.RotateArchives); err != nil {return "", err}diff --git a/cli/beacon/internal/endpoint/writer/writer_test.go b/cli/beacon/internal/endpoint/writer/writer_test.goindex b3674672..81e7d990 100644--- a/cli/beacon/internal/endpoint/writer/writer_test.go+++ b/cli/beacon/internal/endpoint/writer/writer_test.go@@ -4,12 +4,14 @@ import ("encoding/json""os""path/filepath"+ "regexp""strconv""strings""sync""testing""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve")func TestAppendEventWritesSingleJSONLine(t *testing.T) {@@ -294,3 +296,80 @@ func TestSanitizeEventRedactsToolPolicyAndRawValues(t *testing.T) {t.Fatalf("tool path was not truncated: %d", len(sanitized.Tool.Path))}}++var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)++func TestAppendEventStampsAStableEventID(t *testing.T) {+ path := filepath.Join(t.TempDir(), "runtime.jsonl")+ event := schema.NewEvent(schema.NewEventOptions{+ Action: "command.executed",+ Harness: schema.HarnessInfo{Name: "claude_code"},+ Message: "Shell command executed",+ })+ event.Timestamp = "2026-08-21T18:00:01Z"+ event.Session = &schema.SessionInfo{ID: "s1"}+ event.Command = &schema.CommandInfo{Command: "echo hi"}+ event.GenAI = &schema.GenAIInfo{Tool: &schema.GenAIToolInfo{Call: &schema.GenAIToolCallInfo{ID: "toolu_1"}}}++ if _, err := AppendEvent(event, Options{Path: path}); err != nil {+ t.Fatalf("AppendEvent returned error: %v", err)+ }++ line, err := LastLine(path)+ if err != nil {+ t.Fatalf("read last line: %v", err)+ }+ var written schema.Event+ if err := json.Unmarshal([]byte(line), &written); err != nil {+ t.Fatalf("decode written event: %v", err)+ }+ if !uuidV5Pattern.MatchString(written.Event.ID) {+ t.Fatalf("event.id = %q, want an RFC 4122 version 5 UUID", written.Event.ID)+ }+ // The ID has to describe the line it is on, so re-deriving it from that line+ // with the field cleared has to land on the same value.+ bare := written+ bare.Event.ID = ""+ data, err := json.Marshal(bare)+ if err != nil {+ t.Fatalf("re-marshal event: %v", err)+ }+ if got := asymptoteobserve.EventIDForLine(data); got != written.Event.ID {+ t.Fatalf("event.id = %s, but the written line derives %s", written.Event.ID, got)+ }+}++// The regression the call ID exists to fix: after harness normalization both+// capture paths report claude_code, and the collector's batch lands seconds+// after the hook's write. Nothing but a shared call ID can collapse that pair.+func TestAppendEventCollapsesTheHookAndCollectorReportsOfOneCall(t *testing.T) {+ path := filepath.Join(t.TempDir(), "runtime.jsonl")+ hook := schema.NewEvent(schema.NewEventOptions{+ Action: "command.executed",+ Harness: schema.HarnessInfo{Name: "claude_code"},+ Message: "Shell command executed",+ })+ hook.Timestamp = "2026-08-21T18:00:01Z"+ hook.Session = &schema.SessionInfo{ID: "s1"}+ hook.Command = &schema.CommandInfo{Command: "echo hi"}+ hook.GenAI = &schema.GenAIInfo{Tool: &schema.GenAIToolInfo{Call: &schema.GenAIToolCallInfo{ID: "toolu_1"}}}++ collector := hook+ collector.Timestamp = "2026-08-21T18:00:07Z"+ collector.Message = "Tool execution observed"++ if _, err := AppendEvent(hook, Options{Path: path}); err != nil {+ t.Fatalf("first AppendEvent returned error: %v", err)+ }+ if _, err := AppendEvent(collector, Options{Path: path}); err != nil {+ t.Fatalf("second AppendEvent returned error: %v", err)+ }++ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("read log: %v", err)+ }+ if lines := strings.Split(strings.TrimSpace(string(data)), "\n"); len(lines) != 1 {+ t.Fatalf("one Bash call was recorded %d times: %s", len(lines), string(data))+ }+}diff --git a/collector-builder/exporter/beaconjsonexporter/exporter_test.go b/collector-builder/exporter/beaconjsonexporter/exporter_test.goindex 707c3220..278f0a32 100644--- a/collector-builder/exporter/beaconjsonexporter/exporter_test.go+++ b/collector-builder/exporter/beaconjsonexporter/exporter_test.go@@ -11,6 +11,7 @@ import ("testing""time"+ "github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/internal/beaconevent""github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve""go.opentelemetry.io/collector/exporter""go.opentelemetry.io/collector/pdata/plog"@@ -160,6 +161,46 @@ func TestJSONLWriterDedupesRuntimeEvents(t *testing.T) {}}+// The collector writes an event with the same identity the hook writer would+// give it, or the two capture paths cannot recognise each other's reports.+func TestJSONLWriterStampsTheSameEventIDTheHookWriterWould(t *testing.T) {+ path := filepath.Join(t.TempDir(), "runtime.jsonl")+ writer := jsonlWriter{+ path: path,+ maxEventBytes: defaultMaxEventBytes,+ rotateBytes: defaultRotateBytes,+ rotateArchives: defaultRotateArchives,+ redactSecrets: true,+ }+ event := newBeaconEvent("command.executed", "command", "info", "claude_code", time.Date(2026, 8, 21, 18, 0, 7, 0, time.UTC))+ event.Message = "Shell command executed"+ event.Session = &sessionInfo{ID: "s1", WorkingDirectory: "/repo"}+ event.Command = &commandInfo{Command: "echo hi"}+ event.GenAI = &beaconevent.GenAIInfo{Tool: &beaconevent.GenAIToolInfo{Call: &beaconevent.GenAIToolCallInfo{ID: "toolu_1"}}}++ if err := writer.append(event); err != nil {+ t.Fatalf("append returned error: %v", err)+ }+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("read log: %v", err)+ }+ var written beaconEvent+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(data))), &written); err != nil {+ t.Fatalf("unmarshal event: %v", err)+ }+ // The hook path writes the same call at a different second with a different+ // message, and derives its ID from the same four parts.+ hookLine := `{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"command.executed"},` ++ `"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},` ++ `"command":{"command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},` ++ `"message":"Tool execution observed"}`+ if want := asymptoteobserve.EventIDForLine([]byte(hookLine)); written.Event.ID != want {+ t.Fatalf("collector event.id = %s, but the hook's report of the same call derives %s",+ written.Event.ID, want)+ }+}+func TestConsumeLogsWritesBeaconJSONL(t *testing.T) {path := filepath.Join(t.TempDir(), "runtime.jsonl")exp, err := newExporter(&Config{diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.goindex 1522b3d5..edbc75cc 100644--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go@@ -1031,10 +1031,11 @@ func GenAIToolFromAttrs(attrs map[string]interface{}) *GenAIToolInfo {if definitions, ok := AnyAttr(attrs, "gen_ai.tool.definitions"); ok {tool.Definitions = definitions}+ callID := ToolCallID(attrs)if args, ok := AnyAttr(attrs, "gen_ai.tool.call.arguments", "beacon.gen_ai.tool.call.arguments", "function_args", "arguments"); ok {- tool.Call = &GenAIToolCallInfo{Arguments: args, ID: FirstString(attrs, "gen_ai.tool.call.id", "beacon.gen_ai.tool.call.id")}- } else if id := FirstString(attrs, "gen_ai.tool.call.id", "beacon.gen_ai.tool.call.id"); id != "" {- tool.Call = &GenAIToolCallInfo{ID: id}+ tool.Call = &GenAIToolCallInfo{Arguments: args, ID: callID}+ } else if callID != "" {+ tool.Call = &GenAIToolCallInfo{ID: callID}}if result, ok := AnyAttr(attrs, "gen_ai.tool.call.result", "beacon.gen_ai.tool.call.result"); ok {if tool.Call == nil {@@ -1689,6 +1690,18 @@ func HasToolCall(attrs map[string]interface{}) bool {return IsMeaningfulValue(attrs["gen_ai.tool.call.arguments"])}+// ToolCallID reads the runtime's own identifier for one tool invocation.+//+// Claude Code writes it as tool_use_id and Codex as call_id; neither name was+// on the promotion list, so the value reached the log only inside raw and+// nothing linked a tool call to its result. The alias list is shared with the+// hook path so both capture paths promote the same value to the same field --+// which is what lets duplicate suppression recognise the two reports of one+// action as one action.+func ToolCallID(attrs map[string]interface{}) string {+ return FirstString(attrs, asymptoteobserve.ToolCallIDKeys...)+}+func IsMeaningfulValue(value interface{}) bool {switch typed := value.(type) {case nil:diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.goindex ec998d2f..df6b108b 100644--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go@@ -765,6 +765,17 @@ func TestCapturedClaudeCodeLogNormalization(t *testing.T) {t.Fatalf("raw attributes changed: %#v", bash.Raw)}+ // Claude Code names every tool call with a tool_use_id and puts the same one+ // on the decision and the result. Promoting it is what links an approval to+ // the execution it approved, and this event to the hook's report of the same+ // command; until it was promoted the value reached the log only inside raw.+ if got := toolCallIDOfEvent(decision); got != "toolu_fixture_bash" {+ t.Fatalf("decision call ID = %q, want the tool_use_id Claude Code assigned", got)+ }+ if got := toolCallIDOfEvent(bash); got != "toolu_fixture_bash" {+ t.Fatalf("bash call ID = %q, want the tool_use_id Claude Code assigned", got)+ }+for _, tc := range []struct {name stringaction string@@ -783,6 +794,38 @@ func TestCapturedClaudeCodeLogNormalization(t *testing.T) {if event.Tool == nil || event.Tool.Path != event.File.Path {t.Fatalf("%s tool = %#v, want mirrored path", tc.name, event.Tool)}+ if toolCallIDOfEvent(event) == "" {+ t.Fatalf("%s has no call ID, so nothing links it to the hook's report of the same edit", tc.name)+ }+ }+ if toolCallIDOfEvent(byName["write_result"]) == toolCallIDOfEvent(byName["read_result"]) {+ t.Fatal("the write and the read are separate calls and must not share a call ID")+ }+}++func toolCallIDOfEvent(event Event) string {+ if event.GenAI == nil || event.GenAI.Tool == nil || event.GenAI.Tool.Call == nil {+ return ""+ }+ return event.GenAI.Tool.Call.ID+}++// Codex names its calls call_id rather than tool_use_id. Both are read from one+// shared alias list, so a runtime cannot be supported on one capture path and+// invisible on the other.+func TestCapturedCodexLogPromotesItsOwnCallID(t *testing.T) {+ _, events := capturedLogEvents(t, "codex-0.142.4.json")+ found := false+ for _, event := range events {+ if id := toolCallIDOfEvent(event); id != "" {+ if id != "call_fixture" {+ t.Fatalf("call ID = %q, want the call_id Codex assigned", id)+ }+ found = true+ }+ }+ if !found {+ t.Fatal("no event promoted Codex's call_id")}}diff --git a/collector-builder/exporter/beaconjsonexporter/writer.go b/collector-builder/exporter/beaconjsonexporter/writer.goindex 48afc45d..830ddcc5 100644--- a/collector-builder/exporter/beaconjsonexporter/writer.go+++ b/collector-builder/exporter/beaconjsonexporter/writer.go@@ -38,6 +38,21 @@ func (w jsonlWriter) append(event beaconEvent) error {if len(data) > w.maxEventBytes {return fmt.Errorf("event exceeds maximum size after truncation: %d bytes", len(data))}+ // Stamped last, over the bytes that are actually about to be written, so a+ // size fallback above cannot leave the ID describing an event that no longer+ // exists. Marshalling twice is the cost of an identity derived from the+ // event rather than asserted about it. An event already at the size limit+ // keeps its bytes and goes without one.+ if event.Event.ID == "" {+ event.Event.ID = asymptoteobserve.EventIDForLine(data)+ stamped, err := json.Marshal(event)+ if err != nil {+ return err+ }+ if len(stamped) <= w.maxEventBytes {+ data = stamped+ }+ }if err := os.MkdirAll(filepath.Dir(w.path), 0755); err != nil {return err}diff --git a/docs/telemetry-schema/event-schema.mdx b/docs/telemetry-schema/event-schema.mdxindex 007e72a3..1e4a9460 100644--- a/docs/telemetry-schema/event-schema.mdx+++ b/docs/telemetry-schema/event-schema.mdx@@ -37,6 +37,10 @@ The schema gives every event a consistent backbone:| `endpoint` | Host and operating system context || `harness` | Runtime that produced the signal |+`event.id` is written alongside these: a deterministic UUID identifying the event, described under+[event identity](/telemetry-schema/normalization#event-identity). It is not required, so events+written by earlier agent versions remain valid.+## How it extends OpenTelemetryBeacon accepts OpenTelemetry attributes, including the GenAI semantic conventions, and projects them into fields that are easier to query across agent runtimes. OpenTelemetry context is preserved under `gen_ai` where available, while commonly investigated values are also normalized into Beacon fields such as `model`, `tool.name`, `prompt.text`, `command.command`, `file.path`, and `gen_ai.usage`.diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdxindex e08b1246..5162b139 100644--- a/docs/telemetry-schema/normalization.mdx+++ b/docs/telemetry-schema/normalization.mdx@@ -14,7 +14,8 @@ Beacon normalizes [OTLP](/concepts/core-concepts#otlp) attributes and [hook](/co| `gen_ai.request.model`, `gen_ai.response.model`, `model`, `ai.model` | `model` || `gen_ai.tool.name`, `tool.name`, `beacon.tool.name`, `function_name`, `tool_name` | `tool.name` and `gen_ai.tool.name` || `gen_ai.tool.call.arguments`, `function_args`, `arguments` | `tool.command` when command-like, plus `gen_ai.tool.call.arguments` |-| `gen_ai.tool.call.id`, `gen_ai.tool.call.result` | `gen_ai.tool.call.id`, `gen_ai.tool.call.result` |+| `gen_ai.tool.call.id`, `tool_use_id`, `call_id`, `tool_call_id`, `callId` | `gen_ai.tool.call.id` |+| `gen_ai.tool.call.result` | `gen_ai.tool.call.result` || `mcp.method.name`, `mcp.protocol.version`, `mcp.resource.uri`, `mcp.session.id` | `mcp.method.name`, `mcp.protocol.version`, `mcp.resource.uri`, `mcp.session.id` || `mcp.tool`, `beacon.mcp.tool`, `mcp.tool.name` | `mcp.tool` || `mcp.server`, `beacon.mcp.server`, `mcp.server.name` | `mcp.server` |@@ -91,6 +92,23 @@ Canonical `gen_ai.usage` comes from the run-end payload only, including cachereads and runtime-reported cost. Recording usage at a per-model-call boundary aswell would double-count every task's tokens in usage rollups.+## Event identity++Every event carries two identity fields, and both are filled on the hook path and the OTLP path alike.++`gen_ai.tool.call.id` is the runtime's own name for one tool invocation, read from whichever+attribute that runtime uses: Claude Code writes `tool_use_id`, Codex and OpenCode write `call_id`,+Cline writes `callId`. It is what links a tool call to its result, an approval to the execution it+approved, and a hook event to the OTLP event describing the same action. Where two events share+one, they describe one call, and the writer records that call once rather than twice.++`event.id` is Beacon's own identity for the event: a deterministic UUID, so the same event is+named the same way in any process and any release. Where the runtime named the action itself, the+UUID is derived from the session, action, target and call ID, and nothing else — so the hook's+report and the collector's report of one action carry one `event.id` even though they are written+seconds apart with different fields. Otherwise it is derived from the event's own content, which+makes re-reading a log produce the IDs it already had.+## OpenTelemetry GenAI fieldsBeacon preserves OpenTelemetry GenAI semantic convention fields under the nested `gen_ai` object and also projects selected fields into Beacon's common investigation fields. This keeps the raw GenAI context available without forcing downstream rules to parse runtime-specific attribute names.diff --git a/pkg/asymptoteobserve/dedupe.go b/pkg/asymptoteobserve/dedupe.goindex 7a1e5a72..b0734be7 100644--- a/pkg/asymptoteobserve/dedupe.go+++ b/pkg/asymptoteobserve/dedupe.go@@ -42,13 +42,29 @@ func IsDuplicateEndpointEvent(path string, candidateLine []byte, window time.Durif !ok || existing.key != candidate.key {continue}- // Same-harness events are normally preserved because two adjacent calls- // can legitimately target the same file or command. A stable tool call- // ID makes an exact duplicate safe to collapse.+ // An equal, non-empty tool call ID is the runtime's own statement that+ // these two lines describe one call, and it settles the question on its+ // own: no window, and no interest in which capture path reported it.+ //+ // The window is deliberately not applied here. A hook writes when the+ // tool runs and the collector writes when its batch flushes, so the two+ // reports of one call routinely land five seconds apart -- past the+ // two-second window that is the only thing that ever collapsed them.+ if existing.callID != "" && existing.callID == candidate.callID {+ return true+ }+ // Without matching IDs, only the timing heuristic is left, and only+ // across capture paths: two adjacent calls from one path can+ // legitimately touch the same file or command, so same-harness+ // lookalikes are preserved.+ //+ // Unequal IDs are not evidence of two calls unless one path assigned+ // both. Beacon's paths do not share an ID space -- OpenCode's own call+ // ID and the span ID the collector sees for the same call are simply+ // different names -- so across harnesses the IDs are ignored rather+ // than trusted to disagree.if existing.harness == candidate.harness {- if existing.callID == "" || candidate.callID == "" || existing.callID != candidate.callID {- continue- }+ continue}diff := candidate.ts.Sub(existing.ts)if diff < 0 {diff --git a/pkg/asymptoteobserve/dedupe_test.go b/pkg/asymptoteobserve/dedupe_test.goindex 0e45c543..251f14b0 100644--- a/pkg/asymptoteobserve/dedupe_test.go+++ b/pkg/asymptoteobserve/dedupe_test.go@@ -110,3 +110,28 @@ func TestIsDuplicateEndpointEventMatchesToolCompletion(t *testing.T) {}t.Fatal("expected duplicate tool completion within custom window")}++// The regression this exists to prevent. Duplicate suppression was fixed in July+// to collapse the hook and OTLP reports of one action, keyed on the two paths+// reporting different harness names. Harness normalization then landed in+// August -- correct on its own terms, and a real fix -- after which both paths+// reported claude_code, every pair took the same-harness branch, and that branch+// needed a call ID that nothing ever populated. Suppression was inert from+// that day on, and no test could have caught it because each change was right by+// itself.+func TestIsDuplicateEndpointEventCollapsesNormalizedHarnessOnCallID(t *testing.T) {+ path := filepath.Join(t.TempDir(), "runtime.jsonl")+ hook := `{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"command.executed"},"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},"command":{"command":"echo hi"},"tool":{"name":"Bash","command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},"message":"Shell command executed"}`+ otlp := []byte(`{"timestamp":"2026-08-21T18:00:07Z","event":{"action":"command.executed"},"harness":{"name":"claude_code"},"session":{"id":"s1","working_directory":"/repo"},"command":{"command":"echo hi"},"tool":{"name":"Bash","command":"echo hi"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}},"message":"Shell command executed"}`)+ if err := os.WriteFile(path, []byte(hook+"\n"), 0644); err != nil {+ t.Fatalf("write existing event: %v", err)+ }++ // Six seconds apart, which is the ordinary case rather than an edge one: the+ // hook writes when the tool runs and the collector writes when its batch+ // flushes. The two-second window never stood a chance, which is why an equal+ // call ID does not consult it.+ if !IsDuplicateEndpointEvent(path, otlp, EndpointDuplicateWindow) {+ t.Fatal("the hook and OTLP reports of one Bash call should collapse on their shared call ID")+ }+}diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.goindex a3934819..16975ba2 100644--- a/pkg/asymptoteobserve/event.go+++ b/pkg/asymptoteobserve/event.go@@ -48,7 +48,11 @@ const (AttributeRunEphemeral = "beacon.run.ephemeral")+// EventInfo names what happened. ID is the event's stable identity: see+// EventIDForLine for how it is derived and what equality between two of them+// means.type EventInfo struct {+ ID string `json:"id,omitempty"`Kind string `json:"kind"`Action string `json:"action"`Category string `json:"category,omitempty"`diff --git a/pkg/asymptoteobserve/identity.go b/pkg/asymptoteobserve/identity.gonew file mode 100644index 00000000..f67e246b--- /dev/null+++ b/pkg/asymptoteobserve/identity.go@@ -0,0 +1,115 @@+package asymptoteobserve++import (+ "crypto/sha1"+ "encoding/hex"+ "encoding/json"+ "fmt"+ "strings"+)++// ToolCallIDKeys are the names a runtime uses for the identifier it assigns to+// one tool invocation, in the order Beacon prefers them.+//+// Every supported runtime already emits this value -- Claude Code as+// tool_use_id, Codex and OpenCode as call_id, Cline as callId -- and until this+// list existed Beacon dropped all of them into raw, because the promotion list+// held only the canonical OTel name that no runtime actually writes. It is the+// one field that links a tool call to its result, an approval to the execution+// it approved, and a hook event to the OTLP event for the same action, so it is+// promoted to gen_ai.tool.call.id on every capture path from this single list.+//+// Order matters: the canonical names come first so an explicitly mapped value+// always beats a runtime-native one, and the runtime-native names follow in no+// significant order because no payload carries two of them.+var ToolCallIDKeys = []string{+ "gen_ai.tool.call.id",+ "beacon.gen_ai.tool.call.id",+ "tool_use_id",+ "toolUseId",+ "tool_call_id",+ "toolCallId",+ "call_id",+ "callId",+ "callID",+}++// eventIDNamespace is the fixed UUID namespace every Beacon event ID is derived+// under, so the same event derives the same UUID in any process and any+// release. It is an arbitrary constant, not a secret, and must never change:+// changing it renames every event ID Beacon has ever written.+var eventIDNamespace = [16]byte{+ 0x1f, 0x4b, 0x2c, 0x8e, 0x6d, 0x3a, 0x5a, 0x7c,+ 0x9b, 0x61, 0x3f, 0x0d, 0x5e, 0x8c, 0x2a, 0x14,+}++// EventIDForLine derives the deterministic identity of one serialized endpoint+// event whose event.id has not been set yet.+//+// Deterministic means the same event derives the same ID every time, in either+// capture path and in any later run. That is what makes an event addressable:+// re-reading a log, merging two reports of one action, or uploading a trace+// twice can all name the same event rather than guessing at it by position.+//+// Two identities are possible and the event decides which it gets:+//+// - When the runtime named the action itself -- a tool call ID plus a+// resolvable target -- the ID is derived from session, action, target and+// call ID alone. Timestamps and content are deliberately excluded, so the+// hook report and the OTLP report of one real action derive one ID even+// though they are written seconds apart with different fields.+// - Otherwise the ID is a digest of the event itself, which is unique to the+// extent the event is. Two events that agree on every recorded byte,+// including the timestamp, are indistinguishable in the log and get one ID;+// a per-session sequence number would separate them, and when events carry+// one this derivation picks it up for free.+//+// The writer does not suppress duplicates on this field. Equality under the+// content digest means "nothing recorded tells these apart", which is a weaker+// claim than "this is the same action" and not one to drop an event over. The+// call ID carries that claim, and duplicate suppression keys on it directly.+//+// line must be the event's JSON with event.id absent; passing a line that+// already carries one derives an ID for a different event than the caller+// meant, so callers marshal with the field empty and fill it afterwards.+func EventIDForLine(line []byte) string {+ var event map[string]interface{}+ if err := json.Unmarshal(line, &event); err != nil {+ // An event Beacon cannot parse is still an event Beacon is about to+ // write, so it gets a content identity rather than no identity.+ return eventUUID("content", string(line))+ }+ action := nestedString(event, "event", "action")+ callID := nestedString(event, "gen_ai", "tool", "call", "id")+ target := dedupeTarget(action, event)+ if callID != "" && target != "" {+ return eventUUID("call", strings.Join([]string{+ nestedString(event, "session", "id"),+ strings.ToLower(strings.TrimSpace(action)),+ target,+ callID,+ }, "\x00"))+ }+ return eventUUID("content", string(line))+}++// eventUUID renders a name under eventIDNamespace as an RFC 4122 version 5+// UUID. The kind prefix keeps the two identity modes in separate value spaces,+// so a content digest can never collide with a call identity.+//+// SHA-1 is what version 5 specifies. It is used here as a namespaced identifier+// function over data Beacon just wrote, never as a security boundary.+func eventUUID(kind, name string) string {+ buf := make([]byte, 0, len(eventIDNamespace)+len(kind)+len(name))+ buf = append(buf, eventIDNamespace[:]...)+ buf = append(buf, kind...)+ buf = append(buf, name...)+ sum := sha1.Sum(buf)+ var id [16]byte+ copy(id[:], sum[:16])+ id[6] = (id[6] & 0x0f) | 0x50 // version 5+ id[8] = (id[8] & 0x3f) | 0x80 // RFC 4122 variant+ out := make([]byte, 32)+ hex.Encode(out, id[:])+ return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])+}diff --git a/pkg/asymptoteobserve/identity_test.go b/pkg/asymptoteobserve/identity_test.gonew file mode 100644index 00000000..d0d5376a--- /dev/null+++ b/pkg/asymptoteobserve/identity_test.go@@ -0,0 +1,86 @@+package asymptoteobserve++import (+ "regexp"+ "testing"+)++// callLine is one endpoint event the runtime named itself, with the parts the+// call identity is derived from left as parameters and everything else varying+// freely, so a test can say exactly which difference it is testing.+func callLine(harness, timestamp, callID, command string) []byte {+ return []byte(`{"timestamp":"` + timestamp + `","event":{"action":"command.executed"},` ++ `"harness":{"name":"` + harness + `"},"session":{"id":"s1","working_directory":"/repo"},` ++ `"command":{"command":"` + command + `"},"gen_ai":{"tool":{"call":{"id":"` + callID + `"}}},` ++ `"message":"Shell command executed"}`)+}++var uuidV5Pattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)++func TestEventIDForLineIsAVersion5UUID(t *testing.T) {+ for name, line := range map[string][]byte{+ "call identity": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"),+ "content identity": []byte(`{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"session.activity"},"session":{"id":"s1"}}`),+ "unparseable": []byte(`not json at all`),+ } {+ if id := EventIDForLine(line); !uuidV5Pattern.MatchString(id) {+ t.Errorf("%s: EventIDForLine = %q, want an RFC 4122 version 5 UUID", name, id)+ }+ }+}++// The point of the call identity: the hook writes when the tool runs and the+// collector writes when its batch flushes, so the two reports of one call agree+// on almost nothing except the call ID. They must still name one event.+func TestEventIDForLineIgnoresWhatTheTwoCapturePathsDisagreeOn(t *testing.T) {+ hook := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))+ otlp := EventIDForLine(callLine("otel", "2026-08-21T18:00:07Z", "toolu_1", "echo hi"))+ if hook != otlp {+ t.Fatalf("one call reported twice derived two IDs: %s and %s", hook, otlp)+ }+}++func TestEventIDForLineSeparatesDistinctCalls(t *testing.T) {+ first := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))+ for name, other := range map[string][]byte{+ "another call": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_2", "echo hi"),+ "another target": callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "rm -rf /"),+ } {+ if id := EventIDForLine(other); id == first {+ t.Errorf("%s derived the same ID as the original call: %s", name, id)+ }+ }+}++// Without a call ID there is nothing to identify the event by but the event, so+// the ID has to move when any of it does -- and stay put when none of it does,+// which is what makes re-reading a log derive the IDs it already had.+func TestEventIDForLineFallsBackToTheEventItself(t *testing.T) {+ line := []byte(`{"timestamp":"2026-08-21T18:00:01Z","event":{"action":"session.activity"},"session":{"id":"s1"},"message":"Hook executed"}`)+ later := []byte(`{"timestamp":"2026-08-21T18:00:02Z","event":{"action":"session.activity"},"session":{"id":"s1"},"message":"Hook executed"}`)+ if EventIDForLine(line) != EventIDForLine(line) {+ t.Fatal("the same line derived two IDs")+ }+ if EventIDForLine(line) == EventIDForLine(later) {+ t.Fatal("events a second apart derived one ID")+ }+}++// A content digest and a call identity must not be able to collide, because+// they mean different things: see EventIDForLine.+func TestEventIDForLineKeepsTheTwoIdentityModesApart(t *testing.T) {+ if eventUUID("call", "x") == eventUUID("content", "x") {+ t.Fatal("the call and content identity spaces overlap")+ }+}++// The namespace and the derivation are a written contract: an event's ID has to+// survive a release, or nothing downstream can address it across two of them.+func TestEventIDForLineIsStableAcrossReleases(t *testing.T) {+ const want = "244a6772-0cbe-5230-9f79-37cb62ce25ee"+ got := EventIDForLine(callLine("claude_code", "2026-08-21T18:00:01Z", "toolu_1", "echo hi"))+ if got != want {+ t.Fatalf("EventIDForLine = %s, want %s -- if this is deliberate, every ID Beacon has "++ "ever written just changed meaning", got, want)+ }+}diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.mdindex a424dd7e..df7157b7 100644--- a/spec/threat-rules/FIELDS.md+++ b/spec/threat-rules/FIELDS.md@@ -30,6 +30,7 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.| `e.error.type` | string || `e.event.action` | string || `e.event.category` | string |+| `e.event.id` | string || `e.event.kind` | string || `e.field_truncated` | bool || `e.file.diff_bytes` | int |