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
Merge main into the event-ordering branch
Claude817553ddf6a2
diff --cc beacon-sandbox/check/check_test.goindex 26baa3e9,f8578865..812aa5c3--- a/beacon-sandbox/check/check_test.go+++ b/beacon-sandbox/check/check_test.go@@@ -275,12 -275,17 +275,17 @@@ func TestSameHarnessRepeatsSurviveWitho}}- // 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)+ line = strings.Replace(line, "18:00:01.000000000Z", ts, 1)return strings.Replace(line, `"tool":{"name":"Bash"}`,`"tool":{"name":"Bash"},"gen_ai":{"tool":{"call":{"id":"`+id+`"}}}`, 1)}@@@ -301,8 -306,70 +306,70 @@@}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())+ }+ }++ // The hook and the collector describe one call in different words. The hook writes+ // "Shell command executed"; the collector writes "Tool execution observed". The writer's key does+ // not include the message, so it collapses them -- and the verifier has to agree, or it counts two+ // events where the log will only ever hold one. It did not agree while it kept its own copy of the+ // rule and keyed that copy on the message. Reported by Cursor Bugbot.+ func TestOneCallDescribedInDifferentWordsCollapses(t *testing.T) {+ base := goodLog()+ withIDAndMessage := func(line, ts, message string) string {- line = strings.Replace(line, "18:00:01Z", ts, 1)++ line = strings.Replace(line, "18:00:01.000000000Z", ts, 1)+ line = strings.Replace(line, `"message":"claude_code.tool_result"`, `"message":"`+message+`"`, 1)+ return strings.Replace(line, `"tool":{"name":"Bash"}`,+ `"tool":{"name":"Bash"},"gen_ai":{"tool":{"call":{"id":"toolu_1"}}}`, 1)+ }- hook := withIDAndMessage(base[1], "18:00:01Z", "Shell command executed")- collector := withIDAndMessage(base[1], "18:00:07Z", "Tool execution observed")++ hook := withIDAndMessage(base[1], "18:00:01.000000000Z", "Shell command executed")++ collector := withIDAndMessage(base[1], "18:00:07.000000000Z", "Tool execution observed")++ sc := demoScenario()+ sc.Expect = []scenario.Expect{{+ Action: "command.executed", Fields: []string{"command.command"}, MinCount: 2,+ Why: "one call cannot be counted twice just because the two paths word it differently",+ }}++ v := run(t, []string{base[0], hook, collector}, sc, presentSentinel(), nil)+ if v.Outcome != Fail {+ t.Errorf("the two reports of one call share a call ID and must collapse to one, so "++ "min_count 2 has to fail:\n%s", v.Report())+ }+ }++ // One MultiEdit touching two files is two edits under one call ID, and the verifier has to keep+ // both: the writer's key includes the target, so different paths are different events however+ // equal the call ID is.+ //+ // This is the guard on the previous test. Making an equal call ID sufficient on its own is the+ // obvious way to fix a message-driven under-collapse, and it silently trades it for an+ // over-collapse -- which is worse, because it fails a min_count the writer would have satisfied.+ // Asking the writer instead of reordering a copy of its rules is what keeps both true at once.+ func TestMultiEditToTwoFilesUnderOneCallIDKeepsBoth(t *testing.T) {+ base := goodLog()+ edit := func(path string) string {- return `{"timestamp":"2026-08-02T18:00:01Z","vendor":"beacon","product":"endpoint-agent",` +++ return `{"timestamp":"2026-08-02T18:00:01.000000000Z","vendor":"beacon","product":"endpoint-agent",` ++ `"schema_version":"1.0","event":{"kind":"agent_runtime","action":"file.modified",` ++ `"category":"file"},"severity":"info","endpoint":{"os":"linux","hostname":"sandbox"},` ++ `"harness":{"name":"claude_code"},"session":{"id":"s1"},"file":{"path":"` + path ++ `","operation":"modify"},"gen_ai":{"tool":{"call":{"id":"toolu_multi"}}},` ++ `"message":"File edit observed"}`+ }++ sc := demoScenario()+ sc.Expect = []scenario.Expect{{+ Action: "file.modified", Fields: []string{"file.path"}, MinCount: 2,+ Why: "one MultiEdit editing two files is two edits, not one",+ }}++ v := run(t, []string{base[0], edit("/repo/a.go"), edit("/repo/b.go")}, sc, presentSentinel(), nil)+ if v.Outcome != Pass {+ t.Errorf("two files edited under one call ID are two events and the writer keeps both, "++ "so min_count 2 must pass:\n%s", v.Report())}}diff --cc cli/beacon-hooks/internal/logging/endpoint_event_test.goindex fc0a3477,9cd30574..0fc1f0cc--- a/cli/beacon-hooks/internal/logging/endpoint_event_test.go+++ b/cli/beacon-hooks/internal/logging/endpoint_event_test.go@@@ -232,91 -230,140 +232,231 @@@ func TestEndpointEventSurfacesWriteFail}}++// --- ordering: timestamp precision and per-invocation sequence ---+++func TestEndpointEventStampsSubSecondTimestamp(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("pre-tool", "cursor")+ if err := logger.EndpointEvent("tool.started", "tool", "info", "observed", nil); err != nil {+ t.Fatalf("EndpointEvent returned error: %v", err)+ }++ event := readEndpointEvents(t, logPath)[0]+ timestamp, _ := event["timestamp"].(string)+ if _, err := asymptoteobserve.ParseTimestamp(timestamp); err != nil {+ t.Fatalf("timestamp %q does not parse: %v", timestamp, err)+ }+ if !strings.Contains(timestamp, ".") {+ t.Fatalf("timestamp = %q, want sub-second precision", timestamp)+ }+}++func TestEndpointEventNumbersEventsWithinOneHookInvocation(t *testing.T) {+ // A post-tool hook records the tool result, the file edit and the command in one+ // process. On a coarse clock those can land on the same timestamp, and the sequence+ // is what still says which came first.+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("post-tool", "cursor")+ for _, action := range []string{"tool.completed", "file.edited", "command.executed"} {+ if err := logger.EndpointEvent(action, "tool", "info", action, nil); err != nil {+ t.Fatalf("EndpointEvent(%s) returned error: %v", action, err)+ }+ }++ var previous float64+ for i, event := range readEndpointEvents(t, logPath) {+ sequence, ok := event["sequence"].(float64)+ if !ok {+ t.Fatalf("event %d has no sequence: %v", i, event)+ }+ if sequence < 1 {+ t.Fatalf("event %d sequence = %v, want at least 1 (0 means unsequenced)", i, sequence)+ }+ if i > 0 && sequence <= previous {+ t.Fatalf("event %d sequence = %v, want greater than %v", i, sequence, previous)+ }+ previous = sequence+ }+}++func TestMinimalEndpointEventKeepsOrderingFields(t *testing.T) {+ // The oversized-event fallback strips the event down to metadata. Dropping the+ // ordering keys there would leave exactly the events most worth ordering unorderable.+ minimal := minimalEndpointEvent(map[string]interface{}{+ "timestamp": "2026-08-21T10:00:00.000000000Z",+ "sequence": uint64(42),+ "message": "big",+ })+ if minimal["timestamp"] != "2026-08-21T10:00:00.000000000Z" {+ t.Fatalf("minimal timestamp = %v", minimal["timestamp"])+ }+ if minimal["sequence"] != uint64(42) {+ t.Fatalf("minimal sequence = %v, want 42", minimal["sequence"])+ }+}++// readEndpointEvents decodes every event written to the runtime log.+func readEndpointEvents(t *testing.T, path string) []map[string]interface{} {+ t.Helper()+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("read %s: %v", path, err)+ }+ var events []map[string]interface{}+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {+ if line == "" {+ continue+ }+ var event map[string]interface{}+ if err := json.Unmarshal([]byte(line), &event); err != nil {+ t.Fatalf("decode %q: %v", line, err)+ }+ events = append(events, event)+ }+ if len(events) == 0 {+ t.Fatalf("no events written to %s", path)+ }+ return events+}+++ // --- provenance: harness.collection_method and event.fidelity ---++ func decodeSingleEndpointEvent(t *testing.T, path string) map[string]interface{} {+ t.Helper()+ data, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("read endpoint log: %v", err)+ }+ lines := strings.Split(strings.TrimSpace(string(data)), "\n")+ if len(lines) != 1 {+ t.Fatalf("endpoint log has %d lines, want 1", len(lines))+ }+ var event map[string]interface{}+ if err := json.Unmarshal([]byte(lines[0]), &event); err != nil {+ t.Fatalf("unmarshal endpoint event: %v", err)+ }+ return event+ }++ func nestedString(t *testing.T, event map[string]interface{}, block, key string) (string, bool) {+ t.Helper()+ inner, ok := event[block].(map[string]interface{})+ if !ok {+ t.Fatalf("event has no %q block: %#v", block, event)+ }+ value, present := inner[key]+ if !present {+ return "", false+ }+ text, ok := value.(string)+ if !ok {+ t.Fatalf("%s.%s = %#v, want a string", block, key, value)+ }+ return text, true+ }++ func TestEndpointEventRecordsHookCollectionMethod(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("pre-tool", "cursor")+ if err := logger.EndpointEvent("file.modified", "file", "info", "File edit observed", nil); err != nil {+ t.Fatalf("EndpointEvent returned error: %v", err)+ }++ event := decodeSingleEndpointEvent(t, logPath)+ if method, ok := nestedString(t, event, "harness", "collection_method"); !ok || method != "hook" {+ t.Fatalf("harness.collection_method = %q (present=%v), want hook", method, ok)+ }+ }++ // One plugin platform, because the plugin case is the one a future integration gets wrong: the+ // default is hook, so a plugin-shaped runtime that is not enumerated silently reports the wrong+ // method.+ func TestEndpointEventRecordsPluginCollectionMethod(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("cline-event", "cline")+ if err := logger.EndpointEvent("prompt.submitted", "prompt", "info", "Prompt observed", nil); err != nil {+ t.Fatalf("EndpointEvent returned error: %v", err)+ }++ event := decodeSingleEndpointEvent(t, logPath)+ if method, ok := nestedString(t, event, "harness", "collection_method"); !ok || method != "plugin" {+ t.Fatalf("harness.collection_method = %q (present=%v), want plugin", method, ok)+ }+ }++ // This path builds raw maps rather than the shared Event struct, so it gets no `omitempty` for+ // free. An empty string written into either field is worse than an absent one: a consumer would+ // have to treat "" as a third case.+ func TestEndpointEventOmitsProvenanceRatherThanWritingEmpty(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("pre-tool", "")+ if err := logger.EndpointEventWithFidelity("tool.invoked", "tool", "info", "no platform", "", nil); err != nil {+ t.Fatalf("EndpointEventWithFidelity returned error: %v", err)+ }++ event := decodeSingleEndpointEvent(t, logPath)+ if _, present := nestedString(t, event, "harness", "collection_method"); present {+ t.Fatal("harness.collection_method written for an empty platform, want the key omitted")+ }+ if _, present := nestedString(t, event, "event", "fidelity"); present {+ t.Fatal("event.fidelity written when unset, want the key omitted")+ }+ }++ // EndpointEvent is the ordinary path and means "the runtime named this action", so it must not+ // require every existing caller to opt in to being trusted.+ func TestEndpointEventDefaultsToObservedFidelity(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("post-tool", "claude")+ if err := logger.EndpointEvent("command.executed", "command", "info", "Command observed", nil); err != nil {+ t.Fatalf("EndpointEvent returned error: %v", err)+ }++ event := decodeSingleEndpointEvent(t, logPath)+ if fidelity, ok := nestedString(t, event, "event", "fidelity"); !ok || fidelity != "observed" {+ t.Fatalf("event.fidelity = %q (present=%v), want observed", fidelity, ok)+ }+ }++ func TestEndpointEventCarriesExplicitInferredFidelity(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)++ logger := NewLoggerForPlatform("pre-tool", "cursor")+ if err := logger.EndpointEventWithFidelity("approval.allowed", "approval", "info", "Pre-tool observed", "inferred", nil); err != nil {+ t.Fatalf("EndpointEventWithFidelity returned error: %v", err)+ }++ event := decodeSingleEndpointEvent(t, logPath)+ if fidelity, ok := nestedString(t, event, "event", "fidelity"); !ok || fidelity != "inferred" {+ t.Fatalf("event.fidelity = %q (present=%v), want inferred", fidelity, ok)+ }+ }++ // The size-limit fallback rewrites the event down to a key allowlist. Both provenance fields live+ // inside blocks that survive wholesale, but a future edit to that list could drop them -- and+ // losing the marker silently turns an inferred event into an unmarked one, which reads as trusted.+ func TestMinimalEndpointEventKeepsProvenance(t *testing.T) {+ minimal := minimalEndpointEvent(map[string]interface{}{+ "event": map[string]interface{}{"action": "approval.allowed", "fidelity": "inferred"},+ "harness": map[string]interface{}{"name": "cursor", "collection_method": "hook"},+ })+ if fidelity, ok := nestedString(t, minimal, "event", "fidelity"); !ok || fidelity != "inferred" {+ t.Fatalf("compacted event.fidelity = %q (present=%v), want inferred", fidelity, ok)+ }+ if method, ok := nestedString(t, minimal, "harness", "collection_method"); !ok || method != "hook" {+ t.Fatalf("compacted harness.collection_method = %q (present=%v), want hook", method, ok)+ }+ }diff --cc cli/beacon-hooks/internal/logging/logging.goindex 0ab43133,ebfb20d9..750d7359--- a/cli/beacon-hooks/internal/logging/logging.go+++ b/cli/beacon-hooks/internal/logging/logging.go@@@ -129,15 -137,34 +141,41 @@@ func (l *Logger) baseEndpointEvent(actiif uid := firstEnv("BEACON_CLOUD_USER_ID_HASH", "BEACON_CLOUD_USER_ID"); uid != "" {user["uid"] = uid}+ // Both blocks are assembled before the event literal so the provenance keys can be omitted+ // rather than written empty. This path builds raw maps instead of the shared Event struct, so+ // it does not get `omitempty` for free, and an empty "collection_method" on every event would+ // be both noise in the log and a value a consumer could mistake for a real one.+ eventBlock := map[string]interface{}{+ "kind": "agent_runtime",+ "action": action,+ "category": category,+ }+ if fidelity != "" {+ eventBlock["fidelity"] = fidelity+ }+ harnessBlock := map[string]interface{}{+ // Normalized rather than written raw. The OTLP path already reports the canonical name+ // for the same session, so emitting the raw --platform value here recorded one session+ // under two names -- splitting it for any query or SIEM detection that groups by+ // harness.name. The flag itself is unchanged, so existing installs are fixed without+ // having their settings.json rewritten.+ "name": asymptoteobserve.NormalizeHarnessName(l.platform),+ }+ // Derived from --platform rather than from the normalized name above, because the flag is what+ // records which integration shape is installed. The two differ for VS Code, whose hook and+ // OTLP telemetry share a harness name.+ if method := asymptoteobserve.CollectionMethodForPlatform(l.platform); method != "" {+ harnessBlock["collection_method"] = method+ }event := map[string]interface{}{- "timestamp": time.Now().UTC().Format(time.RFC3339),+ "timestamp": asymptoteobserve.FormatTimestamp(time.Now()),+ // Emission order within this hook invocation. One invocation can emit several+ // events (a post-tool hook records the tool result, the file edit and the command+ // in turn), and on a coarse clock those can land on the same nanosecond -- the+ // counter is what still separates them. It restarts at 1 in every hook process,+ // which is why it is a tiebreaker under the timestamp rather than an ordering key+ // of its own; see asymptoteobserve.Event.Sequence.+ "sequence": endpointSequence.Next(),"vendor": "beacon","product": "endpoint-agent","schema_version": "1.0",diff --cc docs/telemetry-schema/event-schema.mdxindex 35b5df47,23cb2e62..d5fa29bd--- a/docs/telemetry-schema/event-schema.mdx+++ b/docs/telemetry-schema/event-schema.mdx@@@ -36,30 -84,12 +84,35 @@@ call was seen. Anything counting real o| `severity` | `info`, `low`, `medium`, `high`, or `critical` || `endpoint` | Host and operating system context || `harness` | Runtime that produced the signal |+ | `harness.collection_method` | Optional. `hook`, `plugin`, `otlp`, or `poll` — see [Provenance](#provenance-how-beacon-knows-what-it-wrote) |++ `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.+## Event ordering++Two events can only be reasoned about together if you can tell which came first, so the+schema carries two ordering fields.++| Field | Meaning |+|-------|---------|+| `timestamp` | The cross-source ordering key. Both capture paths stamp it from the same clock at nanosecond precision and at a fixed width, so two UTC timestamps compare the same way as strings and as instants. |+| `sequence` | Optional. The emitting writer's monotonic emission counter for the event, starting at 1; absent means unsequenced. It breaks ties between events that share a timestamp. |++`sequence` numbers one writer's stream, not the log as a whole. The hook adapter runs as a+fresh short-lived process per hook and the collector exporter runs as one long-lived export+loop, so neither can see the other's counter, and a hook event numbered 1 may well have+happened after an exporter event numbered 900. Order by `timestamp` first and use+`sequence` only to separate events that tie on it — most often the datapoints of a single+metric export, which all carry that export's collection instant.++Do not order events by their position in the log. Append order is not emission order: a+hook writes synchronously the moment it intercepts a tool call, while the exporter writes+on its export interval, so an event that happened earlier routinely lands in the file+later. `beacon scan` and the dashboard's detection view sort the log by `(timestamp,+sequence)` before evaluating correlation rules for exactly this reason.+## 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`.