Skip to content

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

fix(traces): center filtered --around-event on the original event number (#820)

Rudy Mizrahi Celeklid7e26aab1e5a
diff --git a/agent-skills/skills/beacon-memory-distill/SKILL.md b/agent-skills/skills/beacon-memory-distill/SKILL.md
index 4c28ca64..ebcc17d6 100644
--- a/agent-skills/skills/beacon-memory-distill/SKILL.md
+++ b/agent-skills/skills/beacon-memory-distill/SKILL.md
@@ -153,9 +153,8 @@ How to read what comes back:
failed command followed by a different command that succeeded.
- A `user_message` with `content.included` false, or only a hash, means Beacon kept
metadata only. You cannot draft from a hash; say the trace was unreadable.
-- `--around-event` centres on the unfiltered event number. Combined with `--event-type`
- it can return no events at all, so read a small unfiltered window around the number
- and skip the `token_usage` and `session` rows yourself.
+- `--around-event` takes the original event number, also with `--event-type`, and
+ `--before` and `--after` count matching events.
Work out, from the events themselves:
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 39054ade..73846925 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -485,7 +485,7 @@ func init() {
endpointTracesListCmd.Flags().StringVar(&endpointTraceOpts.state, "state", "", "Filter by sharing state: local_only, shared (including stale) or stale")
endpointTracesListCmd.Flags().StringVar(&endpointTraceOpts.visibility, "visibility", "", "Filter by sharing visibility")
endpointTracesSearchCmd.Flags().StringVar(&endpointTraceOpts.resultLevel, "result-level", "trace", "Return trace or event results")
- endpointTracesShowCmd.Flags().IntVar(&endpointTraceOpts.offset, "offset", 1, "Start at this event number")
+ endpointTracesShowCmd.Flags().IntVar(&endpointTraceOpts.offset, "offset", 1, "Start at this position in the filtered events")
endpointTracesShowCmd.Flags().IntVar(&endpointTraceOpts.aroundEvent, "around-event", 0, "Center output on this event number")
endpointTracesShowCmd.Flags().IntVar(&endpointTraceOpts.before, "before", 3, "Events before --around-event")
endpointTracesShowCmd.Flags().IntVar(&endpointTraceOpts.after, "after", 3, "Events after --around-event")
diff --git a/cli/beacon/internal/agentskills/skills/beacon-memory-distill/SKILL.md b/cli/beacon/internal/agentskills/skills/beacon-memory-distill/SKILL.md
index 4c28ca64..ebcc17d6 100644
--- a/cli/beacon/internal/agentskills/skills/beacon-memory-distill/SKILL.md
+++ b/cli/beacon/internal/agentskills/skills/beacon-memory-distill/SKILL.md
@@ -153,9 +153,8 @@ How to read what comes back:
failed command followed by a different command that succeeded.
- A `user_message` with `content.included` false, or only a hash, means Beacon kept
metadata only. You cannot draft from a hash; say the trace was unreadable.
-- `--around-event` centres on the unfiltered event number. Combined with `--event-type`
- it can return no events at all, so read a small unfiltered window around the number
- and skip the `token_usage` and `session` rows yourself.
+- `--around-event` takes the original event number, also with `--event-type`, and
+ `--before` and `--after` count matching events.
Work out, from the events themselves:
diff --git a/cli/beacon/internal/endpoint/dashboard/history_query.go b/cli/beacon/internal/endpoint/dashboard/history_query.go
index aba60a5b..bcce4082 100644
--- a/cli/beacon/internal/endpoint/dashboard/history_query.go
+++ b/cli/beacon/internal/endpoint/dashboard/history_query.go
@@ -397,7 +397,7 @@ func (s *historyStore) show(sourceID int64, id string, query TraceQuery) (TraceS
return TraceShowResultV1{}, false, err
}
total := len(filtered)
- offset, limit := traceRange(query, total)
+ offset, limit := traceShowRange(query, total, func(i int) int { return filtered[i].seq })
end := offset - 1 + limit
if end > total {
end = total
diff --git a/cli/beacon/internal/endpoint/dashboard/trace_around_filtered_test.go b/cli/beacon/internal/endpoint/dashboard/trace_around_filtered_test.go
new file mode 100644
index 00000000..50f56bda
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/trace_around_filtered_test.go
@@ -0,0 +1,82 @@
+package dashboard
+
+import (
+ "fmt"
+ "reflect"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+func TestShowTraceAroundOriginalNumberWithTypeFilter(t *testing.T) {
+ var lines [][]byte
+ for n := 1; n <= 7; n++ {
+ event := testSchemaEvent(fmt.Sprintf("2026-06-11T10:00:0%dZ", n), "cursor", "prompt.submitted", "prompt", "repo-a")
+ event.Event.ID = fmt.Sprintf("e%d", n)
+ event.Session = &schema.SessionInfo{ID: "around"}
+ if n%2 == 0 {
+ event.Event.Action = "command.executed"
+ event.Event.Category = "command"
+ event.Command = &schema.CommandInfo{Command: fmt.Sprintf("command %d", n)}
+ } else {
+ event.Prompt = &schema.PromptInfo{Text: fmt.Sprintf("prompt %d", n)}
+ }
+ lines = append(lines, marshalEvents(t, event)...)
+ }
+ path := newTestLog(t, lines)
+ cases := []struct {
+ name string
+ query TraceQuery
+ numbers []int
+ total, offset, limit int
+ }{
+ {"defaults", TraceQuery{AroundEvent: 4, EventTypes: []string{"command"}}, []int{2, 4, 6}, 3, 1, 3},
+ {"nonpositive context", TraceQuery{AroundEvent: 4, Before: -1, After: -2, EventTypes: []string{"command"}}, []int{2, 4, 6}, 3, 1, 3},
+ {"anchor", TraceQuery{AroundEvent: 4, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{2, 4, 6}, 3, 1, 3},
+ {"filtered anchor", TraceQuery{AroundEvent: 3, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{2, 4}, 3, 1, 2},
+ {"first", TraceQuery{AroundEvent: 2, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{2, 4}, 3, 1, 2},
+ {"last", TraceQuery{AroundEvent: 6, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{4, 6}, 3, 2, 2},
+ {"before first", TraceQuery{AroundEvent: 1, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{2}, 3, 1, 1},
+ {"after last", TraceQuery{AroundEvent: 99, Before: 1, After: 1, EventTypes: []string{"command"}}, []int{6}, 3, 3, 1},
+ {"empty filter", TraceQuery{AroundEvent: 4, Before: 1, After: 1, EventTypes: []string{"approval"}}, nil, 0, 1, 0},
+ {"filtered pagination", TraceQuery{Offset: 2, Limit: 1, EventTypes: []string{"command"}}, []int{4}, 3, 2, 1},
+ {"filtered past end", TraceQuery{Offset: 4, Limit: 1, EventTypes: []string{"command"}}, nil, 3, 4, 0},
+ {"unfiltered", TraceQuery{AroundEvent: 4, Before: 1, After: 1}, []int{3, 4, 5}, 7, 3, 3},
+ {"unfiltered boundary", TraceQuery{AroundEvent: 1, Before: 1, After: 1}, []int{1, 2, 3}, 7, 1, 3},
+ }
+ answers := map[string]string{}
+ for _, mode := range []string{"jsonl", "history"} {
+ t.Run(mode, func(t *testing.T) {
+ if mode == "history" {
+ withHistory(t)
+ optIn(t, path)
+ } else {
+ withoutHistory(t)
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ result, ok, err := ShowTrace(path, "session:cursor:around", tc.query)
+ if err != nil || !ok {
+ t.Fatalf("ShowTrace ok=%v err=%v", ok, err)
+ }
+ var numbers []int
+ for _, event := range result.Events {
+ numbers = append(numbers, event.Number)
+ }
+ if !reflect.DeepEqual(numbers, tc.numbers) {
+ t.Errorf("numbers=%v want %v", numbers, tc.numbers)
+ }
+ if result.Range.TotalEvents != tc.total || result.Range.Offset != tc.offset || result.Range.Limit != tc.limit || result.Range.ReturnedEvents != len(tc.numbers) || result.Range.AroundEvent != tc.query.AroundEvent {
+ t.Errorf("range=%+v want total=%d offset=%d limit=%d", result.Range, tc.total, tc.offset, tc.limit)
+ }
+ encoded := mustJSON(t, result)
+ if mode == "jsonl" {
+ answers[tc.name] = encoded
+ } else if encoded != answers[tc.name] {
+ t.Errorf("history/fallback JSON mismatch\n%s\n%s", answers[tc.name], encoded)
+ }
+ })
+ }
+ })
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.go
index 482706e6..2d779723 100644
--- a/cli/beacon/internal/endpoint/dashboard/traces.go
+++ b/cli/beacon/internal/endpoint/dashboard/traces.go
@@ -296,7 +296,7 @@ func ShowTrace(path, id string, query TraceQuery) (TraceShowResultV1, bool, erro
}
events := filterTraceEvents(agg.events, query.EventTypes)
total := len(events)
- offset, limit := traceRange(query, total)
+ offset, limit := traceShowRange(query, total, func(i int) int { return events[i].Number })
end := offset - 1 + limit
if end > total {
end = total
@@ -444,6 +444,42 @@ func filterTraceEvents(events []TraceEventV1, eventTypes []string) []TraceEventV
return out
}
+// traceShowRange keeps pagination in filtered coordinates, but around-event names
+// an original event number. If that event is filtered out, its insertion point
+// separates the matching events before and after it without adding an anchor slot.
+func traceShowRange(query TraceQuery, total int, numberAt func(int) int) (int, int) {
+ if query.AroundEvent <= 0 || len(query.EventTypes) == 0 {
+ return traceRange(query, total)
+ }
+ before, after := aroundContext(query)
+ anchor := sort.Search(total, func(i int) bool { return numberAt(i) >= query.AroundEvent })
+ start := anchor - before
+ if start < 0 {
+ start = 0
+ }
+ end := anchor
+ if anchor < total && numberAt(anchor) == query.AroundEvent {
+ end++
+ }
+ if after > total-end {
+ after = total - end
+ }
+ end += after
+ return start + 1, end - start
+}
+
+// aroundContext is how many events --around-event shows on each side, 3 unless set.
+func aroundContext(query TraceQuery) (before, after int) {
+ before, after = query.Before, query.After
+ if before <= 0 {
+ before = 3
+ }
+ if after <= 0 {
+ after = 3
+ }
+ return before, after
+}
+
func traceRange(query TraceQuery, total int) (int, int) {
limit := normalizeLimit(query.Limit)
offset := query.Offset
@@ -455,13 +491,7 @@ func traceRange(query TraceQuery, total int) (int, int) {
limit = total
}
if query.AroundEvent > 0 {
- before, after := query.Before, query.After
- if before <= 0 {
- before = 3
- }
- if after <= 0 {
- after = 3
- }
+ before, after := aroundContext(query)
offset = query.AroundEvent - before
if offset < 1 {
offset = 1
diff --git a/docs/cli/endpoint-traces.mdx b/docs/cli/endpoint-traces.mdx
index 0edc8fcc..bd25070a 100644
--- a/docs/cli/endpoint-traces.mdx
+++ b/docs/cli/endpoint-traces.mdx
@@ -110,11 +110,13 @@ All commands accept:
| Flag | Description |
|------|-------------|
-| `--offset <n>` | Start at this event number. Defaults to `1` |
+| `--offset <n>` | Start at this position in the filtered events. Defaults to `1` |
| `--around-event <n>` | Center output around this event number |
| `--before <n>` | Events before `--around-event`. Defaults to `3` |
| `--after <n>` | Events after `--around-event`. Defaults to `3` |
+With `--event-type`, `--around-event` still takes the original event number, and `--before` and `--after` count matching events.
+
## Examples
```bash title="Check the local history"