Skip to content

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

feat(fx): collect fx sessions with `beacon endpoint fx sync`

Claude1023decff112
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e095e01f..014d22cb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -198,6 +198,8 @@ jobs:
./beacon endpoint hooks --help > /tmp/beacon-hooks-help.txt
./beacon endpoint onboarding --help > /tmp/beacon-onboarding-help.txt
./beacon endpoint integrations claude-cowork --help > /tmp/beacon-cowork-help.txt
+ ./beacon endpoint fx --help > /tmp/beacon-fx-help.txt
+ ./beacon endpoint fx sync --help > /tmp/beacon-fx-sync-help.txt
./beacon endpoint wazuh --help > /tmp/beacon-wazuh-help.txt
./beacon endpoint rapid7 --help > /tmp/beacon-rapid7-help.txt
./beacon scan --help > /tmp/beacon-scan-help.txt
diff --git a/cli/beacon/cmd/endpoint_fx.go b/cli/beacon/cmd/endpoint_fx.go
new file mode 100644
index 00000000..38b60bc7
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_fx.go
@@ -0,0 +1,268 @@
+package cmd
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/fxsession"
+ "github.com/spf13/cobra"
+)
+
+// `beacon endpoint fx` collects telemetry from fx (vercel-labs/fx).
+//
+// It is a command rather than an install step because fx has nothing to install into. Every other
+// supported runtime exposes a hook config, a plugin directory, or an OTLP endpoint, so Beacon
+// writes something once and the runtime calls it. fx has none of those: what it has is a durable
+// session log, so collecting from it means reading that log, which is an action rather than a
+// configuration.
+//
+// Everything it reads is already on this machine and nothing it does reaches the network.
+var endpointFxCmd = &cobra.Command{
+ Use: "fx",
+ Short: "Collect telemetry from fx (vercel-labs/fx) sessions",
+ Long: `Collect endpoint telemetry from fx, Vercel Labs' native coding agent.
+
+fx exposes no hook, plugin, or OpenTelemetry surface for third parties, so Beacon
+reads the session records fx commits under ~/.fx/sessions and converts them into
+endpoint events. Every event is marked harness.collection_method=poll: Beacon sees
+what a turn did once fx committed it, rather than observing the agent as it works,
+so nothing here can hold or deny a tool call.
+
+Reading is local and offline. Run 'sync' on a schedule, or with --watch, to keep the
+runtime log current.`,
+}
+
+var endpointFxSyncCmd = &cobra.Command{
+ Use: "sync",
+ Short: "Read new fx session records into the runtime log",
+ SilenceUsage: true,
+ RunE: runEndpointFxSync,
+}
+
+var endpointFxStatusCmd = &cobra.Command{
+ Use: "status",
+ Short: "Show fx sessions on this machine and how much of each has been collected",
+ SilenceUsage: true,
+ RunE: runEndpointFxStatus,
+}
+
+var endpointFxOpts struct {
+ sessionsDir string
+ statePath string
+ logPath string
+ print bool
+ watch bool
+ interval time.Duration
+}
+
+func init() {
+ endpointCmd.AddCommand(endpointFxCmd)
+ endpointFxCmd.AddCommand(endpointFxSyncCmd)
+ endpointFxCmd.AddCommand(endpointFxStatusCmd)
+
+ for _, c := range []*cobra.Command{endpointFxSyncCmd, endpointFxStatusCmd} {
+ f := c.Flags()
+ f.StringVar(&endpointFxOpts.sessionsDir, "sessions-dir", "", "fx session directory (default ~/.fx/sessions)")
+ f.StringVar(&endpointFxOpts.statePath, "state", "", "Collector cursor file (default ~/.beacon/endpoint/state/fx.json)")
+ f.BoolVar(&endpointOpts.jsonOutput, "json", false, "Print the result as JSON")
+ f.BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")
+ f.BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths")
+ }
+
+ sync := endpointFxSyncCmd.Flags()
+ sync.StringVar(&endpointFxOpts.logPath, "log-path", "", "Runtime JSONL log path (default resolved endpoint log)")
+ sync.BoolVar(&endpointFxOpts.print, "print", false, "Print mapped events as JSON without writing them or advancing the cursor (dry run)")
+ sync.BoolVar(&endpointFxOpts.watch, "watch", false, "Sweep continuously on --interval (default: one sweep then exit)")
+ sync.DurationVar(&endpointFxOpts.interval, "interval", time.Minute, "Sweep interval for --watch")
+}
+
+func runEndpointFxSync(cmd *cobra.Command, args []string) error {
+ userMode := endpointUserMode()
+ opts := fxsession.CollectOptions{
+ SessionsDir: endpointFxOpts.sessionsDir,
+ Print: endpointFxOpts.print,
+ Out: cmd.OutOrStdout(),
+ Write: !endpointFxOpts.print,
+ UserMode: userMode,
+ }
+ // --print is a dry run in both directions: it neither writes the runtime log nor advances the
+ // cursor, so running it twice shows the same events and running it does not quietly consume
+ // the work a later real sweep would do.
+ if !endpointFxOpts.print {
+ opts.StatePath = resolveFxStatePath(endpointFxOpts.statePath, userMode)
+ opts.LogPath = lifecycle.ResolveRuntimeLog(userMode, endpointFxOpts.logPath).EffectiveLogPath
+ }
+
+ ctx := cmd.Context()
+ if ctx == nil {
+ ctx = context.Background()
+ }
+ if endpointFxOpts.watch && !endpointFxOpts.print {
+ return watchFx(ctx, cmd, opts)
+ }
+
+ summary, err := fxsession.CollectOnce(opts)
+ // The summary is reported even when the sweep hit an error, because a sweep that collected
+ // nine sessions and failed on the tenth did nine sessions' worth of work.
+ reportFxSweep(cmd, summary)
+ return err
+}
+
+func watchFx(ctx context.Context, cmd *cobra.Command, opts fxsession.CollectOptions) error {
+ interval := endpointFxOpts.interval
+ if interval < 5*time.Second {
+ // A sweep re-reads each changed session's log, so a very short interval spends real work
+ // to shorten a window that fx's own commit latency already bounds.
+ interval = 5 * time.Second
+ }
+ for {
+ summary, err := fxsession.CollectOnce(opts)
+ if err != nil {
+ fmt.Fprintf(cmd.ErrOrStderr(), "fx sync error: %v\n", err)
+ }
+ reportFxSweep(cmd, summary)
+ select {
+ case <-ctx.Done():
+ return nil
+ case <-time.After(interval):
+ }
+ }
+}
+
+func reportFxSweep(cmd *cobra.Command, summary fxsession.Summary) {
+ if endpointFxOpts.print {
+ return
+ }
+ if endpointOpts.jsonOutput {
+ _ = json.NewEncoder(cmd.OutOrStdout()).Encode(summary)
+ return
+ }
+ fmt.Fprintf(cmd.OutOrStdout(), "fx sync: %d sessions, %d changed, %d events, %d errors\n",
+ summary.Sessions, summary.SessionsChanged, summary.EventsEmitted, summary.Errors)
+ // Said out loud rather than left in a counter: a damaged session log and an empty one produce
+ // the same event count, and only one of them is a reason to look at the machine.
+ if summary.MalformedLines > 0 {
+ fmt.Fprintf(cmd.OutOrStdout(), " %d unreadable line(s) in fx session logs\n", summary.MalformedLines)
+ }
+ if summary.PartialSessions > 0 {
+ fmt.Fprintf(cmd.OutOrStdout(), " %d session(s) had a partly written record; it will be read on the next sweep\n", summary.PartialSessions)
+ }
+}
+
+// fxSessionStatus is one session as `status` reports it: what fx has, and how much of it Beacon has
+// collected.
+type fxSessionStatus struct {
+ SessionID string `json:"session_id"`
+ Workspace string `json:"workspace,omitempty"`
+ UpdatedAt string `json:"updated_at,omitempty"`
+ Turns int `json:"turns,omitempty"`
+ LastEventSeq uint64 `json:"last_event_seq,omitempty"`
+ CollectedSeq uint64 `json:"collected_seq"`
+ Collected bool `json:"collected"`
+ SizeBytes int64 `json:"size_bytes"`
+ ManifestFound bool `json:"manifest_found"`
+}
+
+type fxStatusReport struct {
+ SessionsDir string `json:"sessions_dir"`
+ Present bool `json:"present"`
+ StatePath string `json:"state_path,omitempty"`
+ Sessions []fxSessionStatus `json:"sessions"`
+}
+
+func runEndpointFxStatus(cmd *cobra.Command, args []string) error {
+ store, err := fxsession.NewStore(endpointFxOpts.sessionsDir)
+ if err != nil {
+ return err
+ }
+ statePath := resolveFxStatePath(endpointFxOpts.statePath, endpointUserMode())
+ state, err := fxsession.LoadState(statePath)
+ if err != nil {
+ return err
+ }
+ refs, err := store.List()
+ if err != nil {
+ return err
+ }
+
+ report := fxStatusReport{
+ SessionsDir: store.Dir,
+ Present: store.Exists(),
+ StatePath: statePath,
+ Sessions: make([]fxSessionStatus, 0, len(refs)),
+ }
+ for _, ref := range refs {
+ status := fxSessionStatus{
+ SessionID: ref.ID,
+ SizeBytes: ref.SizeBytes,
+ ManifestFound: ref.Manifest != nil,
+ }
+ if ref.Manifest != nil {
+ status.Workspace = ref.Manifest.WorkspaceRoot
+ status.Turns = ref.Manifest.HistoryLen
+ status.LastEventSeq = ref.Manifest.LastEventSeq
+ if ref.Manifest.UpdatedAtMS > 0 {
+ status.UpdatedAt = time.UnixMilli(ref.Manifest.UpdatedAtMS).UTC().Format(time.RFC3339)
+ }
+ }
+ if cursor := state.Sessions[ref.ID]; cursor != nil {
+ status.CollectedSeq = cursor.LastSeq
+ // "Collected" means caught up with what fx says it has committed, which is the question
+ // someone running this command is actually asking. A session with no manifest cannot
+ // answer it, so it is reported as not caught up rather than assumed to be.
+ status.Collected = ref.Manifest != nil && cursor.Generation == ref.Manifest.LogGeneration &&
+ cursor.LastSeq >= ref.Manifest.LastEventSeq
+ }
+ report.Sessions = append(report.Sessions, status)
+ }
+
+ if endpointOpts.jsonOutput {
+ return json.NewEncoder(cmd.OutOrStdout()).Encode(report)
+ }
+ out := cmd.OutOrStdout()
+ if !report.Present {
+ fmt.Fprintf(out, "fx sessions: none (%s does not exist)\n", report.SessionsDir)
+ return nil
+ }
+ fmt.Fprintf(out, "fx sessions: %d in %s\n", len(report.Sessions), report.SessionsDir)
+ for _, session := range report.Sessions {
+ state := "pending"
+ if session.Collected {
+ state = "collected"
+ }
+ fmt.Fprintf(out, " %s %s seq %d/%d %s\n",
+ session.SessionID, state, session.CollectedSeq, session.LastEventSeq,
+ strings.TrimSpace(session.Workspace))
+ }
+ return nil
+}
+
+// resolveFxStatePath always returns a path so the cursor survives between runs. Without one, every
+// scheduled sweep would re-append every session's whole history.
+//
+// It prefers the endpoint state directory next to the runtime log, and falls back to the OS temp
+// directory when there is no home to put it in -- some cron and service environments have none, and
+// a sweep with no cursor is worse than a cursor in a volatile place.
+func resolveFxStatePath(override string, userMode bool) string {
+ if strings.TrimSpace(override) != "" {
+ return override
+ }
+ base := filepath.Join(os.TempDir(), "beacon")
+ if home, err := os.UserHomeDir(); err == nil && strings.TrimSpace(home) != "" {
+ base = filepath.Join(home, ".beacon")
+ }
+ if !userMode {
+ // A system-mode sweep collects on behalf of the machine, so its cursor belongs beside the
+ // system runtime log rather than in whichever home the operator happened to run from.
+ if dir := filepath.Dir(lifecycle.ResolveRuntimeLog(false, "").EffectiveLogPath); dir != "" && dir != "." {
+ return filepath.Join(dir, "fx-state.json")
+ }
+ }
+ return filepath.Join(base, "endpoint", "state", "fx.json")
+}
diff --git a/cli/beacon/cmd/endpoint_fx_test.go b/cli/beacon/cmd/endpoint_fx_test.go
new file mode 100644
index 00000000..0bf91860
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_fx_test.go
@@ -0,0 +1,274 @@
+package cmd
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/spf13/cobra"
+)
+
+// fxCommandFixture writes one fx session on disk and points the command's flags at it, with the
+// runtime log and cursor in temp directories so nothing touches the machine running the test.
+type fxCommandFixture struct {
+ sessionsDir string
+ statePath string
+ logPath string
+}
+
+func newFxCommandFixture(t *testing.T) fxCommandFixture {
+ t.Helper()
+ root := t.TempDir()
+ f := fxCommandFixture{
+ sessionsDir: filepath.Join(root, "fx-sessions"),
+ statePath: filepath.Join(root, "state", "fx.json"),
+ logPath: filepath.Join(root, "logs", "runtime.jsonl"),
+ }
+ f.writeSession(t)
+
+ // Command flags are package-level in this CLI, so each test sets the whole set it depends on
+ // rather than inheriting whatever the previous test left behind.
+ endpointFxOpts.sessionsDir = f.sessionsDir
+ endpointFxOpts.statePath = f.statePath
+ endpointFxOpts.logPath = f.logPath
+ endpointFxOpts.print = false
+ endpointFxOpts.watch = false
+ endpointOpts.jsonOutput = false
+ endpointOpts.userMode = true
+ endpointOpts.systemMode = false
+ t.Cleanup(func() {
+ endpointFxOpts.sessionsDir = ""
+ endpointFxOpts.statePath = ""
+ endpointFxOpts.logPath = ""
+ endpointFxOpts.print = false
+ endpointOpts.jsonOutput = false
+ })
+ return f
+}
+
+// The fixture is fx's wire format, transcribed from its own writers rather than produced by
+// Beacon's structs. See the package-level note in internal/fxsession/fixtures_test.go.
+func (f fxCommandFixture) writeSession(t *testing.T) {
+ t.Helper()
+ const generation = "1f4b2c8e6d3a5a7c9b613f0d5e8c2a14"
+ const sessionID = "1770000000000-1770000000000000000-a1b2c3d4e5f60718"
+ started := fmt.Sprintf(
+ `{"schema_version":1,"log_generation":%q,"seq":1,"event_id":"a1","timestamp_ms":1770000000000,"kind":"session_started",`+
+ `"payload":{"id":%q,"created_at_ms":1770000000000,"origin_workspace_root":"/repo","workspace_root":"/repo",`+
+ `"conversation_language":"en","preferences":{"provider":"gateway","model":"anthropic/claude-opus-4","effort":"medium","fast_mode":false},"usage":null}}`,
+ generation, sessionID)
+ turn := fmt.Sprintf(
+ `{"schema_version":1,"log_generation":%q,"seq":2,"event_id":"a2","timestamp_ms":1770000004000,"kind":"history_turn_committed",`+
+ `"payload":{"conversation_language":"en","total_input_tokens":100,"total_output_tokens":20,"turn":{"kind":"assistant",`+
+ `"user":{"text":"run the tests","images":[]},"assistant":"Done.","execution":{"schema_version":5,"tool_steps":[`+
+ `{"assistant":null,"tool_calls":[{"id":"call_1","name":"run_command","arguments_json":"{\"command\":\"npm test\"}","provider_result":null}],`+
+ `"tool_results":[{"tool_call_id":"call_1","tool_name":"run_command","status":"success","output":"ok","output_handle":null,"preview":null,`+
+ `"output_bytes":2,"stored_output_bytes":2,"truncated":false,"provider_native":false,"created_at_ms":1770000003000,"permission_feedback":[],`+
+ `"committed_file_presentation":null,"command_output_replay":null,"command_process_presentation":{"kind":"exit_code","value":0},`+
+ `"terminal_action_presentation":null}]}],"files":[],"turn_summary":{"started_at_ms":1770000000500,"completed_at_ms":1770000004000,`+
+ `"thinking_duration_ms":100,"turn_duration_ms":3500,"token_progress":{"input_tokens":100,"output_tokens":20,"input_exact":true,"output_exact":true}}}}}}`,
+ generation)
+ body := started + "\n" + turn + "\n"
+
+ dir := filepath.Join(f.sessionsDir, sessionID)
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(dir, "events.jsonl"), []byte(body), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ manifest := fmt.Sprintf(
+ `{"schema_version":3,"storage_format":"event_log_v1","id":%q,"authority_id":"ab","log_generation":%q,`+
+ `"created_at_ms":1770000000000,"updated_at_ms":1770000004000,"origin_workspace_root":"/repo","workspace_root":"/repo",`+
+ `"conversation_language":"en","history_len":1,"total_input_tokens":100,"total_output_tokens":20,`+
+ `"last_event_seq":2,"event_log_bytes":%d,"event_log_stat_fingerprint":"cd",`+
+ `"generation_base_seq":0,"generation_base_bytes":0,"checkpoint_seq":null,"checkpoint_sha256":null,`+
+ `"preferences":{"provider":"gateway","model":"anthropic/claude-opus-4","effort":"medium","fast_mode":false}}`,
+ sessionID, generation, len(body))
+ if err := os.WriteFile(filepath.Join(dir, "session.json"), []byte(manifest), 0o600); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func runFxCommand(t *testing.T, cmd *cobra.Command, run func(*cobra.Command, []string) error) string {
+ t.Helper()
+ var out bytes.Buffer
+ cmd.SetOut(&out)
+ cmd.SetErr(&out)
+ t.Cleanup(func() {
+ cmd.SetOut(nil)
+ cmd.SetErr(nil)
+ })
+ if err := run(cmd, nil); err != nil {
+ t.Fatalf("command failed: %v", err)
+ }
+ return out.String()
+}
+
+func TestEndpointFxSyncWritesTheRuntimeLogAndReportsWhatItDid(t *testing.T) {
+ f := newFxCommandFixture(t)
+
+ output := runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ if !strings.Contains(output, "fx sync:") {
+ t.Fatalf("sweep reported nothing readable: %q", output)
+ }
+
+ data, err := os.ReadFile(f.logPath)
+ if err != nil {
+ t.Fatalf("read runtime log: %v", err)
+ }
+ if !strings.Contains(string(data), `"vercel_fx"`) {
+ t.Fatalf("runtime log has no fx events:\n%s", data)
+ }
+ if !strings.Contains(string(data), `"command.executed"`) {
+ t.Errorf("the session's command was not collected:\n%s", data)
+ }
+}
+
+// The command is what a schedule runs, so its second run over an unchanged machine has to be a
+// no-op. If it is not, a cron entry doubles the log every time it fires.
+func TestEndpointFxSyncIsIdempotentAcrossRuns(t *testing.T) {
+ f := newFxCommandFixture(t)
+
+ runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ first, err := os.ReadFile(f.logPath)
+ if err != nil {
+ t.Fatalf("read runtime log: %v", err)
+ }
+ runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ second, err := os.ReadFile(f.logPath)
+ if err != nil {
+ t.Fatalf("read runtime log: %v", err)
+ }
+ if !bytes.Equal(first, second) {
+ t.Fatalf("a second sweep changed the runtime log:\nfirst:\n%s\nsecond:\n%s", first, second)
+ }
+}
+
+// --print is the flag someone reaches for to see what Beacon would collect before letting it write
+// anything. It has to leave no trace at all -- neither log lines nor a cursor that would make a
+// later real sweep skip the events it just previewed.
+func TestEndpointFxSyncPrintLeavesNoTrace(t *testing.T) {
+ f := newFxCommandFixture(t)
+ endpointFxOpts.print = true
+
+ output := runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ if !strings.Contains(output, `"vercel_fx"`) {
+ t.Fatalf("--print showed no events:\n%s", output)
+ }
+ for _, line := range strings.Split(strings.TrimSpace(output), "\n") {
+ var event map[string]interface{}
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("--print emitted a non-JSON line %q: %v", line, err)
+ }
+ }
+ if _, err := os.Stat(f.logPath); !os.IsNotExist(err) {
+ t.Error("--print wrote the runtime log")
+ }
+ if _, err := os.Stat(f.statePath); !os.IsNotExist(err) {
+ t.Error("--print wrote a cursor file")
+ }
+
+ // And the real sweep afterwards still collects everything the preview showed.
+ endpointFxOpts.print = false
+ runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ data, err := os.ReadFile(f.logPath)
+ if err != nil {
+ t.Fatalf("read runtime log: %v", err)
+ }
+ if !strings.Contains(string(data), `"command.executed"`) {
+ t.Error("the preview consumed events the real sweep should have collected")
+ }
+}
+
+func TestEndpointFxStatusReportsCollectionProgress(t *testing.T) {
+ newFxCommandFixture(t)
+
+ before := runFxCommand(t, endpointFxStatusCmd, runEndpointFxStatus)
+ if !strings.Contains(before, "pending") {
+ t.Fatalf("status before a sweep does not report pending work:\n%s", before)
+ }
+
+ runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+
+ after := runFxCommand(t, endpointFxStatusCmd, runEndpointFxStatus)
+ if !strings.Contains(after, "collected") {
+ t.Fatalf("status after a sweep does not report the session as collected:\n%s", after)
+ }
+}
+
+func TestEndpointFxStatusJSONDescribesEachSession(t *testing.T) {
+ newFxCommandFixture(t)
+ runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ endpointOpts.jsonOutput = true
+
+ output := runFxCommand(t, endpointFxStatusCmd, runEndpointFxStatus)
+ var report fxStatusReport
+ if err := json.Unmarshal([]byte(output), &report); err != nil {
+ t.Fatalf("status --json is not JSON: %v\n%s", err, output)
+ }
+ if !report.Present || len(report.Sessions) != 1 {
+ t.Fatalf("report = %+v", report)
+ }
+ session := report.Sessions[0]
+ if !session.Collected || session.CollectedSeq != 2 || session.LastEventSeq != 2 {
+ t.Errorf("session status = %+v, want a collected session at sequence 2", session)
+ }
+ if session.Workspace != "/repo" || session.Turns != 1 {
+ t.Errorf("session metadata = %+v", session)
+ }
+}
+
+// A machine without fx is the common case. Status has to say so plainly rather than fail, because
+// this command runs inside `beacon endpoint status` territory where an error reads as a broken
+// install.
+func TestEndpointFxStatusOnAMachineWithoutFxSaysSoWithoutFailing(t *testing.T) {
+ newFxCommandFixture(t)
+ endpointFxOpts.sessionsDir = filepath.Join(t.TempDir(), "no-fx-here")
+
+ output := runFxCommand(t, endpointFxStatusCmd, runEndpointFxStatus)
+ if !strings.Contains(output, "none") {
+ t.Fatalf("status on a machine without fx: %q", output)
+ }
+}
+
+func TestEndpointFxSyncOnAMachineWithoutFxIsAQuietNoOp(t *testing.T) {
+ f := newFxCommandFixture(t)
+ endpointFxOpts.sessionsDir = filepath.Join(t.TempDir(), "no-fx-here")
+
+ output := runFxCommand(t, endpointFxSyncCmd, runEndpointFxSync)
+ if !strings.Contains(output, "0 sessions") {
+ t.Fatalf("sweep output = %q", output)
+ }
+ if _, err := os.Stat(f.logPath); !os.IsNotExist(err) {
+ t.Error("a sweep with nothing to collect created a runtime log")
+ }
+}
+
+// The cursor has to land somewhere durable even when the process has no home directory, which is
+// the case in some cron and service environments. A sweep with no cursor re-appends every session's
+// whole history on every run.
+func TestFxStatePathAlwaysResolvesSomewhereDurable(t *testing.T) {
+ if got := resolveFxStatePath("/explicit/path.json", true); got != "/explicit/path.json" {
+ t.Errorf("an explicit --state was overridden: %q", got)
+ }
+
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ got := resolveFxStatePath("", true)
+ if want := filepath.Join(home, ".beacon", "endpoint", "state", "fx.json"); got != want {
+ t.Errorf("resolveFxStatePath = %q, want %q", got, want)
+ }
+
+ t.Setenv("HOME", "")
+ t.Setenv("USERPROFILE", "")
+ fallback := resolveFxStatePath("", true)
+ if fallback == "" || !filepath.IsAbs(fallback) {
+ t.Errorf("with no home the cursor path is %q, which is not somewhere it can be written", fallback)
+ }
+}
diff --git a/cli/beacon/internal/fxsession/collect.go b/cli/beacon/internal/fxsession/collect.go
new file mode 100644
index 00000000..ea9396b8
--- /dev/null
+++ b/cli/beacon/internal/fxsession/collect.go
@@ -0,0 +1,302 @@
+package fxsession
+
+import (
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "path/filepath"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
+)
+
+// StateVersion is the on-disk version of the collector's cursor file. It exists so a future change
+// to what a cursor holds can reset the file rather than misread it: re-collecting a session is
+// cheap and duplicates are suppressed downstream, while misreading a cursor loses events silently.
+const StateVersion = 1
+
+// Cursor is what the collector remembers about one fx session between sweeps.
+//
+// Generation is fx's log generation and LastSeq is the last sequence collected within it. Both are
+// needed because fx restarts the sequence at 1 whenever it compacts a session's log -- a cursor
+// holding only a sequence would silently skip the first events of every compacted session.
+type Cursor struct {
+ Generation string `json:"generation"`
+ LastSeq uint64 `json:"last_seq"`
+ // Started records that a session.started has already been reported. fx writes a fresh
+ // session_started at sequence 1 of every generation, including the one compaction creates,
+ // and a session that never restarted must not be reported as starting twice.
+ Started bool `json:"started"`
+ // UpdatedAtMS is the manifest's updated_at at the last full sweep, kept only as a cheap
+ // "nothing changed" check. It is never the thing that decides what to emit.
+ UpdatedAtMS int64 `json:"updated_at_ms,omitempty"`
+}
+
+// State is the collector's cursor file: one cursor per fx session.
+type State struct {
+ Version int `json:"version"`
+ Sessions map[string]*Cursor `json:"sessions"`
+}
+
+// LoadState reads the cursor file. A missing file is an empty state, which is what a first run
+// looks like. An empty path yields state that is never persisted, which is what --print uses.
+//
+// A file from another state version is discarded rather than parsed: re-collecting a session
+// appends events that the writer's own duplicate window and the deterministic event ids already
+// make harmless, while reading a cursor under the wrong meaning skips events for good.
+func LoadState(path string) (*State, error) {
+ state := &State{Version: StateVersion, Sessions: map[string]*Cursor{}}
+ if path == "" {
+ return state, nil
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return state, nil
+ }
+ return nil, err
+ }
+ var stored State
+ if err := json.Unmarshal(data, &stored); err != nil {
+ return nil, fmt.Errorf("read fx collector state %s: %w", path, err)
+ }
+ if stored.Version != StateVersion || stored.Sessions == nil {
+ return state, nil
+ }
+ state.Sessions = stored.Sessions
+ return state, nil
+}
+
+// Save writes the cursor file atomically. An empty path is a no-op.
+func (s *State) Save(path string) error {
+ if path == "" {
+ return nil
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ return err
+ }
+ s.Version = StateVersion
+ data, err := json.MarshalIndent(s, "", " ")
+ if err != nil {
+ return err
+ }
+ tmp := path + ".tmp"
+ if err := os.WriteFile(tmp, data, 0o600); err != nil {
+ return err
+ }
+ return os.Rename(tmp, path)
+}
+
+func (s *State) cursor(sessionID string) *Cursor {
+ if s.Sessions == nil {
+ s.Sessions = map[string]*Cursor{}
+ }
+ c := s.Sessions[sessionID]
+ if c == nil {
+ c = &Cursor{}
+ s.Sessions[sessionID] = c
+ }
+ return c
+}
+
+// CollectOptions configures one sweep over fx's session store.
+type CollectOptions struct {
+ // SessionsDir is fx's session directory. Empty means fx's default location.
+ SessionsDir string
+ // StatePath is the cursor file. Empty disables persistence, which makes the sweep a dry run
+ // that re-reads everything next time.
+ StatePath string
+ // Write appends mapped events to the runtime JSONL at LogPath.
+ Write bool
+ // LogPath is the runtime JSONL. Empty means the writer's default for UserMode.
+ LogPath string
+ UserMode bool
+ // Print writes each mapped event to Out as JSON. Used by --print, which pairs with an empty
+ // StatePath so a dry run shows the same events every time.
+ Print bool
+ Out io.Writer
+}
+
+// Summary reports what a sweep did. Malformed and PartialSessions are reported rather than logged
+// because "Beacon collected nothing" and "Beacon could not read this" look identical from outside.
+type Summary struct {
+ Sessions int
+ SessionsChanged int
+ EventsEmitted int
+ Errors int
+ MalformedLines int
+ PartialSessions int
+}
+
+// CollectOnce performs one sweep: list fx's sessions, read the ones that moved since the last
+// sweep, map their new records, and emit them.
+//
+// Idempotent by construction. The cursor advances only over records that were actually emitted, so
+// a sweep that fails partway leaves the rest to be retried; and because the cursor is a position in
+// fx's own log rather than a set of ids, its size does not grow with the session.
+//
+// One session's failure does not end the sweep. A session directory can be unreadable for ordinary
+// reasons -- another user owns it, fx is mid-write, a disk error -- and none of them is a reason to
+// collect nothing from the other sessions on the machine.
+func CollectOnce(opts CollectOptions) (summary Summary, err error) {
+ store, err := NewStore(opts.SessionsDir)
+ if err != nil {
+ return summary, err
+ }
+ refs, err := store.List()
+ if err != nil {
+ return summary, err
+ }
+ summary.Sessions = len(refs)
+ if len(refs) == 0 {
+ return summary, nil
+ }
+
+ state, err := LoadState(opts.StatePath)
+ if err != nil {
+ return summary, err
+ }
+ // Progress is saved however this returns. Events are appended as each session is processed, so
+ // a later session's failure must not throw away the cursor advances already earned -- otherwise
+ // the next sweep re-emits everything the failed sweep already wrote. err is a named return so a
+ // failure to persist the cursor is reported rather than swallowed: an unsaved sweep re-emits
+ // everything it just wrote.
+ defer func() {
+ if saveErr := state.Save(opts.StatePath); saveErr != nil && err == nil {
+ err = fmt.Errorf("save fx collector state: %w", saveErr)
+ }
+ }()
+
+ var errs []error
+ for _, ref := range refs {
+ changed, collectErr := collectSession(store, ref, state, opts, &summary)
+ if collectErr != nil {
+ summary.Errors++
+ errs = append(errs, fmt.Errorf("fx session %s: %w", ref.ID, collectErr))
+ continue
+ }
+ if changed {
+ summary.SessionsChanged++
+ }
+ }
+ if len(errs) > 0 {
+ return summary, errors.Join(errs...)
+ }
+ return summary, nil
+}
+
+func collectSession(store *Store, ref SessionRef, state *State, opts CollectOptions, summary *Summary) (bool, error) {
+ cursor := state.cursor(ref.ID)
+
+ // The manifest is fx's own summary of what it has committed, so when it says the session has
+ // not moved past the cursor there is nothing to read. Skipping on it keeps a sweep over a
+ // machine with hundreds of old sessions proportional to what changed rather than to what
+ // exists. A session with no readable manifest is always read: there is nothing cheaper to
+ // trust, and reading it is correct, just not free.
+ if ref.Manifest != nil && ref.Manifest.LogGeneration == cursor.Generation &&
+ ref.Manifest.LastEventSeq <= cursor.LastSeq {
+ return false, nil
+ }
+
+ events, stats, err := store.Read(ref)
+ summary.MalformedLines += stats.Malformed
+ if stats.PartialTail {
+ summary.PartialSessions++
+ }
+ if err != nil {
+ return false, err
+ }
+ if len(events) == 0 {
+ return false, nil
+ }
+
+ minSeq := cursor.LastSeq
+ if cursor.Generation != "" && cursor.Generation != generationOf(events) {
+ // fx compacted this session's log: the sequence restarted, and the turns that were in the
+ // old log are not in the new one -- compaction rewrites it as a session_started plus an
+ // opaque state blob. So everything in the new generation is new, and starting from zero
+ // re-reads nothing that was already collected.
+ //
+ // The honest limitation of reading a log rather than being handed events: a turn committed
+ // after the last sweep and before a compaction is folded into that blob and is gone. fx
+ // compacts on log growth, so this needs a long gap between sweeps and a lot of activity in
+ // it; sweeping on a schedule (the watch mode of `beacon endpoint fx sync`) is what keeps
+ // the window small.
+ minSeq = 0
+ }
+
+ mapped := MapSession(ref, events, MapOptions{MinSeq: minSeq, SkipSessionStarted: cursor.Started})
+ if len(mapped) == 0 {
+ advanceCursor(cursor, ref, events)
+ return false, nil
+ }
+
+ for _, item := range mapped {
+ if err := emit(item.Event, opts); err != nil {
+ // The cursor is deliberately not advanced here. The events already written stay
+ // written, and the next sweep re-reads from the last confirmed position -- which the
+ // writer's duplicate window and the deterministic event ids make safe.
+ return true, err
+ }
+ summary.EventsEmitted++
+ if item.Event.Event.Action == "session.started" {
+ cursor.Started = true
+ }
+ }
+ advanceCursor(cursor, ref, events)
+ return true, nil
+}
+
+// advanceCursor moves the cursor to the last record this sweep read.
+//
+// It uses the events actually decoded rather than the manifest's numbers, so a manifest that runs
+// ahead of the log -- a copied session directory, an interrupted sync -- cannot advance the cursor
+// past records that were never read.
+func advanceCursor(cursor *Cursor, ref SessionRef, events []Event) {
+ if len(events) == 0 {
+ return
+ }
+ last := events[len(events)-1]
+ cursor.Generation = last.LogGeneration
+ cursor.LastSeq = last.Seq
+ if ref.Manifest != nil {
+ cursor.UpdatedAtMS = ref.Manifest.UpdatedAtMS
+ } else {
+ cursor.UpdatedAtMS = ref.ModTimeUnixMS
+ }
+ // A session whose start was collected before this cursor existed still counts as started: the
+ // records are in the log, and re-reporting the start on the next generation would double it.
+ for i := range events {
+ if events[i].Kind == KindSessionStarted && events[i].Seq <= cursor.LastSeq {
+ cursor.Started = true
+ break
+ }
+ }
+}
+
+func generationOf(events []Event) string {
+ if len(events) == 0 {
+ return ""
+ }
+ return events[len(events)-1].LogGeneration
+}
+
+func emit(event schema.Event, opts CollectOptions) error {
+ if opts.Print && opts.Out != nil {
+ data, err := json.Marshal(event)
+ if err != nil {
+ return err
+ }
+ if _, err := opts.Out.Write(append(data, '\n')); err != nil {
+ return err
+ }
+ }
+ if opts.Write {
+ if _, err := writer.AppendEvent(event, writer.Options{Path: opts.LogPath, UserMode: opts.UserMode}); err != nil {
+ return err
+ }
+ }
+ return nil
+}
diff --git a/cli/beacon/internal/fxsession/collect_test.go b/cli/beacon/internal/fxsession/collect_test.go
new file mode 100644
index 00000000..8e7eee95
--- /dev/null
+++ b/cli/beacon/internal/fxsession/collect_test.go
@@ -0,0 +1,436 @@
+package fxsession
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+type sweepFixture struct {
+ root string
+ statePath string
+ logPath string
+}
+
+func newSweepFixture(t *testing.T) sweepFixture {
+ t.Helper()
+ dir := t.TempDir()
+ return sweepFixture{
+ root: filepath.Join(dir, "sessions"),
+ statePath: filepath.Join(dir, "state", "fx.json"),
+ logPath: filepath.Join(dir, "logs", "runtime.jsonl"),
+ }
+}
+
+func (f sweepFixture) options() CollectOptions {
+ return CollectOptions{
+ SessionsDir: f.root,
+ StatePath: f.statePath,
+ Write: true,
+ LogPath: f.logPath,
+ UserMode: true,
+ }
+}
+
+// writeSessionLog lays out a session whose manifest matches exactly what was written, which is what
+// fx leaves behind once a turn is committed.
+func (f sweepFixture) writeSessionLog(t *testing.T, id string, lines []string) {
+ t.Helper()
+ manifest := manifestJSON(testGeneration, logBytes(lines), len(lines), "/repo")
+ writeSession(t, f.root, id, lines, manifest)
+}
+
+func (f sweepFixture) logLines(t *testing.T) []schema.Event {
+ t.Helper()
+ data, err := os.ReadFile(f.logPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ t.Fatalf("read runtime log: %v", err)
+ }
+ var events []schema.Event
+ for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+ if line == "" {
+ continue
+ }
+ var event schema.Event
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("decode runtime log line: %v", err)
+ }
+ events = append(events, event)
+ }
+ return events
+}
+
+func TestSweepWritesFxActivityIntoTheRuntimeLog(t *testing.T) {
+ f := newSweepFixture(t)
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+
+ summary, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary.Sessions != 1 || summary.SessionsChanged != 1 {
+ t.Errorf("summary = %+v, want one session, one changed", summary)
+ }
+ if summary.EventsEmitted == 0 {
+ t.Fatal("no events emitted")
+ }
+
+ events := f.logLines(t)
+ if len(events) != summary.EventsEmitted {
+ t.Fatalf("wrote %d lines for %d emitted events", len(events), summary.EventsEmitted)
+ }
+ for _, event := range events {
+ if event.Harness.Name != Harness {
+ t.Errorf("harness = %q", event.Harness.Name)
+ }
+ // The writer stamps a deterministic id on every line. Without one, the same fx record read
+ // twice cannot be recognized as the same event downstream.
+ if event.Event.ID == "" {
+ t.Errorf("%s has no event id", event.Event.Action)
+ }
+ }
+}
+
+// The property the cursor exists for. A machine sweeping every minute must not append a session's
+// history again every minute.
+func TestSecondSweepOverUnchangedSessionsWritesNothing(t *testing.T) {
+ f := newSweepFixture(t)
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+
+ first, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("first sweep: %v", err)
+ }
+ before := len(f.logLines(t))
+
+ second, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("second sweep: %v", err)
+ }
+ if second.EventsEmitted != 0 {
+ t.Errorf("second sweep emitted %d events, want 0", second.EventsEmitted)
+ }
+ if second.SessionsChanged != 0 {
+ t.Errorf("second sweep reported %d changed sessions, want 0", second.SessionsChanged)
+ }
+ if after := len(f.logLines(t)); after != before {
+ t.Errorf("runtime log grew from %d to %d lines on a sweep with nothing new", before, after)
+ }
+ if first.EventsEmitted == 0 {
+ t.Fatal("first sweep emitted nothing, so this proves nothing")
+ }
+}
+
+// A session that gained a turn between sweeps must contribute only that turn.
+func TestSweepEmitsOnlyWhatIsNewSinceTheCursor(t *testing.T) {
+ f := newSweepFixture(t)
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+ if _, err := CollectOnce(f.options()); err != nil {
+ t.Fatalf("first sweep: %v", err)
+ }
+ firstCount := len(f.logLines(t))
+
+ f.writeSessionLog(t, testSessionID, []string{
+ sessionStartedLine(1, "/repo"),
+ assistantTurnLine(2),
+ usageCheckpointLine(3, 4200, 880, 0.75),
+ })
+ second, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("second sweep: %v", err)
+ }
+ if second.EventsEmitted != 1 {
+ t.Fatalf("second sweep emitted %d events, want just the new checkpoint", second.EventsEmitted)
+ }
+ events := f.logLines(t)
+ if len(events) != firstCount+1 {
+ t.Fatalf("log has %d lines, want %d", len(events), firstCount+1)
+ }
+ last := events[len(events)-1]
+ if last.Event.Action != "token.usage" {
+ t.Errorf("new line action = %q, want token.usage", last.Event.Action)
+ }
+ // The delta is measured against the snapshot the earlier sweep already saw, which the mapper
+ // re-derives by reading the log from the start rather than by storing it in the cursor.
+ if last.GenAI == nil || last.GenAI.Usage == nil || last.GenAI.Usage.CostUSD == nil {
+ t.Fatalf("usage event carries no cost: %+v", last.GenAI)
+ }
+}
+
+// fx compacts a session's log by rewriting it under a new generation with the sequence restarted at
+// 1. A cursor holding only a sequence would skip everything up to the old high-water mark; a cursor
+// that forgot the session had started would report it as starting twice.
+func TestCompactedLogIsNeitherSkippedNorRestarted(t *testing.T) {
+ f := newSweepFixture(t)
+ f.writeSessionLog(t, testSessionID, []string{
+ sessionStartedLine(1, "/repo"),
+ assistantTurnLine(2),
+ usageCheckpointLine(3, 100, 20, 0.05),
+ })
+ if _, err := CollectOnce(f.options()); err != nil {
+ t.Fatalf("first sweep: %v", err)
+ }
+ beforeCompaction := len(f.logLines(t))
+
+ // What fx leaves after compacting: a new generation, a fresh session_started at sequence 1, and
+ // the turns that follow it. The compacted history itself is gone from the log.
+ const newGeneration = "aaaaaaaabbbbbbbbccccccccdddddddd"
+ rewrite := func(line string) string {
+ return strings.Replace(line, testGeneration, newGeneration, 1)
+ }
+ lines := []string{
+ rewrite(sessionStartedLine(1, "/repo")),
+ rewrite(assistantTurnLine(2)),
+ }
+ manifest := manifestJSON(newGeneration, logBytes(lines), 2, "/repo")
+ writeSession(t, f.root, testSessionID, lines, manifest)
+
+ second, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("second sweep: %v", err)
+ }
+ if second.EventsEmitted == 0 {
+ t.Fatal("nothing collected after compaction: the sequence restart hid the new generation")
+ }
+ events := f.logLines(t)
+ starts := 0
+ for _, event := range events {
+ if event.Event.Action == "session.started" {
+ starts++
+ }
+ }
+ if starts != 1 {
+ t.Errorf("session.started appears %d times, want 1 -- compaction is not a new session", starts)
+ }
+ if len(events) <= beforeCompaction {
+ t.Errorf("log did not grow after compaction: %d lines then %d", beforeCompaction, len(events))
+ }
+}
+
+// The cursor is a position in fx's log, so its size must not grow with the session's history. A
+// dedup-id set would grow without bound on a machine that runs fx daily.
+func TestCursorStaysOneRecordPerSession(t *testing.T) {
+ f := newSweepFixture(t)
+ lines := []string{sessionStartedLine(1, "/repo")}
+ for seq := 2; seq <= 12; seq++ {
+ lines = append(lines, assistantTurnLine(seq))
+ }
+ f.writeSessionLog(t, testSessionID, lines)
+ if _, err := CollectOnce(f.options()); err != nil {
+ t.Fatalf("sweep: %v", err)
+ }
+
+ state, err := LoadState(f.statePath)
+ if err != nil {
+ t.Fatalf("LoadState: %v", err)
+ }
+ if len(state.Sessions) != 1 {
+ t.Fatalf("state holds %d sessions, want 1", len(state.Sessions))
+ }
+ cursor := state.Sessions[testSessionID]
+ if cursor == nil {
+ t.Fatal("no cursor for the swept session")
+ }
+ if cursor.LastSeq != 12 {
+ t.Errorf("cursor.LastSeq = %d, want 12", cursor.LastSeq)
+ }
+ if cursor.Generation != testGeneration {
+ t.Errorf("cursor.Generation = %q", cursor.Generation)
+ }
+ if !cursor.Started {
+ t.Error("cursor does not record that the session was already reported as started")
+ }
+ data, err := os.ReadFile(f.statePath)
+ if err != nil {
+ t.Fatalf("read state: %v", err)
+ }
+ // A cursor file that grew with the number of turns would be the tell that ids are being stored.
+ if len(data) > 2048 {
+ t.Errorf("cursor file is %d bytes for one session; it should be a position, not a set", len(data))
+ }
+}
+
+// One unreadable session must not cost the sweep the sessions around it -- and the sweep must still
+// say something went wrong rather than reporting a clean run.
+func TestOneUnreadableSessionDoesNotStopTheSweep(t *testing.T) {
+ f := newSweepFixture(t)
+ good := "1770000000009-9-999999"
+ f.writeSessionLog(t, good, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+
+ // A session whose log is a directory: readable listing, unreadable log.
+ broken := "1770000000001-1-111111"
+ brokenDir := filepath.Join(f.root, broken)
+ if err := os.MkdirAll(filepath.Join(brokenDir, EventsFileName, "nested"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+
+ summary, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ // The broken session is skipped at listing time (its log is not a file), so the sweep is clean
+ // and the good session is collected. What must not happen is the good session being lost.
+ if summary.EventsEmitted == 0 {
+ t.Fatal("the readable session was not collected")
+ }
+ events := f.logLines(t)
+ for _, event := range events {
+ if event.Session == nil || event.Session.ID != good {
+ t.Fatalf("unexpected session in the log: %+v", event.Session)
+ }
+ }
+}
+
+// A corrupt line inside an otherwise good session is counted and reported, and the records around
+// it are still collected. A sweep that reported a clean run over a damaged log would be worse than
+// one that collected nothing.
+func TestCorruptLineIsReportedAndTheRestIsStillCollected(t *testing.T) {
+ f := newSweepFixture(t)
+ lines := []string{
+ sessionStartedLine(1, "/repo"),
+ `{"schema_version":1,"log_generation":"x","seq":2,"kind":"history_turn_committed","payload":{`,
+ usageCheckpointLine(3, 10, 5, 0.02),
+ }
+ // No manifest: the byte watermark would not match a hand-corrupted log.
+ writeSession(t, f.root, testSessionID, lines, "")
+
+ summary, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary.MalformedLines != 1 {
+ t.Errorf("summary.MalformedLines = %d, want 1", summary.MalformedLines)
+ }
+ if summary.EventsEmitted == 0 {
+ t.Error("the readable records around the corrupt line were dropped")
+ }
+}
+
+// --print is a dry run: it shows what would be collected without writing the runtime log and
+// without advancing any cursor, so running it twice shows the same thing both times.
+func TestPrintModeWritesNothingAndKeepsNoCursor(t *testing.T) {
+ f := newSweepFixture(t)
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+
+ var first, second bytes.Buffer
+ opts := CollectOptions{SessionsDir: f.root, Print: true, Out: &first}
+ if _, err := CollectOnce(opts); err != nil {
+ t.Fatalf("first print sweep: %v", err)
+ }
+ opts.Out = &second
+ if _, err := CollectOnce(opts); err != nil {
+ t.Fatalf("second print sweep: %v", err)
+ }
+
+ if first.Len() == 0 {
+ t.Fatal("print mode produced no output")
+ }
+ if first.String() != second.String() {
+ t.Error("two dry runs disagreed, so one of them consumed state")
+ }
+ if _, err := os.Stat(f.logPath); !os.IsNotExist(err) {
+ t.Error("print mode wrote the runtime log")
+ }
+ if _, err := os.Stat(f.statePath); !os.IsNotExist(err) {
+ t.Error("print mode wrote a cursor file")
+ }
+ for _, line := range strings.Split(strings.TrimSpace(first.String()), "\n") {
+ var event schema.Event
+ if err := json.Unmarshal([]byte(line), &event); err != nil {
+ t.Fatalf("print output is not one JSON event per line: %v", err)
+ }
+ }
+}
+
+// A machine that has never run fx is the common case for most installs. It must produce a clean,
+// empty result rather than an error a status command has to explain away.
+func TestSweepOverAMissingSessionsDirectoryIsCleanAndEmpty(t *testing.T) {
+ f := newSweepFixture(t)
+ summary, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary != (Summary{}) {
+ t.Errorf("summary = %+v, want a zero summary", summary)
+ }
+ if _, err := os.Stat(f.logPath); !os.IsNotExist(err) {
+ t.Error("a sweep with nothing to collect created a runtime log")
+ }
+}
+
+// A cursor file written by a future version of the collector is discarded rather than
+// misinterpreted: re-collecting is harmless, and reading a cursor under the wrong meaning would
+// skip events permanently.
+func TestCursorFileFromAnotherVersionIsDiscardedNotMisread(t *testing.T) {
+ f := newSweepFixture(t)
+ if err := os.MkdirAll(filepath.Dir(f.statePath), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ stale := `{"version":99,"sessions":{"` + testSessionID + `":{"generation":"` + testGeneration + `","last_seq":9999,"started":true}}}`
+ if err := os.WriteFile(f.statePath, []byte(stale), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)})
+
+ summary, err := CollectOnce(f.options())
+ if err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ if summary.EventsEmitted == 0 {
+ t.Fatal("the sweep trusted a cursor from another version and collected nothing")
+ }
+}
+
+// The manifest is what makes a sweep over a machine with hundreds of old sessions cheap. It must
+// not be what decides correctness: a manifest that runs ahead of the log cannot be allowed to
+// advance the cursor past records nobody read.
+func TestCursorFollowsRecordsReadNotTheManifestsClaim(t *testing.T) {
+ f := newSweepFixture(t)
+ lines := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}
+ // A manifest claiming sequence 900 over a log that holds two records.
+ manifest := manifestJSON(testGeneration, logBytes(lines), 900, "/repo")
+ writeSession(t, f.root, testSessionID, lines, manifest)
+
+ if _, err := CollectOnce(f.options()); err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ state, err := LoadState(f.statePath)
+ if err != nil {
+ t.Fatalf("LoadState: %v", err)
+ }
+ if got := state.Sessions[testSessionID].LastSeq; got != 2 {
+ t.Fatalf("cursor.LastSeq = %d, want 2 -- the manifest's claim was trusted over the log", got)
+ }
+}
+
+// Every event that reaches the runtime log has been through the writer's sanitizer, which redacts
+// what looks like a credential. An fx session that printed a token must not put it in the log.
+func TestSecretsInFxOutputAreRedactedByTheWriter(t *testing.T) {
+ f := newSweepFixture(t)
+ line := strings.Replace(assistantTurnLine(2),
+ `"status":"failure","output":"1 test failed"`,
+ `"status":"failure","output":"api_key=sk-abcdefghijklmnopqrstuvwxyz012345 leaked"`, 1)
+ f.writeSessionLog(t, testSessionID, []string{sessionStartedLine(1, "/repo"), line})
+
+ if _, err := CollectOnce(f.options()); err != nil {
+ t.Fatalf("CollectOnce: %v", err)
+ }
+ data, err := os.ReadFile(f.logPath)
+ if err != nil {
+ t.Fatalf("read runtime log: %v", err)
+ }
+ if strings.Contains(string(data), "sk-abcdefghijklmnopqrstuvwxyz012345") {
+ t.Fatal("a credential printed by an fx command reached the runtime log verbatim")
+ }
+ if !strings.Contains(string(data), "REDACTED") {
+ t.Error("the command output was dropped rather than redacted")
+ }
+}