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
Keep a durable local history behind `beacon endpoint traces`
shukieshah8b1204cbbfdc
diff --git a/CLAUDE.md b/CLAUDE.mdindex 7b4c4e3f..5f5b2ade 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -527,6 +527,7 @@ unpacked through Chrome's developer mode.- 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.+- The local trace history (`~/.beacon/endpoint/history.db`, `cli/beacon/internal/endpoint/dashboard/history_*.go`) is opt-in: only `beacon endpoint traces reindex`, a yes to the first-run prompt, or (later) `beacon mcp setup` creates it, and nothing non-interactive is ever prompted. Once it exists, `list`, `search` and `show` must return exactly what the JSONL scan returns for the same log (`TestHistoryAnswersExactlyLikeTheJSONLScan`), so it stores every event and projects it with the same code. A change to the trace projection bumps `historyDerivationVersion`, which rebuilds derived data from the stored lines. The stored lines keep only the raw keys in `historyRawKeys`, and a test fails if the dashboard reads one that is missing. The line dictionary (`historyLineDictionary`) must never change without a new codec.- The Asymptote device key has exactly one home, `<BaseDir>/asymptote/vector-secrets.json`, read by Vector's `secret` file backend. Never copy it into `config.json`, `vector.toml`, a service unit, an environment variable, a log line, or a `--json` result; `HasSecretDestinations` is unchanged because the key is not in `config.json`. `internal/auth` is flow-agnostic (PKCE, loopback callback server with an injected exchange function, browser opener, `PostJSON`); new browser flows reuse it rather than adding a second callback server. `connect` must fail before opening a browser when Vector or a service manager is missing, or when Vector rejects the rendered config, so no key is minted or rotated that cannot be used; enrollment rotates a connected device's key in place, so every local check runs ahead of it; the steps that can only fail after the exchange (storing the key, writing the config and unit, starting the service) are covered by the `asymptote/connect-pending` marker, written as soon as the key arrives and removed only when connect finishes, so status reports an incomplete connect instead of the previous connection. A failed first connect stops and removes any partial forwarder before returning, which keeps a later local-only onboarding choice local.- Keep the release readiness guidance in `README.md` up to date when install, packaging, collector, or dashboard behavior changes.diff --git a/agent-skills/skills/beacon-memory-distill/SKILL.md b/agent-skills/skills/beacon-memory-distill/SKILL.mdindex b78fe285..004447d9 100644--- a/agent-skills/skills/beacon-memory-distill/SKILL.md+++ b/agent-skills/skills/beacon-memory-distill/SKILL.md@@ -39,7 +39,9 @@ beacon endpoint traces status --json- If `beacon` is missing, stop and point the user tohttps://docs.beacon.sh/get-started/overview. Do not install it yourself.-- If the trace store is empty or stale, rebuild it (local only, never touches the log):+- If `status` reports `"enabled": false`, there is no local history, and only the last day or+ two of sessions are still in the runtime log. Suggest creating the history, which keeps+ sessions for 90 days and stays on this machine, and run it only if the user agrees:`beacon endpoint traces reindex`.## Step 2: pick tracesdiff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.goindex f4606221..f164967b 100644--- a/cli/beacon/cmd/endpoint.go+++ b/cli/beacon/cmd/endpoint.go@@ -395,6 +395,7 @@ func init() {endpointTracesCmd.AddCommand(endpointTracesListCmd)endpointTracesCmd.AddCommand(endpointTracesSearchCmd)endpointTracesCmd.AddCommand(endpointTracesShowCmd)+ endpointTracesCmd.AddCommand(endpointTracesResetCmd)endpointCoworkCmd.AddCommand(endpointCoworkPrintConfigCmd)endpointCoworkCmd.AddCommand(endpointCoworkSetupCmd)endpointCoworkCmd.AddCommand(endpointCoworkStatusCmd)@@ -407,7 +408,7 @@ func init() {endpointVSCodeCmd.AddCommand(endpointVSCodeStatusCmd)endpointVSCodeCmd.AddCommand(endpointVSCodeValidateCmd)- for _, c := range []*cobra.Command{endpointInstallCmd, endpointStatusCmd, endpointDoctorCmd, endpointInventoryCmd, endpointInventoryHeartbeatCmd, endpointInventoryInstallDaemonCmd, endpointDiscoverCmd, endpointTestEventCmd, endpointBundleDiagnosticsCmd, endpointUninstallCmd, endpointRepairCmd, endpointConfigShowCmd, endpointConfigValidateCmd, endpointIntegrationsValidateCmd, endpointUserConfigRepairInstalledCmd, endpointTracesStatusCmd, endpointTracesReindexCmd, endpointTracesListCmd, endpointTracesSearchCmd, endpointTracesShowCmd, topLevelDoctorCmd, topLevelStatusCmd, topLevelInventoryCmd} {+ for _, c := range []*cobra.Command{endpointInstallCmd, endpointStatusCmd, endpointDoctorCmd, endpointInventoryCmd, endpointInventoryHeartbeatCmd, endpointInventoryInstallDaemonCmd, endpointDiscoverCmd, endpointTestEventCmd, endpointBundleDiagnosticsCmd, endpointUninstallCmd, endpointRepairCmd, endpointConfigShowCmd, endpointConfigValidateCmd, endpointIntegrationsValidateCmd, endpointUserConfigRepairInstalledCmd, endpointTracesStatusCmd, endpointTracesReindexCmd, endpointTracesListCmd, endpointTracesSearchCmd, endpointTracesShowCmd, endpointTracesResetCmd, topLevelDoctorCmd, topLevelStatusCmd, topLevelInventoryCmd} {c.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")c.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and the system collector service")c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")@@ -466,6 +467,10 @@ func init() {c.Flags().IntVar(&endpointTraceOpts.limit, "limit", 100, "Limit returned traces or events")c.Flags().StringVar(&endpointTraceOpts.eventTypes, "event-type", "", "Filter trace events by comma-separated type")}+ endpointTracesReindexCmd.Flags().IntVar(&endpointTraceHistoryOpts.retentionDays, "retention-days", 0, "Keep traces whose last event is newer than this many days (default 90; kept once set)")+ endpointTracesReindexCmd.Flags().Int64Var(&endpointTraceHistoryOpts.maxSizeMB, "max-size-mb", 0, "Drop the oldest traces once the history reaches this size (default 1024; kept once set)")+ endpointTracesReindexCmd.Flags().BoolVar(&endpointTraceHistoryOpts.rebuild, "rebuild", false, "Recompute search text and summaries from the stored events")+ endpointTracesResetCmd.Flags().BoolVar(&endpointTraceHistoryOpts.yes, "yes", false, "Delete without asking")endpointTracesListCmd.Flags().StringVarP(&endpointTraceOpts.query, "query", "q", "", "Filter traces by text")endpointTracesListCmd.Flags().IntVar(&endpointTraceOpts.page, "page", 1, "Page number for trace listing")endpointTracesListCmd.Flags().StringVar(&endpointTraceOpts.state, "state", "", "Filter by sharing state")diff --git a/cli/beacon/cmd/endpoint_traces.go b/cli/beacon/cmd/endpoint_traces.goindex 17e8a13f..5c47b41a 100644--- a/cli/beacon/cmd/endpoint_traces.go+++ b/cli/beacon/cmd/endpoint_traces.go@@ -30,7 +30,7 @@ var endpointTraceOpts struct {var endpointTracesCmd = &cobra.Command{Use: "traces",- Short: "Index and search local endpoint traces",+ Short: "Search local endpoint traces and keep their history",}var topLevelTracesCmd = &cobra.Command{@@ -44,6 +44,7 @@ var runTraceView = traceview.Runfunc runTopLevelTraces(cmd *cobra.Command, args []string) error {logPath := endpointTraceLogPath()+ offerTraceHistory(logPath, true)if !isTerminal(os.Stdin) || !isTerminal(os.Stdout) || strings.EqualFold(os.Getenv("TERM"), "dumb") {result, err := dashboard.ReadTraceList(logPath, dashboard.TraceQuery{Limit: 100})if err != nil {@@ -67,10 +68,11 @@ func printPlainTraceList(out io.Writer, result dashboard.TraceListResultV1) {var endpointTracesStatusCmd = &cobra.Command{Use: "status",- Short: "Show local trace store status",+ Short: "Show the local trace history's status",SilenceUsage: true,RunE: func(cmd *cobra.Command, args []string) error {logPath := endpointTraceLogPath()+ offerTraceHistory(logPath, false)status, err := dashboard.TraceStoreStatus(logPath)if err != nil {return err@@ -78,40 +80,21 @@ var endpointTracesStatusCmd = &cobra.Command{if endpointOpts.jsonOutput {return json.NewEncoder(os.Stdout).Encode(status)}- fmt.Printf("Trace store: %s\n", status.Path)- fmt.Printf("Runtime log: %s\n", logPath)- fmt.Printf("Traces: %d\nEvents: %d\nIndex rows: %d\n", status.Traces, status.Events, status.IndexRows)- fmt.Printf("Size: %d bytes", status.SizeBytes)- if status.WALBytes > 0 {- fmt.Printf(" (+%d bytes WAL)", status.WALBytes)- }- fmt.Println()- if status.IndexedAt != "" {- fmt.Printf("Indexed at: %s\n", status.IndexedAt)- }+ printTraceStoreStatus(cmd.OutOrStdout(), logPath, status)return nil},}var endpointTracesReindexCmd = &cobra.Command{- Use: "reindex",- Short: "Rebuild the local trace store from runtime JSONL",+ Use: "reindex",+ Short: "Create or update the local trace history from the runtime log",+ Long: `Create or update the local trace history (history.db) from the runtime log.++The runtime log rotates after about 60MB, a day or two of agent activity. The local history keeps+sessions after that, for --retention-days or until it reaches --max-size-mb, whichever comes+first, and makes trace search faster. Every trace command keeps it up to date once it exists.`,SilenceUsage: true,- RunE: func(cmd *cobra.Command, args []string) error {- logPath := endpointTraceLogPath()- if err := dashboard.ReindexTraceStore(logPath); err != nil {- return err- }- status, err := dashboard.TraceStoreStatus(logPath)- if err != nil {- return err- }- if endpointOpts.jsonOutput {- return json.NewEncoder(os.Stdout).Encode(status)- }- fmt.Printf("Reindexed %d traces and %d events into %s\n", status.Traces, status.Events, status.Path)- return nil- },+ RunE: runEndpointTracesReindex,}var endpointTracesListCmd = &cobra.Command{@@ -119,7 +102,9 @@ var endpointTracesListCmd = &cobra.Command{Short: "List local traces",SilenceUsage: true,RunE: func(cmd *cobra.Command, args []string) error {- result, err := dashboard.ReadTraceList(endpointTraceLogPath(), endpointTraceQuery())+ logPath := endpointTraceLogPath()+ offerTraceHistory(logPath, true)+ result, err := dashboard.ReadTraceList(logPath, endpointTraceQuery())if err != nil {return err}@@ -140,7 +125,9 @@ var endpointTracesSearchCmd = &cobra.Command{query := endpointTraceQuery()query.Q = args[0]query.ResultLevel = endpointTraceOpts.resultLevel- result, err := dashboard.SearchTraces(endpointTraceLogPath(), query)+ logPath := endpointTraceLogPath()+ offerTraceHistory(logPath, true)+ result, err := dashboard.SearchTraces(logPath, query)if err != nil {return err}@@ -166,7 +153,9 @@ var endpointTracesShowCmd = &cobra.Command{Args: cobra.ExactArgs(1),SilenceUsage: true,RunE: func(cmd *cobra.Command, args []string) error {- result, ok, err := dashboard.ShowTrace(endpointTraceLogPath(), args[0], endpointTraceQuery())+ logPath := endpointTraceLogPath()+ offerTraceHistory(logPath, true)+ result, ok, err := dashboard.ShowTrace(logPath, args[0], endpointTraceQuery())if err != nil {return err}diff --git a/cli/beacon/cmd/endpoint_traces_history.go b/cli/beacon/cmd/endpoint_traces_history.gonew file mode 100644index 00000000..8c21d812--- /dev/null+++ b/cli/beacon/cmd/endpoint_traces_history.go@@ -0,0 +1,186 @@+package cmd++import (+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "os"+ "strings"+ "time"++ "github.com/spf13/cobra"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/onboarding"+)++var endpointTraceHistoryOpts struct {+ retentionDays int+ maxSizeMB int64+ rebuild bool+ yes bool+}++// traceHistoryIO is where the first-run prompt reads and writes; tests replace it.+var traceHistoryIO = struct {+ in io.Reader+ out io.Writer+ interactive func() bool+}{+ in: os.Stdin,+ out: os.Stderr,+ interactive: func() bool {+ return isTerminal(os.Stdin) && isTerminal(os.Stdout) && !strings.EqualFold(os.Getenv("TERM"), "dumb")+ },+}++// offerTraceHistory runs before the trace commands read anything. On a machine that has not opted+// in to the local history it asks once, on an interactive terminal, whether to create it. Anything+// that is not a person at a terminal -- an agent calling through a shell, --json, a pipe, CI -- is+// never asked and gets one line on stderr instead, so a script is never left waiting on a prompt.+// hint is false for `status`, which says the same thing in its own output.+func offerTraceHistory(logPath string, hint bool) {+ if dashboard.HistoryStoreEnabled() {+ return+ }+ profile := onboarding.Load()+ if profile.HistoryDeclined() {+ return+ }+ if endpointOpts.jsonOutput || os.Getenv("CI") != "" || !traceHistoryIO.interactive() {+ if !hint {+ return+ }+ fmt.Fprintln(os.Stderr, "Beacon: reading traces from the runtime log, which holds about a day or two of activity. Run `beacon endpoint traces reindex` to keep a local history.")+ return+ }+ out := traceHistoryIO.out+ fmt.Fprintln(out)+ fmt.Fprintln(out, " Beacon's runtime log rotates after about 60MB, a day or two of agent activity. A local")+ fmt.Fprintln(out, " history keeps sessions after that, for 90 days or up to 1GB, and makes trace search faster.")+ fmt.Fprintf(out, " It lives at %s, readable only by you, and holds the same prompts,\n", dashboard.TraceStorePath(logPath))+ fmt.Fprintln(out, " commands and output as the log. Nothing leaves this machine. Remove it with")+ fmt.Fprintln(out, " `beacon endpoint traces reset`.")+ fmt.Fprintln(out)+ index, err := onboarding.Choose(traceHistoryIO.in, out, "Keep a local history of your agent sessions?", []onboarding.Option{+ {Label: "Create it now", Detail: "Reads the current log once, then keeps up as you work."},+ {Label: "Not now", Detail: "Traces are read from the log each time. `beacon endpoint traces reindex` creates it later."},+ })+ if err != nil {+ // An aborted prompt answers nothing; the command runs on the log and asks again next time.+ return+ }+ if index == 1 {+ profile.History = &onboarding.History{DeclinedAt: time.Now().UTC().Format(time.RFC3339)}+ if err := onboarding.Save(profile); err != nil {+ fmt.Fprintf(out, " Could not record the answer: %v\n", err)+ }+ return+ }+ status, err := dashboard.EnableHistoryStore(logPath, dashboard.HistoryOptions{Progress: historyProgress(out)})+ if err != nil {+ fmt.Fprintf(out, "\r Could not create the local history: %v\n Traces are read from the runtime log instead.\n\n", err)+ return+ }+ fmt.Fprintf(out, "\r Local history ready: %d traces, %d events. \n\n", status.Traces, status.Events)+}++// historyProgress draws one updating line while a catch-up reads the log.+func historyProgress(out io.Writer) func(done, total int64) {+ last := -1+ return func(done, total int64) {+ if total <= 0 {+ return+ }+ percent := int(done * 100 / total)+ if percent == last {+ return+ }+ last = percent+ fmt.Fprintf(out, "\r Reading the runtime log... %d%%", percent)+ }+}++var endpointTracesResetCmd = &cobra.Command{+ Use: "reset",+ Short: "Delete the local trace history",+ Long: "Delete the local trace history (history.db). The runtime log is not touched. Sessions the log has already rotated away cannot be recovered.",+ SilenceUsage: true,+ RunE: func(cmd *cobra.Command, args []string) error {+ path := dashboard.TraceStorePath(endpointTraceLogPath())+ if !dashboard.HistoryStoreEnabled() {+ fmt.Fprintf(cmd.OutOrStdout(), "No local history at %s\n", path)+ return nil+ }+ if !endpointTraceHistoryOpts.yes {+ if !traceHistoryIO.interactive() {+ return errors.New("pass --yes to delete the local history without a prompt")+ }+ index, err := onboarding.Choose(traceHistoryIO.in, traceHistoryIO.out, "Delete the local history? Sessions no longer in the runtime log are lost.", []onboarding.Option{+ {Label: "Keep it"},+ {Label: "Delete it"},+ })+ if err != nil || index != 1 {+ fmt.Fprintln(cmd.OutOrStdout(), "Local history kept.")+ return nil+ }+ }+ if err := dashboard.ResetHistoryStore(); err != nil {+ return err+ }+ fmt.Fprintf(cmd.OutOrStdout(), "Deleted the local history at %s\n", path)+ return nil+ },+}++func runEndpointTracesReindex(cmd *cobra.Command, args []string) error {+ logPath := endpointTraceLogPath()+ opts := dashboard.HistoryOptions{+ RetentionDays: endpointTraceHistoryOpts.retentionDays,+ MaxBytes: endpointTraceHistoryOpts.maxSizeMB << 20,+ Rebuild: endpointTraceHistoryOpts.rebuild,+ }+ if !endpointOpts.jsonOutput && isTerminal(os.Stderr) {+ opts.Progress = historyProgress(os.Stderr)+ }+ status, err := dashboard.EnableHistoryStore(logPath, opts)+ if opts.Progress != nil {+ fmt.Fprint(os.Stderr, "\r\033[K")+ }+ if err != nil {+ return err+ }+ if endpointOpts.jsonOutput {+ return json.NewEncoder(cmd.OutOrStdout()).Encode(status)+ }+ fmt.Fprintf(cmd.OutOrStdout(), "Local history: %d traces and %d events in %s\n", status.Traces, status.Events, status.Path)+ return nil+}++func printTraceStoreStatus(out io.Writer, logPath string, status dashboard.HistoryStatus) {+ if !status.Enabled {+ fmt.Fprintf(out, "Local history: not set up (%s)\n", status.Path)+ fmt.Fprintf(out, "Runtime log: %s\n", logPath)+ fmt.Fprintln(out, "Traces are read from the runtime log. Run `beacon endpoint traces reindex` to keep a local history.")+ return+ }+ fmt.Fprintf(out, "Local history: %s\n", status.Path)+ fmt.Fprintf(out, "Runtime log: %s\n", logPath)+ fmt.Fprintf(out, "Traces: %d\nEvents: %d\nIndex rows: %d\n", status.Traces, status.Events, status.IndexRows)+ if status.OldestEventAt != "" {+ fmt.Fprintf(out, "Oldest event: %s\nNewest event: %s\n", status.OldestEventAt, status.NewestEventAt)+ }+ fmt.Fprintf(out, "Size: %s of %s", humanBytes(status.SizeBytes+status.WALBytes), humanBytes(status.MaxBytes))+ fmt.Fprintf(out, ", kept for %d days\n", status.RetentionDays)+ if status.Gaps > 0 {+ fmt.Fprintf(out, "Gaps: %d. A log file left before the history finished reading it, so events may be missing", status.Gaps)+ if status.GapBytes > 0 {+ fmt.Fprintf(out, " (at least %s of the log)", humanBytes(status.GapBytes))+ }+ fmt.Fprintln(out, ". Trace commands read new events as they run; the log rotates away unread only if more than about 60 MB is written between two of them.")+ }+ if status.IndexedAt != "" {+ fmt.Fprintf(out, "Last updated: %s\n", status.IndexedAt)+ }+}diff --git a/cli/beacon/cmd/endpoint_traces_history_test.go b/cli/beacon/cmd/endpoint_traces_history_test.gonew file mode 100644index 00000000..d9b271da--- /dev/null+++ b/cli/beacon/cmd/endpoint_traces_history_test.go@@ -0,0 +1,138 @@+package cmd++import (+ "bytes"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "time"++ "github.com/spf13/cobra"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/onboarding"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// traceHistoryFixture gives the test its own home, history path and a small runtime log, and+// replaces the prompt's terminal with answers.+func traceHistoryFixture(t *testing.T, interactive bool, answers string) (logPath, historyPath string, prompt *bytes.Buffer) {+ t.Helper()+ home := t.TempDir()+ testenv.SetHome(t, home)+ historyPath = filepath.Join(home, ".beacon", "endpoint", "history.db")+ t.Setenv(endpointconfig.HistoryStoreEnv, historyPath)+ t.Setenv("CI", "")+ logPath = filepath.Join(home, "logs", "runtime.jsonl")+ if err := os.MkdirAll(filepath.Dir(logPath), 0o700); err != nil {+ t.Fatal(err)+ }+ line := `{"timestamp":"` + time.Now().UTC().Format(time.RFC3339) + `","event":{"id":"e1","action":"prompt.submitted","category":"prompt"},"harness":{"name":"cursor"},"session":{"id":"s1"},"prompt":{"text":"keep this session"}}` + "\n"+ if err := os.WriteFile(logPath, []byte(line), 0o600); err != nil {+ t.Fatal(err)+ }+ prompt = &bytes.Buffer{}+ previous := traceHistoryIO+ traceHistoryIO.in = strings.NewReader(answers)+ traceHistoryIO.out = prompt+ traceHistoryIO.interactive = func() bool { return interactive }+ previousOpts, previousHistory := endpointOpts, endpointTraceHistoryOpts+ endpointOpts.logPath = logPath+ endpointOpts.jsonOutput = false+ t.Cleanup(func() {+ traceHistoryIO = previous+ endpointOpts, endpointTraceHistoryOpts = previousOpts, previousHistory+ })+ return logPath, historyPath, prompt+}++func TestTraceHistoryIsNeverPromptedWithoutATerminal(t *testing.T) {+ logPath, historyPath, prompt := traceHistoryFixture(t, false, "1\n")+ offerTraceHistory(logPath, true)+ if prompt.Len() != 0 {+ t.Fatalf("prompted without a terminal: %q", prompt.String())+ }+ if _, err := os.Stat(historyPath); !os.IsNotExist(err) {+ t.Fatalf("history created without an answer: %v", err)+ }+}++func TestTraceHistoryIsNeverPromptedForJSON(t *testing.T) {+ logPath, historyPath, prompt := traceHistoryFixture(t, true, "1\n")+ endpointOpts.jsonOutput = true+ offerTraceHistory(logPath, true)+ if prompt.Len() != 0 {+ t.Fatalf("prompted for --json: %q", prompt.String())+ }+ if _, err := os.Stat(historyPath); !os.IsNotExist(err) {+ t.Fatalf("history created for --json: %v", err)+ }+}++func TestTraceHistoryPromptCreatesTheStore(t *testing.T) {+ logPath, historyPath, prompt := traceHistoryFixture(t, true, "1\n")+ offerTraceHistory(logPath, true)+ if !strings.Contains(prompt.String(), "Keep a local history") || !strings.Contains(prompt.String(), "Local history ready: 1 traces, 1 events") {+ t.Fatalf("prompt output = %q", prompt.String())+ }+ if _, err := os.Stat(historyPath); err != nil {+ t.Fatalf("history not created: %v", err)+ }+ // Asked once: with the store in place the next command says nothing.+ prompt.Reset()+ offerTraceHistory(logPath, true)+ if prompt.Len() != 0 {+ t.Fatalf("prompted again after creating the store: %q", prompt.String())+ }+}++func TestTraceHistoryPromptRemembersNotNow(t *testing.T) {+ logPath, historyPath, prompt := traceHistoryFixture(t, true, "2\n")+ offerTraceHistory(logPath, true)+ if _, err := os.Stat(historyPath); !os.IsNotExist(err) {+ t.Fatalf("history created after \"Not now\": %v", err)+ }+ if !onboarding.Load().HistoryDeclined() {+ t.Fatal("\"Not now\" was not recorded in the profile")+ }+ prompt.Reset()+ traceHistoryIO.in = strings.NewReader("1\n")+ offerTraceHistory(logPath, true)+ if prompt.Len() != 0 {+ t.Fatalf("asked again after \"Not now\": %q", prompt.String())+ }+ // reindex still opts in.+ var out bytes.Buffer+ cmd := &cobra.Command{}+ cmd.SetOut(&out)+ if err := runEndpointTracesReindex(cmd, nil); err != nil {+ t.Fatal(err)+ }+ if _, err := os.Stat(historyPath); err != nil {+ t.Fatalf("reindex did not create the history: %v", err)+ }+}++func TestTraceHistoryResetNeedsConfirmation(t *testing.T) {+ logPath, historyPath, _ := traceHistoryFixture(t, false, "")+ if err := dashboard.ReindexTraceStore(logPath); err != nil {+ t.Fatal(err)+ }+ var out bytes.Buffer+ endpointTracesResetCmd.SetOut(&out)+ if err := endpointTracesResetCmd.RunE(endpointTracesResetCmd, nil); err == nil {+ t.Fatal("reset without --yes and without a terminal should refuse")+ }+ if _, err := os.Stat(historyPath); err != nil {+ t.Fatalf("history removed without confirmation: %v", err)+ }+ endpointTraceHistoryOpts.yes = true+ if err := endpointTracesResetCmd.RunE(endpointTracesResetCmd, nil); err != nil {+ t.Fatal(err)+ }+ if _, err := os.Stat(historyPath); !os.IsNotExist(err) {+ t.Fatalf("history still present after reset --yes: %v", err)+ }+}diff --git a/cli/beacon/cmd/history_env_test.go b/cli/beacon/cmd/history_env_test.gonew file mode 100644index 00000000..a7605d5b--- /dev/null+++ b/cli/beacon/cmd/history_env_test.go@@ -0,0 +1,24 @@+package cmd++import (+ "fmt"+ "os"+ "path/filepath"+ "testing"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+)++// Every test in this package runs with the local history pointed at a path that does not exist, so+// a command under test never reads or writes a developer's real ~/.beacon/endpoint/history.db.+func TestMain(m *testing.M) {+ dir, err := os.MkdirTemp("", "beacon-cmd-test")+ if err != nil {+ fmt.Fprintln(os.Stderr, err)+ os.Exit(1)+ }+ _ = os.Setenv(endpointconfig.HistoryStoreEnv, filepath.Join(dir, "absent", "history.db"))+ code := m.Run()+ _ = os.RemoveAll(dir)+ os.Exit(code)+}diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.goindex 1ae2a677..d2317888 100644--- a/cli/beacon/internal/endpoint/config/config.go+++ b/cli/beacon/internal/endpoint/config/config.go@@ -6,6 +6,7 @@ import ("os""path/filepath""runtime"+ "strings")const (@@ -302,6 +303,24 @@ func BaseDir(userMode bool) string {return SystemBaseDir()}+// HistoryStoreFile is the durable local history `beacon endpoint traces` reads once the user+// opts in to it.+const HistoryStoreFile = "history.db"++// HistoryStoreEnv overrides where the local history lives.+const HistoryStoreEnv = "BEACON_HISTORY_DB"++// HistoryStorePath is where the local history lives: BEACON_HISTORY_DB when set, otherwise the+// user's own endpoint directory, whichever log it indexes. The system log's directory is root's,+// and the history holds the same prompts and commands the log does, so it belongs to the person+// reading it.+func HistoryStorePath() string {+ if path := strings.TrimSpace(os.Getenv(HistoryStoreEnv)); path != "" {+ return path+ }+ return filepath.Join(BaseDir(true), HistoryStoreFile)+}+func ConfigPath(userMode bool) string {if userMode {home, err := os.UserHomeDir()diff --git a/cli/beacon/internal/endpoint/dashboard/history_file_unix.go b/cli/beacon/internal/endpoint/dashboard/history_file_unix.gonew file mode 100644index 00000000..972073c7--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_file_unix.go@@ -0,0 +1,27 @@+//go:build !windows++package dashboard++import (+ "fmt"+ "os"+ "syscall"+)++// openLogFile opens a runtime log file for reading.+func openLogFile(path string) (*os.File, error) {+ return os.Open(path)+}++// logFileIdentity is the device and inode, which survive the rename rotation does.+func logFileIdentity(f *os.File) (uint64, uint64, error) {+ info, err := f.Stat()+ if err != nil {+ return 0, 0, err+ }+ stat, ok := info.Sys().(*syscall.Stat_t)+ if !ok {+ return 0, 0, fmt.Errorf("no file identity for %s", f.Name())+ }+ return uint64(stat.Dev), uint64(stat.Ino), nil+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_file_windows.go b/cli/beacon/internal/endpoint/dashboard/history_file_windows.gonew file mode 100644index 00000000..46bf545a--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_file_windows.go@@ -0,0 +1,35 @@+//go:build windows++package dashboard++import (+ "os"++ "golang.org/x/sys/windows"+)++// openLogFile opens a runtime log file for reading with FILE_SHARE_DELETE. os.Open leaves it out,+// and on Windows a rename fails while any handle lacks it: a catch-up holding a log file open+// would make the writer's rotation fail and the event it was writing would be lost.+func openLogFile(path string) (*os.File, error) {+ name, err := windows.UTF16PtrFromString(path)+ if err != nil {+ return nil, &os.PathError{Op: "open", Path: path, Err: err}+ }+ handle, err := windows.CreateFile(name, windows.GENERIC_READ,+ windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,+ nil, windows.OPEN_EXISTING, windows.FILE_ATTRIBUTE_NORMAL, 0)+ if err != nil {+ return nil, &os.PathError{Op: "open", Path: path, Err: err}+ }+ return os.NewFile(uintptr(handle), path), nil+}++// logFileIdentity is the volume serial number and file index, which survive a rename.+func logFileIdentity(f *os.File) (uint64, uint64, error) {+ var info windows.ByHandleFileInformation+ if err := windows.GetFileInformationByHandle(windows.Handle(f.Fd()), &info); err != nil {+ return 0, 0, err+ }+ return uint64(info.VolumeSerialNumber), uint64(info.FileIndexHigh)<<32 | uint64(info.FileIndexLow), nil+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_ingest.go b/cli/beacon/internal/endpoint/dashboard/history_ingest.gonew file mode 100644index 00000000..9654f747--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_ingest.go@@ -0,0 +1,1182 @@+package dashboard++import (+ "bufio"+ "bytes"+ "crypto/sha256"+ "database/sql"+ "encoding/hex"+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "io/fs"+ "math"+ "os"+ "sort"+ "strconv"+ "strings"+ "time"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"+)++// logFile is one file of a runtime log, opened during a snapshot.+type logFile struct {+ path string+ archive int+ f *os.File+ dev uint64+ ino uint64+ // head identifies the file's content: a hash of its first line. Together with the device and+ // inode it tells a rotated file apart from a new file that happens to reuse an inode.+ head string+ size int64+}++func (lf logFile) key() string {+ return fmt.Sprintf("%d:%d:%s", lf.dev, lf.ino, lf.head)+}++type fileCheckpoint struct {+ offset int64+ lines int64+ size int64+ archive int+}++// snapshotLogFiles opens every file of a runtime log while holding the writers' lock shared, so no+// rotation can land between listing the files and opening them. The files are read after the lock+// is released, each up to the size it had here.+func snapshotLogFiles(logPath string) ([]logFile, error) {+ unlock := lockLogShared(logPath)+ defer unlock()+ var files []logFile+ for _, source := range eventSources(logPath) {+ f, err := openLogFile(source.path)+ if err != nil {+ if errors.Is(err, fs.ErrNotExist) {+ continue+ }+ closeLogFiles(files)+ return nil, err+ }+ lf := logFile{path: source.path, archive: source.archive, f: f}+ info, err := f.Stat()+ if err == nil {+ lf.size = info.Size()+ lf.dev, lf.ino, err = logFileIdentity(f)+ }+ if err == nil {+ lf.head, err = readLogHead(f, lf.size)+ }+ if err != nil {+ _ = f.Close()+ closeLogFiles(files)+ return nil, err+ }+ files = append(files, lf)+ }+ // Oldest first: the highest archive number, down to the live file.+ sort.SliceStable(files, func(i, j int) bool {+ ai, aj := files[i].archive, files[j].archive+ if ai == 0 || aj == 0 {+ return aj == 0 && ai != 0+ }+ return ai > aj+ })+ return files, nil+}++func closeLogFiles(files []logFile) {+ for _, lf := range files {+ _ = lf.f.Close()+ }+}++// lockLogShared takes the lock Beacon's log writers hold while they append and rotate. A log+// without a lock file, or one this user cannot open, is read without it: a rotation racing the+// snapshot then costs at most a missed file, which the next catch-up picks up.+func lockLogShared(logPath string) func() {+ f, err := os.Open(logPath + ".lock")+ if err != nil {+ return func() {}+ }+ held, err := filelock.Shared(f)+ if err != nil {+ _ = f.Close()+ return func() {}+ }+ return func() {+ _ = held.Release()+ _ = f.Close()+ }+}++// readLogHead hashes the file's first complete line. An empty file, or one whose first line is+// still being written, has no head yet and is skipped until it does.+func readLogHead(f *os.File, size int64) (string, error) {+ if size == 0 {+ return "", nil+ }+ limit := size+ if limit > historyMaxLineBytes+1 {+ limit = historyMaxLineBytes + 1+ }+ reader := bufio.NewReader(io.NewSectionReader(f, 0, limit))+ line, err := reader.ReadBytes('\n')+ if err == io.EOF {+ if int64(len(line)) > historyMaxLineBytes {+ // A first line longer than any event is identified by its prefix alone.+ sum := sha256.Sum256(line)+ return hex.EncodeToString(sum[:16]), nil+ }+ return "", nil+ }+ if err != nil {+ return "", err+ }+ sum := sha256.Sum256(line)+ return hex.EncodeToString(sum[:16]), nil+}++func (s *historyStore) loadCheckpoints(q queryer, sourceID int64) (map[string]fileCheckpoint, error) {+ rows, err := q.Query(`SELECT dev, ino, head, offset, lines, size, archive FROM files WHERE source_id = ?`, sourceID)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ out := map[string]fileCheckpoint{}+ for rows.Next() {+ var dev, ino int64+ var head string+ var cp fileCheckpoint+ if err := rows.Scan(&dev, &ino, &head, &cp.offset, &cp.lines, &cp.size, &cp.archive); err != nil {+ return nil, err+ }+ out[fmt.Sprintf("%d:%d:%s", uint64(dev), uint64(ino), head)] = cp+ }+ return out, rows.Err()+}++// needsCatchUp reports whether the log holds anything the store has not read, or whether a file the+// store was reading has gone.+func needsCatchUp(files []logFile, checkpoints map[string]fileCheckpoint) bool {+ seen := map[string]bool{}+ for _, lf := range files {+ if lf.head == "" {+ continue+ }+ cp, ok := checkpoints[lf.key()]+ if !ok || cp.offset != lf.size {+ return true+ }+ seen[lf.key()] = true+ }+ for key := range checkpoints {+ if !seen[key] {+ return true+ }+ }+ return false+}++// catchUp appends whatever the log gained since the last catch-up, prunes what is past retention or+// over the size cap, and returns the log's source ID. With nothing to do it is a stat of each log+// file and two small queries. force runs a full pass regardless, for a settings change.+func (s *historyStore) catchUp(logPath string, progress func(done, total int64), force bool) (int64, error) {+ files, err := snapshotLogFiles(logPath)+ if err != nil {+ return 0, err+ }+ defer closeLogFiles(files)++ derivationCurrent := s.metaInt("derivation_version", 0) == historyDerivationVersion+ sourceID, err := s.sourceID(s.db, logPath, false)+ if err != nil && err != sql.ErrNoRows {+ return 0, err+ }+ if sourceID != 0 && derivationCurrent && !force {+ checkpoints, err := s.loadCheckpoints(s.db, sourceID)+ if err != nil {+ return 0, err+ }+ expired, err := s.hasExpiredTraces(time.Now())+ if err != nil {+ return 0, err+ }+ if !needsCatchUp(files, checkpoints) && !expired {+ return sourceID, nil+ }+ }++ unlock, err := s.lockExclusive()+ if err != nil {+ return 0, err+ }+ defer unlock()+ retentionDays := s.metaInt("retention_days", defaultHistoryRetentionDays)+ maxBytes := s.metaInt("max_bytes", defaultHistoryMaxBytes)+ // Re-read under the lock: another process may have caught up, or rebuilt, while this one+ // waited for it.+ derivationCurrent = s.metaInt("derivation_version", 0) == historyDerivationVersion++ tx, err := s.db.Begin()+ if err != nil {+ return 0, err+ }+ defer tx.Rollback()+ if !derivationCurrent {+ if err := rebuildHistoryDerived(tx); err != nil {+ return 0, fmt.Errorf("rebuild local history: %w", err)+ }+ }+ sourceID, err = s.sourceID(tx, logPath, true)+ if err != nil {+ return 0, err+ }+ checkpoints, err := s.loadCheckpoints(tx, sourceID)+ if err != nil {+ return 0, err+ }++ pass, err := newHistoryPass(tx, sourceID)+ if err != nil {+ return 0, err+ }+ defer pass.close()++ var total, done int64+ for _, lf := range files {+ if cp, ok := checkpoints[lf.key()]; ok && cp.offset <= lf.size {+ total += lf.size - cp.offset+ } else {+ total += lf.size+ }+ }+ seen := map[string]bool{}+ for _, lf := range files {+ if lf.head == "" {+ continue+ }+ key := lf.key()+ seen[key] = true+ cp := checkpoints[key]+ if cp.offset > lf.size {+ // Shorter than what was read from it: not the file the checkpoint describes.+ cp = fileCheckpoint{}+ }+ start := cp.offset+ offset, lines, err := pass.ingestFile(lf, cp.offset, cp.lines, func(n int64) {+ if progress != nil {+ progress(done+n, total)+ }+ })+ if err != nil {+ return 0, err+ }+ done += offset - start+ if _, err := tx.Exec(`INSERT INTO files (source_id, dev, ino, head, offset, lines, size, archive) VALUES (?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT (source_id, dev, ino, head) DO UPDATE SET offset = excluded.offset, lines = excluded.lines, size = excluded.size, archive = excluded.archive`,+ sourceID, int64(lf.dev), int64(lf.ino), lf.head, offset, lines, lf.size, lf.archive); err != nil {+ return 0, err+ }+ }+ // A file leaves the log when rotation deletes the oldest archive. An archive read to its end+ // leaving is normal. A file that was the live log at the last catch-up and is gone now went+ // through every archive slot in between, so the log rotated past the store and whatever was+ // written to that file after it was read, and to any file created and deleted since, is lost.+ // Its size is unknown, so it is counted as a gap; unread bytes known at the last catch-up are+ // added to gap_bytes as a lower bound.+ var gaps, gap int64+ for key, cp := range checkpoints {+ if seen[key] {+ continue+ }+ if cp.size > cp.offset {+ gap += cp.size - cp.offset+ }+ if cp.archive == 0 || cp.size > cp.offset {+ gaps+++ }+ dev, ino, head, err := splitFileKey(key)+ if err != nil {+ return 0, err+ }+ if _, err := tx.Exec(`DELETE FROM files WHERE source_id = ? AND dev = ? AND ino = ? AND head = ?`, sourceID, dev, ino, head); err != nil {+ return 0, err+ }+ }+ if gaps > 0 {+ if _, err := tx.Exec(`UPDATE sources SET gaps = gaps + ?, gap_bytes = gap_bytes + ? WHERE id = ?`, gaps, gap, sourceID); err != nil {+ return 0, err+ }+ }+ if err := pass.flush(); err != nil {+ return 0, err+ }+ pruned, err := pruneHistory(tx, time.Now(), retentionDays, maxBytes)+ if err != nil {+ return 0, err+ }+ now := time.Now().UTC().Format(time.RFC3339Nano)+ if _, err := tx.Exec(`INSERT INTO meta (key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, now); err != nil {+ return 0, err+ }+ if err := tx.Commit(); err != nil {+ return 0, err+ }+ if pruned {+ // Hand the freed pages back to the file system, so the cap bounds the file on disk.+ _, _ = s.db.Exec(`PRAGMA incremental_vacuum`)+ }+ if pruned || done > 4<<20 {+ // A large catch-up leaves a write-ahead log as large as what it wrote, and the database+ // file only shrinks after a vacuum once the log is folded into it.+ _, _ = s.db.Exec(`PRAGMA wal_checkpoint(TRUNCATE)`)+ }+ return sourceID, nil+}++func splitFileKey(key string) (int64, int64, string, error) {+ parts := strings.SplitN(key, ":", 3)+ if len(parts) != 3 {+ return 0, 0, "", fmt.Errorf("malformed file key %q", key)+ }+ dev, err := strconv.ParseUint(parts[0], 10, 64)+ if err != nil {+ return 0, 0, "", err+ }+ ino, err := strconv.ParseUint(parts[1], 10, 64)+ if err != nil {+ return 0, 0, "", err+ }+ return int64(dev), int64(ino), parts[2], nil+}++// historyCheckpointEvery is how often, in events, a trace's running aggregate is saved. An event+// that arrives after later ones -- an OpenTelemetry batch lands seconds after the hook events it+// precedes -- belongs earlier in its trace, and the summary is refolded from the last checkpoint+// before it rather than from the start of a trace that may hold tens of thousands of events.+const historyCheckpointEvery = 256++// historyOrder is where an event sits in its trace. It is the order SortRecordsAppendOrder gives+// the JSONL path: timestamp, then unsequenced before sequenced, then sequence, then position in the+// log, which is the row ID because rows are stored in log order.+type historyOrder struct {+ ts int64+ seq uint64+ id int64+}++func (a historyOrder) less(b historyOrder) bool {+ if a.ts != b.ts {+ return a.ts < b.ts+ }+ if (a.seq != 0) != (b.seq != 0) {+ return a.seq == 0+ }+ if a.seq != b.seq {+ return a.seq < b.seq+ }+ return a.id < b.id+}++// orderTime is the event's timestamp as SortRecordsAppendOrder compares it: parsed with the same+// function, and a timestamp that does not parse sorting first, as the zero time does.+func orderTime(value string) int64 {+ parsed, err := asymptoteobserve.ParseTimestamp(value)+ if err != nil || parsed.IsZero() {+ return math.MinInt64+ }+ if parsed.Year() < 1678 {+ return math.MinInt64 + 1+ }+ if parsed.Year() > 2261 {+ return math.MaxInt64+ }+ return parsed.UnixNano()+}++// historyEvent is an event on its way into a trace's fold.+type historyEvent struct {+ id int64+ seq int+ order historyOrder+ recordID string+ event schema.Event+}++// historyPass is one catch-up's worth of appends. New events are stored as they are read, and+// each trace's summary is brought up to date when the pass flushes.+type historyPass struct {+ tx *sql.Tx+ sourceID int64+ pending map[string][]*historyEvent+ pendingN int+ insertEvent *sql.Stmt+ insertFTS *sql.Stmt+ updateSeq *sql.Stmt+}++// historyFlushEvery bounds how many new events a pass holds in memory before folding them in.+const historyFlushEvery = 4096++func newHistoryPass(tx *sql.Tx, sourceID int64) (*historyPass, error) {+ insertEvent, err := tx.Prepare(`INSERT INTO events (source_id, file_key, offset, record_id, trace_key, seq, event_type, event_id, ts_ns,+ ord_ts, ord_seq, span_id, parent_span_id, otel_trace_id, span_name, hay, line)+ VALUES (?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT (source_id, file_key, offset) DO NOTHING`)+ if err != nil {+ return nil, err+ }+ insertFTS, err := tx.Prepare(`INSERT INTO event_fts (rowid, hay) VALUES (?, ?)`)+ if err != nil {+ _ = insertEvent.Close()+ return nil, err+ }+ updateSeq, err := tx.Prepare(`UPDATE events SET seq = ? WHERE id = ?`)+ if err != nil {+ _ = insertEvent.Close()+ _ = insertFTS.Close()+ return nil, err+ }+ return &historyPass{+ tx: tx,+ sourceID: sourceID,+ pending: map[string][]*historyEvent{},+ insertEvent: insertEvent,+ insertFTS: insertFTS,+ updateSeq: updateSeq,+ }, nil+}++func (p *historyPass) close() {+ _ = p.insertEvent.Close()+ _ = p.insertFTS.Close()+ _ = p.updateSeq.Close()+}++// ingestFile reads complete lines from offset to the file's snapshot size. A final line without a+// newline is left for the next catch-up; Beacon's writers append whole lines, so that is a line+// another process is still writing.+func (p *historyPass) ingestFile(lf logFile, offset, lines int64, progress func(int64)) (int64, int64, error) {+ reader := bufio.NewReaderSize(io.NewSectionReader(lf.f, offset, lf.size-offset), 256*1024)+ source := eventSource{path: lf.path, archive: lf.archive}+ key := lf.key()+ pos := offset+ var read int64+ for {+ line, err := reader.ReadBytes('\n')+ if err == io.EOF {+ break+ }+ if err != nil {+ return 0, 0, err+ }+ start := pos+ pos += int64(len(line))+ read += int64(len(line))+ lines+++ if progress != nil && lines%2000 == 0 {+ progress(read)+ }+ trimmed := bytes.TrimSpace(line)+ if len(trimmed) == 0 || len(trimmed) > historyMaxLineBytes {+ continue+ }+ var event schema.Event+ if err := json.Unmarshal(trimmed, &event); err != nil {+ continue+ }+ normalizeDashboardEvent(&event)+ record := EventRecord{ID: source.lineID(int(lines)), Line: int(lines), Event: event, Raw: trimmed}+ if err := p.add(key, start, record); err != nil {+ return 0, 0, err+ }+ }+ if progress != nil {+ progress(read)+ }+ return pos, lines, nil+}++// historyRow is what the store derives from one event, apart from its place in the trace.+type historyRow struct {+ traceKey string+ eventType string+ eventID string+ tsNS int64+ order historyOrder+ spanID string+ parentSpanID string+ otelTraceID string+ spanName string+ hay string+}++// deriveRow computes an event's trace and every derived column the way the JSONL path would. The+// event number is not among them: it is the event's place in its trace, set when the trace folds.+func deriveRow(record EventRecord) historyRow {+ event := record.Event+ te := traceEventFromRecord(record, 0)+ row := historyRow{+ traceKey: traceProjectionID(event),+ eventType: te.Type,+ eventID: te.ID,+ tsNS: timeKey(event.Timestamp),+ order: historyOrder{ts: orderTime(event.Timestamp), seq: event.Sequence},+ hay: strings.ToLower(traceEventHaystack(te)),+ }+ if te.Trace != nil && te.Trace.SpanID != "" {+ row.spanID = te.Trace.SpanID+ row.parentSpanID = te.Trace.ParentSpanID+ row.otelTraceID = te.Trace.ID+ row.spanName = firstNonEmpty(te.Summary, te.Title, te.Action)+ }+ return row+}++func (p *historyPass) add(fileKey string, offset int64, record EventRecord) error {+ row := deriveRow(record)+ stored, err := storedLine(record.Raw)+ if err != nil {+ return err+ }+ result, err := p.insertEvent.Exec(p.sourceID, fileKey, offset, record.ID, row.traceKey, row.eventType, row.eventID, row.tsNS,+ row.order.ts, int64(row.order.seq), row.spanID, row.parentSpanID, row.otelTraceID, row.spanName, row.hay, compressLine(stored))+ if err != nil {+ return err+ }+ if n, err := result.RowsAffected(); err != nil || n == 0 {+ // Already stored: a checkpoint lost after a crash re-reads lines the store has.+ return err+ }+ id, err := result.LastInsertId()+ if err != nil {+ return err+ }+ if _, err := p.insertFTS.Exec(id, row.hay); err != nil {+ return err+ }+ row.order.id = id+ p.pending[row.traceKey] = append(p.pending[row.traceKey], &historyEvent{id: id, order: row.order, recordID: record.ID, event: record.Event})+ p.pendingN+++ if p.pendingN >= historyFlushEvery {+ return p.flush()+ }+ return nil+}++// flush folds every pending event into its trace.+func (p *historyPass) flush() error {+ keys := make([]string, 0, len(p.pending))+ for key := range p.pending {+ keys = append(keys, key)+ }+ sort.Strings(keys)+ for _, key := range keys {+ if err := p.foldTrace(key, p.pending[key]); err != nil {+ return err+ }+ }+ p.pending = map[string][]*historyEvent{}+ p.pendingN = 0+ return nil+}++type historyTraceState struct {+ id int64+ exists bool+ count int+ aggregate string+ hay string+}++func (p *historyPass) traceState(traceKey string) (historyTraceState, error) {+ var state historyTraceState+ err := p.tx.QueryRow(`SELECT id, event_count, aggregate, hay FROM traces WHERE source_id = ? AND trace_key = ?`, p.sourceID, traceKey).+ Scan(&state.id, &state.count, &state.aggregate, &state.hay)+ if err == sql.ErrNoRows {+ return historyTraceState{}, nil+ }+ state.exists = err == nil+ return state, err+}++// foldTrace places new events in their trace and brings the trace's summary up to date. New events+// that all sort after the trace's last event are folded onto its stored aggregate. Otherwise the+// trace is refolded from the last checkpoint before the earliest of them, renumbering the events+// after it.+func (p *historyPass) foldTrace(traceKey string, added []*historyEvent) error {+ sort.Slice(added, func(i, j int) bool { return added[i].order.less(added[j].order) })+ state, err := p.traceState(traceKey)+ if err != nil {+ return err+ }+ var agg *traceAggregate+ base := 0+ var existing []*historyEvent+ if state.exists {+ position, err := p.insertionPoint(traceKey, added[0].order)+ if err != nil {+ return err+ }+ if position > state.count {+ if agg, err = decodeTraceAggregate(state.aggregate); err != nil {+ return err+ }+ base = state.count+ } else {+ var checkpoint string+ err := p.tx.QueryRow(`SELECT seq, state FROM trace_checkpoints WHERE source_id = ? AND trace_key = ? AND seq < ? ORDER BY seq DESC LIMIT 1`,+ p.sourceID, traceKey, position).Scan(&base, &checkpoint)+ switch {+ case err == sql.ErrNoRows:+ base = 0+ case err != nil:+ return err+ default:+ if agg, err = decodeTraceAggregate(checkpoint); err != nil {+ return err+ }+ }+ if _, err := p.tx.Exec(`DELETE FROM trace_checkpoints WHERE source_id = ? AND trace_key = ? AND seq > ?`, p.sourceID, traceKey, base); err != nil {+ return err+ }+ if existing, err = p.storedEvents(traceKey, base); err != nil {+ return err+ }+ }+ }+ folder := &traceFolder{pass: p, traceKey: traceKey, agg: agg, seq: base}+ i, j := 0, 0+ for i < len(existing) || j < len(added) {+ var next *historyEvent+ if j >= len(added) || (i < len(existing) && existing[i].order.less(added[j].order)) {+ next = existing[i]+ i+++ } else {+ next = added[j]+ j+++ }+ if err := folder.fold(next); err != nil {+ return err+ }+ }+ return folder.finish(state)+}++// insertionPoint is where an event with the given order lands among the trace's stored events:+// one past the last stored event that sorts before it. Late events land near the end, so the scan+// runs backwards from there.+func (p *historyPass) insertionPoint(traceKey string, order historyOrder) (int, error) {+ rows, err := p.tx.Query(`SELECT seq, ord_ts, ord_seq, id FROM events WHERE source_id = ? AND trace_key = ? AND seq > 0 ORDER BY seq DESC`, p.sourceID, traceKey)+ if err != nil {+ return 0, err+ }+ defer rows.Close()+ for rows.Next() {+ var seq int+ var stored historyOrder+ var ordSeq int64+ if err := rows.Scan(&seq, &stored.ts, &ordSeq, &stored.id); err != nil {+ return 0, err+ }+ stored.seq = uint64(ordSeq)+ if stored.less(order) {+ return seq + 1, rows.Err()+ }+ }+ return 1, rows.Err()+}++// storedEvents loads the trace's events after position base, in order, to be refolded.+func (p *historyPass) storedEvents(traceKey string, base int) ([]*historyEvent, error) {+ rows, err := p.tx.Query(`SELECT id, seq, ord_ts, ord_seq, record_id, line FROM events WHERE source_id = ? AND trace_key = ? AND seq > ? ORDER BY seq`,+ p.sourceID, traceKey, base)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ var out []*historyEvent+ for rows.Next() {+ ev := &historyEvent{}+ var ordSeq int64+ var line []byte+ if err := rows.Scan(&ev.id, &ev.seq, &ev.order.ts, &ordSeq, &ev.recordID, &line); err != nil {+ return nil, err+ }+ ev.order.seq = uint64(ordSeq)+ ev.order.id = ev.id+ if ev.event, err = decodeStoredEvent(line); err != nil {+ return nil, err+ }+ out = append(out, ev)+ }+ return out, rows.Err()+}++func decodeStoredEvent(compressed []byte) (schema.Event, error) {+ raw, err := decompressLine(compressed)+ if err != nil {+ return schema.Event{}, err+ }+ var event schema.Event+ if err := json.Unmarshal(raw, &event); err != nil {+ return schema.Event{}, err+ }+ normalizeDashboardEvent(&event)+ return event, nil+}++// traceFolder runs readTraceAggregates' fold over one trace's events in order, numbering them,+// saving a checkpoint every historyCheckpointEvery events, and writing the summary at the end.+type traceFolder struct {+ pass *historyPass+ traceKey string+ agg *traceAggregate+ seq int+}++func (f *traceFolder) fold(ev *historyEvent) error {+ f.seq+++ if f.agg == nil {+ f.agg = newTraceAggregate(f.traceKey, ev.event)+ }+ te := traceEventFromRecord(EventRecord{ID: ev.recordID, Event: ev.event}, f.seq)+ f.agg.update(ev.event, te)+ if ev.seq != f.seq {+ if _, err := f.pass.updateSeq.Exec(f.seq, ev.id); err != nil {+ return err+ }+ ev.seq = f.seq+ }+ if f.seq%historyCheckpointEvery == 0 {+ state, err := json.Marshal(f.agg.state())+ if err != nil {+ return err+ }+ if _, err := f.pass.tx.Exec(`INSERT INTO trace_checkpoints (source_id, trace_key, seq, state) VALUES (?, ?, ?, ?)+ ON CONFLICT (source_id, trace_key, seq) DO UPDATE SET state = excluded.state`, f.pass.sourceID, f.traceKey, f.seq, string(state)); err != nil {+ return err+ }+ }+ return nil+}++func (f *traceFolder) finish(previous historyTraceState) error {+ p := f.pass+ summary := f.agg.finishedSummary()+ hay := strings.ToLower(traceSummaryHaystack(summary))+ state, err := json.Marshal(f.agg.state())+ if err != nil {+ return err+ }+ updated := timeKey(summary.UpdatedAt)+ retain := updated+ if retain <= math.MinInt64+1 {+ retain = time.Now().UnixNano()+ }+ if previous.exists {+ if _, err := p.tx.Exec(`INSERT INTO trace_fts (trace_fts, rowid, hay) VALUES ('delete', ?, ?)`, previous.id, previous.hay); err != nil {+ return err+ }+ if _, err := p.tx.Exec(`UPDATE traces SET started_ns = ?, updated_ns = ?, retain_ns = ?, state = ?, visibility = ?, event_count = ?, aggregate = ?, hay = ? WHERE id = ?`,+ timeKey(summary.StartedAt), updated, retain, summary.Sharing.State, summary.Sharing.Visibility, f.seq, string(state), hay, previous.id); err != nil {+ return err+ }+ _, err := p.tx.Exec(`INSERT INTO trace_fts (rowid, hay) VALUES (?, ?)`, previous.id, hay)+ return err+ }+ result, err := p.tx.Exec(`INSERT INTO traces (source_id, trace_key, started_ns, updated_ns, retain_ns, state, visibility, event_count, aggregate, hay) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,+ p.sourceID, f.traceKey, timeKey(summary.StartedAt), updated, retain, summary.Sharing.State, summary.Sharing.Visibility, f.seq, string(state), hay)+ if err != nil {+ return err+ }+ id, err := result.LastInsertId()+ if err != nil {+ return err+ }+ _, err = p.tx.Exec(`INSERT INTO trace_fts (rowid, hay) VALUES (?, ?)`, id, hay)+ return err+}++// traceAggregateState is a trace's running aggregate between catch-ups: the summary before finish()+// and the sets finish() reads. finish() runs on a copy each time a summary is read, so it never+// feeds back into the running state.+type traceAggregateState struct {+ Summary TraceSummaryV1 `json:"summary"`+ Models []string `json:"models,omitempty"`+ Methods []string `json:"methods,omitempty"`+ TitlePriority int `json:"title_priority"`+}++func (a *traceAggregate) state() traceAggregateState {+ return traceAggregateState{+ Summary: a.summary,+ Models: sortedKeys(a.models),+ Methods: sortedKeys(a.methods),+ TitlePriority: a.titlePriority,+ }+}++func decodeTraceAggregate(raw string) (*traceAggregate, error) {+ var state traceAggregateState+ if err := json.Unmarshal([]byte(raw), &state); err != nil {+ return nil, err+ }+ agg := &traceAggregate{+ summary: state.Summary,+ spans: map[string]*TraceSpanV1{},+ models: map[string]bool{},+ methods: map[string]bool{},+ titlePriority: state.TitlePriority,+ }+ for _, model := range state.Models {+ agg.models[model] = true+ }+ for _, method := range state.Methods {+ agg.methods[method] = true+ }+ return agg, nil+}++func (a *traceAggregate) finishedSummary() TraceSummaryV1 {+ copied := *a+ copied.finish()+ return copied.summary+}++func finishedSummaryFromState(raw string) (TraceSummaryV1, error) {+ agg, err := decodeTraceAggregate(raw)+ if err != nil {+ return TraceSummaryV1{}, err+ }+ return agg.finishedSummary(), nil+}++// rebuildHistoryDerived recomputes every derived column, the search index and the summaries from+// the stored lines, for a store written by an older projection.+func rebuildHistoryDerived(tx *sql.Tx) error {+ for _, stmt := range []string{+ `INSERT INTO event_fts (event_fts) VALUES ('delete-all')`,+ `INSERT INTO trace_fts (trace_fts) VALUES ('delete-all')`,+ `DELETE FROM traces`,+ `DELETE FROM trace_checkpoints`,+ } {+ if _, err := tx.Exec(stmt); err != nil {+ return err+ }+ }+ update, err := tx.Prepare(`UPDATE events SET trace_key = ?, seq = 0, event_type = ?, event_id = ?, ts_ns = ?, ord_ts = ?, ord_seq = ?,+ span_id = ?, parent_span_id = ?, otel_trace_id = ?, span_name = ?, hay = ? WHERE id = ?`)+ if err != nil {+ return err+ }+ defer update.Close()+ insertFTS, err := tx.Prepare(`INSERT INTO event_fts (rowid, hay) VALUES (?, ?)`)+ if err != nil {+ return err+ }+ defer insertFTS.Close()+ // First every event's derived columns, which may move it to another trace.+ var last int64+ for {+ rows, err := tx.Query(`SELECT id, record_id, line FROM events WHERE id > ? ORDER BY id LIMIT 2000`, last)+ if err != nil {+ return err+ }+ type stored struct {+ id int64+ recordID string+ line []byte+ }+ var batch []stored+ for rows.Next() {+ var row stored+ if err := rows.Scan(&row.id, &row.recordID, &row.line); err != nil {+ rows.Close()+ return err+ }+ batch = append(batch, row)+ }+ if err := rows.Close(); err != nil {+ return err+ }+ if len(batch) == 0 {+ break+ }+ for _, row := range batch {+ last = row.id+ event, err := decodeStoredEvent(row.line)+ if err != nil {+ return err+ }+ derived := deriveRow(EventRecord{ID: row.recordID, Event: event})+ if _, err := update.Exec(derived.traceKey, derived.eventType, derived.eventID, derived.tsNS, derived.order.ts, int64(derived.order.seq),+ derived.spanID, derived.parentSpanID, derived.otelTraceID, derived.spanName, derived.hay, row.id); err != nil {+ return err+ }+ if _, err := insertFTS.Exec(row.id, derived.hay); err != nil {+ return err+ }+ }+ }+ // Then every trace folded from its first event.+ rows, err := tx.Query(`SELECT DISTINCT source_id, trace_key FROM events ORDER BY source_id, trace_key`)+ if err != nil {+ return err+ }+ type traceRef struct {+ sourceID int64+ traceKey string+ }+ var traces []traceRef+ for rows.Next() {+ var ref traceRef+ if err := rows.Scan(&ref.sourceID, &ref.traceKey); err != nil {+ rows.Close()+ return err+ }+ traces = append(traces, ref)+ }+ if err := rows.Close(); err != nil {+ return err+ }+ for _, ref := range traces {+ pass, err := newHistoryPass(tx, ref.sourceID)+ if err != nil {+ return err+ }+ events, err := pass.storedEventsInOrder(ref.traceKey)+ if err == nil && len(events) > 0 {+ folder := &traceFolder{pass: pass, traceKey: ref.traceKey}+ for _, ev := range events {+ if err = folder.fold(ev); err != nil {+ break+ }+ }+ if err == nil {+ err = folder.finish(historyTraceState{})+ }+ }+ pass.close()+ if err != nil {+ return err+ }+ }+ _, err = tx.Exec(`INSERT INTO meta (key, value) VALUES ('derivation_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`,+ strconv.Itoa(historyDerivationVersion))+ return err+}++// storedEventsInOrder loads every event of a trace in trace order, for a rebuild.+func (p *historyPass) storedEventsInOrder(traceKey string) ([]*historyEvent, error) {+ rows, err := p.tx.Query(`SELECT id, ord_ts, ord_seq, record_id, line FROM events WHERE source_id = ? AND trace_key = ?`, p.sourceID, traceKey)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ var out []*historyEvent+ for rows.Next() {+ ev := &historyEvent{}+ var ordSeq int64+ var line []byte+ if err := rows.Scan(&ev.id, &ev.order.ts, &ordSeq, &ev.recordID, &line); err != nil {+ return nil, err+ }+ ev.order.seq = uint64(ordSeq)+ ev.order.id = ev.id+ if ev.event, err = decodeStoredEvent(line); err != nil {+ return nil, err+ }+ out = append(out, ev)+ }+ if err := rows.Err(); err != nil {+ return nil, err+ }+ sort.Slice(out, func(i, j int) bool { return out[i].order.less(out[j].order) })+ return out, nil+}++// pruneHistory drops whole traces: first those whose last event is older than the retention+// period, then the oldest until the store fits its size cap. A trace is never cut in part, so the+// event numbers of what remains do not move.+func pruneHistory(tx *sql.Tx, now time.Time, retentionDays, maxBytes int64) (bool, error) {+ pruned := false+ cutoff := now.Add(-time.Duration(retentionDays) * 24 * time.Hour).UnixNano()+ expired, err := historyTraceRows(tx, `SELECT id, source_id, trace_key FROM traces WHERE retain_ns < ? ORDER BY retain_ns`, cutoff)+ if err != nil {+ return false, err+ }+ for _, row := range expired {+ if err := deleteHistoryTrace(tx, row); err != nil {+ return false, err+ }+ pruned = true+ }+ // Over the cap, drop the oldest traces until the store is back to four fifths of it, so pruning+ // runs once per fifth of the cap rather than on every catch-up. Deleted rows leave markers in+ // the search index until its segments merge, so the index is merged once after the deletes;+ // the freed pages go back to the file system when the caller vacuums after commit.+ for attempt := 0; attempt < 4; attempt++ {+ used, err := historyUsedBytes(tx)+ if err != nil {+ return false, err+ }+ if used <= maxBytes {+ return pruned, nil+ }+ var totalEvents int64+ if err := tx.QueryRow(`SELECT COALESCE(SUM(event_count), 0) FROM traces`).Scan(&totalEvents); err != nil {+ return false, err+ }+ if totalEvents == 0 {+ return pruned, nil+ }+ // Events are most of the store, so a trace's share of the events estimates its share of the+ // bytes.+ excess := used - maxBytes*4/5+ eventsToFree := (excess*totalEvents + used - 1) / used+ oldest, err := historyOldestTraces(tx, eventsToFree)+ if err != nil {+ return false, err+ }+ if len(oldest) == 0 {+ return pruned, nil+ }+ for _, row := range oldest {+ if err := deleteHistoryTrace(tx, row); err != nil {+ return false, err+ }+ }+ pruned = true+ for _, stmt := range []string{+ `INSERT INTO event_fts (event_fts) VALUES ('optimize')`,+ `INSERT INTO trace_fts (trace_fts) VALUES ('optimize')`,+ } {+ if _, err := tx.Exec(stmt); err != nil {+ return false, err+ }+ }+ }+ return pruned, nil+}++// historyOldestTraces returns the oldest traces holding at least events events between them.+func historyOldestTraces(tx *sql.Tx, events int64) ([]historyTraceRow, error) {+ rows, err := tx.Query(`SELECT id, source_id, trace_key, event_count FROM traces ORDER BY retain_ns, id`)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ var out []historyTraceRow+ var total int64+ for total < events && rows.Next() {+ var row historyTraceRow+ var count int64+ if err := rows.Scan(&row.id, &row.sourceID, &row.traceKey, &count); err != nil {+ return nil, err+ }+ out = append(out, row)+ total += count+ }+ return out, rows.Err()+}++type historyTraceRow struct {+ id int64+ sourceID int64+ traceKey string+}++func historyTraceRows(tx *sql.Tx, query string, args ...any) ([]historyTraceRow, error) {+ rows, err := tx.Query(query, args...)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ var out []historyTraceRow+ for rows.Next() {+ var row historyTraceRow+ if err := rows.Scan(&row.id, &row.sourceID, &row.traceKey); err != nil {+ return nil, err+ }+ out = append(out, row)+ }+ return out, rows.Err()+}++func deleteHistoryTrace(tx *sql.Tx, trace historyTraceRow) error {+ rows, err := tx.Query(`SELECT id, hay FROM events WHERE source_id = ? AND trace_key = ?`, trace.sourceID, trace.traceKey)+ if err != nil {+ return err+ }+ type ftsRow struct {+ id int64+ hay string+ }+ var events []ftsRow+ for rows.Next() {+ var row ftsRow+ if err := rows.Scan(&row.id, &row.hay); err != nil {+ rows.Close()+ return err+ }+ events = append(events, row)+ }+ if err := rows.Close(); err != nil {+ return err+ }+ for _, row := range events {+ if _, err := tx.Exec(`INSERT INTO event_fts (event_fts, rowid, hay) VALUES ('delete', ?, ?)`, row.id, row.hay); err != nil {+ return err+ }+ }+ if _, err := tx.Exec(`DELETE FROM events WHERE source_id = ? AND trace_key = ?`, trace.sourceID, trace.traceKey); err != nil {+ return err+ }+ var hay string+ if err := tx.QueryRow(`SELECT hay FROM traces WHERE id = ?`, trace.id).Scan(&hay); err != nil {+ return err+ }+ if _, err := tx.Exec(`INSERT INTO trace_fts (trace_fts, rowid, hay) VALUES ('delete', ?, ?)`, trace.id, hay); err != nil {+ return err+ }+ if _, err := tx.Exec(`DELETE FROM trace_checkpoints WHERE source_id = ? AND trace_key = ?`, trace.sourceID, trace.traceKey); err != nil {+ return err+ }+ _, err = tx.Exec(`DELETE FROM traces WHERE id = ?`, trace.id)+ return err+}++// historyUsedBytes is the space the store's live pages take, which pruning can reduce inside the+// transaction; the file shrinks to match once the freed pages are vacuumed after commit.+func historyUsedBytes(tx *sql.Tx) (int64, error) {+ var pages, free, size int64+ if err := tx.QueryRow(`PRAGMA page_count`).Scan(&pages); err != nil {+ return 0, err+ }+ if err := tx.QueryRow(`PRAGMA freelist_count`).Scan(&free); err != nil {+ return 0, err+ }+ if err := tx.QueryRow(`PRAGMA page_size`).Scan(&size); err != nil {+ return 0, err+ }+ return (pages - free) * size, nil+}++// hasExpiredTraces reports whether any trace is past retention, so an idle log still has its old+// history pruned on schedule.+func (s *historyStore) hasExpiredTraces(now time.Time) (bool, error) {+ days := s.metaInt("retention_days", defaultHistoryRetentionDays)+ cutoff := now.Add(-time.Duration(days) * 24 * time.Hour).UnixNano()+ var oldest sql.NullInt64+ if err := s.db.QueryRow(`SELECT MIN(retain_ns) FROM traces`).Scan(&oldest); err != nil {+ return false, err+ }+ return oldest.Valid && oldest.Int64 < cutoff, nil+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_line.go b/cli/beacon/internal/endpoint/dashboard/history_line.gonew file mode 100644index 00000000..0fb3f994--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_line.go@@ -0,0 +1,97 @@+package dashboard++import (+ "bytes"+ "compress/flate"+ "encoding/json"+ "io"+ "sync"+)++// historyRawKeys are the keys of an event's raw payload that the trace projection reads. The raw+// payload is the runtime's own record of the event, usually as large as everything else in the+// line together, and the rest of the event already holds what Beacon kept from it, redacted and+// bounded. The store keeps these keys and drops the rest, which halves what it stores. A test fails+// if the dashboard package reads a raw key that is missing here.+var historyRawKeys = map[string]bool{+ "first_prompt": true,+ "last_refreshed_at": true,+ "metric_name": true,+ "namespace_id": true,+ "namespace_name": true,+ "namespace_slug": true,+ "remote_ai_title": true,+ "remote_event_count": true,+ "remote_message_count": true,+ "remote_title": true,+ "shared_at": true,+ "shared_event_count": true,+ "shared_url": true,+ "shared_visibility": true,+ "sharedUrl": true,+ "synced_at": true,+ "visibility": true,+}++// storedLine is the line the store keeps for an event: every field of the log line except the+// parts of raw the projection never reads. Fields this Beacon version does not know stay, so a+// later version that reads them can rebuild from the store.+func storedLine(line []byte) ([]byte, error) {+ var fields map[string]json.RawMessage+ if err := json.Unmarshal(line, &fields); err != nil {+ return nil, err+ }+ if raw, ok := fields["raw"]; ok {+ var values map[string]json.RawMessage+ if err := json.Unmarshal(raw, &values); err == nil {+ kept := map[string]json.RawMessage{}+ for key, value := range values {+ if historyRawKeys[key] {+ kept[key] = value+ }+ }+ if len(kept) == 0 {+ delete(fields, "raw")+ } else if encoded, err := json.Marshal(kept); err == nil {+ fields["raw"] = encoded+ }+ }+ }+ return json.Marshal(fields)+}++// historyLineDictionary primes the compressor with the shape of a Beacon event, so each stored line+// compresses on its own as well as a run of lines would. Lines are stored with sorted keys, the+// order storedLine marshals them in, and so is this.+//+// Stored lines can only be read with the dictionary they were written with, so this text must never+// change. A different dictionary is a new historyLineCodec, with a migration.+const historyLineDictionary = `{"branch":"main","command":{"command":"go test ./...","duration_ms":12,"exit_code":0,"output":""},"content":{"bytes":1174,"hash":"68924de4069ab59e961113ef4e90fb8db4215cb3f9cb611438d2ebbc38e48461","included":true,"retention":"full"},"endpoint":{"hostname":"Mac","os":"darwin"},"event":{"action":"prompt.submitted","category":"prompt","fidelity":"observed","id":"228a0964-3886-536e-ac8d-f32435cb4172","kind":"agent_runtime"},"gen_ai":{"input":{"messages":[{"parts":[{"content":"","type":"text"}],"role":"user"}]}},"harness":{"collection_method":"hook","name":"claude_code","version":"2.1.270"},"message":"claude_code.user_prompt","product":"endpoint-agent","prompt":{"text":""},"repository":"agent-beacon","schema_version":"1.0","sequence":29600,"session":{"id":"8d035bed-4d8d-4966-9a97-bf237e9b2e31","working_directory":"/Users/"},"severity":"info","timestamp":"2026-09-22T21:08:52.347000000Z","trace":{"id":"session:claude_code:8d035bed-4d8d-4966-9a97-bf237e9b2e31","parent_span_id":"","span_id":""},"user":{"name":""},"vendor":"beacon"}+{"endpoint":{"hostname":"Mac","os":"darwin"},"event":{"action":"session.activity","category":"session","fidelity":"observed","id":"c49c4cc0-413e-5e16-9a24-6466315fca40","kind":"agent_runtime"},"harness":{"collection_method":"otlp","name":"claude_code","version":"2.1.270"},"message":"claude_code.hook_execution_complete","product":"endpoint-agent","schema_version":"1.0","sequence":1438,"session":{"id":"fcf451af-d600-48c9-9bf1-649471e70bf5"},"severity":"info","timestamp":"2026-09-22T20:59:13.412000000Z","user":{"name":""},"vendor":"beacon"}+{"endpoint":{"hostname":"Mac","os":"darwin"},"event":{"action":"token.usage","category":"metric","fidelity":"observed","id":"fd994f18-70ae-561c-b31c-9dbd6ea7ad06","kind":"agent_runtime"},"gen_ai":{"token":{"type":"input"},"usage":{"cache_creation":{"input_tokens":0},"cache_read":{"input_tokens":0},"cost_usd":0.0123,"input_tokens":52,"output_tokens":0}},"harness":{"collection_method":"otlp","name":"claude_code","version":"2.1.270"},"message":"claude_code.token.usage","model":"claude-opus-5[1m]","product":"endpoint-agent","raw":{"metric_name":"claude_code.cost.usage"},"schema_version":"1.0","sequence":1807,"session":{"id":""},"severity":"info","timestamp":"2026-09-22T20:59:41.577000000Z","user":{"name":""},"vendor":"beacon"}+{"approval":{"decision":"allowed","reason":"","required":true},"branch":"main","command":{"command":""},"endpoint":{"hostname":"Mac","os":"darwin"},"event":{"action":"approval.allowed","category":"approval","fidelity":"inferred","id":"","kind":"agent_runtime"},"gen_ai":{"tool":{"call":{"arguments":{"command":"","description":""},"id":"toolu_01S5orE4VdnGrQNVfd8BvmW1"},"name":"Bash"}},"harness":{"collection_method":"hook","name":"codex_cli","version":""},"message":"Tool execution observed","product":"endpoint-agent","repository":"","schema_version":"1.0","sequence":0,"session":{"id":"","working_directory":""},"severity":"info","timestamp":"","tool":{"command":"","name":"Bash","path":""},"trace":{"id":"","parent_span_id":"","span_id":""},"user":{"name":""},"vendor":"beacon"}+{"branch":"main","endpoint":{"hostname":"Mac","os":"darwin"},"event":{"action":"command.executed","category":"command","fidelity":"observed","id":"999d2760-4edd-505e-91f9-d2fcf0ec9f72","kind":"agent_runtime"},"file":{"diff":"","language":"go","operation":"modify","path":""},"gen_ai":{"output":{"messages":[{"parts":[{"content":"","type":"text"}],"role":"assistant"}]},"tool":{"call":{"id":"call_","result":""},"name":"shell"}},"harness":{"collection_method":"otlp","name":"cursor","version":""},"mcp":{"method":{"name":"tools/call"},"server":"","tool":""},"message":"claude_code.tool_result","product":"endpoint-agent","repository":"","schema_version":"1.0","sequence":1437,"session":{"id":"999d2760-4edd-505e-91f9-d2fcf0ec9f72"},"severity":"info","timestamp":"2026-09-22T20:59:13.412000000Z","tool":{"command":"","name":"Bash"},"trace":{"id":"","parent_span_id":"","span_id":""},"user":{"name":""},"vendor":"beacon"}`++// historyLineCodec names how stored lines are encoded, recorded in the store's meta table.+const historyLineCodec = "flate-dict-1"++var historyWriters = sync.Pool{New: func() any {+ w, _ := flate.NewWriterDict(io.Discard, flate.DefaultCompression, []byte(historyLineDictionary))+ return w+}}++func compressLine(line []byte) []byte {+ var buf bytes.Buffer+ w := historyWriters.Get().(*flate.Writer)+ w.Reset(&buf)+ _, _ = w.Write(line)+ _ = w.Close()+ historyWriters.Put(w)+ return buf.Bytes()+}++func decompressLine(data []byte) ([]byte, error) {+ r := flate.NewReaderDict(bytes.NewReader(data), []byte(historyLineDictionary))+ defer r.Close()+ return io.ReadAll(r)+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_query.go b/cli/beacon/internal/endpoint/dashboard/history_query.gonew file mode 100644index 00000000..21a85206--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_query.go@@ -0,0 +1,502 @@+package dashboard++import (+ "database/sql"+ "encoding/json"+ "strings"+ "unicode/utf8"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+)++// historyList, historySearch and historyShow answer a trace query from the local history, or+// return an error that sends the caller to the JSONL scan: the store is not set up, the query uses+// a filter the store does not index, or the store could not be read.+func historyList(logPath string, query TraceQuery) (TraceListResultV1, error) {+ if !traceStoreSupportsQuery(query) {+ return TraceListResultV1{}, errTraceStoreUnsupported+ }+ store, sourceID, err := openCaughtUpHistory(logPath)+ if err != nil {+ return TraceListResultV1{}, err+ }+ defer store.close()+ return store.list(sourceID, query)+}++func historySearch(logPath string, query TraceQuery) (TraceSearchResultV1, error) {+ if !traceStoreSupportsQuery(query) {+ return TraceSearchResultV1{}, errTraceStoreUnsupported+ }+ store, sourceID, err := openCaughtUpHistory(logPath)+ if err != nil {+ return TraceSearchResultV1{}, err+ }+ defer store.close()+ return store.search(sourceID, query)+}++func historyShow(logPath, id string, query TraceQuery) (TraceShowResultV1, bool, error) {+ if !traceStoreSupportsQuery(query) {+ return TraceShowResultV1{}, false, errTraceStoreUnsupported+ }+ store, sourceID, err := openCaughtUpHistory(logPath)+ if err != nil {+ return TraceShowResultV1{}, false, err+ }+ defer store.close()+ return store.show(sourceID, id, query)+}++func openCaughtUpHistory(logPath string) (*historyStore, int64, error) {+ store, err := openHistoryStore(false)+ if err != nil {+ return nil, 0, err+ }+ sourceID, err := store.catchUp(logPath, nil, false)+ if err != nil {+ store.close()+ return nil, 0, err+ }+ return store, sourceID, nil+}++// traceStoreSupportsQuery reports whether the store can answer a query. The store indexes free+// text, sharing state and visibility; any other event filter is answered by the JSONL scan.+func traceStoreSupportsQuery(query TraceQuery) bool {+ eq := query.EventQuery+ return eq.Since.IsZero() &&+ eq.Until.IsZero() &&+ eq.Harness == "" &&+ eq.Model == "" &&+ eq.Action == "" &&+ eq.Severity == "" &&+ eq.Category == "" &&+ eq.Repository == "" &&+ eq.Session == "" &&+ eq.Trace == "" &&+ eq.File == "" &&+ eq.Command == "" &&+ eq.MCP == "" &&+ eq.Approval == "" &&+ eq.Decision == "" &&+ eq.Policy == "" &&+ eq.Review == "" &&+ eq.WazuhLevel == "" &&+ eq.SessionState == ""+}++// textMatch turns a free-text query into SQL that selects exactly what matchesAllTerms selects.+// Terms of three or more characters go to the trigram index, where a quoted term matches the rows+// that contain it as a substring. Shorter terms have no trigram, so they are checked with instr()+// on the stored haystack, which the index text is also built from.+type textMatch struct {+ long []string+ short []string+}++func newTextMatch(q string) textMatch {+ var m textMatch+ for _, term := range strings.Fields(strings.ToLower(q)) {+ if utf8.RuneCountInString(term) >= 3 {+ m.long = append(m.long, term)+ } else {+ m.short = append(m.short, term)+ }+ }+ return m+}++func (m textMatch) empty() bool {+ return len(m.long) == 0 && len(m.short) == 0+}++func ftsPhrases(terms []string) string {+ quoted := make([]string, len(terms))+ for i, term := range terms {+ quoted[i] = `"` + strings.ReplaceAll(term, `"`, `""`) + `"`+ }+ return strings.Join(quoted, " ")+}++// condition returns a WHERE fragment over alias (a row of table, whose FTS table is fts).+func (m textMatch) condition(alias, fts string) (string, []any) {+ var parts []string+ var args []any+ if len(m.long) > 0 {+ parts = append(parts, alias+".id IN (SELECT rowid FROM "+fts+" WHERE "+fts+" MATCH ?)")+ args = append(args, ftsPhrases(m.long))+ }+ for _, term := range m.short {+ parts = append(parts, "instr("+alias+".hay, ?) > 0")+ args = append(args, term)+ }+ if len(parts) == 0 {+ return "1", nil+ }+ return strings.Join(parts, " AND "), args+}++func sharingCondition(alias string, query TraceQuery) (string, []any) {+ var parts []string+ var args []any+ if query.State != "" {+ parts = append(parts, alias+".state = ? COLLATE NOCASE")+ args = append(args, query.State)+ }+ if query.Visibility != "" {+ parts = append(parts, alias+".visibility = ? COLLATE NOCASE")+ args = append(args, query.Visibility)+ }+ if len(parts) == 0 {+ return "1", nil+ }+ return strings.Join(parts, " AND "), args+}++// list returns one page of traces, newest first. With free text it keeps a trace whose summary or+// any of its events match, as traceAggregateMatches does.+func (s *historyStore) list(sourceID int64, query TraceQuery) (TraceListResultV1, error) {+ match := newTextMatch(query.Q)+ sharing, sharingArgs := sharingCondition("t", query)+ where := "t.source_id = ? AND " + sharing+ args := append([]any{sourceID}, sharingArgs...)+ if !match.empty() {+ summaryCond, summaryArgs := match.condition("m", "trace_fts")+ eventCond, eventArgs := match.condition("e", "event_fts")+ where += ` AND t.trace_key IN (+ SELECT m.trace_key FROM traces m WHERE m.source_id = ? AND ` + summaryCond + `+ UNION+ SELECT e.trace_key FROM events e WHERE e.source_id = ? AND ` + eventCond + `)`+ args = append(args, sourceID)+ args = append(args, summaryArgs...)+ args = append(args, sourceID)+ args = append(args, eventArgs...)+ }+ var total int+ if err := s.db.QueryRow(`SELECT COUNT(*) FROM traces t WHERE `+where, args...).Scan(&total); err != nil {+ return TraceListResultV1{}, err+ }+ limit := normalizeLimit(query.Limit)+ page := query.Page+ if page <= 0 {+ page = 1+ }+ start := (page - 1) * limit+ if start > total {+ start = total+ }+ summaries, err := s.summaries(`SELECT t.aggregate FROM traces t WHERE `+where+` ORDER BY t.updated_ns DESC, t.trace_key ASC LIMIT ? OFFSET ?`,+ append(args, limit, start)...)+ if err != nil {+ return TraceListResultV1{}, err+ }+ end := start + len(summaries)+ return TraceListResultV1{+ Traces: summaries,+ TotalMatched: total,+ Returned: len(summaries),+ Limit: limit,+ Page: page,+ Truncated: end < total,+ Filters: activeTraceFilters(query),+ }, nil+}++func (s *historyStore) summaries(query string, args ...any) ([]TraceSummaryV1, error) {+ rows, err := s.db.Query(query, args...)+ if err != nil {+ return nil, err+ }+ defer rows.Close()+ out := []TraceSummaryV1{}+ for rows.Next() {+ var raw string+ if err := rows.Scan(&raw); err != nil {+ return nil, err+ }+ summary, err := finishedSummaryFromState(raw)+ if err != nil {+ return nil, err+ }+ out = append(out, summary)+ }+ return out, rows.Err()+}++func (s *historyStore) search(sourceID int64, query TraceQuery) (TraceSearchResultV1, error) {+ if query.ResultLevel == "" {+ query.ResultLevel = "trace"+ }+ limit := normalizeLimit(query.Limit)+ resp := TraceSearchResultV1{ResultLevel: query.ResultLevel, Limit: limit, Filters: activeTraceFilters(query)}+ match := newTextMatch(query.Q)+ sharing, sharingArgs := sharingCondition("t", query)+ if query.ResultLevel == "event" {+ return s.searchEvents(sourceID, query, match, sharing, sharingArgs, resp)+ }+ resp.ResultLevel = "trace"+ // Trace-level search matches the summary alone, as the JSONL path does with+ // traceSummaryMatches.+ cond, condArgs := match.condition("t", "trace_fts")+ where := "t.source_id = ? AND " + sharing + " AND " + cond+ args := append(append([]any{sourceID}, sharingArgs...), condArgs...)+ if err := s.db.QueryRow(`SELECT COUNT(*) FROM traces t WHERE `+where, args...).Scan(&resp.TotalMatched); err != nil {+ return TraceSearchResultV1{}, err+ }+ traces, err := s.summaries(`SELECT t.aggregate FROM traces t WHERE `+where+` ORDER BY t.updated_ns DESC, t.trace_key ASC LIMIT ?`, append(args, limit)...)+ if err != nil {+ return TraceSearchResultV1{}, err+ }+ if len(traces) > 0 {+ resp.Traces = traces+ }+ resp.Returned = len(traces)+ return resp, nil+}++type historyEventRef struct {+ id int64+ traceRow int64+ seq int+ eventType string+}++// searchEvents returns matching events across traces, newest trace first and in event order+// within a trace, counting every match and returning the first limit of them.+func (s *historyStore) searchEvents(sourceID int64, query TraceQuery, match textMatch, sharing string, sharingArgs []any, resp TraceSearchResultV1) (TraceSearchResultV1, error) {+ cond, condArgs := match.condition("e", "event_fts")+ args := append(append([]any{sourceID}, sharingArgs...), condArgs...)+ rows, err := s.db.Query(`SELECT e.id, t.id, e.seq, e.event_type+ FROM events e JOIN traces t ON t.source_id = e.source_id AND t.trace_key = e.trace_key+ WHERE e.source_id = ? AND `+sharing+` AND `+cond+`+ ORDER BY t.updated_ns DESC, t.trace_key ASC, e.seq ASC`, args...)+ if err != nil {+ return TraceSearchResultV1{}, err+ }+ allowed := traceEventTypeSet(query.EventTypes)+ var picked []historyEventRef+ for rows.Next() {+ var ref historyEventRef+ if err := rows.Scan(&ref.id, &ref.traceRow, &ref.seq, &ref.eventType); err != nil {+ rows.Close()+ return TraceSearchResultV1{}, err+ }+ if len(allowed) > 0 && !allowed[traceEventTypeAlias(ref.eventType)] && !allowed[strings.ToLower(ref.eventType)] {+ continue+ }+ resp.TotalMatched+++ if len(picked) < resp.Limit {+ picked = append(picked, ref)+ }+ }+ if err := rows.Close(); err != nil {+ return TraceSearchResultV1{}, err+ }+ summaries := map[int64]TraceSummaryV1{}+ needle := strings.TrimSpace(query.Q)+ for _, ref := range picked {+ summary, ok := summaries[ref.traceRow]+ if !ok {+ var raw string+ if err := s.db.QueryRow(`SELECT aggregate FROM traces WHERE id = ?`, ref.traceRow).Scan(&raw); err != nil {+ return TraceSearchResultV1{}, err+ }+ if summary, err = finishedSummaryFromState(raw); err != nil {+ return TraceSearchResultV1{}, err+ }+ summaries[ref.traceRow] = summary+ }+ event, err := s.loadTraceEvent(ref.id, ref.seq)+ if err != nil {+ return TraceSearchResultV1{}, err+ }+ resp.Events = append(resp.Events, TraceEventMatchV1{+ Trace: summary,+ Event: event,+ Snippet: traceSnippet(event, needle),+ Score: 1,+ })+ }+ resp.Returned = len(resp.Events)+ return resp, nil+}++// loadTraceEvent projects one stored event, numbered as it was when stored.+func (s *historyStore) loadTraceEvent(id int64, seq int) (TraceEventV1, error) {+ var recordID string+ var line []byte+ if err := s.db.QueryRow(`SELECT record_id, line FROM events WHERE id = ?`, id).Scan(&recordID, &line); err != nil {+ return TraceEventV1{}, err+ }+ return projectStoredEvent(recordID, line, seq)+}++func projectStoredEvent(recordID string, compressed []byte, seq int) (TraceEventV1, error) {+ raw, err := decompressLine(compressed)+ if err != nil {+ return TraceEventV1{}, err+ }+ var event schema.Event+ if err := json.Unmarshal(raw, &event); err != nil {+ return TraceEventV1{}, err+ }+ normalizeDashboardEvent(&event)+ return traceEventFromRecord(EventRecord{ID: recordID, Event: event, Raw: raw}, seq), nil+}++type historyShowRow struct {+ id int64+ seq int+ eventType string+ eventID string+ spanID string+ parentSpanID string+ otelTraceID string+ spanName string+}++func (s *historyStore) show(sourceID int64, id string, query TraceQuery) (TraceShowResultV1, bool, error) {+ var raw string+ err := s.db.QueryRow(`SELECT aggregate FROM traces WHERE source_id = ? AND trace_key = ?`, sourceID, id).Scan(&raw)+ if err == sql.ErrNoRows {+ return TraceShowResultV1{}, false, nil+ }+ if err != nil {+ return TraceShowResultV1{}, false, err+ }+ summary, err := finishedSummaryFromState(raw)+ if err != nil {+ return TraceShowResultV1{}, false, err+ }+ rows, err := s.db.Query(`SELECT id, seq, event_type, event_id, span_id, parent_span_id, otel_trace_id, span_name+ FROM events WHERE source_id = ? AND trace_key = ? ORDER BY seq`, sourceID, id)+ if err != nil {+ return TraceShowResultV1{}, false, err+ }+ allowed := traceEventTypeSet(query.EventTypes)+ var filtered []historyShowRow+ for rows.Next() {+ var row historyShowRow+ if err := rows.Scan(&row.id, &row.seq, &row.eventType, &row.eventID, &row.spanID, &row.parentSpanID, &row.otelTraceID, &row.spanName); err != nil {+ rows.Close()+ return TraceShowResultV1{}, false, err+ }+ if len(allowed) > 0 && !allowed[strings.ToLower(row.eventType)] && !allowed[traceEventTypeAlias(row.eventType)] {+ continue+ }+ filtered = append(filtered, row)+ }+ if err := rows.Close(); err != nil {+ return TraceShowResultV1{}, false, err+ }+ total := len(filtered)+ offset, limit := traceRange(query, total)+ end := offset - 1 + limit+ if end > total {+ end = total+ }+ if offset-1 > end {+ end = offset - 1+ }+ // nil rather than empty when the range is past the end, which is how both other paths encode it.+ var events []TraceEventV1+ for _, row := range filtered[offset-1 : end] {+ event, err := s.loadTraceEvent(row.id, row.seq)+ if err != nil {+ return TraceShowResultV1{}, false, err+ }+ events = append(events, event)+ }+ return TraceShowResultV1{+ Trace: summary,+ Events: events,+ Spans: historySpans(filtered),+ Range: TraceRangeV1{+ TotalEvents: total,+ ReturnedEvents: end - (offset - 1),+ Offset: offset,+ Limit: limit,+ AroundEvent: query.AroundEvent,+ },+ }, true, nil+}++// historySpans is spansFromEvents over stored rows, so show does not have to project every event+// of a long trace to list its spans.+func historySpans(rows []historyShowRow) []TraceSpanV1 {+ spans := map[string]*TraceSpanV1{}+ for _, row := range rows {+ if row.spanID == "" {+ continue+ }+ span := spans[row.spanID]+ if span == nil {+ span = &TraceSpanV1{ID: row.spanID, ParentSpanID: row.parentSpanID, TraceID: row.otelTraceID}+ spans[row.spanID] = span+ }+ if span.Name == "" {+ span.Name = row.spanName+ }+ span.EventIDs = append(span.EventIDs, row.eventID)+ }+ return traceSpanList(spans)+}++// spansFromEvents lists the spans of the given events, in the order traceSpanList sorts them. Both+// paths build show's spans from the events the query selected, so a type filter narrows the spans+// the same way whether the store or the JSONL scan answers.+func spansFromEvents(events []TraceEventV1) []TraceSpanV1 {+ spans := map[string]*TraceSpanV1{}+ for _, event := range events {+ if event.Trace == nil || event.Trace.SpanID == "" {+ continue+ }+ span := spans[event.Trace.SpanID]+ if span == nil {+ span = &TraceSpanV1{ID: event.Trace.SpanID, ParentSpanID: event.Trace.ParentSpanID, TraceID: event.Trace.ID}+ spans[event.Trace.SpanID] = span+ }+ if span.Name == "" {+ span.Name = firstNonEmpty(event.Summary, event.Title, event.Action)+ }+ span.EventIDs = append(span.EventIDs, event.ID)+ }+ return traceSpanList(spans)+}++func traceEventTypeSet(values []string) map[string]bool {+ if len(values) == 0 {+ return nil+ }+ out := map[string]bool{}+ for _, value := range values {+ value = strings.ToLower(strings.TrimSpace(value))+ if value == "" {+ continue+ }+ out[value] = true+ switch value {+ case "agent_text":+ out["agent_message"] = true+ case "agent_thinking":+ out["agent_reasoning"] = true+ case "agent_message":+ out["agent_text"] = true+ case "agent_reasoning":+ out["agent_thinking"] = true+ }+ }+ return out+}++func traceEventTypeAlias(value string) string {+ switch strings.ToLower(value) {+ case "agent_message":+ return "agent_text"+ case "agent_reasoning":+ return "agent_thinking"+ default:+ return strings.ToLower(value)+ }+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_store.go b/cli/beacon/internal/endpoint/dashboard/history_store.gonew file mode 100644index 00000000..dcec1dd5--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_store.go@@ -0,0 +1,523 @@+package dashboard++import (+ "context"+ "database/sql"+ "errors"+ "fmt"+ "math"+ "os"+ "path/filepath"+ "strconv"+ "strings"+ "time"++ _ "modernc.org/sqlite"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/filelock"+)++// The local history store backs `beacon endpoint traces` once the user opts in to it.+//+// It replaces traces.db, which was a cache: dropped and rebuilt from whatever JSONL was on disk+// whenever the log changed, so it never held more than the rotation window, about a day or two on+// an active machine. history.db is appended to as the log grows, follows the log across rotation,+// and keeps what rotation deletes, up to a retention period and a size cap.+//+// It exists only after the user opts in: `beacon endpoint traces reindex`, `beacon mcp setup`, or+// the first-run prompt. Until then every trace read scans the JSONL, as it also does whenever the+// store cannot answer a query.+//+// The store must answer the same question the JSONL scan answers. Every event is stored, in log+// order, and projected by the same code (traceEventFromRecord and traceAggregate), so trace+// membership, event numbers, summaries and search results match the JSONL path for the same log.++const (+ // historySchemaVersion is the table layout. A store written by another layout is not read;+ // every query falls back to the JSONL scan until `traces reset` or `traces reindex --rebuild`.+ historySchemaVersion = 1+ // historyDerivationVersion covers everything computed from a stored line: trace keys, event+ // numbers, types, summaries and search text. Bump it when that projection changes; the next+ // catch-up recomputes it from the stored lines, so history survives the change.+ historyDerivationVersion = 1++ defaultHistoryRetentionDays = 90+ defaultHistoryMaxBytes = int64(1) << 30++ // historyMaxLineBytes matches the JSONL scanner's line limit, so a line too long for one path+ // is skipped by the other rather than read by only one of them.+ historyMaxLineBytes = 4 * 1024 * 1024++ // historyLockWait bounds how long a reader waits for another process's catch-up.+ historyLockWait = 30 * time.Second+)++var (+ errHistoryNotEnabled = errors.New("local history is not set up")+ errTraceStoreUnsupported = errors.New("local history does not support this query")+)++// HistoryStatus is `beacon endpoint traces status`. The first seven fields keep the names the+// traces.db status used.+type HistoryStatus struct {+ Path string `json:"path"`+ Traces int `json:"traces"`+ Events int `json:"events"`+ IndexRows int `json:"index_rows"`+ SizeBytes int64 `json:"size_bytes"`+ WALBytes int64 `json:"wal_bytes,omitempty"`+ IndexedAt string `json:"indexed_at,omitempty"`+ Enabled bool `json:"enabled"`+ Source string `json:"source,omitempty"`+ OldestEventAt string `json:"oldest_event_at,omitempty"`+ NewestEventAt string `json:"newest_event_at,omitempty"`+ Gaps int `json:"gaps,omitempty"`+ GapBytes int64 `json:"gap_bytes,omitempty"`+ RetentionDays int `json:"retention_days,omitempty"`+ MaxBytes int64 `json:"max_bytes,omitempty"`+}++// HistoryOptions configures EnableHistoryStore. Zero values keep the store's current settings.+type HistoryOptions struct {+ RetentionDays int+ MaxBytes int64+ // Rebuild recomputes every derived column from the stored lines.+ Rebuild bool+ // Progress, when set, is called while a catch-up reads the log, with bytes read and total.+ Progress func(done, total int64)+}++// TraceStorePath is where the local history lives. The log path is accepted for the callers that+// predate history.db; the history is per user, not per log.+func TraceStorePath(string) string {+ return endpointconfig.HistoryStorePath()+}++// HistoryStoreEnabled reports whether the user has opted in to the local history.+func HistoryStoreEnabled() bool {+ _, err := os.Stat(endpointconfig.HistoryStorePath())+ return err == nil+}++// TraceStoreStatus reports on the local history for one log without creating it.+func TraceStoreStatus(logPath string) (HistoryStatus, error) {+ store, err := openHistoryStore(false)+ if errors.Is(err, errHistoryNotEnabled) {+ return HistoryStatus{Path: endpointconfig.HistoryStorePath()}, nil+ }+ if err != nil {+ return HistoryStatus{}, err+ }+ defer store.close()+ sourceID, err := store.catchUp(logPath, nil, false)+ if err != nil {+ return HistoryStatus{}, err+ }+ return store.status(sourceID)+}++// ReindexTraceStore creates the local history if it does not exist and catches it up with the log.+func ReindexTraceStore(logPath string) error {+ _, err := EnableHistoryStore(logPath, HistoryOptions{})+ return err+}++// EnableHistoryStore creates the local history if needed, applies opts, and catches it up with the+// log. This is the opt-in: nothing else creates the store.+func EnableHistoryStore(logPath string, opts HistoryOptions) (HistoryStatus, error) {+ store, err := openHistoryStore(true)+ if err != nil {+ return HistoryStatus{}, err+ }+ defer store.close()+ if opts.RetentionDays > 0 {+ if err := store.setMeta("retention_days", strconv.Itoa(opts.RetentionDays)); err != nil {+ return HistoryStatus{}, err+ }+ }+ if opts.MaxBytes > 0 {+ if err := store.setMeta("max_bytes", strconv.FormatInt(opts.MaxBytes, 10)); err != nil {+ return HistoryStatus{}, err+ }+ }+ if opts.Rebuild {+ if err := store.setMeta("derivation_version", "0"); err != nil {+ return HistoryStatus{}, err+ }+ }+ removeLegacyTraceStore(logPath)+ sourceID, err := store.catchUp(logPath, opts.Progress, true)+ if err != nil {+ return HistoryStatus{}, err+ }+ return store.status(sourceID)+}++// ResetHistoryStore deletes the local history. The runtime log is untouched.+func ResetHistoryStore() error {+ path := endpointconfig.HistoryStorePath()+ var problems []string+ for _, suffix := range []string{"", "-wal", "-shm", ".lock"} {+ if err := os.Remove(path + suffix); err != nil && !os.IsNotExist(err) {+ problems = append(problems, err.Error())+ }+ }+ if len(problems) > 0 {+ return fmt.Errorf("remove local history: %s", strings.Join(problems, "; "))+ }+ return nil+}++// removeLegacyTraceStore deletes the traces.db cache history.db replaces. It sat beside the log+// directory; a system log's copy is root's and stays until the system install removes it.+func removeLegacyTraceStore(logPath string) {+ if strings.TrimSpace(logPath) == "" {+ return+ }+ dir := filepath.Dir(logPath)+ legacy := filepath.Join(dir, "traces.db")+ if filepath.Base(dir) == "logs" {+ legacy = filepath.Join(filepath.Dir(dir), "traces.db")+ }+ for _, suffix := range []string{"", "-wal", "-shm"} {+ _ = os.Remove(legacy + suffix)+ }+}++type historyStore struct {+ path string+ db *sql.DB+}++func openHistoryStore(create bool) (*historyStore, error) {+ path := endpointconfig.HistoryStorePath()+ if _, err := os.Stat(path); err != nil {+ if !os.IsNotExist(err) {+ return nil, err+ }+ if !create {+ return nil, errHistoryNotEnabled+ }+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {+ return nil, err+ }+ // Created here rather than by SQLite so the mode is 0600 from the first byte: the store+ // holds the same prompts and command output the log does. SQLite gives the -wal and -shm+ // files the database file's mode.+ f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600)+ if err != nil && !os.IsExist(err) {+ return nil, err+ }+ if f != nil {+ _ = f.Close()+ }+ }+ db, err := sql.Open("sqlite", historyURI(path))+ if err != nil {+ return nil, err+ }+ store := &historyStore{path: path, db: db}+ if err := store.ensureSchema(); err != nil {+ _ = db.Close()+ return nil, err+ }+ return store, nil+}++func historyURI(path string) string {+ abs, err := filepath.Abs(path)+ if err != nil {+ abs = path+ }+ return "file:" + filepath.ToSlash(abs) + "?_pragma=busy_timeout(10000)&_pragma=journal_mode(WAL)&_pragma=synchronous(NORMAL)"+}++func (s *historyStore) close() {+ _ = s.db.Close()+}++func (s *historyStore) ensureSchema() error {+ var tables int+ if err := s.db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'meta'`).Scan(&tables); err != nil {+ return err+ }+ if tables == 1 {+ version, err := s.meta("schema_version")+ if err != nil {+ return err+ }+ if version != strconv.Itoa(historySchemaVersion) {+ return fmt.Errorf("local history schema %q is not supported by this Beacon version; run `beacon endpoint traces reset` to start over", version)+ }+ if codec, err := s.meta("line_codec"); err != nil {+ return err+ } else if codec != historyLineCodec {+ return fmt.Errorf("local history line encoding %q is not supported by this Beacon version; run `beacon endpoint traces reset` to start over", codec)+ }+ return nil+ }+ // auto_vacuum only takes effect before the first table exists. Incremental mode lets pruning+ // hand pages back to the file system, so the size cap is a real bound on disk use.+ // One connection for the whole setup: auto_vacuum is a pending setting of the connection that+ // runs it, and only takes effect if that same connection creates the first table.+ conn, err := s.db.Conn(context.Background())+ if err != nil {+ return err+ }+ defer conn.Close()+ stmts := []string{+ `PRAGMA auto_vacuum = INCREMENTAL`,+ `CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)`,+ // A source is one runtime log path. Every query is scoped to the log it was asked about,+ // so `--log-path` and a user-mode/system-mode switch never mix two logs' traces.+ // gaps counts the times the log rotated past the store before it was read: a file that+ // was the live log at one catch-up and gone by the next took the lines written to it in+ // between. gap_bytes is what is known to be lost, a lower bound.+ `CREATE TABLE sources (+ id INTEGER PRIMARY KEY,+ path TEXT NOT NULL UNIQUE,+ gaps INTEGER NOT NULL DEFAULT 0,+ gap_bytes INTEGER NOT NULL DEFAULT 0+ )`,+ // files is the tail position in every log file seen: identity is the device, inode and+ // first line, so a rotated file is recognized under its new name and a new file that+ // reuses an inode is not mistaken for the old one.+ `CREATE TABLE files (+ source_id INTEGER NOT NULL,+ dev INTEGER NOT NULL,+ ino INTEGER NOT NULL,+ head TEXT NOT NULL,+ offset INTEGER NOT NULL,+ lines INTEGER NOT NULL,+ size INTEGER NOT NULL,+ archive INTEGER NOT NULL,+ PRIMARY KEY (source_id, dev, ino, head)+ )`,+ // One row per log line that parsed as an event, in log order. The row key is the file and+ // byte offset rather than the event ID: two lines can share an ID (a repeated line, or a+ // hook and an OTLP capture of one call) and the JSONL path keeps both.+ `CREATE TABLE events (+ id INTEGER PRIMARY KEY,+ source_id INTEGER NOT NULL,+ file_key TEXT NOT NULL,+ offset INTEGER NOT NULL,+ record_id TEXT NOT NULL,+ trace_key TEXT NOT NULL,+ seq INTEGER NOT NULL,+ event_type TEXT NOT NULL,+ event_id TEXT NOT NULL,+ ts_ns INTEGER NOT NULL,+ ord_ts INTEGER NOT NULL,+ ord_seq INTEGER NOT NULL,+ span_id TEXT NOT NULL DEFAULT '',+ parent_span_id TEXT NOT NULL DEFAULT '',+ otel_trace_id TEXT NOT NULL DEFAULT '',+ span_name TEXT NOT NULL DEFAULT '',+ hay TEXT NOT NULL,+ line BLOB NOT NULL,+ UNIQUE (source_id, file_key, offset)+ )`,+ `CREATE INDEX events_by_trace ON events (source_id, trace_key, seq)`,+ // traces keeps each trace's running aggregate, so a catch-up updates a summary with the new+ // events alone instead of rereading the trace.+ `CREATE TABLE traces (+ id INTEGER PRIMARY KEY,+ source_id INTEGER NOT NULL,+ trace_key TEXT NOT NULL,+ started_ns INTEGER NOT NULL,+ updated_ns INTEGER NOT NULL,+ retain_ns INTEGER NOT NULL,+ state TEXT NOT NULL,+ visibility TEXT NOT NULL,+ event_count INTEGER NOT NULL,+ aggregate TEXT NOT NULL,+ hay TEXT NOT NULL,+ UNIQUE (source_id, trace_key)+ )`,+ `CREATE INDEX traces_by_updated ON traces (source_id, updated_ns DESC, trace_key)`,+ // A trace's running aggregate every historyCheckpointEvery events, so a late event refolds+ // the summary from near where it lands.+ `CREATE TABLE trace_checkpoints (+ source_id INTEGER NOT NULL,+ trace_key TEXT NOT NULL,+ seq INTEGER NOT NULL,+ state TEXT NOT NULL,+ PRIMARY KEY (source_id, trace_key, seq)+ )`,+ `CREATE INDEX traces_by_retention ON traces (retain_ns)`,+ // Search runs over the same lowercased haystacks the JSONL path matches. The trigram+ // tokenizer makes a quoted term match exactly the rows containing it as a substring, so a+ // term of three or more characters needs no second check. case_sensitive 1 because the+ // text is lowercased before it is indexed, by the same strings.ToLower the JSONL matcher+ // uses, rather than by SQLite's own folding.+ `CREATE VIRTUAL TABLE event_fts USING fts5(hay, content='events', content_rowid='id', tokenize='trigram case_sensitive 1')`,+ `CREATE VIRTUAL TABLE trace_fts USING fts5(hay, content='traces', content_rowid='id', tokenize='trigram case_sensitive 1')`,+ }+ for _, stmt := range stmts {+ if _, err := conn.ExecContext(context.Background(), stmt); err != nil {+ return err+ }+ }+ // The WAL switch in the connection string has already written the database header by now,+ // which fixes auto_vacuum at none until a VACUUM rewrites the file. The store is empty, so that+ // costs nothing.+ if _, err := conn.ExecContext(context.Background(), `VACUUM`); err != nil {+ return err+ }+ now := time.Now().UTC().Format(time.RFC3339Nano)+ for key, value := range map[string]string{+ "schema_version": strconv.Itoa(historySchemaVersion),+ "derivation_version": strconv.Itoa(historyDerivationVersion),+ "retention_days": strconv.Itoa(defaultHistoryRetentionDays),+ "max_bytes": strconv.FormatInt(defaultHistoryMaxBytes, 10),+ "line_codec": historyLineCodec,+ "created_at": now,+ } {+ if err := s.setMeta(key, value); err != nil {+ return err+ }+ }+ return nil+}++func (s *historyStore) meta(key string) (string, error) {+ var value string+ err := s.db.QueryRow(`SELECT value FROM meta WHERE key = ?`, key).Scan(&value)+ if err == sql.ErrNoRows {+ return "", nil+ }+ return value, err+}++func (s *historyStore) setMeta(key, value string) error {+ _, err := s.db.Exec(`INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, key, value)+ return err+}++func (s *historyStore) metaInt(key string, fallback int64) int64 {+ value, err := s.meta(key)+ if err != nil {+ return fallback+ }+ parsed, err := strconv.ParseInt(value, 10, 64)+ if err != nil || parsed <= 0 {+ return fallback+ }+ return parsed+}++// sourceID returns the source row for a log path, creating it when asked.+func (s *historyStore) sourceID(q queryer, logPath string, create bool) (int64, error) {+ key := traceSourceKey(logPath)+ var id int64+ err := q.QueryRow(`SELECT id FROM sources WHERE path = ?`, key).Scan(&id)+ if err == nil || err != sql.ErrNoRows || !create {+ return id, err+ }+ result, err := q.Exec(`INSERT INTO sources (path) VALUES (?)`, key)+ if err != nil {+ return 0, err+ }+ return result.LastInsertId()+}++// traceSourceKey normalizes a log path so the same log reached by a relative and an absolute path+// is one source rather than two.+func traceSourceKey(logPath string) string {+ abs, err := filepath.Abs(logPath)+ if err != nil {+ return logPath+ }+ return filepath.Clean(abs)+}++type queryer interface {+ QueryRow(query string, args ...any) *sql.Row+ Query(query string, args ...any) (*sql.Rows, error)+ Exec(query string, args ...any) (sql.Result, error)+}++func (s *historyStore) status(sourceID int64) (HistoryStatus, error) {+ status := HistoryStatus{+ Path: s.path,+ Enabled: true,+ SizeBytes: fileSize(s.path),+ WALBytes: fileSize(s.path + "-wal"),+ RetentionDays: int(s.metaInt("retention_days", defaultHistoryRetentionDays)),+ MaxBytes: s.metaInt("max_bytes", defaultHistoryMaxBytes),+ }+ var oldest, newest sql.NullInt64+ if err := s.db.QueryRow(`SELECT path, gaps, gap_bytes FROM sources WHERE id = ?`, sourceID).Scan(&status.Source, &status.Gaps, &status.GapBytes); err != nil {+ return HistoryStatus{}, err+ }+ // From the traces table alone: counting the events table would read every stored event.+ if err := s.db.QueryRow(`SELECT COUNT(*), COALESCE(SUM(event_count), 0), MIN(NULLIF(started_ns, ?)), MAX(NULLIF(updated_ns, ?))+ FROM traces WHERE source_id = ?`, int64(math.MinInt64), int64(math.MinInt64), sourceID).Scan(&status.Traces, &status.Events, &oldest, &newest); err != nil {+ return HistoryStatus{}, err+ }+ // Rows searchable, counted the way traces.db counted them: one per trace and one per event.+ status.IndexRows = status.Traces + status.Events+ if oldest.Valid {+ status.OldestEventAt = time.Unix(0, oldest.Int64).UTC().Format(time.RFC3339Nano)+ }+ if newest.Valid {+ status.NewestEventAt = time.Unix(0, newest.Int64).UTC().Format(time.RFC3339Nano)+ }+ indexedAt, err := s.meta("indexed_at")+ if err != nil {+ return HistoryStatus{}, err+ }+ status.IndexedAt = indexedAt+ return status, nil+}++// lockExclusive serializes catch-ups across processes: the CLI, the dashboard and the MCP server can+// all hold the store open at once, and only one may append at a time. Readers never take it.+func (s *historyStore) lockExclusive() (func(), error) {+ f, err := os.OpenFile(s.path+".lock", os.O_CREATE|os.O_RDWR, 0o600)+ if err != nil {+ return nil, err+ }+ deadline := time.Now().Add(historyLockWait)+ for {+ held, err := filelock.TryExclusive(f)+ if err == nil {+ return func() {+ _ = held.Release()+ _ = f.Close()+ }, nil+ }+ if time.Now().After(deadline) {+ _ = f.Close()+ return nil, fmt.Errorf("local history is busy: another Beacon process has been updating it for %s", historyLockWait)+ }+ time.Sleep(25 * time.Millisecond)+ }+}++func fileSize(path string) int64 {+ info, err := os.Stat(path)+ if err != nil {+ return 0+ }+ return info.Size()+}++// timeKey turns a trace or event timestamp into an integer that sorts the way+// sortTraceSummaries orders the parsed times: later first, and an unparseable time after every+// valid one.+func timeKey(value string) int64 {+ parsed, err := schema.ParseTimestamp(value)+ if err != nil || parsed.IsZero() {+ return math.MinInt64+ }+ if parsed.Year() < 1678 {+ return math.MinInt64 + 1+ }+ if parsed.Year() > 2261 {+ return math.MaxInt64+ }+ return parsed.UnixNano()+}diff --git a/cli/beacon/internal/endpoint/dashboard/history_test.go b/cli/beacon/internal/endpoint/dashboard/history_test.gonew file mode 100644index 00000000..4df1e2b0--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/history_test.go@@ -0,0 +1,887 @@+package dashboard++import (+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "fmt"+ "os"+ "path/filepath"+ "regexp"+ "strings"+ "sync"+ "testing"+ "time"++ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// Every test in this package runs with the local history pointed at a path that does not exist,+// so nothing here can read or write a developer's real ~/.beacon/endpoint/history.db. Tests that+// want a history opt in with withHistory.+func TestMain(m *testing.M) {+ dir, err := os.MkdirTemp("", "beacon-dashboard-test")+ if err != nil {+ fmt.Fprintln(os.Stderr, err)+ os.Exit(1)+ }+ _ = os.Setenv(endpointconfig.HistoryStoreEnv, filepath.Join(dir, "absent", "history.db"))+ code := m.Run()+ _ = os.RemoveAll(dir)+ os.Exit(code)+}++// withHistory points the local history at a fresh path for the rest of the test. The store+// itself is created by the first ReindexTraceStore.+func withHistory(t *testing.T) string {+ t.Helper()+ path := filepath.Join(t.TempDir(), "history.db")+ t.Setenv(endpointconfig.HistoryStoreEnv, path)+ return path+}++// withoutHistory makes every trace read in the rest of the test take the JSONL scan.+func withoutHistory(t *testing.T) {+ t.Helper()+ t.Setenv(endpointconfig.HistoryStoreEnv, filepath.Join(t.TempDir(), "absent", "history.db"))+}++func newTestLog(t *testing.T, lines [][]byte) string {+ t.Helper()+ path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {+ t.Fatalf("mkdir log dir: %v", err)+ }+ writeTestLog(t, path, lines...)+ return path+}++// optIn builds the history from a log. Fixtures are dated in the past, so retention is set far+// beyond them; the retention test sets its own.+func optIn(t *testing.T, path string) {+ t.Helper()+ if _, err := EnableHistoryStore(path, HistoryOptions{RetentionDays: 100 * 365}); err != nil {+ t.Fatalf("EnableHistoryStore: %v", err)+ }+}++// traceStoreIndexedLog writes lines to a new log and opts the test in to a history built from it.+func traceStoreIndexedLog(t *testing.T, lines [][]byte) string {+ t.Helper()+ path := newTestLog(t, lines)+ withHistory(t)+ optIn(t, path)+ return path+}++// traceStoreBlockedLog writes lines to a new log that only the JSONL scan will read.+func traceStoreBlockedLog(t *testing.T, lines [][]byte) string {+ t.Helper()+ withoutHistory(t)+ return newTestLog(t, lines)+}++func mustJSON(t *testing.T, value any) string {+ t.Helper()+ data, err := json.Marshal(value)+ if err != nil {+ t.Fatal(err)+ }+ return string(data)+}++// traceAnswers runs a fixed set of list, search and show queries against a log and returns their+// JSON, keyed by query, so two ways of answering can be compared byte for byte.+func traceAnswers(t *testing.T, path string, showIDs []string) map[string]string {+ t.Helper()+ out := map[string]string{}+ queries := []string{+ "", "index", "INDEX LOCAL", "go", "go test", "dashboard go", "endpoint.dashboard", "endpoint/dashboard",+ "(", `"quoted"`, "a-b", "path:/repo", "*", "AND", "NEAR", "ü", "naïve café", "claude_code.token.usage",+ "nothing-matches-this", " ", "evt", "s1", "codex_cli", "retained answer",+ }+ for _, q := range queries {+ for _, page := range []int{1, 2} {+ list, err := ReadTraceList(path, TraceQuery{EventQuery: EventQuery{Q: q}, Limit: 3, Page: page})+ if err != nil {+ t.Fatalf("ReadTraceList(%q): %v", q, err)+ }+ out[fmt.Sprintf("list q=%q page=%d", q, page)] = mustJSON(t, list)+ }+ for _, level := range []string{"trace", "event"} {+ search, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: level, Limit: 4})+ if err != nil {+ t.Fatalf("SearchTraces(%q, %s): %v", q, level, err)+ }+ out[fmt.Sprintf("search q=%q level=%s", q, level)] = mustJSON(t, search)+ }+ typed, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: "event", EventTypes: []string{"command", "agent_text"}, Limit: 50})+ if err != nil {+ t.Fatalf("SearchTraces typed(%q): %v", q, err)+ }+ out[fmt.Sprintf("search q=%q typed", q)] = mustJSON(t, typed)+ }+ for _, state := range []string{"local_only", "LOCAL_ONLY", "shared"} {+ list, err := ReadTraceList(path, TraceQuery{State: state, Limit: 50})+ if err != nil {+ t.Fatalf("ReadTraceList state=%s: %v", state, err)+ }+ out["list state="+state] = mustJSON(t, list)+ }+ for _, id := range showIDs {+ for name, query := range map[string]TraceQuery{+ "all": {Limit: 100},+ "page": {Limit: 2, Offset: 2},+ "past-end": {Limit: 5, Offset: 999},+ "typed": {Limit: 100, EventTypes: []string{"user_message", "command"}},+ "around": {AroundEvent: 3, Before: 1, After: 1},+ "agent": {Limit: 100, EventTypes: []string{"agent_text"}},+ } {+ show, ok, err := ShowTrace(path, id, query)+ if err != nil {+ t.Fatalf("ShowTrace(%s, %s): %v", id, name, err)+ }+ out[fmt.Sprintf("show %s %s ok=%v", id, name, ok)] = mustJSON(t, show)+ }+ }+ return out+}++func compareAnswers(t *testing.T, want, got map[string]string) {+ t.Helper()+ for key, w := range want {+ if g, ok := got[key]; !ok || g != w {+ t.Errorf("%s differs\n want %s\n got %s", key, w, g)+ }+ }+}++// parityFixture is a log with the shapes the projection treats differently: hook and OTLP+// captures, spans, commands with output, file edits, MCP calls, approvals, token usage, metric+// samples the dashboard renames, retained assistant text, sharing metadata in raw, events that+// share an ID, events with no ID, and text in several scripts.+func parityFixture() [][]byte {+ lines := []string{+ `{"timestamp":"2026-06-11T10:00:00Z","event":{"id":"e1","action":"session.started","category":"session"},"harness":{"name":"cursor","collection_method":"hook"},"session":{"id":"s1","working_directory":"/repo/a"},"repository":"repo-a","branch":"main","message":"Session started"}`,+ `{"timestamp":"2026-06-11T10:00:05Z","event":{"id":"e2","action":"prompt.submitted","category":"prompt"},"harness":{"name":"cursor","collection_method":"hook"},"session":{"id":"s1"},"prompt":{"text":"Index local traces for the dashboard, naïve café ü"},"content":{"retention":"full","included":true,"hash":"abc","bytes":40}}`,+ `{"timestamp":"2026-06-11T10:01:00Z","event":{"id":"e3","action":"command.executed","category":"command"},"harness":{"name":"cursor","collection_method":"hook"},"session":{"id":"s1"},"tool":{"name":"Shell","command":"go test ./internal/endpoint/dashboard"},"command":{"command":"go test ./internal/endpoint/dashboard","exit_code":1,"duration_ms":1200,"output":"FAIL a-b path:/repo \"quoted\""}}`,+ `{"timestamp":"2026-06-11T10:01:30Z","event":{"id":"e3","action":"command.executed","category":"command"},"harness":{"name":"cursor","collection_method":"otlp"},"session":{"id":"s1"},"command":{"command":"go test ./internal/endpoint/dashboard","exit_code":0}}`,+ `{"timestamp":"2026-06-11T10:02:00Z","event":{"id":"e4","action":"file.modified","category":"file"},"harness":{"name":"cursor"},"session":{"id":"s1"},"file":{"path":"internal/endpoint/dashboard/traces.go","operation":"modify","language":"go","diff":"+ matchesAllTerms","diff_hash":"dh"}}`,+ `{"timestamp":"2026-06-11T10:02:30Z","event":{"id":"e5","action":"approval.denied","category":"approval"},"harness":{"name":"cursor"},"session":{"id":"s1"},"approval":{"required":true,"decision":"denied","reason":"AND NEAR * not allowed"}}`,+ `{"timestamp":"2026-06-11T10:03:00Z","event":{"id":"e6","action":"mcp.tool_invoked","category":"mcp"},"harness":{"name":"cursor"},"session":{"id":"s1"},"mcp":{"server":"beacon","tool":"search_sessions","method":{"name":"tools/call"}},"gen_ai":{"tool":{"name":"mcp__beacon__search_sessions","call":{"id":"call-1","arguments":{"query":"index"},"result":"one session"}}}}`,+ `{"timestamp":"2026-06-11T10:04:00Z","event":{"action":"session.activity","category":"session"},"harness":{"name":"cursor"},"session":{"id":"s1"},"message":"hook with no event id"}`,+ `{"timestamp":"2026-06-11T11:00:00Z","event":{"id":"o1","action":"tool.invoked","category":"tool"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"s2"},"trace":{"id":"t-abc","span_id":"span-1"},"tool":{"name":"Bash"},"message":"root span","model":"claude-opus-5"}`,+ `{"timestamp":"2026-06-11T11:00:01Z","event":{"id":"o2","action":"tool.completed","category":"tool"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"s2"},"trace":{"id":"t-abc","span_id":"span-2","parent_span_id":"span-1"},"tool":{"name":"Bash"}}`,+ `{"timestamp":"2026-06-11T11:00:02Z","event":{"id":"o3","action":"token.usage","category":"metric"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"s2"},"trace":{"id":"t-abc","span_id":"span-2","parent_span_id":"span-1"},"gen_ai":{"usage":{"input_tokens":120,"output_tokens":30,"cache_read":{"input_tokens":5},"cost_usd":0.0123}},"model":"claude-opus-5"}`,+ `{"timestamp":"2026-06-11T11:00:03Z","event":{"id":"m1","action":"","category":""},"harness":{"name":"claude_code","collection_method":"otlp"},"message":"claude_code.token.usage","raw":{"metric_name":"claude_code.token.usage","otel_signal":"metrics"}}`,+ `{"timestamp":"2026-06-11T11:00:04Z","event":{"id":"m2","action":"metric.observed","category":"metric"},"harness":{"name":"claude_code","collection_method":"otlp"},"message":"claude_code.active_time.total"}`,+ `{"timestamp":"2026-06-11T12:00:00Z","event":{"id":"c1","action":"prompt.submitted","category":"prompt"},"harness":{"name":"codex_cli","collection_method":"hook"},"session":{"id":"s3"},"prompt":{"text":"rotate the flaky fixture"}}`,+ `{"timestamp":"2026-06-11T12:00:10Z","event":{"id":"c2","action":"agent.message","category":"agent"},"harness":{"name":"codex_cli","collection_method":"hook"},"session":{"id":"s3"},"message":"Codex assistant message","gen_ai":{"output":{"messages":[{"role":"assistant","parts":[{"type":"text","content":"the retained answer"},{"type":"reasoning","content":"hidden thought"}]}]}}}`,+ `{"timestamp":"2026-06-11T12:00:11Z","event":{"id":"c3","action":"agent.reasoning","category":"agent"},"harness":{"name":"codex_cli"},"session":{"id":"s3"},"gen_ai":{"output":{"messages":"bare string output"}}}`,+ `{"timestamp":"2026-06-11T12:00:12Z","event":{"id":"c4","action":"session.status","category":"session"},"harness":{"name":"codex_cli"},"session":{"id":"s3"},"raw":{"shared_url":"https://example.test/s3","visibility":"team","remote_event_count":9,"namespace_slug":"acme"}}`,+ `{"timestamp":"not-a-time","event":{"id":"x1","action":"prompt.submitted","category":"prompt"},"harness":{"name":"opencode"},"session":{"id":"s4"},"prompt":{"text":"日本語のプロンプト index"}}`,+ `{"timestamp":"2026-06-11T13:00:00Z","event":{"action":"prompt.submitted","category":"prompt"},"harness":{"name":"opencode"},"session":{"id":"s5"},"prompt":{"text":"no id at all"}}`,+ `not json at all`,+ ``,+ // Out of order, as an OpenTelemetry batch lands after the hook events it precedes: this+ // event becomes the first of session s1, which changes the trace's start, its session+ // working directory and its harness version.+ `{"timestamp":"2026-06-11T09:59:59Z","event":{"id":"late1","action":"session.activity","category":"session"},"harness":{"name":"cursor","version":"9.9.9","collection_method":"otlp"},"session":{"id":"s1","working_directory":"/late/first"},"message":"arrived last, happened first"}`,+ // Equal timestamps: unsequenced first, then by sequence, then by position.+ `{"timestamp":"2026-06-11T14:00:00Z","sequence":7,"event":{"id":"q7","action":"tool.invoked","category":"tool"},"harness":{"name":"codex_cli"},"session":{"id":"s6"},"tool":{"name":"seven"}}`,+ `{"timestamp":"2026-06-11T14:00:00Z","sequence":3,"event":{"id":"q3","action":"tool.invoked","category":"tool"},"harness":{"name":"codex_cli"},"session":{"id":"s6"},"tool":{"name":"three"}}`,+ `{"timestamp":"2026-06-11T14:00:00Z","event":{"id":"q0","action":"prompt.submitted","category":"prompt"},"harness":{"name":"codex_cli"},"session":{"id":"s6"},"prompt":{"text":"unsequenced goes first"}}`,+ `{"timestamp":"2026-06-11T13:59:00Z","event":{"id":"q-early","action":"session.started","category":"session"},"harness":{"name":"codex_cli","version":"1.0"},"session":{"id":"s6"}}`,+ `{"timestamp":"2026-06-11T13:00:05Z","event":{"id":"s5b","action":"command.executed","category":"command"},"harness":{"name":"opencode"},"session":{"id":"s5"},"command":{"command":"ls a-b"}}`,+ }+ out := make([][]byte, len(lines))+ for i, line := range lines {+ out[i] = []byte(line)+ }+ return out+}++var parityShowIDs = []string{+ "session:cursor:s1", "trace:t-abc", "session:codex_cli:s3", "session:opencode:s4", "session:opencode:s5",+ "session:codex_cli:s6", "event:m1", "missing",+}++// The core promise: for the same log, the history answers every list, search and show exactly+// as the JSONL scan does.+func TestHistoryAnswersExactlyLikeTheJSONLScan(t *testing.T) {+ path := newTestLog(t, parityFixture())+ withoutHistory(t)+ want := traceAnswers(t, path, parityShowIDs)++ withHistory(t)+ optIn(t, path)+ compareAnswers(t, want, traceAnswers(t, path, parityShowIDs))+}++func TestHistoryIsNotCreatedWithoutOptIn(t *testing.T) {+ path := newTestLog(t, parityFixture())+ store := endpointconfig.HistoryStorePath()+ if _, err := ReadTraceList(path, TraceQuery{Limit: 10}); err != nil {+ t.Fatal(err)+ }+ if _, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "index"}, Limit: 10}); err != nil {+ t.Fatal(err)+ }+ if _, _, err := ShowTrace(path, "session:cursor:s1", TraceQuery{Limit: 10}); err != nil {+ t.Fatal(err)+ }+ status, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Enabled {+ t.Fatalf("status = %#v, want a disabled history", status)+ }+ if HistoryStoreEnabled() {+ t.Fatal("HistoryStoreEnabled reported a store nobody opted in to")+ }+ if _, err := os.Stat(store); !os.IsNotExist(err) {+ t.Fatalf("history store exists after reads without opt-in: %v", err)+ }+ if _, err := os.Stat(filepath.Join(filepath.Dir(filepath.Dir(path)), "traces.db")); !os.IsNotExist(err) {+ t.Fatalf("a traces.db cache was created: %v", err)+ }+}++func TestHistoryIndexesAndCatchesUp(t *testing.T) {+ prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")+ prompt.Event.ID = "evt-prompt"+ prompt.Session = &schema.SessionInfo{ID: "s1", WorkingDirectory: "/repo/a"}+ prompt.Prompt = &schema.PromptInfo{Text: "Index local traces"}+ command := testSchemaEvent("2026-06-11T10:01:00Z", "cursor", "command.executed", "command", "repo-a")+ command.Event.ID = "evt-command"+ command.Session = prompt.Session+ command.Command = &schema.CommandInfo{Command: "go test ./internal/endpoint/dashboard"}+ path := traceStoreIndexedLog(t, marshalEvents(t, prompt, command))++ status, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if !status.Enabled || status.Path != endpointconfig.HistoryStorePath() || status.Source != traceSourceKey(path) {+ t.Fatalf("status = %#v", status)+ }+ if status.Traces != 1 || status.Events != 2 || status.IndexRows != 3 || status.SizeBytes == 0 {+ t.Fatalf("status = %#v, want 1 trace, 2 events, 3 index rows", status)+ }+ if status.RetentionDays != 100*365 || status.MaxBytes != defaultHistoryMaxBytes {+ t.Fatalf("status settings = %#v", status)+ }+ results, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "dashboard"}, ResultLevel: "event", Limit: 10})+ if err != nil {+ t.Fatal(err)+ }+ if results.TotalMatched != 1 || results.Events[0].Event.ID != "evt-command" {+ t.Fatalf("search = %#v", results)+ }++ later := testSchemaEvent("2026-06-11T10:02:00Z", "cursor", "file.modified", "file", "repo-a")+ later.Event.ID = "evt-file"+ later.Session = prompt.Session+ later.File = &schema.FileInfo{Path: "history_store.go", Operation: "modify"}+ writeTestLog(t, path, marshalEvents(t, prompt, command, later)...)++ status, err = TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Events != 3 || status.IndexRows != 4 {+ t.Fatalf("after append status = %#v, want 3 events and 4 index rows", status)+ }+}++// What the store is for: the log rotates away, the history does not.+func TestHistoryKeepsTracesAfterTheLogIsGone(t *testing.T) {+ path := traceStoreIndexedLog(t, parityFixture())+ for _, archive := range []string{"", ".1", ".2"} {+ _ = os.Remove(path + archive)+ }+ list, err := ReadTraceList(path, TraceQuery{EventQuery: EventQuery{Q: "retained answer"}, Limit: 10})+ if err != nil {+ t.Fatal(err)+ }+ if list.TotalMatched != 1 || list.Traces[0].ID != "session:codex_cli:s3" {+ t.Fatalf("list after the log was removed = %#v", list)+ }+ show, ok, err := ShowTrace(path, "session:cursor:s1", TraceQuery{Limit: 100})+ if err != nil || !ok || len(show.Events) == 0 {+ t.Fatalf("show after the log was removed ok=%v err=%v events=%d", ok, err, len(show.Events))+ }+}++func TestHistorySearchesLongEventTextInFull(t *testing.T) {+ needle := "needle-after-sixteen-kilobytes"+ prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")+ prompt.Event.ID = "evt-prompt"+ prompt.Session = &schema.SessionInfo{ID: "s1"}+ prompt.Prompt = &schema.PromptInfo{Text: strings.Repeat("a", 20*1024) + needle}+ path := traceStoreIndexedLog(t, marshalEvents(t, prompt))+ _ = os.Remove(path) // only the store can answer now+ list, err := ReadTraceList(path, TraceQuery{EventQuery: EventQuery{Q: needle}, Limit: 10})+ if err != nil {+ t.Fatal(err)+ }+ if list.TotalMatched != 1 {+ t.Fatalf("matched %d traces, want the one whose text holds the needle past 16KB", list.TotalMatched)+ }+}++func TestHistoryKeepsEventsThatShareAnID(t *testing.T) {+ first := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "command.executed", "command", "repo-a")+ first.Event.ID = "same-event-id"+ first.Session = &schema.SessionInfo{ID: "s1"}+ first.Command = &schema.CommandInfo{Command: "go build ./..."}+ second := first+ second.Timestamp = "2026-06-11T10:00:01Z"+ path := traceStoreIndexedLog(t, marshalEvents(t, first, second))+ status, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Traces != 1 || status.Events != 2 {+ t.Fatalf("status = %#v, want 1 trace and 2 events", status)+ }+ show, ok, err := ShowTrace(path, "session:cursor:s1", TraceQuery{Limit: 10})+ if err != nil || !ok || len(show.Events) != 2 {+ t.Fatalf("ShowTrace ok=%v err=%v events=%d", ok, err, len(show.Events))+ }+}++// Two logs can describe the same session. Each is its own source.+func TestHistoryScopesTracesBySourceLog(t *testing.T) {+ withHistory(t)+ dir := filepath.Join(t.TempDir(), "logs")+ if err := os.MkdirAll(dir, 0o700); err != nil {+ t.Fatal(err)+ }+ shared := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")+ shared.Event.ID = "evt-prompt"+ shared.Session = &schema.SessionInfo{ID: "shared-session"}+ shared.Prompt = &schema.PromptInfo{Text: "first log"}+ other := shared+ other.Prompt = &schema.PromptInfo{Text: "second log"}+ first := filepath.Join(dir, "runtime.jsonl")+ second := filepath.Join(dir, "archive.jsonl")+ writeTestLog(t, first, marshalEvents(t, shared)...)+ writeTestLog(t, second, marshalEvents(t, other)...)+ if TraceStorePath(first) != TraceStorePath(second) {+ t.Fatal("both logs should share one history")+ }+ for _, tc := range []struct{ path, want, not string }{{first, "first log", "second log"}, {second, "second log", "first log"}} {+ optIn(t, tc.path)+ status, err := TraceStoreStatus(tc.path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Traces != 1 || status.Events != 1 {+ t.Fatalf("status for %s = %#v", tc.path, status)+ }+ for q, want := range map[string]int{tc.want: 1, tc.not: 0} {+ result, err := SearchTraces(tc.path, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: "event", Limit: 10})+ if err != nil {+ t.Fatal(err)+ }+ if result.TotalMatched != want {+ t.Fatalf("searching %s for %q matched %d, want %d", tc.path, q, result.TotalMatched, want)+ }+ }+ }+}++func TestHistoryTreatsEquivalentLogPathsAsOneSource(t *testing.T) {+ path := traceStoreIndexedLog(t, parityFixture())+ before, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ after, err := TraceStoreStatus(filepath.Join(filepath.Dir(path), ".", "runtime.jsonl"))+ if err != nil {+ t.Fatal(err)+ }+ if after.Traces != before.Traces || after.Events != before.Events || after.Source != before.Source {+ t.Fatalf("equivalent path status = %#v, want %#v", after, before)+ }+}++// rotatingLog writes every event to a log that rotates at rotateSize and to an unrotated shadow+// log holding every line ever written, so the history over the first can be compared with a JSONL+// scan over the second.+type rotatingLog struct {+ path, shadow string+ rotateSize int64+ n int+}++func newRotatingLog(t *testing.T, rotateSize int64) *rotatingLog {+ t.Helper()+ dir := t.TempDir()+ for _, sub := range []string{"logs", "shadow"} {+ if err := os.MkdirAll(filepath.Join(dir, sub), 0o700); err != nil {+ t.Fatal(err)+ }+ }+ return &rotatingLog{path: filepath.Join(dir, "logs", "runtime.jsonl"), shadow: filepath.Join(dir, "shadow", "runtime.jsonl"), rotateSize: rotateSize}+}++// append writes n distinct events. Distinct matters: the writer drops a repeat of a recent event,+// judged against the tail of each file, and the two files' tails differ after a rotation.+func (r *rotatingLog) append(t *testing.T, n int) {+ t.Helper()+ for i := 0; i < n; i++ {+ r.n+++ // Every third event is stamped a few seconds before the ones already written, as an+ // OpenTelemetry batch is.+ at := time.Date(2026, 6, 11, 10, 0, 0, 0, time.UTC).Add(time.Duration(r.n) * time.Second)+ if r.n%3 == 0 {+ at = at.Add(-7 * time.Second)+ }+ event := testSchemaEvent(at.Format(time.RFC3339), "cursor", "command.executed", "command", "repo-a")+ event.Session = &schema.SessionInfo{ID: fmt.Sprintf("s%d", r.n%4)}+ event.Command = &schema.CommandInfo{Command: fmt.Sprintf("echo event-%04d %s", r.n, strings.Repeat("x", 120))}+ for _, opts := range []writer.Options{{Path: r.path, RotateSize: r.rotateSize}, {Path: r.shadow, RotateSize: 1 << 40}} {+ if _, err := writer.AppendEvent(event, opts); err != nil {+ t.Fatalf("append: %v", err)+ }+ }+ }+}++// appendRotations appends events until the log has rotated exactly n more times.+func (r *rotatingLog) appendRotations(t *testing.T, n int) {+ t.Helper()+ for rotated := 0; rotated < n; {+ before, beforeErr := os.Stat(r.path)+ r.append(t, 1)+ after, afterErr := os.Stat(r.path)+ if beforeErr == nil && afterErr == nil && !os.SameFile(before, after) {+ rotated+++ }+ }+}++func (r *rotatingLog) compare(t *testing.T) {+ t.Helper()+ ids := []string{"session:cursor:s0", "session:cursor:s1", "session:cursor:s2", "session:cursor:s3"}+ history := traceAnswers(t, r.path, ids)+ previous := os.Getenv(endpointconfig.HistoryStoreEnv)+ withoutHistory(t)+ want := traceAnswers(t, r.shadow, ids)+ t.Setenv(endpointconfig.HistoryStoreEnv, previous)+ compareAnswers(t, want, history)+}++func TestHistoryFollowsTheLogAcrossRotation(t *testing.T) {+ withHistory(t)+ log := newRotatingLog(t, 4*1024)+ log.append(t, 5)+ optIn(t, log.path)+ // One rotation, then three, then five between catch-ups: never more than the five archives+ // the writer keeps, so nothing is lost.+ for _, rotations := range []int{1, 3, 5} {+ log.appendRotations(t, rotations)+ log.append(t, 2)+ if _, err := ReadTraceList(log.path, TraceQuery{Limit: 1}); err != nil {+ t.Fatal(err)+ }+ }+ log.compare(t)+ status, err := TraceStoreStatus(log.path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Events != log.n || status.Gaps != 0 || status.GapBytes != 0 {+ t.Fatalf("status = %#v, want %d events and no gap", status, log.n)+ }+}++func TestHistoryRecordsAGapWhenTheLogRotatesPastIt(t *testing.T) {+ withHistory(t)+ log := newRotatingLog(t, 2*1024)+ log.append(t, 3)+ optIn(t, log.path)+ // Seven rotations with no catch-up: more than the five archives, so files are deleted unread.+ log.appendRotations(t, 7)+ status, err := TraceStoreStatus(log.path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Gaps == 0 {+ t.Fatalf("status = %#v, want a recorded gap", status)+ }+ if status.Events >= log.n {+ t.Fatalf("history holds %d of %d events after files rotated away unread", status.Events, log.n)+ }+ // Nothing read twice: every stored event is distinct.+ show, ok, err := ShowTrace(log.path, "session:cursor:s1", TraceQuery{Limit: 1000})+ if err != nil || !ok {+ t.Fatalf("ShowTrace ok=%v err=%v", ok, err)+ }+ seen := map[string]bool{}+ for _, event := range show.Events {+ if seen[event.ID] {+ t.Fatalf("event %s stored twice", event.ID)+ }+ seen[event.ID] = true+ }+}++func TestHistoryWaitsForAPartialLine(t *testing.T) {+ withHistory(t)+ lines := parityFixture()+ path := newTestLog(t, lines[:2])+ partial := lines[2][:40]+ f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0o644)+ if err != nil {+ t.Fatal(err)+ }+ if _, err := f.Write(partial); err != nil {+ t.Fatal(err)+ }+ optIn(t, path)+ status, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Events != 2 {+ t.Fatalf("events = %d, want the two complete lines only", status.Events)+ }+ if _, err := f.Write(append(lines[2][40:], '\n')); err != nil {+ t.Fatal(err)+ }+ _ = f.Close()+ status, err = TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if status.Events != 3 {+ t.Fatalf("events = %d, want the completed line read once", status.Events)+ }+}++func TestHistoryTreatsAReplacedOrShrunkFileAsNew(t *testing.T) {+ lines := parityFixture()+ path := traceStoreIndexedLog(t, lines[:5])+ before, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ // Replaced: a new file at the same path, whose first line differs.+ if err := os.Remove(path); err != nil {+ t.Fatal(err)+ }+ writeTestLog(t, path, lines[13:15]...)+ after, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if after.Events != before.Events+2 {+ t.Fatalf("after replacement events = %d, want %d", after.Events, before.Events+2)+ }+ // Shrunk in place: shorter than what was read from it.+ writeTestLog(t, path, lines[16])+ shrunk, err := TraceStoreStatus(path)+ if err != nil {+ t.Fatal(err)+ }+ if shrunk.Events != after.Events+1 {+ t.Fatalf("after shrink events = %d, want %d", shrunk.Events, after.Events+1)+ }+}++// Readers and a writer at once, as the MCP server, the CLI and the agents' hooks will be.+func TestHistoryConcurrentWriterAndReaders(t *testing.T) {+ withHistory(t)+ log := newRotatingLog(t, 32*1024)+ log.append(t, 5)+ optIn(t, log.path)+ done := make(chan struct{})+ var wg sync.WaitGroup+ for reader := 0; reader < 3; reader++ {+ wg.Add(1)+ go func() {+ defer wg.Done()+ for {+ select {+ case <-done:+ return+ default:+ }+ if _, err := ReadTraceList(log.path, TraceQuery{EventQuery: EventQuery{Q: "event"}, Limit: 5}); err != nil {+ t.Errorf("reader: %v", err)+ return+ }+ }+ }()+ }+ log.append(t, 250)+ close(done)+ wg.Wait()+ log.compare(t)+}++func TestHistoryPrunesByRetentionAndSize(t *testing.T) {+ withHistory(t)+ var events []schema.Event+ old := testSchemaEvent("2020-01-01T00:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")+ old.Event.ID = "old"+ old.Session = &schema.SessionInfo{ID: "old-session"}+ old.Prompt = &schema.PromptInfo{Text: "an old prompt"}+ events = append(events, old)+ now := time.Now().UTC()+ for i := 0; i < 60; i++ {+ event := testSchemaEvent(now.Add(time.Duration(i-60)*time.Minute).Format(time.RFC3339), "cursor", "prompt.submitted", "prompt", "repo-a")+ event.Event.ID = fmt.Sprintf("recent-%d", i)+ event.Session = &schema.SessionInfo{ID: fmt.Sprintf("recent-%d", i)}+ event.Prompt = &schema.PromptInfo{Text: fmt.Sprintf("recent prompt %d %s", i, noiseText(i, 3000))}+ events = append(events, event)+ }+ path := newTestLog(t, marshalEvents(t, events...))+ status, err := EnableHistoryStore(path, HistoryOptions{RetentionDays: 30})+ if err != nil {+ t.Fatal(err)+ }+ if status.Traces != 60 {+ t.Fatalf("after retention traces = %d, want the 60 recent ones", status.Traces)+ }+ if _, ok, _ := ShowTrace(path, "session:cursor:old-session", TraceQuery{Limit: 10}); ok {+ t.Fatal("a trace past retention is still stored")+ }++ status, err = EnableHistoryStore(path, HistoryOptions{MaxBytes: 256 * 1024})+ if err != nil {+ t.Fatal(err)+ }+ if status.Traces == 0 || status.Traces >= 60 {+ t.Fatalf("after the size cap traces = %d, want some but not all", status.Traces)+ }+ if status.SizeBytes > 256*1024+64*1024 {+ t.Fatalf("store is %d bytes after pruning to a 256KiB cap", status.SizeBytes)+ }+ // The newest trace survives; the oldest recent one does not.+ if _, ok, _ := ShowTrace(path, "session:cursor:recent-59", TraceQuery{Limit: 1}); !ok {+ t.Fatal("the newest trace was pruned")+ }+ if _, ok, _ := ShowTrace(path, "session:cursor:recent-0", TraceQuery{Limit: 1}); ok {+ t.Fatal("the oldest trace survived the size cap")+ }+ // Search stays consistent with what remains.+ result, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "recent prompt"}, ResultLevel: "event", Limit: 100})+ if err != nil {+ t.Fatal(err)+ }+ if result.TotalMatched != status.Traces {+ t.Fatalf("search matched %d events, want one per remaining trace (%d)", result.TotalMatched, status.Traces)+ }+}++// A new Beacon version that projects events differently rebuilds what it derives from the stored+// lines rather than serving what the old one derived.+func TestHistoryRebuildsDerivedDataForANewProjection(t *testing.T) {+ path := traceStoreIndexedLog(t, parityFixture())+ withoutHistoryPath := os.Getenv(endpointconfig.HistoryStoreEnv)+ want, _, err := ShowTrace(path, "session:codex_cli:s3", TraceQuery{Limit: 100})+ if err != nil {+ t.Fatal(err)+ }+ store, err := openHistoryStore(false)+ if err != nil {+ t.Fatal(err)+ }+ for _, stmt := range []string{+ `UPDATE traces SET aggregate = replace(aggregate, '"title":"rotate the flaky fixture"', '"title":"stale title"')`,+ `UPDATE events SET event_type = 'other', hay = 'stale'`,+ `UPDATE meta SET value = '0' WHERE key = 'derivation_version'`,+ } {+ if _, err := store.db.Exec(stmt); err != nil {+ t.Fatal(err)+ }+ }+ store.close()+ if os.Getenv(endpointconfig.HistoryStoreEnv) != withoutHistoryPath {+ t.Fatal("history path changed")+ }+ got, ok, err := ShowTrace(path, "session:codex_cli:s3", TraceQuery{Limit: 100})+ if err != nil || !ok {+ t.Fatalf("ShowTrace ok=%v err=%v", ok, err)+ }+ if mustJSON(t, got) != mustJSON(t, want) {+ t.Fatalf("after rebuild\n got %s\nwant %s", mustJSON(t, got), mustJSON(t, want))+ }+ result, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "retained answer"}, ResultLevel: "event", Limit: 10})+ if err != nil || result.TotalMatched != 1 {+ t.Fatalf("search after rebuild = %#v err=%v", result, err)+ }+}++func TestHistoryResetRemovesTheStore(t *testing.T) {+ path := traceStoreIndexedLog(t, parityFixture())+ if !HistoryStoreEnabled() {+ t.Fatal("history not enabled after reindex")+ }+ if err := ResetHistoryStore(); err != nil {+ t.Fatal(err)+ }+ if HistoryStoreEnabled() {+ t.Fatal("history still enabled after reset")+ }+ status, err := TraceStoreStatus(path)+ if err != nil || status.Enabled {+ t.Fatalf("status after reset = %#v err=%v", status, err)+ }+}++func TestHistoryStoreIsPrivateToItsOwner(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ traceStoreIndexedLog(t, parityFixture())+ info, err := os.Stat(endpointconfig.HistoryStorePath())+ if err != nil {+ t.Fatal(err)+ }+ if mode := info.Mode().Perm(); mode != 0o600 {+ t.Fatalf("history store mode = %o, want 600", mode)+ }+}++func TestHistoryRemovesTheLegacyTraceCache(t *testing.T) {+ path := newTestLog(t, parityFixture())+ legacy := filepath.Join(filepath.Dir(filepath.Dir(path)), "traces.db")+ if err := os.WriteFile(legacy, []byte("old cache"), 0o600); err != nil {+ t.Fatal(err)+ }+ withHistory(t)+ optIn(t, path)+ if _, err := os.Stat(legacy); !os.IsNotExist(err) {+ t.Fatalf("traces.db still present after opting in: %v", err)+ }+}++// On Windows a rename fails while any handle lacks FILE_SHARE_DELETE. A catch-up holding a log+// file must not stop the writer rotating it.+func TestOpenLogFileAllowsTheWriterToRotate(t *testing.T) {+ path := newTestLog(t, parityFixture())+ f, err := openLogFile(path)+ if err != nil {+ t.Fatal(err)+ }+ defer f.Close()+ if err := os.Rename(path, path+".1"); err != nil {+ t.Fatalf("rename with the log open for reading: %v", err)+ }+}++// noiseText is deterministic text without repeats, so its search index is as large as real text's.+func noiseText(seed, n int) string {+ var b strings.Builder+ sum := sha256.Sum256([]byte(fmt.Sprint(seed)))+ for b.Len() < n {+ sum = sha256.Sum256(sum[:])+ b.WriteString(hex.EncodeToString(sum[:]))+ b.WriteByte(' ')+ }+ return b.String()[:n]+}++// The store keeps only the raw keys in historyRawKeys. A raw key the dashboard reads and the store+// drops would make a rebuilt history differ from the log, so every one must be listed.+func TestHistoryKeepsEveryRawKeyTheDashboardReads(t *testing.T) {+ files, err := filepath.Glob("*.go")+ if err != nil {+ t.Fatal(err)+ }+ pattern := regexp.MustCompile(`(?:rawString\([^,]+, |intFromRaw\([^,]+, |Raw\[)"([^"]+)"`)+ found := 0+ for _, file := range files {+ if strings.HasSuffix(file, "_test.go") {+ continue+ }+ data, err := os.ReadFile(file)+ if err != nil {+ t.Fatal(err)+ }+ for _, match := range pattern.FindAllStringSubmatch(string(data), -1) {+ found+++ if !historyRawKeys[match[1]] {+ t.Errorf("%s reads raw key %q, which the history store drops; add it to historyRawKeys", file, match[1])+ }+ }+ }+ if found < 10 {+ t.Fatalf("found %d raw key reads; the pattern no longer matches the code", found)+ }+}++func TestStoredLineKeepsEverythingButUnreadRawKeys(t *testing.T) {+ line := []byte(`{"timestamp":"t","future_field":{"a":1},"raw":{"metric_name":"m","attributes":{"prompt":"secret"},"shared_url":"u"},"event":{"id":"x"}}`)+ stored, err := storedLine(line)+ if err != nil {+ t.Fatal(err)+ }+ want := `{"event":{"id":"x"},"future_field":{"a":1},"raw":{"metric_name":"m","shared_url":"u"},"timestamp":"t"}`+ if string(stored) != want {+ t.Fatalf("stored line = %s, want %s", stored, want)+ }+ roundTrip, err := decompressLine(compressLine(stored))+ if err != nil || string(roundTrip) != want {+ t.Fatalf("round trip = %s, %v", roundTrip, err)+ }+ onlyUnread, err := storedLine([]byte(`{"raw":{"attributes":{}},"event":{"id":"y"}}`))+ if err != nil || string(onlyUnread) != `{"event":{"id":"y"}}` {+ t.Fatalf("stored line without kept raw keys = %s, %v", onlyUnread, err)+ }+}++// Events that arrive after later ones are folded into their place in the trace, both before the+// first checkpoint and after one, and the trace reads exactly as the JSONL scan reads it.+func TestHistoryRefoldsWhenAnEventArrivesLate(t *testing.T) {+ withHistory(t)+ path := newTestLog(t, nil)+ base := time.Date(2026, 6, 11, 10, 0, 0, 0, time.UTC)+ var lines [][]byte+ appendEvent := func(at time.Time, id, text string) {+ event := testSchemaEvent(at.Format(time.RFC3339Nano), "claude_code", "prompt.submitted", "prompt", "repo-a")+ event.Event.ID = id+ event.Session = &schema.SessionInfo{ID: "long"}+ event.Prompt = &schema.PromptInfo{Text: text}+ lines = append(lines, marshalEvents(t, event)...)+ writeTestLog(t, path, lines...)+ }+ for i := 0; i < 600; i++ {+ appendEvent(base.Add(time.Duration(i)*time.Second), fmt.Sprintf("in-order-%d", i), fmt.Sprintf("prompt %d", i))+ }+ optIn(t, path)+ check := func(label string) {+ t.Helper()+ ids := []string{"session:claude_code:long"}+ history := traceAnswers(t, path, ids)+ previous := os.Getenv(endpointconfig.HistoryStoreEnv)+ withoutHistory(t)+ want := traceAnswers(t, path, ids)+ t.Setenv(endpointconfig.HistoryStoreEnv, previous)+ for key, w := range want {+ if history[key] != w {+ t.Fatalf("%s: %s differs from the JSONL scan", label, key)+ }+ }+ }+ // Lands after the second checkpoint (event 512).+ appendEvent(base.Add(550*time.Second+time.Millisecond), "late-after-checkpoint", "late near the end")+ check("after a checkpoint")+ // Lands between the first two checkpoints.+ appendEvent(base.Add(300*time.Second+time.Millisecond), "late-mid", "late in the middle")+ check("between checkpoints")+ // Becomes the first event: the trace refolds from its start.+ appendEvent(base.Add(-time.Hour), "late-first", "late and first")+ check("first event")+ show, ok, err := ShowTrace(path, "session:claude_code:long", TraceQuery{Limit: 1})+ if err != nil || !ok || show.Events[0].ID != "late-first" || show.Trace.EventCount != 603 {+ t.Fatalf("show = %#v ok=%v err=%v", show.Range, ok, err)+ }+}diff --git a/cli/beacon/internal/endpoint/dashboard/trace_store.go b/cli/beacon/internal/endpoint/dashboard/trace_store.godeleted file mode 100644index e941260c..00000000--- a/cli/beacon/internal/endpoint/dashboard/trace_store.go+++ /dev/null@@ -1,801 +0,0 @@-package dashboard--import (- "database/sql"- "encoding/json"- "fmt"- "os"- "path/filepath"- "sort"- "strings"- "time"-- _ "modernc.org/sqlite"-)--const traceStoreFile = "traces.db"--// traceStoreSchemaVersion is written to the database's user_version. The store-// is a rebuildable index over the runtime log, never a source of truth, so a-// version bump drops the tables and reindexes rather than migrating them.-const traceStoreSchemaVersion = 4--// Search rows are an acceleration structure, not retained evidence. Keep them-// small and fall back to the JSONL scan for free-text queries when truncation-// could hide a match.-const maxTraceStoreSearchBodyBytes = 16 * 1024--type traceStore struct {- dbPath string- // logPath is the log to read; sourceKey is the same path normalized, and is- // what every row is scoped by. Sibling logs in one directory share one- // traces.db, so two sources can hold the same trace or event id.- logPath string- sourceKey string-}--type traceStoreStatus struct {- Path string `json:"path"`- Traces int `json:"traces"`- Events int `json:"events"`- IndexRows int `json:"index_rows"`- SizeBytes int64 `json:"size_bytes"`- WALBytes int64 `json:"wal_bytes,omitempty"`- IndexedAt string `json:"indexed_at,omitempty"`-}--func TraceStorePath(logPath string) string {- return defaultTraceStorePath(logPath)-}--func TraceStoreStatus(logPath string) (traceStoreStatus, error) {- return openTraceStore(logPath).Status()-}--func ReindexTraceStore(logPath string) error {- return openTraceStore(logPath).Reindex()-}--func defaultTraceStorePath(logPath string) string {- if strings.TrimSpace(logPath) == "" {- return traceStoreFile- }- dir := filepath.Dir(logPath)- if filepath.Base(dir) == "logs" {- return filepath.Join(filepath.Dir(dir), traceStoreFile)- }- return filepath.Join(dir, traceStoreFile)-}--func openTraceStore(logPath string) *traceStore {- return &traceStore{- dbPath: defaultTraceStorePath(logPath),- logPath: logPath,- sourceKey: traceSourceKey(logPath),- }-}--// traceSourceKey normalizes a log path so the same log reached by a relative-// and an absolute path indexes once rather than twice.-func traceSourceKey(logPath string) string {- abs, err := filepath.Abs(logPath)- if err != nil {- return logPath- }- return filepath.Clean(abs)-}--func (s *traceStore) db() (*sql.DB, error) {- if err := os.MkdirAll(filepath.Dir(s.dbPath), 0700); err != nil {- return nil, err- }- db, err := sql.Open("sqlite", sqliteURI(s.dbPath))- if err != nil {- return nil, err- }- if _, err := db.Exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;`); err != nil {- _ = db.Close()- return nil, err- }- if err := ensureTraceStoreSchema(db); err != nil {- _ = db.Close()- return nil, err- }- return db, nil-}--func sqliteURI(path string) string {- abs, err := filepath.Abs(path)- if err != nil {- abs = path- }- return "file:" + filepath.ToSlash(abs) + "?_pragma=busy_timeout(5000)"-}--func ensureTraceStoreSchema(db *sql.DB) error {- var version int- if err := db.QueryRow(`PRAGMA user_version`).Scan(&version); err != nil {- return err- }- // Any version but the current one is dropped, 0 included: a database this- // build has never stamped either is empty, where the drops are no-ops, or- // predates the stamp and holds tables CREATE TABLE IF NOT EXISTS would- // leave in their old shape.- if version != traceStoreSchemaVersion {- for _, table := range []string{"trace_search", "trace_events", "traces", "trace_index_state"} {- if _, err := db.Exec(`DROP TABLE IF EXISTS ` + table); err != nil {- return err- }- }- }- stmts := []string{- `CREATE TABLE IF NOT EXISTS trace_index_state (- source_key TEXT PRIMARY KEY,- fingerprint TEXT NOT NULL,- indexed_at TEXT NOT NULL- )`,- // Trace ids are unique within one source, not across a directory of- // them, so the key carries the source.- `CREATE TABLE IF NOT EXISTS traces (- source_key TEXT NOT NULL,- id TEXT NOT NULL,- summary_json TEXT NOT NULL,- updated_at TEXT,- created_at TEXT NOT NULL,- PRIMARY KEY (source_key, id)- )`,- `CREATE INDEX IF NOT EXISTS traces_by_source_updated ON traces (source_key, updated_at DESC)`,- // event_number is the event's ordinal within its trace, which is what- // makes a row unique. event_id is the runtime's own name for the call- // and is deliberately not part of the key: two events can share one --- // a repeated log line, or a hook and an OTLP capture of the same call,- // whose ids are derived to match -- and the JSONL path keeps both.- `CREATE TABLE IF NOT EXISTS trace_events (- source_key TEXT NOT NULL,- trace_id TEXT NOT NULL,- event_number INTEGER NOT NULL,- event_id TEXT NOT NULL,- event_type TEXT,- tool_name TEXT,- event_json TEXT NOT NULL,- created_at TEXT NOT NULL,- PRIMARY KEY (source_key, trace_id, event_number)- )`,- `CREATE INDEX IF NOT EXISTS trace_events_by_event_id ON trace_events (source_key, trace_id, event_id)`,- `CREATE TABLE IF NOT EXISTS trace_search (- source_key TEXT NOT NULL,- trace_id TEXT NOT NULL,- event_id TEXT,- source TEXT NOT NULL,- event_type TEXT,- tool_name TEXT,- event_number INTEGER,- body TEXT NOT NULL,- body_truncated INTEGER NOT NULL DEFAULT 0- )`,- `CREATE INDEX IF NOT EXISTS trace_search_by_source_trace ON trace_search (source_key, source, trace_id)`,- }- for _, stmt := range stmts {- if _, err := db.Exec(stmt); err != nil {- return err- }- }- if version != traceStoreSchemaVersion {- if _, err := db.Exec(fmt.Sprintf(`PRAGMA user_version = %d`, traceStoreSchemaVersion)); err != nil {- return err- }- }- return nil-}--func (s *traceStore) ensureCurrent() error {- db, err := s.db()- if err != nil {- return err- }- defer db.Close()- fingerprint := traceLogFingerprint(s.logPath)- var current string- err = db.QueryRow(`SELECT fingerprint FROM trace_index_state WHERE source_key = ?`, s.sourceKey).Scan(¤t)- if err == nil && current == fingerprint {- return nil- }- if err != nil && err != sql.ErrNoRows {- return err- }- return s.reindexDB(db, fingerprint)-}--func (s *traceStore) Reindex() error {- db, err := s.db()- if err != nil {- return err- }- defer db.Close()- return s.reindexDB(db, traceLogFingerprint(s.logPath))-}--func (s *traceStore) reindexDB(db *sql.DB, fingerprint string) error {- traces, err := readTraceAggregates(s.logPath, EventQuery{})- if err != nil {- return err- }- tx, err := db.Begin()- if err != nil {- return err- }- defer tx.Rollback()- if err := purgeMissingTraceSources(tx); err != nil {- return err- }- for _, stmt := range []string{- `DELETE FROM trace_search WHERE source_key = ?`,- `DELETE FROM trace_events WHERE source_key = ?`,- `DELETE FROM traces WHERE source_key = ?`,- } {- if _, err := tx.Exec(stmt, s.sourceKey); err != nil {- return err- }- }- now := time.Now().UTC().Format(time.RFC3339Nano)- for _, agg := range traces {- if err := insertTraceAggregate(tx, s.sourceKey, agg, now); err != nil {- return err- }- }- if _, err := tx.Exec(`INSERT INTO trace_index_state (source_key, fingerprint, indexed_at) VALUES (?, ?, ?)- ON CONFLICT(source_key) DO UPDATE SET fingerprint = excluded.fingerprint, indexed_at = excluded.indexed_at`,- s.sourceKey, fingerprint, now); err != nil {- return err- }- if err := tx.Commit(); err != nil {- return err- }- return checkpointTraceStore(db)-}--func insertTraceAggregate(tx *sql.Tx, sourceKey string, agg *traceAggregate, now string) error {- summaryJSON, err := json.Marshal(agg.summary)- if err != nil {- return err- }- if _, err := tx.Exec(`INSERT INTO traces (source_key, id, summary_json, updated_at, created_at) VALUES (?, ?, ?, ?, ?)`,- sourceKey, agg.summary.ID, string(summaryJSON), agg.summary.UpdatedAt, now); err != nil {- return err- }- if err := insertTraceSearchRow(tx, sourceKey, agg.summary.ID, "", "trace", "", "", 0, traceSummaryHaystack(agg.summary)); err != nil {- return err- }- for _, event := range agg.events {- eventJSON, err := json.Marshal(event)- if err != nil {- return err- }- toolName := ""- if event.Tool != nil {- toolName = event.Tool.Name- }- if event.Command != nil && toolName == "" {- toolName = "command"- }- if _, err := tx.Exec(`INSERT INTO trace_events (source_key, trace_id, event_number, event_id, event_type, tool_name, event_json, created_at)- VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,- sourceKey, agg.summary.ID, event.Number, event.ID, event.Type, toolName, string(eventJSON), now); err != nil {- return err- }- if err := insertTraceSearchRow(tx, sourceKey, agg.summary.ID, event.ID, "event", event.Type, toolName, event.Number, traceEventHaystack(event)); err != nil {- return err- }- }- return nil-}--func insertTraceSearchRow(tx *sql.Tx, sourceKey, traceID, eventID, source, eventType, toolName string, eventNumber int, body string) error {- body, truncated := truncateTraceSearchBody(body)- truncatedInt := 0- if truncated {- truncatedInt = 1- }- _, err := tx.Exec(`INSERT INTO trace_search (source_key, trace_id, event_id, source, event_type, tool_name, event_number, body, body_truncated)- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,- sourceKey, traceID, eventID, source, eventType, toolName, eventNumber, body, truncatedInt)- return err-}--func (s *traceStore) Status() (traceStoreStatus, error) {- if err := s.ensureCurrent(); err != nil {- return traceStoreStatus{}, err- }- db, err := s.db()- if err != nil {- return traceStoreStatus{}, err- }- defer db.Close()- status := traceStoreStatus{Path: s.dbPath, SizeBytes: fileSize(s.dbPath), WALBytes: fileSize(s.dbPath + "-wal")}- _ = db.QueryRow(`SELECT COUNT(*) FROM traces WHERE source_key = ?`, s.sourceKey).Scan(&status.Traces)- _ = db.QueryRow(`SELECT COUNT(*) FROM trace_events WHERE source_key = ?`, s.sourceKey).Scan(&status.Events)- _ = db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE source_key = ?`, s.sourceKey).Scan(&status.IndexRows)- _ = db.QueryRow(`SELECT indexed_at FROM trace_index_state WHERE source_key = ?`, s.sourceKey).Scan(&status.IndexedAt)- return status, nil-}--func (s *traceStore) List(query TraceQuery) (TraceListResultV1, error) {- if !traceStoreSupportsQuery(query) {- return TraceListResultV1{}, errTraceStoreUnsupported- }- if err := s.ensureCurrent(); err != nil {- return TraceListResultV1{}, err- }- summaries, err := s.loadSummaries()- if err != nil {- return TraceListResultV1{}, err- }- filtered := make([]TraceSummaryV1, 0, len(summaries))- // traceAggregateMatches keeps a trace whose summary or any of its events- // match, so the store searches both kinds of row.- matchingIDs, err := s.matchingTraceIDs(query.Q, "trace", "event")- if err != nil {- return TraceListResultV1{}, err- }- for _, summary := range summaries {- if query.State != "" && !strings.EqualFold(summary.Sharing.State, query.State) {- continue- }- if query.Visibility != "" && !strings.EqualFold(summary.Sharing.Visibility, query.Visibility) {- continue- }- if query.Q != "" && !matchingIDs[summary.ID] {- continue- }- filtered = append(filtered, summary)- }- sortTraceSummaries(filtered)- limit := normalizeLimit(query.Limit)- page := query.Page- if page <= 0 {- page = 1- }- start := (page - 1) * limit- if start > len(filtered) {- start = len(filtered)- }- end := start + limit- if end > len(filtered) {- end = len(filtered)- }- return TraceListResultV1{- Traces: filtered[start:end],- TotalMatched: len(filtered),- Returned: end - start,- Limit: limit,- Page: page,- Truncated: end < len(filtered),- Filters: activeTraceFilters(query),- }, nil-}--func (s *traceStore) Search(query TraceQuery) (TraceSearchResultV1, error) {- if !traceStoreSupportsQuery(query) {- return TraceSearchResultV1{}, errTraceStoreUnsupported- }- if query.ResultLevel == "" {- query.ResultLevel = "trace"- }- if err := s.ensureCurrent(); err != nil {- return TraceSearchResultV1{}, err- }- limit := normalizeLimit(query.Limit)- resp := TraceSearchResultV1{ResultLevel: query.ResultLevel, Limit: limit, Filters: activeTraceFilters(query)}- switch query.ResultLevel {- case "event":- events, err := s.searchEvents(query, limit)- if err != nil {- return TraceSearchResultV1{}, err- }- resp.Events = events.returned- resp.TotalMatched = events.total- resp.Returned = len(resp.Events)- default:- resp.ResultLevel = "trace"- summaries, err := s.loadSummaries()- if err != nil {- return TraceSearchResultV1{}, err- }- // Unlike List, trace-level search matches the summary alone -- the- // JSONL path uses traceSummaryMatches here, not traceAggregateMatches.- matching, err := s.matchingTraceIDs(query.Q, "trace")- if err != nil {- return TraceSearchResultV1{}, err- }- for _, summary := range summaries {- if query.State != "" && !strings.EqualFold(summary.Sharing.State, query.State) {- continue- }- if query.Visibility != "" && !strings.EqualFold(summary.Sharing.Visibility, query.Visibility) {- continue- }- if query.Q != "" && !matching[summary.ID] {- continue- }- resp.Traces = append(resp.Traces, summary)- }- sortTraceSummaries(resp.Traces)- resp.TotalMatched = len(resp.Traces)- if len(resp.Traces) > limit {- resp.Traces = resp.Traces[:limit]- }- resp.Returned = len(resp.Traces)- }- return resp, nil-}--func (s *traceStore) Show(id string, query TraceQuery) (TraceShowResultV1, bool, error) {- if !traceStoreSupportsQuery(query) {- return TraceShowResultV1{}, false, errTraceStoreUnsupported- }- if err := s.ensureCurrent(); err != nil {- return TraceShowResultV1{}, false, err- }- db, err := s.db()- if err != nil {- return TraceShowResultV1{}, false, err- }- defer db.Close()- var summaryJSON string- err = db.QueryRow(`SELECT summary_json FROM traces WHERE source_key = ? AND id = ?`, s.sourceKey, id).Scan(&summaryJSON)- if err == sql.ErrNoRows {- return TraceShowResultV1{}, false, nil- }- if err != nil {- return TraceShowResultV1{}, false, err- }- var summary TraceSummaryV1- if err := json.Unmarshal([]byte(summaryJSON), &summary); err != nil {- return TraceShowResultV1{}, false, err- }- events, err := s.loadTraceEvents(db, id, query.EventTypes)- if err != nil {- return TraceShowResultV1{}, false, err- }- total := len(events)- offset, limit := traceRange(query, total)- end := offset - 1 + limit- if end > total {- end = total- }- if offset-1 > end {- end = offset - 1- }- return TraceShowResultV1{- Trace: summary,- Events: append([]TraceEventV1(nil), events[offset-1:end]...),- Spans: spansFromEvents(events),- Range: TraceRangeV1{- TotalEvents: total,- ReturnedEvents: end - (offset - 1),- Offset: offset,- Limit: limit,- AroundEvent: query.AroundEvent,- },- }, true, nil-}--var errTraceStoreUnsupported = fmt.Errorf("trace store does not support query")--func traceStoreSupportsQuery(query TraceQuery) bool {- eq := query.EventQuery- return eq.Since.IsZero() &&- eq.Until.IsZero() &&- eq.Harness == "" &&- eq.Model == "" &&- eq.Action == "" &&- eq.Severity == "" &&- eq.Category == "" &&- eq.Repository == "" &&- eq.Session == "" &&- eq.Trace == "" &&- eq.File == "" &&- eq.Command == "" &&- eq.MCP == "" &&- eq.Approval == "" &&- eq.Decision == "" &&- eq.Policy == "" &&- eq.Review == "" &&- eq.WazuhLevel == "" &&- eq.SessionState == ""-}--func (s *traceStore) loadSummaries() ([]TraceSummaryV1, error) {- db, err := s.db()- if err != nil {- return nil, err- }- defer db.Close()- rows, err := db.Query(`SELECT summary_json FROM traces WHERE source_key = ?`, s.sourceKey)- if err != nil {- return nil, err- }- defer rows.Close()- var summaries []TraceSummaryV1- for rows.Next() {- var raw string- if err := rows.Scan(&raw); err != nil {- return nil, err- }- var summary TraceSummaryV1- if err := json.Unmarshal([]byte(raw), &summary); err != nil {- return nil, err- }- summaries = append(summaries, summary)- }- return summaries, rows.Err()-}--// matchingTraceIDs returns the traces whose indexed text matches the free-text-// query, looking only at the named row kinds ("trace" for summaries, "event"-// for events).-func (s *traceStore) matchingTraceIDs(q string, kinds ...string) (map[string]bool, error) {- out := map[string]bool{}- needle := strings.TrimSpace(q)- if needle == "" || len(kinds) == 0 {- return out, nil- }- db, err := s.db()- if err != nil {- return nil, err- }- defer db.Close()- if truncated, err := s.hasTruncatedSearchRows(db, kinds...); err != nil {- return nil, err- } else if truncated {- return nil, errTraceStoreUnsupported- }- args := []any{s.sourceKey}- for _, kind := range kinds {- args = append(args, kind)- }- rows, err := db.Query(`SELECT trace_id, body FROM trace_search WHERE source_key = ? AND source IN (`+placeholders(len(kinds))+`)`, args...)- if err != nil {- return nil, err- }- defer rows.Close()- for rows.Next() {- var id, body string- if err := rows.Scan(&id, &body); err != nil {- return nil, err- }- if matchesAllTerms(body, needle) {- out[id] = true- }- }- return out, rows.Err()-}--type traceEventSearchRows struct {- returned []TraceEventMatchV1- total int-}--func (s *traceStore) searchEvents(query TraceQuery, limit int) (traceEventSearchRows, error) {- db, err := s.db()- if err != nil {- return traceEventSearchRows{}, err- }- defer db.Close()- summaries, err := s.loadSummaries()- if err != nil {- return traceEventSearchRows{}, err- }- sortTraceSummaries(summaries)- result := traceEventSearchRows{}- allowedTypes := traceEventTypeSet(query.EventTypes)- needle := strings.TrimSpace(query.Q)- for _, summary := range summaries {- if query.State != "" && !strings.EqualFold(summary.Sharing.State, query.State) {- continue- }- if query.Visibility != "" && !strings.EqualFold(summary.Sharing.Visibility, query.Visibility) {- continue- }- events, err := s.loadTraceEvents(db, summary.ID, nil)- if err != nil {- return traceEventSearchRows{}, err- }- for _, event := range events {- if len(allowedTypes) > 0 && !allowedTypes[traceEventTypeAlias(event.Type)] && !allowedTypes[strings.ToLower(event.Type)] {- continue- }- if needle != "" && !traceEventMatches(event, needle) {- continue- }- result.total++- if len(result.returned) < limit {- result.returned = append(result.returned, TraceEventMatchV1{- Trace: summary,- Event: event,- Snippet: traceSnippet(event, needle),- Score: 1,- })- }- }- }- return result, nil-}--func (s *traceStore) loadTraceEvents(db *sql.DB, traceID string, eventTypes []string) ([]TraceEventV1, error) {- rows, err := db.Query(`SELECT event_json FROM trace_events WHERE source_key = ? AND trace_id = ? ORDER BY event_number`, s.sourceKey, traceID)- if err != nil {- return nil, err- }- defer rows.Close()- allowed := traceEventTypeSet(eventTypes)- var events []TraceEventV1- for rows.Next() {- var raw string- if err := rows.Scan(&raw); err != nil {- return nil, err- }- var event TraceEventV1- if err := json.Unmarshal([]byte(raw), &event); err != nil {- return nil, err- }- if len(allowed) == 0 || allowed[strings.ToLower(event.Type)] || allowed[traceEventTypeAlias(event.Type)] {- events = append(events, event)- }- }- return events, rows.Err()-}--func spansFromEvents(events []TraceEventV1) []TraceSpanV1 {- spans := map[string]*TraceSpanV1{}- for _, event := range events {- if event.Trace == nil || event.Trace.SpanID == "" {- continue- }- span := spans[event.Trace.SpanID]- if span == nil {- span = &TraceSpanV1{ID: event.Trace.SpanID, ParentSpanID: event.Trace.ParentSpanID, TraceID: event.Trace.ID}- spans[event.Trace.SpanID] = span- }- if span.Name == "" {- span.Name = firstNonEmpty(event.Summary, event.Title, event.Action)- }- span.EventIDs = append(span.EventIDs, event.ID)- }- return traceSpanList(spans)-}--func traceLogFingerprint(logPath string) string {- parts := []string{}- for _, source := range eventSources(logPath) {- info, err := os.Stat(source.path)- if err != nil {- continue- }- parts = append(parts, fmt.Sprintf("%s:%d:%d", source.path, info.Size(), info.ModTime().UnixNano()))- }- sort.Strings(parts)- return strings.Join(parts, "|")-}--func purgeMissingTraceSources(tx *sql.Tx) error {- rows, err := tx.Query(`SELECT source_key FROM trace_index_state`)- if err != nil {- return err- }- var missing []string- for rows.Next() {- var source string- if err := rows.Scan(&source); err != nil {- rows.Close()- return err- }- if _, err := os.Stat(source); os.IsNotExist(err) {- missing = append(missing, source)- }- }- if err := rows.Close(); err != nil {- return err- }- if err := rows.Err(); err != nil {- return err- }- for _, source := range missing {- for _, stmt := range []string{- `DELETE FROM trace_search WHERE source_key = ?`,- `DELETE FROM trace_events WHERE source_key = ?`,- `DELETE FROM traces WHERE source_key = ?`,- `DELETE FROM trace_index_state WHERE source_key = ?`,- } {- if _, err := tx.Exec(stmt, source); err != nil {- return err- }- }- }- return nil-}--func checkpointTraceStore(db *sql.DB) error {- _, err := db.Exec(`PRAGMA wal_checkpoint(TRUNCATE)`)- return err-}--func fileSize(path string) int64 {- info, err := os.Stat(path)- if err != nil {- return 0- }- return info.Size()-}--func truncateTraceSearchBody(body string) (string, bool) {- if len(body) <= maxTraceStoreSearchBodyBytes {- return body, false- }- used := 0- for i, r := range body {- next := used + len(string(r))- if next > maxTraceStoreSearchBodyBytes {- return body[:i], true- }- used = next- }- return body, false-}--func (s *traceStore) hasTruncatedSearchRows(db *sql.DB, kinds ...string) (bool, error) {- if len(kinds) == 0 {- return false, nil- }- args := []any{s.sourceKey}- for _, kind := range kinds {- args = append(args, kind)- }- var count int- err := db.QueryRow(`SELECT COUNT(*) FROM trace_search WHERE source_key = ? AND source IN (`+placeholders(len(kinds))+`) AND body_truncated = 1`, args...).Scan(&count)- return count > 0, err-}--// placeholders builds an n-wide SQL "?,?,..." list.-func placeholders(n int) string {- if n <= 0 {- return ""- }- return strings.TrimSuffix(strings.Repeat("?,", n), ",")-}--func traceEventTypeSet(values []string) map[string]bool {- if len(values) == 0 {- return nil- }- out := map[string]bool{}- for _, value := range values {- value = strings.ToLower(strings.TrimSpace(value))- if value == "" {- continue- }- out[value] = true- switch value {- case "agent_text":- out["agent_message"] = true- case "agent_thinking":- out["agent_reasoning"] = true- case "agent_message":- out["agent_text"] = true- case "agent_reasoning":- out["agent_thinking"] = true- }- }- return out-}--func traceEventTypeAlias(value string) string {- switch strings.ToLower(value) {- case "agent_message":- return "agent_text"- case "agent_reasoning":- return "agent_thinking"- default:- return strings.ToLower(value)- }-}diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.goindex 347dba46..1ac0ac5c 100644--- a/cli/beacon/internal/endpoint/dashboard/traces.go+++ b/cli/beacon/internal/endpoint/dashboard/traces.go@@ -67,14 +67,14 @@ type traceAggregate struct {titlePriority int}-// The local store is an index over the runtime log, never a second source of-// truth: it answers the same question the JSONL scan below answers, and any-// error -- a query it does not support, an unreadable database, a stale index-// it could not rebuild -- falls back to that scan rather than failing the read.-// The two paths share one free-text matcher (matchesAllTerms) and one pair of-// haystacks precisely so the fallback cannot change the answer.+// The local history, once the user has opted in to it, answers the same+// question the JSONL scan below answers, over a longer window: it keeps what+// rotation deletes. Any error -- no history, a query it does not support, an+// unreadable database -- falls back to the scan rather than failing the read.+// The two paths share one free-text matcher (matchesAllTerms), one pair of+// haystacks and one event projection so the fallback cannot change the answer.func ReadTraceList(path string, query TraceQuery) (TraceListResultV1, error) {- if result, err := openTraceStore(path).List(query); err == nil {+ if result, err := historyList(path, query); err == nil {return result, nil}traces, err := readTraceAggregates(path, withoutFreeText(query.EventQuery))@@ -119,7 +119,7 @@ func ReadTraceList(path string, query TraceQuery) (TraceListResultV1, error) {// SearchTraces prefers the local store and falls back to scanning JSONL; see// ReadTraceList on why a store error is not an error here.func SearchTraces(path string, query TraceQuery) (TraceSearchResultV1, error) {- if result, err := openTraceStore(path).Search(query); err == nil {+ if result, err := historySearch(path, query); err == nil {return result, nil}if query.ResultLevel == "" {@@ -181,7 +181,7 @@ func SearchTraces(path string, query TraceQuery) (TraceSearchResultV1, error) {// ShowTrace prefers the local store and falls back to scanning JSONL; see// ReadTraceList on why a store error is not an error here.func ShowTrace(path, id string, query TraceQuery) (TraceShowResultV1, bool, error) {- if result, ok, err := openTraceStore(path).Show(id, query); err == nil {+ if result, ok, err := historyShow(path, id, query); err == nil {return result, ok, nil}traces, err := readTraceAggregates(path, withoutFreeText(query.EventQuery))@@ -205,7 +205,7 @@ func ShowTrace(path, id string, query TraceQuery) (TraceShowResultV1, bool, erroresp := TraceShowResultV1{Trace: agg.summary,Events: append([]TraceEventV1(nil), events[offset-1:end]...),- Spans: traceSpanList(agg.spans),+ Spans: spansFromEvents(events),Range: TraceRangeV1{TotalEvents: total,ReturnedEvents: end - (offset - 1),@@ -246,13 +246,7 @@ func readTraceAggregates(path string, query EventQuery) (map[string]*traceAggregid := traceProjectionID(event)agg := traces[id]if agg == nil {- agg = &traceAggregate{- summary: newTraceSummary(id, event),- spans: map[string]*TraceSpanV1{},- models: map[string]bool{},- methods: map[string]bool{},- titlePriority: -1,- }+ agg = newTraceAggregate(id, event)traces[id] = agg}te := traceEventFromRecord(record, len(agg.events)+1)@@ -265,6 +259,16 @@ func readTraceAggregates(path string, query EventQuery) (map[string]*traceAggregreturn traces, nil}+func newTraceAggregate(id string, event schema.Event) *traceAggregate {+ return &traceAggregate{+ summary: newTraceSummary(id, event),+ spans: map[string]*TraceSpanV1{},+ models: map[string]bool{},+ methods: map[string]bool{},+ titlePriority: -1,+ }+}+func newTraceSummary(id string, event schema.Event) TraceSummaryV1 {summary := TraceSummaryV1{ID: id,diff --git a/cli/beacon/internal/endpoint/dashboard/traces_content_test.go b/cli/beacon/internal/endpoint/dashboard/traces_content_test.goindex 63e8f618..5663145c 100644--- a/cli/beacon/internal/endpoint/dashboard/traces_content_test.go+++ b/cli/beacon/internal/endpoint/dashboard/traces_content_test.go@@ -316,11 +316,12 @@ func TestTraceContentKeepsPromptText(t *testing.T) {// fallback agree on it.func TestTraceSearchFindsRetainedAssistantText(t *testing.T) {lines := marshalEvents(t, assistantEvent("agent.message", codexAnswerLabel, asymptoteobserve.TextOutputMessages("rotate the flaky fixture")))- for name, path := range map[string]string{- "index": traceStoreIndexedLog(t, lines),- "fallback": traceStoreBlockedLog(t, lines),+ for name, logFor := range map[string]func(*testing.T, [][]byte) string{+ "index": traceStoreIndexedLog,+ "fallback": traceStoreBlockedLog,} {t.Run(name, func(t *testing.T) {+ path := logFor(t, lines)result, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "flaky fixture"}, ResultLevel: "event", Limit: 10})if err != nil {t.Fatalf("SearchTraces: %v", err)@@ -331,42 +332,3 @@ func TestTraceSearchFindsRetainedAssistantText(t *testing.T) {})}}--// A trace index written before this change holds the label as the assistant-// content, and its fingerprint still matches an unchanged log, so it would-// keep serving the label. The schema version bump makes it rebuild.-func TestTraceStoreRebuildsIndexFromBeforeRetainedOutputText(t *testing.T) {- answer := "the retained answer"- path := traceStoreIndexedLog(t, marshalEvents(t, assistantEvent("agent.message", codexAnswerLabel, asymptoteobserve.TextOutputMessages(answer))))- if _, err := TraceStoreStatus(path); err != nil {- t.Fatalf("index trace store: %v", err)- }-- // Rewrite the index as the previous build left it: schema version 3, with- // the label projected as the content.- db, err := openTraceStore(path).db()- if err != nil {- t.Fatalf("open trace store: %v", err)- }- stale, err := json.Marshal(TraceEventV1{ID: "evt-agent.message", Number: 1, Type: "agent_message", Action: "agent.message", Summary: codexAnswerLabel, Content: &TraceContentV1{Text: codexAnswerLabel, Retention: "full", Included: true}})- if err != nil {- t.Fatal(err)- }- if _, err := db.Exec(`UPDATE trace_events SET event_json = ? WHERE event_type = 'agent_message'`, string(stale)); err != nil {- t.Fatalf("write stale event: %v", err)- }- if _, err := db.Exec(`PRAGMA user_version = 3`); err != nil {- t.Fatalf("stamp old version: %v", err)- }- if err := db.Close(); err != nil {- t.Fatal(err)- }-- show, ok, err := ShowTrace(path, "session:codex_cli:s1", TraceQuery{Limit: 10})- if err != nil || !ok || len(show.Events) != 1 {- t.Fatalf("ShowTrace ok=%v err=%v events=%d", ok, err, len(show.Events))- }- if content := show.Events[0].Content; content == nil || content.Text != answer {- t.Fatalf("content = %#v, want the rebuilt %q rather than the stale label", content, answer)- }-}diff --git a/cli/beacon/internal/endpoint/dashboard/traces_test.go b/cli/beacon/internal/endpoint/dashboard/traces_test.goindex 03049a6a..cc69d284 100644--- a/cli/beacon/internal/endpoint/dashboard/traces_test.go+++ b/cli/beacon/internal/endpoint/dashboard/traces_test.go@@ -4,7 +4,6 @@ import ("encoding/json""net/http""net/http/httptest"- "os""path/filepath""strings""testing"@@ -377,327 +376,4 @@ func TestFreeTextSelectsTracesWithoutDroppingTheirEvents(t *testing.T) {}}-func TestTraceStoreIndexesAndRefreshesRuntimeLog(t *testing.T) {- path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")- if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {- t.Fatalf("mkdir log dir: %v", err)- }- prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- prompt.Event.ID = "evt-prompt"- prompt.Session = &schema.SessionInfo{ID: "s1", WorkingDirectory: "/repo/a"}- prompt.Prompt = &schema.PromptInfo{Text: "Index local traces"}- command := testSchemaEvent("2026-06-11T10:01:00Z", "cursor", "command.executed", "command", "repo-a")- command.Event.ID = "evt-command"- command.Session = prompt.Session- command.Command = &schema.CommandInfo{Command: "go test ./internal/endpoint/dashboard"}- writeTestLog(t, path, marshalEvents(t, prompt, command)...)-- status, err := TraceStoreStatus(path)- if err != nil {- t.Fatalf("TraceStoreStatus returned error: %v", err)- }- if status.Path != filepath.Join(filepath.Dir(filepath.Dir(path)), "traces.db") {- t.Fatalf("trace store path = %q", status.Path)- }- if status.Traces != 1 || status.Events != 2 || status.IndexRows != 3 {- t.Fatalf("status = %#v, want 1 trace, 2 events, 3 index rows", status)- }- if status.SizeBytes == 0 {- t.Fatalf("status size = %#v, want a non-empty trace store", status)- }-- results, err := SearchTraces(path, TraceQuery{EventQuery: EventQuery{Q: "dashboard"}, ResultLevel: "event", Limit: 10})- if err != nil {- t.Fatalf("SearchTraces returned error: %v", err)- }- if results.TotalMatched != 1 || len(results.Events) != 1 || results.Events[0].Event.ID != "evt-command" {- t.Fatalf("indexed search results = %#v", results)- }-- later := testSchemaEvent("2026-06-11T10:02:00Z", "cursor", "file.modified", "file", "repo-a")- later.Event.ID = "evt-file"- later.Session = prompt.Session- later.File = &schema.FileInfo{Path: "trace_store.go", Operation: "modify"}- writeTestLog(t, path, marshalEvents(t, prompt, command, later)...)-- status, err = TraceStoreStatus(path)- if err != nil {- t.Fatalf("TraceStoreStatus after refresh returned error: %v", err)- }- if status.Events != 3 || status.IndexRows != 4 {- t.Fatalf("refreshed status = %#v, want 3 events and 4 index rows", status)- }-}--func TestTraceStoreTruncatesSearchRowsAndFallsBackForExactSearch(t *testing.T) {- needle := "needle-after-index-cap"- prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- prompt.Event.ID = "evt-prompt"- prompt.Session = &schema.SessionInfo{ID: "s1"}- prompt.Prompt = &schema.PromptInfo{Text: strings.Repeat("a", maxTraceStoreSearchBodyBytes+1024) + needle}- path := traceStoreIndexedLog(t, marshalEvents(t, prompt))- if _, err := TraceStoreStatus(path); err != nil {- t.Fatalf("TraceStoreStatus returned error: %v", err)- }-- db, err := openTraceStore(path).db()- if err != nil {- t.Fatalf("open trace store: %v", err)- }- defer db.Close()- var maxBodyLen int- var truncatedRows int- if err := db.QueryRow(`SELECT MAX(length(body)), SUM(body_truncated) FROM trace_search WHERE source_key = ?`, traceSourceKey(path)).Scan(&maxBodyLen, &truncatedRows); err != nil {- t.Fatalf("query trace search rows: %v", err)- }- if maxBodyLen > maxTraceStoreSearchBodyBytes {- t.Fatalf("indexed search body length = %d, want <= %d", maxBodyLen, maxTraceStoreSearchBodyBytes)- }- if truncatedRows == 0 {- t.Fatalf("truncated rows = 0, want at least one capped search row")- }-- list, err := ReadTraceList(path, TraceQuery{EventQuery: EventQuery{Q: needle}, Limit: 10})- if err != nil {- t.Fatalf("ReadTraceList returned error: %v", err)- }- if list.TotalMatched != 1 {- t.Fatalf("ReadTraceList matched %d traces, want fallback to find the truncated term", list.TotalMatched)- }-}--// traceStoreBlockedLog copies the given log lines into a directory where the-// trace store cannot be opened (a directory sits where traces.db would go), so-// a query against the returned path exercises the JSONL fallback.-func traceStoreBlockedLog(t *testing.T, lines [][]byte) string {- t.Helper()- path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")- if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {- t.Fatalf("mkdir log dir: %v", err)- }- if err := os.MkdirAll(TraceStorePath(path), 0700); err != nil {- t.Fatalf("block trace store path: %v", err)- }- writeTestLog(t, path, lines...)- return path-}--func traceStoreIndexedLog(t *testing.T, lines [][]byte) string {- t.Helper()- path := filepath.Join(t.TempDir(), "logs", "runtime.jsonl")- if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {- t.Fatalf("mkdir log dir: %v", err)- }- writeTestLog(t, path, lines...)- return path-}--// The store may be faster than scanning JSONL, but it may not answer a-// different question. A query that reaches the index and the same query that-// falls back must select the same traces and the same events -- which they do-// not if the store reinterprets the query as a regular expression, or searches-// event text where the JSONL path searches only the summary.-func TestTraceStoreAndJSONLFallbackMatchIdentically(t *testing.T) {- prompt := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- prompt.Event.ID = "evt-prompt"- prompt.Session = &schema.SessionInfo{ID: "s1", WorkingDirectory: "/repo/a"}- prompt.Prompt = &schema.PromptInfo{Text: "Index local traces"}- command := testSchemaEvent("2026-06-11T10:01:00Z", "cursor", "command.executed", "command", "repo-a")- command.Event.ID = "evt-command"- command.Session = prompt.Session- command.Command = &schema.CommandInfo{Command: "go test ./internal/endpoint/dashboard"}- lines := marshalEvents(t, prompt, command)-- indexed := traceStoreIndexedLog(t, lines)- fallback := traceStoreBlockedLog(t, lines)-- queries := []string{- "dashboard go", // terms out of order: a substring match, not a regex one- "endpoint.dashboard", // "." is a literal here, so this must not match "endpoint/dashboard"- "endpoint/dashboard", // ... while the real separator must- "go test", // multi-word phrase- "(", // not a valid regular expression- "index local",- "INDEX LOCAL", // matching is case-insensitive- "nothing-matches-this",- }- for _, q := range queries {- t.Run(q, func(t *testing.T) {- indexedList, err := ReadTraceList(indexed, TraceQuery{EventQuery: EventQuery{Q: q}, Limit: 10})- if err != nil {- t.Fatalf("indexed list: %v", err)- }- fallbackList, err := ReadTraceList(fallback, TraceQuery{EventQuery: EventQuery{Q: q}, Limit: 10})- if err != nil {- t.Fatalf("fallback list: %v", err)- }- if indexedList.TotalMatched != fallbackList.TotalMatched {- t.Errorf("list matched %d traces from the index and %d from JSONL", indexedList.TotalMatched, fallbackList.TotalMatched)- }-- for _, level := range []string{"trace", "event"} {- indexedSearch, err := SearchTraces(indexed, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: level, Limit: 10})- if err != nil {- t.Fatalf("indexed %s search: %v", level, err)- }- fallbackSearch, err := SearchTraces(fallback, TraceQuery{EventQuery: EventQuery{Q: q}, ResultLevel: level, Limit: 10})- if err != nil {- t.Fatalf("fallback %s search: %v", level, err)- }- if indexedSearch.TotalMatched != fallbackSearch.TotalMatched {- t.Errorf("%s search matched %d from the index and %d from JSONL", level, indexedSearch.TotalMatched, fallbackSearch.TotalMatched)- }- if len(indexedSearch.Events) != len(fallbackSearch.Events) {- t.Fatalf("%s search returned %d events from the index and %d from JSONL", level, len(indexedSearch.Events), len(fallbackSearch.Events))- }- for i := range indexedSearch.Events {- if indexedSearch.Events[i].Event.ID != fallbackSearch.Events[i].Event.ID {- t.Errorf("%s search event %d = %q from the index, %q from JSONL", level, i, indexedSearch.Events[i].Event.ID, fallbackSearch.Events[i].Event.ID)- }- }- }- })- }-}--// Two events can carry one id -- a repeated log line, or a hook and an OTLP-// capture of the same call, whose ids are derived to match. The JSONL path-// keeps both, so the index must too rather than failing the whole reindex.-func TestTraceStoreKeepsEventsThatShareAnID(t *testing.T) {- first := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "command.executed", "command", "repo-a")- first.Event.ID = "same-event-id"- first.Session = &schema.SessionInfo{ID: "s1"}- first.Command = &schema.CommandInfo{Command: "go build ./..."}- second := first- second.Timestamp = "2026-06-11T10:00:01Z"- path := traceStoreIndexedLog(t, marshalEvents(t, first, second))-- status, err := TraceStoreStatus(path)- if err != nil {- t.Fatalf("TraceStoreStatus returned error: %v", err)- }- if status.Traces != 1 || status.Events != 2 {- t.Fatalf("status = %#v, want 1 trace and 2 events", status)- }-- list, err := ReadTraceList(path, TraceQuery{Limit: 10})- if err != nil {- t.Fatalf("ReadTraceList returned error: %v", err)- }- if len(list.Traces) != 1 {- t.Fatalf("ReadTraceList returned %d traces, want 1", len(list.Traces))- }-- show, ok, err := ShowTrace(path, list.Traces[0].ID, TraceQuery{Limit: 10})- if err != nil || !ok {- t.Fatalf("ShowTrace ok=%v err=%v", ok, err)- }- if len(show.Events) != 2 {- t.Fatalf("ShowTrace returned %d events, want both events that share an id", len(show.Events))- }-}--// Sibling logs in one directory share one traces.db, and two logs can describe-// the same session. Each must index under its own source rather than colliding.-func TestTraceStoreScopesTracesBySourceLog(t *testing.T) {- dir := filepath.Join(t.TempDir(), "logs")- if err := os.MkdirAll(dir, 0700); err != nil {- t.Fatalf("mkdir log dir: %v", err)- }- shared := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- shared.Event.ID = "evt-prompt"- shared.Session = &schema.SessionInfo{ID: "shared-session"}- shared.Prompt = &schema.PromptInfo{Text: "first log"}- other := shared- other.Prompt = &schema.PromptInfo{Text: "second log"}-- first := filepath.Join(dir, "runtime.jsonl")- second := filepath.Join(dir, "archive.jsonl")- writeTestLog(t, first, marshalEvents(t, shared)...)- writeTestLog(t, second, marshalEvents(t, other)...)- if TraceStorePath(first) != TraceStorePath(second) {- t.Fatalf("expected both logs to share one trace store")- }-- for _, tc := range []struct{ path, want string }{{first, "first log"}, {second, "second log"}} {- status, err := TraceStoreStatus(tc.path)- if err != nil {- t.Fatalf("TraceStoreStatus(%s) returned error: %v", tc.path, err)- }- if status.Traces != 1 || status.Events != 1 {- t.Fatalf("status for %s = %#v, want 1 trace and 1 event", tc.path, status)- }- result, err := SearchTraces(tc.path, TraceQuery{EventQuery: EventQuery{Q: tc.want}, ResultLevel: "event", Limit: 10})- if err != nil {- t.Fatalf("SearchTraces(%s) returned error: %v", tc.path, err)- }- if result.TotalMatched != 1 {- t.Fatalf("searching %s for %q matched %d events, want 1", tc.path, tc.want, result.TotalMatched)- }- }-}--func TestTraceStorePurgesMissingSourceLogs(t *testing.T) {- dir := filepath.Join(t.TempDir(), "logs")- if err := os.MkdirAll(dir, 0700); err != nil {- t.Fatalf("mkdir log dir: %v", err)- }- first := filepath.Join(dir, "runtime.jsonl")- second := filepath.Join(dir, "old-runtime.jsonl")- event := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- event.Event.ID = "evt-prompt"- event.Session = &schema.SessionInfo{ID: "s1"}- event.Prompt = &schema.PromptInfo{Text: "purge stale source"}- writeTestLog(t, first, marshalEvents(t, event)...)- writeTestLog(t, second, marshalEvents(t, event)...)-- if _, err := TraceStoreStatus(first); err != nil {- t.Fatalf("index first source: %v", err)- }- if _, err := TraceStoreStatus(second); err != nil {- t.Fatalf("index second source: %v", err)- }- if err := os.Remove(second); err != nil {- t.Fatalf("remove second source: %v", err)- }- if err := ReindexTraceStore(first); err != nil {- t.Fatalf("reindex first source: %v", err)- }-- db, err := openTraceStore(first).db()- if err != nil {- t.Fatalf("open trace store: %v", err)- }- defer db.Close()- var sources int- if err := db.QueryRow(`SELECT COUNT(*) FROM trace_index_state`).Scan(&sources); err != nil {- t.Fatalf("count sources: %v", err)- }- if sources != 1 {- t.Fatalf("indexed sources = %d, want stale source purged", sources)- }-}--// A relative and an absolute path to one log are one source, not two.-func TestTraceStoreTreatsEquivalentLogPathsAsOneSource(t *testing.T) {- path := traceStoreIndexedLog(t, marshalEvents(t, func() schema.Event {- event := testSchemaEvent("2026-06-11T10:00:00Z", "cursor", "prompt.submitted", "prompt", "repo-a")- event.Event.ID = "evt-prompt"- event.Session = &schema.SessionInfo{ID: "s1"}- event.Prompt = &schema.PromptInfo{Text: "one source"}- return event- }()))-- if _, err := TraceStoreStatus(path); err != nil {- t.Fatalf("TraceStoreStatus returned error: %v", err)- }- status, err := TraceStoreStatus(filepath.Join(filepath.Dir(path), ".", "runtime.jsonl"))- if err != nil {- t.Fatalf("TraceStoreStatus for the equivalent path returned error: %v", err)- }- if status.Traces != 1 || status.Events != 1 {- t.Fatalf("status = %#v, want the same single indexed trace", status)- }-}-func int64Ptr(v int64) *int64 { return &v }diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex ba4ff6de..2c844b79 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -650,6 +650,14 @@ func Uninstall(opts UninstallOptions) error {for _, path := range runtimeLogFiles(cfg.LogPath) {fail("remove "+path, os.Remove(path))}+ // The local history holds what the log held, and more, so it goes with the logs. It lives+ // in the user's own endpoint directory, which a system uninstall does not own.+ if cfg.UserMode {+ history := endpointconfig.HistoryStorePath()+ for _, suffix := range []string{"", "-wal", "-shm", ".lock"} {+ fail("remove "+history+suffix, os.Remove(history+suffix))+ }+ }}fail("remove install manifest", os.Remove(manifestPath(cfg.UserMode)))diff --git a/cli/beacon/internal/endpoint/lifecycle/uninstall_reporting_test.go b/cli/beacon/internal/endpoint/lifecycle/uninstall_reporting_test.goindex 545307c9..084572dd 100644--- a/cli/beacon/internal/endpoint/lifecycle/uninstall_reporting_test.go+++ b/cli/beacon/internal/endpoint/lifecycle/uninstall_reporting_test.go@@ -37,19 +37,21 @@ func TestUninstallAllowsUserModeWithoutPrivileges(t *testing.T) {}}-// Rotation turns one log into six files. Removing only runtime.jsonl left the archives -- up to+// Rotation turns one log into six files, and the local history keeps what rotation deleted. Removing only runtime.jsonl left the archives -- up to// 50 MB of retained prompt text and command lines -- on disk after an uninstall that was not asked// to keep logs, and invisible, because the file an operator would look for was gone.func TestUninstallRemovesRotatedArchivesToo(t *testing.T) {home := t.TempDir()testenv.SetHome(t, home)+ t.Setenv("BEACON_HISTORY_DB", "")logDir := filepath.Join(home, ".beacon", "endpoint", "logs")if err := os.MkdirAll(logDir, 0o755); err != nil {t.Fatal(err)}logPath := filepath.Join(logDir, "runtime.jsonl")- written := []string{logPath, logPath + ".1", logPath + ".2", logPath + ".lock"}+ history := filepath.Join(home, ".beacon", "endpoint", "history.db")+ written := []string{logPath, logPath + ".1", logPath + ".2", logPath + ".lock", history, history + "-wal"}for _, p := range written {if err := os.WriteFile(p, []byte("{}\n"), 0o600); err != nil {t.Fatal(err)@@ -71,13 +73,15 @@ func TestUninstallRemovesRotatedArchivesToo(t *testing.T) {func TestUninstallKeepLogsKeepsTheArchives(t *testing.T) {home := t.TempDir()testenv.SetHome(t, home)+ t.Setenv("BEACON_HISTORY_DB", "")logDir := filepath.Join(home, ".beacon", "endpoint", "logs")if err := os.MkdirAll(logDir, 0o755); err != nil {t.Fatal(err)}logPath := filepath.Join(logDir, "runtime.jsonl")- for _, p := range []string{logPath, logPath + ".1"} {+ history := filepath.Join(home, ".beacon", "endpoint", "history.db")+ for _, p := range []string{logPath, logPath + ".1", history} {if err := os.WriteFile(p, []byte("{}\n"), 0o600); err != nil {t.Fatal(err)}@@ -87,7 +91,7 @@ func TestUninstallKeepLogsKeepsTheArchives(t *testing.T) {t.Fatal(err)}- for _, p := range []string{logPath, logPath + ".1"} {+ for _, p := range []string{logPath, logPath + ".1", history} {if _, err := os.Stat(p); err != nil {t.Errorf("%s was removed despite --keep-logs", filepath.Base(p))}diff --git a/cli/beacon/internal/onboarding/choose.go b/cli/beacon/internal/onboarding/choose.gonew file mode 100644index 00000000..5700e3b5--- /dev/null+++ b/cli/beacon/internal/onboarding/choose.go@@ -0,0 +1,66 @@+package onboarding++import (+ "bufio"+ "errors"+ "fmt"+ "io"+ "strconv"+ "strings"+)++// Option is one answer to a Choose question: a label and an optional line of detail.+type Option struct {+ Label string+ Detail string+}++// Choose asks one question with the same arrow-key picker as the install wizard, or a numbered+// menu where the terminal cannot do raw input, and returns the index of the answer. Enter, or an+// empty typed answer, picks the first option.+func Choose(in io.Reader, out io.Writer, question string, options []Option) (int, error) {+ if len(options) == 0 {+ return 0, errors.New("no options to choose from")+ }+ color := supportsColor(out)+ fmt.Fprintf(out, " %s%s%s\n\n", title(color), question, reset(color))+ if tty, ok := terminalFile(in); ok {+ rows := make([]choice, len(options))+ for i, option := range options {+ rows[i] = choice{Label: option.Label, Detail: option.Detail}+ }+ index, err := selectOption(tty, out, rows, color)+ if err == nil {+ printChoice(out, options[index].Label, color)+ return index, nil+ }+ if !errors.Is(err, errRawUnavailable) {+ return 0, ErrPromptAborted+ }+ }+ for i, option := range options {+ fmt.Fprintf(out, " %d) %s\n", i+1, option.Label)+ if option.Detail != "" {+ fmt.Fprintf(out, " %s%s%s\n", dim(color), option.Detail, reset(color))+ }+ }+ fmt.Fprintln(out)+ reader := bufio.NewReader(in)+ for attempt := 0; attempt < maxAttempts; attempt++ {+ line, err := readLine(reader, out, fmt.Sprintf(" Choice [1-%d] ", len(options)))+ if err != nil {+ return 0, err+ }+ line = strings.TrimSpace(line)+ if line == "" {+ printChoice(out, options[0].Label, color)+ return 0, nil+ }+ if n, err := strconv.Atoi(line); err == nil && n >= 1 && n <= len(options) {+ printChoice(out, options[n-1].Label, color)+ return n - 1, nil+ }+ fmt.Fprintf(out, " %s✗ enter a number from 1 to %d%s\n", warn(color), len(options), reset(color))+ }+ return 0, ErrTooManyAttempts+}diff --git a/cli/beacon/internal/onboarding/profile.go b/cli/beacon/internal/onboarding/profile.goindex 88851cb6..2a2835a2 100644--- a/cli/beacon/internal/onboarding/profile.go+++ b/cli/beacon/internal/onboarding/profile.go@@ -50,6 +50,19 @@ type Profile struct {InstallID string `json:"install_id"`Onboarding Onboarding `json:"onboarding"`Pending *Submission `json:"pending_submission,omitempty"`+ // History records the answer to the local history prompt that `beacon endpoint traces` shows+ // once, so a "not now" is not asked again.+ History *History `json:"history,omitempty"`+}++// History is the answer to the local history prompt.+type History struct {+ DeclinedAt string `json:"declined_at,omitempty"`+}++// HistoryDeclined reports whether the user answered "not now" to the local history prompt.+func (p Profile) HistoryDeclined() bool {+ return p.History != nil && p.History.DeclinedAt != ""}// Onboarding records the outcome of the one-time prompt.diff --git a/docs/cli/endpoint-traces.mdx b/docs/cli/endpoint-traces.mdxindex 07ea0625..e15e8591 100644--- a/docs/cli/endpoint-traces.mdx+++ b/docs/cli/endpoint-traces.mdx@@ -1,11 +1,11 @@---title: "beacon endpoint traces"-description: "Index and search local endpoint traces from Beacon runtime logs"+description: "Search local endpoint traces and keep a local history of them"---## Command overview-`beacon endpoint traces` builds and reads a local trace index over the Beacon runtime JSONL log. Use it when you want a trace-oriented view of endpoint activity without starting the dashboard.+`beacon endpoint traces` reads the Beacon runtime JSONL log as traces: one per session or OpenTelemetry trace, with its events in order. Use it when you want a trace-oriented view of endpoint activity without starting the dashboard.Run the top-level command on an interactive terminal to open the full-screen local trace browser:@@ -21,7 +21,31 @@ When stdout or stdin is redirected, `beacon traces` falls back to a bounded tab-beacon endpoint traces [command]```-The index is local SQLite state derived from `runtime.jsonl`. Rebuilding it does not change the runtime log, and the command does not contact the network.+The commands read local files only and do not contact the network.++## Local history++The runtime log rotates after about 60 MB, which is a day or two of activity on a busy machine. Without a local history, trace commands can only see what is still in the log.++The local history is a SQLite file, `~/.beacon/endpoint/history.db`, that keeps sessions after the log rotates them away. Every trace command catches it up with the log before answering, so it needs no background service. It also makes search faster, since it keeps a full-text index of the same text the commands search.++It is off until you turn it on:++- The first `beacon endpoint traces` or `beacon traces` command on an interactive terminal asks once whether to create it. "Not now" is remembered.+- `beacon endpoint traces reindex` creates it without asking.+- Commands run by scripts, agents, pipes, `--json` or CI are never asked. They read the log and print a one-line note on stderr.++What it holds:++- The same prompts, commands, output and file changes the runtime log holds, after the same redaction. The runtime's raw payload is dropped except for the few fields trace summaries read.+- Nothing leaves the machine. The file is readable only by you (mode `0600`).+- Traces whose last event is older than 90 days are removed, and the oldest traces are removed once the file reaches 1 GB. Change either with `reindex --retention-days` and `reindex --max-size-mb`.++If the log rotates more than five times between two trace commands, the files in between are deleted before the history reads them. `status` reports this as a gap.++`beacon endpoint traces reset` deletes the history. `beacon endpoint uninstall` deletes it along with the runtime logs, unless you pass `--keep-logs`.++Set `BEACON_HISTORY_DB` to keep the history somewhere else.For assistant message and reasoning events, an event's `content.text` is the text retained in `gen_ai.output.messages`: what the assistant said, or its reasoning. The event's label, such as `Codex assistant message`, stays in `summary`, and fills `content.text` only when the event retained no text. The retained text went through Beacon's redaction and size limits when it was written, and `content.redacted` and `content.truncated` report either change. `beacon memory` evaluates traces from this same view.@@ -29,8 +53,9 @@ For assistant message and reasoning events, an event's `content.text` is the tex| Command | Description ||---------|-------------|-| `beacon endpoint traces status` | Show the trace-store path, indexed trace count, event count, index rows, size, and last index time |-| `beacon endpoint traces reindex` | Rebuild the trace store from the current runtime JSONL log |+| `beacon endpoint traces status` | Show whether the local history is set up, and its size, trace and event counts, oldest and newest event, limits, and any gaps |+| `beacon endpoint traces reindex` | Create the local history, or bring it up to date with the runtime log |+| `beacon endpoint traces reset` | Delete the local history. Asks first; `--yes` skips the question || `beacon endpoint traces list` | List local traces with harness, update time, and title || `beacon endpoint traces search <pattern>` | Search trace metadata or indexed event text || `beacon endpoint traces show <trace-id>` | Show events from one trace |@@ -69,6 +94,14 @@ All commands accept:| `--result-level trace` | Return matching traces. This is the default || `--result-level event` | Return matching events with snippets |+`reindex` also accepts:++| Flag | Description |+|------|-------------|+| `--retention-days <n>` | Remove traces whose last event is older than this. Defaults to `90`, and a value you set is kept |+| `--max-size-mb <n>` | Remove the oldest traces once the history reaches this size. Defaults to `1024`, and a value you set is kept |+| `--rebuild` | Recompute search text and summaries from the stored events |+`show` also accepts:| Flag | Description |@@ -80,12 +113,12 @@ All commands accept:## Examples-```bash title="Check the trace index"+```bash title="Check the local history"beacon endpoint traces status```-```bash title="Rebuild from runtime JSONL"-beacon endpoint traces reindex+```bash title="Create the local history, keeping 30 days"+beacon endpoint traces reindex --retention-days 30``````bash title="List recent traces"@@ -107,6 +140,6 @@ beacon endpoint traces show <trace-id> --around-event 42 --before 5 --after 10Inspect the same local endpoint activity in the loopback dashboard.</Card><Card title="Local JSONL" icon="file-lines" href="/log-forwarding/local-jsonl">- Understand the runtime log that the trace index is derived from.+ Understand the runtime log that traces and the local history are read from.</Card></Columns>diff --git a/docs/cli/index.mdx b/docs/cli/index.mdxindex 65d306e7..2e4068b4 100644--- a/docs/cli/index.mdx+++ b/docs/cli/index.mdx@@ -163,7 +163,7 @@ Manage the local endpoint agent and inspect supported agent harness telemetry.| [`beacon endpoint config`](/cli/endpoint-config) | Inspect endpoint configuration and validate destination settings. || [`beacon endpoint onboarding`](/cli/endpoint-onboarding) | Show, reset, or resend the one-time onboarding record. || [`beacon endpoint dashboard`](/cli/dashboard#beacon-endpoint-dashboard) | Run the local dashboard over Beacon runtime logs for endpoint inspection. |-| [`beacon endpoint traces`](/cli/endpoint-traces) | Index, list, search, and show local traces from Beacon runtime logs. |+| [`beacon endpoint traces`](/cli/endpoint-traces) | List, search, and show local traces, and keep a local history of them. || [`beacon endpoint wazuh`](/cli/wazuh) | Configure Wazuh ingestion for Beacon endpoint events. || [`beacon endpoint elastic`](/cli/elastic) | Generate Elastic content and run a local Elasticsearch, Kibana, and Filebeat validation stack. || [`beacon endpoint datadog`](/cli/datadog) | Generate Datadog Agent custom log collection content for Beacon endpoint events. |