Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Merge main into the event-ordering branch

Claude817553ddf6a2
diff --cc beacon-sandbox/check/check_test.go
index 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.go
index 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.go
index 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(acti
if 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.mdx
index 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 OpenTelemetry
Beacon 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`.