Skip to content

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

feat(fx): read fx's on-disk session store

Claude855539e302d1
diff --git a/cli/beacon/internal/fxsession/fixtures_test.go b/cli/beacon/internal/fxsession/fixtures_test.go
new file mode 100644
index 00000000..b36ea95e
--- /dev/null
+++ b/cli/beacon/internal/fxsession/fixtures_test.go
@@ -0,0 +1,147 @@
+package fxsession
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// The fixtures in this file are raw JSON text rather than structs marshalled by Beacon's own types.
+//
+// That is deliberate and it is the whole point of the file. Beacon does not control this format:
+// fx encodes its session records by hand in Zig, field by field, with no shared schema to generate
+// from. A fixture built by marshalling Beacon's structs would prove only that Beacon can read what
+// Beacon wrote, and would keep passing after fx renamed a field. These lines are transcribed from
+// fx's writers (writeHistoryTurn, writeExecutionMemory, writePersistedToolResult,
+// writeCommittedFilePresentation, writeToolCall, writeUserTurn, writeTurnSummary in
+// src/core/session/session_codec.zig; encodeFrame in session_event.zig; encodeManifest in
+// session_projection.zig), so a test that fails here is telling you fx moved.
+
+const (
+ testGeneration = "1f4b2c8e6d3a5a7c9b613f0d5e8c2a14"
+ testSessionID = "1770000000000-1770000000000000000-a1b2c3d4e5f60718"
+)
+
+// frame wraps a payload in fx's envelope. Envelope fields are written in fx's own order so the
+// fixture reads like a line pulled off a real log.
+func frame(seq int, timestampMS int64, kind, payload string) string {
+ return fmt.Sprintf(
+ `{"schema_version":1,"log_generation":%q,"seq":%d,"event_id":"%032x","timestamp_ms":%d,"kind":%q,"payload":%s}`,
+ testGeneration, seq, seq, timestampMS, kind, payload,
+ )
+}
+
+func sessionStartedLine(seq int, workspace string) string {
+ payload := fmt.Sprintf(
+ `{"id":%q,"created_at_ms":1770000000000,"origin_workspace_root":%q,"workspace_root":%q,`+
+ `"conversation_language":"en","preferences":{"provider":"gateway","model":"anthropic/claude-opus-4","effort":"medium","fast_mode":false},`+
+ `"usage":null}`,
+ testSessionID, workspace, workspace,
+ )
+ return frame(seq, 1770000000000, KindSessionStarted, payload)
+}
+
+// assistantTurnLine is a full turn: a prompt, a read, an edit that committed a diff, and a command
+// that exited non-zero. It carries every sub-record the mapper reads, so one fixture exercises the
+// decoder end to end rather than a different fixture per field.
+func assistantTurnLine(seq int) string {
+ payload := `{"conversation_language":"en","total_input_tokens":4200,"total_output_tokens":880,"work_id":"work-7","turn":{` +
+ `"kind":"assistant",` +
+ `"user":{"text":"add a health endpoint and run the tests","images":[]},` +
+ `"assistant":"Added the endpoint; the suite fails on an unrelated case.",` +
+ `"execution":{"schema_version":5,"tool_steps":[` +
+ `{"assistant":"Reading the server first.","tool_calls":[` +
+ `{"id":"call_read_1","name":"read_file","arguments_json":"{\"path\":\"src/server.ts\"}","provider_result":null}` +
+ `],"tool_results":[` +
+ `{"tool_call_id":"call_read_1","tool_name":"read_file","status":"success","output":"export function serve() {}",` +
+ `"output_handle":null,"preview":null,"output_bytes":26,"stored_output_bytes":26,"truncated":false,` +
+ `"provider_native":false,"created_at_ms":1770000001000,"permission_feedback":[],` +
+ `"committed_file_presentation":null,"command_output_replay":null,"command_process_presentation":null,` +
+ `"terminal_action_presentation":null}` +
+ `]},` +
+ `{"assistant":null,"tool_calls":[` +
+ `{"id":"call_edit_1","name":"edit_file","arguments_json":"{\"path\":\"src/server.ts\",\"old\":\"serve\",\"new\":\"serveHealth\"}","provider_result":null},` +
+ `{"id":"call_cmd_1","name":"run_command","arguments_json":"{\"command\":\"npm test\"}","provider_result":null}` +
+ `],"tool_results":[` +
+ `{"tool_call_id":"call_edit_1","tool_name":"edit_file","status":"success","output":"edited src/server.ts",` +
+ `"output_handle":null,"preview":null,"output_bytes":19,"stored_output_bytes":19,"truncated":false,` +
+ `"provider_native":false,"created_at_ms":1770000002000,"permission_feedback":[],` +
+ `"committed_file_presentation":{"path":"src/server.ts","kind":"edited","lines":[` +
+ `{"kind":"context","old_line":1,"new_line":1,"text":"import http from \"http\";"},` +
+ `{"kind":"deletion","old_line":2,"new_line":null,"text":"export function serve() {}"},` +
+ `{"kind":"addition","old_line":null,"new_line":2,"text":"export function serveHealth() {}"}` +
+ `],"additions":1,"deletions":1,"truncated":false,"previous_content":"old","after_content":"new",` +
+ `"lifecycle_id":{"turn_id":7,"call_id":"call_edit_1"}},` +
+ `"command_output_replay":null,"command_process_presentation":null,"terminal_action_presentation":null},` +
+ `{"tool_call_id":"call_cmd_1","tool_name":"run_command","status":"failure","output":"1 test failed",` +
+ `"output_handle":"handle-1","preview":"1 test failed","output_bytes":4096,"stored_output_bytes":13,"truncated":true,` +
+ `"provider_native":false,"created_at_ms":1770000003000,"permission_feedback":["approved by rule"],` +
+ `"committed_file_presentation":null,"command_output_replay":{"kind":"available","handle":"handle-1","framed_bytes":4096},` +
+ `"command_process_presentation":{"kind":"exit_code","value":1},"terminal_action_presentation":null}` +
+ `]}` +
+ `],"files":[` +
+ `{"path":"src/server.ts","new_path":null,"tool_call_id":"call_read_1","tool_name":"read_file","action":"read","status":"success","model_view_covers_full_file":true,"stale":false},` +
+ `{"path":"src/server.ts","new_path":null,"tool_call_id":"call_edit_1","tool_name":"edit_file","action":"edit","status":"success","model_view_covers_full_file":true,"stale":false}` +
+ `],"turn_summary":{"started_at_ms":1770000000500,"completed_at_ms":1770000004000,"thinking_duration_ms":900,"turn_duration_ms":3500,` +
+ `"token_progress":{"input_tokens":1200,"output_tokens":340,"input_exact":true,"output_exact":false}}}}}`
+ return frame(seq, 1770000004000, KindHistoryTurnCommitted, payload)
+}
+
+func usageCheckpointLine(seq int, inputTokens, outputTokens int64, cost float64) string {
+ payload := fmt.Sprintf(
+ `{"usage":{"billing":"complete","api_duration_complete":true,"wall_duration_complete":true,"code_complete":true,`+
+ `"next_sequence":3,"settled_through_sequence":2,"api_duration_ms":5100,"wall_duration_ms":7200,"total_cost":%v,`+
+ `"input_tokens":%d,"output_tokens":%d,"cache_read_tokens":900,"cache_write_tokens":120,`+
+ `"billable_web_search_calls":0,"lines_added":12,"lines_removed":3,"models":[`+
+ `{"model":"anthropic/claude-opus-4","total_cost":%v,"input_tokens":%d,"output_tokens":%d,`+
+ `"cache_read_tokens":900,"cache_write_tokens":120,"reasoning_tokens":64}]}}`,
+ cost, inputTokens, outputTokens, cost, inputTokens, outputTokens,
+ )
+ return frame(seq, 1770000005000, KindUsageCheckpointed, payload)
+}
+
+func manifestJSON(generation string, eventLogBytes int64, lastSeq int, workspace string) string {
+ return fmt.Sprintf(
+ `{"schema_version":3,"storage_format":"event_log_v1","id":%q,"authority_id":"%032x","log_generation":%q,`+
+ `"created_at_ms":1770000000000,"updated_at_ms":1770000005000,"origin_workspace_root":%q,"workspace_root":%q,`+
+ `"conversation_language":"en","history_len":1,"total_input_tokens":4200,"total_output_tokens":880,`+
+ `"last_event_seq":%d,"event_log_bytes":%d,"event_log_stat_fingerprint":"%032x",`+
+ `"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}}`,
+ testSessionID, 1, generation, workspace, workspace, lastSeq, eventLogBytes, 2,
+ )
+}
+
+// writeSession lays out one fx session directory: the lines joined with trailing newlines, plus a
+// manifest whose watermark covers exactly the bytes written unless the caller overrides it.
+func writeSession(t *testing.T, root, id string, lines []string, manifest string) string {
+ t.Helper()
+ dir := filepath.Join(root, id)
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ t.Fatalf("create session dir: %v", err)
+ }
+ body := ""
+ if len(lines) > 0 {
+ body = strings.Join(lines, "\n") + "\n"
+ }
+ if err := os.WriteFile(filepath.Join(dir, EventsFileName), []byte(body), 0o600); err != nil {
+ t.Fatalf("write events log: %v", err)
+ }
+ if manifest != "" {
+ if err := os.WriteFile(filepath.Join(dir, ManifestFileName), []byte(manifest), 0o600); err != nil {
+ t.Fatalf("write manifest: %v", err)
+ }
+ }
+ return dir
+}
+
+// logBytes is the on-disk length of a set of lines, which is what fx's committed watermark holds.
+func logBytes(lines []string) int64 {
+ total := 0
+ for _, line := range lines {
+ total += len(line) + 1
+ }
+ return int64(total)
+}
diff --git a/cli/beacon/internal/fxsession/log.go b/cli/beacon/internal/fxsession/log.go
new file mode 100644
index 00000000..05526bce
--- /dev/null
+++ b/cli/beacon/internal/fxsession/log.go
@@ -0,0 +1,252 @@
+package fxsession
+
+import (
+ "bufio"
+ "bytes"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "strings"
+)
+
+// MaxFrameBytes is the largest events.jsonl line this decoder will hold in memory.
+//
+// It is fx's own `event_frame_max_bytes` (8 MiB, src/core/session/session_event.zig): fx refuses to
+// write a frame larger than this, so a longer line is not a big event but a corrupt one -- two
+// frames with a lost newline between them, or a partially overwritten file. Matching fx's limit
+// rather than picking a Beacon-specific number keeps the decoder from rejecting a record fx
+// considers valid, which is the failure that would silently drop a real turn.
+const MaxFrameBytes = 8 * 1024 * 1024
+
+// Stats records what a decoding pass saw. It is returned alongside the events rather than logged,
+// because "Beacon collected nothing from this session" and "Beacon could not read this session"
+// look identical from the outside and the collector reports the difference.
+type Stats struct {
+ Lines int // complete lines read
+ Decoded int // envelopes decoded, including kinds with no mapped payload
+ Skipped int // envelopes skipped: unknown kind or unsupported schema version
+ Malformed int // lines that were not a decodable envelope, or exceeded MaxFrameBytes
+ // PartialTail is set when the file ended without a newline, which means fx was mid-append.
+ // The incomplete bytes are not decoded and not counted as malformed: they are a frame that
+ // has not been written yet, and the next sweep will read it whole.
+ PartialTail bool
+ // FirstError is the first malformed line's error, kept so a caller can say what went wrong
+ // without accumulating one error per line of a corrupt file.
+ FirstError error
+}
+
+// Decoder reads fx event envelopes from an events.jsonl stream.
+//
+// Streaming rather than slurping: a long-running fx session's log grows without bound, and the
+// collector re-reads it on every sweep. Decoding one line at a time keeps that cost proportional
+// to the line rather than to the file.
+//
+// Malformed lines do not stop the pass. An append-only log written by another process can be torn
+// by a crash mid-line, and one unreadable line is not a reason to stop collecting the hundreds of
+// good ones after it -- but it is a reason to say so, which is what Stats.Malformed is for.
+type Decoder struct {
+ reader *bufio.Reader
+ limit int64 // bytes to read, 0 for "until EOF"
+ read int64
+ stats Stats
+ done bool
+}
+
+// NewDecoder reads from r. When limit is positive the decoder stops after that many bytes, which is
+// how a caller restricts a read to the committed prefix fx's manifest reports; see Store.Read.
+func NewDecoder(r io.Reader, limit int64) *Decoder {
+ return &Decoder{reader: bufio.NewReaderSize(r, 64*1024), limit: limit}
+}
+
+// Stats reports what the decoder has seen so far.
+func (d *Decoder) Stats() Stats { return d.stats }
+
+// Next returns the next decoded event, or io.EOF when the stream is exhausted.
+//
+// A line that is skipped (unknown kind, unsupported schema) or malformed is counted and stepped
+// over rather than returned, so a caller's loop only ever sees events it can act on.
+func (d *Decoder) Next() (*Event, error) {
+ for {
+ if d.done {
+ return nil, io.EOF
+ }
+ line, err := d.readLine()
+ if err != nil {
+ if errors.Is(err, io.EOF) {
+ d.done = true
+ return nil, io.EOF
+ }
+ return nil, err
+ }
+ if len(strings.TrimSpace(string(line))) == 0 {
+ continue
+ }
+ d.stats.Lines++
+ event, err := DecodeEnvelope(line)
+ switch {
+ case errors.Is(err, ErrUnsupportedSchema):
+ d.stats.Skipped++
+ continue
+ case err != nil:
+ d.stats.Malformed++
+ if d.stats.FirstError == nil {
+ d.stats.FirstError = err
+ }
+ continue
+ }
+ d.stats.Decoded++
+ if !mapsToPayload(event.Kind) {
+ d.stats.Skipped++
+ continue
+ }
+ return event, nil
+ }
+}
+
+// readLine returns one complete line without its newline, or io.EOF.
+//
+// Three endings are distinguished on purpose. A complete line is returned. A trailing fragment with
+// no newline is a frame fx is still writing, so it is reported through Stats.PartialTail and the
+// stream ends. A line longer than MaxFrameBytes is consumed and discarded as malformed rather than
+// buffered, so a corrupt file cannot make the collector allocate without bound.
+func (d *Decoder) readLine() ([]byte, error) {
+ for {
+ var buf []byte
+ oversized := false
+ for {
+ if d.limit > 0 && d.read >= d.limit {
+ // The committed prefix ends on a frame boundary, so anything buffered here is a
+ // frame fx wrote past the watermark and has not committed yet.
+ d.notePartial(buf, oversized)
+ return nil, io.EOF
+ }
+ chunk, err := d.reader.ReadSlice('\n')
+ if d.limit > 0 && int64(len(chunk)) > d.limit-d.read {
+ chunk = chunk[:d.limit-d.read]
+ err = io.EOF
+ }
+ d.read += int64(len(chunk))
+ if oversized || len(buf)+len(chunk) > MaxFrameBytes {
+ // Discard rather than buffer: a line this long is corruption, and holding it
+ // would let a damaged file dictate the collector's memory use.
+ oversized = true
+ buf = nil
+ } else {
+ buf = append(buf, chunk...)
+ }
+ if errors.Is(err, bufio.ErrBufferFull) {
+ continue
+ }
+ if errors.Is(err, io.EOF) {
+ d.notePartial(buf, oversized)
+ return nil, io.EOF
+ }
+ if err != nil {
+ return nil, err
+ }
+ break
+ }
+ if oversized {
+ d.noteMalformed(fmt.Errorf("fx event frame exceeds %d bytes", MaxFrameBytes))
+ continue
+ }
+ return bytes.TrimSuffix(bytes.TrimSuffix(buf, []byte("\n")), []byte("\r")), nil
+ }
+}
+
+// notePartial records an unterminated trailing frame. An oversized fragment is corruption rather
+// than a frame in flight, so it is counted as malformed instead.
+func (d *Decoder) notePartial(buf []byte, oversized bool) {
+ switch {
+ case oversized:
+ d.noteMalformed(fmt.Errorf("fx event frame exceeds %d bytes", MaxFrameBytes))
+ case len(buf) > 0:
+ d.stats.PartialTail = true
+ }
+}
+
+func (d *Decoder) noteMalformed(err error) {
+ d.stats.Malformed++
+ if d.stats.FirstError == nil {
+ d.stats.FirstError = err
+ }
+}
+
+// mapsToPayload reports whether Beacon decodes a payload for this kind.
+//
+// The kinds that return false are fx's internal storage machinery: recovery checkpoints and the
+// chunked state replacement it writes when it compacts a log. They describe how fx keeps its own
+// records, not anything the agent did, and turning them into endpoint events would fill the log
+// with rows no reader could act on.
+func mapsToPayload(kind string) bool {
+ switch kind {
+ case KindSessionStarted, KindPreferencesChanged, KindWorkspaceRebound,
+ KindHistoryTurnCommitted, KindUsageCheckpointed:
+ return true
+ default:
+ return false
+ }
+}
+
+// DecodeEnvelope decodes one events.jsonl line, including the payload of the kinds Beacon maps.
+//
+// Returns ErrUnsupportedSchema for a version this decoder does not understand, so the caller can
+// skip that line rather than treat the file as corrupt. fx makes the same distinction: it rejects
+// an unknown schema version outright instead of parsing it as the version it knows.
+func DecodeEnvelope(line []byte) (*Event, error) {
+ var envelope Envelope
+ if err := json.Unmarshal(line, &envelope); err != nil {
+ return nil, fmt.Errorf("fx event envelope: %w", err)
+ }
+ if envelope.SchemaVersion != SupportedSchemaVersion {
+ return nil, fmt.Errorf("%w: %d", ErrUnsupportedSchema, envelope.SchemaVersion)
+ }
+ if envelope.Kind == "" {
+ return nil, errors.New("fx event envelope: missing kind")
+ }
+ event := &Event{Envelope: envelope}
+ if err := decodePayload(event); err != nil {
+ return nil, err
+ }
+ return event, nil
+}
+
+func decodePayload(event *Event) error {
+ if len(event.Payload) == 0 {
+ if mapsToPayload(event.Kind) {
+ return fmt.Errorf("fx event %q: missing payload", event.Kind)
+ }
+ return nil
+ }
+ switch event.Kind {
+ case KindSessionStarted:
+ return unmarshalPayload(event.Payload, event.Kind, &event.SessionStarted)
+ case KindPreferencesChanged:
+ return unmarshalPayload(event.Payload, event.Kind, &event.PreferencesChanged)
+ case KindWorkspaceRebound:
+ return unmarshalPayload(event.Payload, event.Kind, &event.WorkspaceRebound)
+ case KindHistoryTurnCommitted:
+ return unmarshalPayload(event.Payload, event.Kind, &event.TurnCommitted)
+ case KindUsageCheckpointed:
+ var wrapper struct {
+ Usage *UsageSnapshot `json:"usage"`
+ }
+ if err := json.Unmarshal(event.Payload, &wrapper); err != nil {
+ return fmt.Errorf("fx event %q: %w", event.Kind, err)
+ }
+ event.UsageCheckpointed = wrapper.Usage
+ return nil
+ default:
+ return nil
+ }
+}
+
+func unmarshalPayload[T any](payload json.RawMessage, kind string, out **T) error {
+ value := new(T)
+ if err := json.Unmarshal(payload, value); err != nil {
+ return fmt.Errorf("fx event %q: %w", kind, err)
+ }
+ *out = value
+ return nil
+}
diff --git a/cli/beacon/internal/fxsession/log_test.go b/cli/beacon/internal/fxsession/log_test.go
new file mode 100644
index 00000000..f49524ae
--- /dev/null
+++ b/cli/beacon/internal/fxsession/log_test.go
@@ -0,0 +1,393 @@
+package fxsession
+
+import (
+ "encoding/json"
+ "errors"
+ "io"
+ "strings"
+ "testing"
+)
+
+// The turn record is the payload the whole integration rests on: it is the only place fx records
+// what the agent did. This test reads one off a fixture transcribed from fx's writers and asserts
+// every field the mapper will later read, because a silently-nil sub-record here becomes a missing
+// event downstream with nothing to explain it.
+func TestDecodeAssistantTurnCarriesEveryExecutionRecord(t *testing.T) {
+ event, err := DecodeEnvelope([]byte(assistantTurnLine(3)))
+ if err != nil {
+ t.Fatalf("DecodeEnvelope: %v", err)
+ }
+ if event.Kind != KindHistoryTurnCommitted {
+ t.Fatalf("kind = %q, want %q", event.Kind, KindHistoryTurnCommitted)
+ }
+ if event.Seq != 3 || event.LogGeneration != testGeneration {
+ t.Errorf("envelope identity = seq %d generation %q, want seq 3 generation %q",
+ event.Seq, event.LogGeneration, testGeneration)
+ }
+ committed := event.TurnCommitted
+ if committed == nil {
+ t.Fatal("TurnCommitted is nil for a history_turn_committed event")
+ }
+ if committed.TotalInputTokens != 4200 || committed.TotalOutputTokens != 880 {
+ t.Errorf("session totals = %d/%d, want 4200/880", committed.TotalInputTokens, committed.TotalOutputTokens)
+ }
+ turn := committed.Turn
+ if turn.Kind != TurnKindAssistant {
+ t.Fatalf("turn kind = %q, want %q", turn.Kind, TurnKindAssistant)
+ }
+ if turn.User == nil || turn.User.Text != "add a health endpoint and run the tests" {
+ t.Fatalf("user prompt not decoded: %+v", turn.User)
+ }
+ if turn.Assistant == nil || *turn.Assistant == "" {
+ t.Error("assistant text missing")
+ }
+ if turn.Execution == nil {
+ t.Fatal("execution missing")
+ }
+ if got := len(turn.Execution.ToolSteps); got != 2 {
+ t.Fatalf("tool steps = %d, want 2", got)
+ }
+
+ read := turn.Execution.ToolSteps[0]
+ if len(read.ToolCalls) != 1 || read.ToolCalls[0].Name != "read_file" {
+ t.Fatalf("first step calls = %+v", read.ToolCalls)
+ }
+ if read.ToolCalls[0].ArgumentsJSON != `{"path":"src/server.ts"}` {
+ t.Errorf("arguments_json = %q, want the tool's own JSON preserved verbatim", read.ToolCalls[0].ArgumentsJSON)
+ }
+ if len(read.ToolResults) != 1 || read.ToolResults[0].Status != ToolStatusSuccess {
+ t.Fatalf("first step results = %+v", read.ToolResults)
+ }
+
+ work := turn.Execution.ToolSteps[1]
+ if len(work.ToolCalls) != 2 || len(work.ToolResults) != 2 {
+ t.Fatalf("second step = %d calls / %d results, want 2/2", len(work.ToolCalls), len(work.ToolResults))
+ }
+ edit := work.ToolResults[0]
+ if edit.CommittedFile == nil {
+ t.Fatal("edit result carries no committed_file_presentation, so no diff would reach the log")
+ }
+ if edit.CommittedFile.Path != "src/server.ts" || edit.CommittedFile.Kind != "edited" {
+ t.Errorf("committed file = %+v", edit.CommittedFile)
+ }
+ if edit.CommittedFile.Additions != 1 || edit.CommittedFile.Deletions != 1 {
+ t.Errorf("diff counts = +%d/-%d, want +1/-1", edit.CommittedFile.Additions, edit.CommittedFile.Deletions)
+ }
+ if got := len(edit.CommittedFile.Lines); got != 3 {
+ t.Errorf("diff lines = %d, want 3", got)
+ }
+ if edit.CommittedFile.LifecycleD == nil || edit.CommittedFile.LifecycleD.CallID != "call_edit_1" {
+ t.Errorf("lifecycle id = %+v, want the edit's call id", edit.CommittedFile.LifecycleD)
+ }
+
+ command := work.ToolResults[1]
+ if command.Status != ToolStatusFailure {
+ t.Errorf("command status = %q, want %q", command.Status, ToolStatusFailure)
+ }
+ if command.CommandProcess == nil || command.CommandProcess.Kind != ProcessExitCode {
+ t.Fatalf("command process outcome = %+v", command.CommandProcess)
+ }
+ if command.CommandProcess.Value == nil || *command.CommandProcess.Value != 1 {
+ t.Errorf("exit code = %+v, want 1", command.CommandProcess.Value)
+ }
+ // fx stored 13 of 4096 bytes. Both numbers have to survive: a reader that sees only the stored
+ // size cannot tell a short output from a truncated one.
+ if command.OutputBytes != 4096 || command.StoredOutputBytes != 13 || !command.Truncated {
+ t.Errorf("output accounting = %d/%d truncated=%v, want 4096/13 truncated=true",
+ command.OutputBytes, command.StoredOutputBytes, command.Truncated)
+ }
+ if len(command.PermissionFeedback) != 1 || command.PermissionFeedback[0] != "approved by rule" {
+ t.Errorf("permission feedback = %+v", command.PermissionFeedback)
+ }
+
+ if got := len(turn.Execution.Files); got != 2 {
+ t.Fatalf("file evidence = %d records, want 2", got)
+ }
+ if turn.Execution.Files[0].Action != FileActionRead || turn.Execution.Files[1].Action != FileActionEdit {
+ t.Errorf("file actions = %q/%q, want read/edit",
+ turn.Execution.Files[0].Action, turn.Execution.Files[1].Action)
+ }
+ summary := turn.Execution.TurnSummary
+ if summary == nil {
+ t.Fatal("turn summary missing, so the turn's own token counts would be lost")
+ }
+ if summary.TokenProgress.InputTokens != 1200 || summary.TokenProgress.OutputTokens != 340 {
+ t.Errorf("turn tokens = %d/%d, want 1200/340",
+ summary.TokenProgress.InputTokens, summary.TokenProgress.OutputTokens)
+ }
+ // fx says the output count is an estimate. Carrying the flag is what keeps Beacon from
+ // presenting an estimate as a measurement.
+ if !summary.TokenProgress.InputExact || summary.TokenProgress.OutputExact {
+ t.Errorf("exactness flags = in %v / out %v, want true/false",
+ summary.TokenProgress.InputExact, summary.TokenProgress.OutputExact)
+ }
+}
+
+// A session's cumulative totals and its per-turn counts are different numbers in the same record.
+// Reading one for the other reports a session's entire history as the cost of its last turn, which
+// is the kind of error a token report shows without ever looking wrong.
+func TestSessionTotalsAndTurnTokensAreDistinctFields(t *testing.T) {
+ event, err := DecodeEnvelope([]byte(assistantTurnLine(3)))
+ if err != nil {
+ t.Fatalf("DecodeEnvelope: %v", err)
+ }
+ committed := event.TurnCommitted
+ if committed.TotalInputTokens == uint64(committed.Turn.Execution.TurnSummary.TokenProgress.InputTokens) {
+ t.Fatal("fixture no longer distinguishes cumulative totals from per-turn counts")
+ }
+}
+
+func TestDecodeSessionStartedCarriesWorkspaceAndPreferences(t *testing.T) {
+ event, err := DecodeEnvelope([]byte(sessionStartedLine(1, "/home/dev/api")))
+ if err != nil {
+ t.Fatalf("DecodeEnvelope: %v", err)
+ }
+ started := event.SessionStarted
+ if started == nil {
+ t.Fatal("SessionStarted is nil")
+ }
+ if started.ID != testSessionID {
+ t.Errorf("session id = %q, want %q", started.ID, testSessionID)
+ }
+ if started.WorkspaceRoot != "/home/dev/api" {
+ t.Errorf("workspace root = %q", started.WorkspaceRoot)
+ }
+ if started.Preferences == nil || started.Preferences.Model != "anthropic/claude-opus-4" {
+ t.Fatalf("preferences = %+v", started.Preferences)
+ }
+ if started.Preferences.Provider != "gateway" {
+ t.Errorf("provider = %q, want gateway", started.Preferences.Provider)
+ }
+}
+
+func TestDecodeUsageCheckpointCarriesCostAndCacheTokens(t *testing.T) {
+ event, err := DecodeEnvelope([]byte(usageCheckpointLine(4, 4200, 880, 0.1234)))
+ if err != nil {
+ t.Fatalf("DecodeEnvelope: %v", err)
+ }
+ usage := event.UsageCheckpointed
+ if usage == nil {
+ t.Fatal("UsageCheckpointed is nil")
+ }
+ if usage.InputTokens != 4200 || usage.OutputTokens != 880 {
+ t.Errorf("tokens = %d/%d, want 4200/880", usage.InputTokens, usage.OutputTokens)
+ }
+ if usage.CacheReadTokens != 900 || usage.CacheWriteTokens != 120 {
+ t.Errorf("cache tokens = %d/%d, want 900/120", usage.CacheReadTokens, usage.CacheWriteTokens)
+ }
+ if usage.TotalCost != 0.1234 {
+ t.Errorf("total cost = %v, want 0.1234", usage.TotalCost)
+ }
+ if len(usage.Models) != 1 || usage.Models[0].Model != "anthropic/claude-opus-4" {
+ t.Fatalf("model breakdown = %+v", usage.Models)
+ }
+ if usage.Models[0].ReasoningTokens == nil || *usage.Models[0].ReasoningTokens != 64 {
+ t.Errorf("reasoning tokens = %+v, want 64", usage.Models[0].ReasoningTokens)
+ }
+}
+
+// fx rejects an events.jsonl frame whose schema_version it does not know rather than reading it
+// leniently, because a version bump means the fields moved. Beacon skips the line for the same
+// reason -- but skipping one line must not cost the rest of the session.
+func TestUnsupportedSchemaVersionSkipsTheLineNotTheSession(t *testing.T) {
+ future := strings.Replace(assistantTurnLine(3), `"schema_version":1`, `"schema_version":99`, 1)
+ lines := []string{sessionStartedLine(1, "/repo"), future, usageCheckpointLine(4, 10, 5, 0.01)}
+
+ events, stats := decodeAll(t, strings.Join(lines, "\n")+"\n")
+ if len(events) != 2 {
+ t.Fatalf("decoded %d events, want 2 (the start and the usage checkpoint)", len(events))
+ }
+ if stats.Skipped != 1 {
+ t.Errorf("stats.Skipped = %d, want 1", stats.Skipped)
+ }
+ if stats.Malformed != 0 {
+ t.Errorf("stats.Malformed = %d, want 0 -- a future version is not corruption", stats.Malformed)
+ }
+ if _, err := DecodeEnvelope([]byte(future)); !errors.Is(err, ErrUnsupportedSchema) {
+ t.Errorf("DecodeEnvelope error = %v, want ErrUnsupportedSchema", err)
+ }
+}
+
+// fx writes kinds Beacon has no mapping for -- recovery checkpoints, and the chunked state blob it
+// writes when it compacts a log. They must be stepped over silently: they describe fx's own
+// storage, not anything the agent did.
+func TestStorageOnlyKindsAreSkipped(t *testing.T) {
+ for _, kind := range []string{
+ KindRecoveryCheckpointSet, KindRecoveryCheckpointClear,
+ KindStateReplacementStarted, KindStateReplacementChunk, KindStateReplacementCommited,
+ "some_kind_fx_adds_in_2027",
+ } {
+ t.Run(kind, func(t *testing.T) {
+ line := frame(2, 1770000002000, kind, `{"anything":true}`)
+ events, stats := decodeAll(t, line+"\n")
+ if len(events) != 0 {
+ t.Fatalf("decoded %d events for %q, want 0", len(events), kind)
+ }
+ if stats.Skipped != 1 || stats.Malformed != 0 {
+ t.Errorf("stats = %+v, want one skip and no malformed line", stats)
+ }
+ })
+ }
+}
+
+// A log Beacon reads while fx is writing it ends mid-frame. That tail is not corruption and must
+// not be reported as such: the frame is simply not there yet, and the next sweep reads it whole.
+func TestPartialTrailingFrameIsNotTreatedAsCorruption(t *testing.T) {
+ complete := sessionStartedLine(1, "/repo")
+ partial := assistantTurnLine(2)
+ body := complete + "\n" + partial[:len(partial)/2]
+
+ events, stats := decodeAll(t, body)
+ if len(events) != 1 {
+ t.Fatalf("decoded %d events, want 1", len(events))
+ }
+ if !stats.PartialTail {
+ t.Error("stats.PartialTail = false, want true for a log that ends mid-frame")
+ }
+ if stats.Malformed != 0 {
+ t.Errorf("stats.Malformed = %d, want 0 -- an unfinished append is not a damaged record", stats.Malformed)
+ }
+}
+
+// A line that is complete but not decodable is corruption, and one corrupt line is not a reason to
+// abandon the good lines around it. Both halves of that sentence are asserted here.
+func TestMalformedLineIsCountedAndSteppedOver(t *testing.T) {
+ body := strings.Join([]string{
+ sessionStartedLine(1, "/repo"),
+ `{"schema_version":1,"log_generation":"x","seq":2,"kind":"history_turn_committed","payload":{`,
+ usageCheckpointLine(3, 10, 5, 0.02),
+ }, "\n") + "\n"
+
+ events, stats := decodeAll(t, body)
+ if len(events) != 2 {
+ t.Fatalf("decoded %d events, want 2", len(events))
+ }
+ if stats.Malformed != 1 {
+ t.Errorf("stats.Malformed = %d, want 1", stats.Malformed)
+ }
+ if stats.FirstError == nil {
+ t.Error("stats.FirstError is nil; a caller has nothing to report")
+ }
+}
+
+// A frame larger than fx will ever write is corruption -- two frames with a lost newline, or a
+// partially overwritten file. The decoder must discard it without buffering it, and must keep
+// reading afterwards.
+func TestOversizedFrameIsDiscardedAndReadingContinues(t *testing.T) {
+ oversized := `{"schema_version":1,"kind":"history_turn_committed","payload":"` +
+ strings.Repeat("x", MaxFrameBytes+1024) + `"}`
+ body := oversized + "\n" + sessionStartedLine(2, "/repo") + "\n"
+
+ events, stats := decodeAll(t, body)
+ if len(events) != 1 {
+ t.Fatalf("decoded %d events, want the one good line after the oversized frame", len(events))
+ }
+ if stats.Malformed != 1 {
+ t.Errorf("stats.Malformed = %d, want 1", stats.Malformed)
+ }
+ if stats.PartialTail {
+ t.Error("stats.PartialTail = true; an oversized frame is corruption, not an append in flight")
+ }
+}
+
+// Blank lines and \r\n endings both occur: the first from an editor that touched the file, the
+// second from a log copied through a Windows tool. Neither is a record and neither is damage.
+func TestBlankLinesAndCarriageReturnsAreTolerated(t *testing.T) {
+ body := "\n" + sessionStartedLine(1, "/repo") + "\r\n" + "\n" + usageCheckpointLine(2, 1, 1, 0.0) + "\n"
+ events, stats := decodeAll(t, body)
+ if len(events) != 2 {
+ t.Fatalf("decoded %d events, want 2", len(events))
+ }
+ if stats.Malformed != 0 {
+ t.Errorf("stats.Malformed = %d, want 0", stats.Malformed)
+ }
+}
+
+// fx writes a byte sequence that is not valid UTF-8 as {"encoding":"base64","data":...} rather than
+// as a JSON string. Those are the sessions worth reading -- the agent read a binary file, or a
+// command printed a stray byte -- so a decoder that assumed a plain string would drop exactly the
+// turns an investigator came for.
+func TestDurableStringDecodesBothOfFxEncodings(t *testing.T) {
+ var plain DurableString
+ if err := json.Unmarshal([]byte(`"hello"`), &plain); err != nil {
+ t.Fatalf("plain string: %v", err)
+ }
+ if plain != "hello" {
+ t.Errorf("plain = %q, want %q", plain, "hello")
+ }
+
+ var binary DurableString
+ if err := json.Unmarshal([]byte(`{"encoding":"base64","data":"/w=="}`), &binary); err != nil {
+ t.Fatalf("base64 object: %v", err)
+ }
+ if string(binary) != "\xff" {
+ t.Errorf("binary = %q, want the decoded 0xff byte", string(binary))
+ }
+
+ var missing DurableString
+ if err := json.Unmarshal([]byte(`null`), &missing); err != nil {
+ t.Fatalf("null: %v", err)
+ }
+ if missing != "" {
+ t.Errorf("null decoded to %q, want the empty string", missing)
+ }
+
+ if _, err := (DurableString("ok")).MarshalJSON(); err != nil {
+ t.Fatalf("marshal plain: %v", err)
+ }
+ roundTrip, err := json.Marshal(binary)
+ if err != nil {
+ t.Fatalf("marshal binary: %v", err)
+ }
+ if !strings.Contains(string(roundTrip), `"encoding":"base64"`) {
+ t.Errorf("binary re-encoded as %s, want fx's base64 form", roundTrip)
+ }
+}
+
+// An unsupported encoding is a decode failure rather than a silently empty field. A tool output
+// that Beacon cannot read must not reach the log as an empty string, which would read as "the tool
+// returned nothing".
+func TestDurableStringRejectsUnknownEncoding(t *testing.T) {
+ var value DurableString
+ err := json.Unmarshal([]byte(`{"encoding":"rot13","data":"uryyb"}`), &value)
+ if err == nil {
+ t.Fatal("unknown encoding decoded without error")
+ }
+ if !strings.Contains(err.Error(), "rot13") {
+ t.Errorf("error = %v, want it to name the encoding", err)
+ }
+}
+
+func TestDecodeEnvelopeRejectsRecordsWithNoKind(t *testing.T) {
+ _, err := DecodeEnvelope([]byte(`{"schema_version":1,"log_generation":"x","seq":1,"payload":{}}`))
+ if err == nil {
+ t.Fatal("envelope with no kind decoded without error")
+ }
+}
+
+// A mapped kind with no payload is a broken record, not an empty one: fx never writes a
+// history_turn_committed without a turn, so accepting it would put an event with no content into
+// the log.
+func TestMappedKindWithoutPayloadIsMalformed(t *testing.T) {
+ line := `{"schema_version":1,"log_generation":"x","seq":1,"event_id":"y","timestamp_ms":1,"kind":"history_turn_committed"}`
+ if _, err := DecodeEnvelope([]byte(line)); err == nil {
+ t.Fatal("history_turn_committed with no payload decoded without error")
+ }
+}
+
+func decodeAll(t *testing.T, body string) ([]Event, Stats) {
+ t.Helper()
+ decoder := NewDecoder(strings.NewReader(body), 0)
+ var events []Event
+ for {
+ event, err := decoder.Next()
+ if errors.Is(err, io.EOF) {
+ break
+ }
+ if err != nil {
+ t.Fatalf("Decoder.Next: %v", err)
+ }
+ events = append(events, *event)
+ }
+ return events, decoder.Stats()
+}
diff --git a/cli/beacon/internal/fxsession/store.go b/cli/beacon/internal/fxsession/store.go
new file mode 100644
index 00000000..4f226d03
--- /dev/null
+++ b/cli/beacon/internal/fxsession/store.go
@@ -0,0 +1,257 @@
+package fxsession
+
+import (
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+)
+
+const (
+ // EventsFileName and ManifestFileName are fx's names for the two files in a session directory
+ // (src/core/session/session_log.zig).
+ EventsFileName = "events.jsonl"
+ ManifestFileName = "session.json"
+
+ // ManifestSchemaVersion is the session.json version this reader understands. A different
+ // version is not an error: the manifest is an optimization, and the log can be read whole
+ // without it. See Store.Read.
+ ManifestSchemaVersion = 3
+
+ // MaxManifestBytes bounds the manifest read. fx's own limit is smaller; this leaves room for
+ // growth while still refusing to read an arbitrarily large file that happens to sit at that
+ // path.
+ MaxManifestBytes = 1 << 20
+)
+
+// DefaultSessionsDir returns fx's session directory for the current user.
+//
+// fx resolves its profile from $HOME (falling back to %USERPROFILE% on Windows), which is what
+// os.UserHomeDir reports on both, so Beacon looks where fx writes rather than where a Beacon
+// convention would put it. Nothing here creates the directory: its absence is the answer to "is
+// this machine running fx", and creating it would fabricate the evidence.
+func DefaultSessionsDir() (string, error) {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", fmt.Errorf("resolve home directory: %w", err)
+ }
+ if strings.TrimSpace(home) == "" {
+ return "", errors.New("home directory is empty")
+ }
+ return filepath.Join(home, ".fx", "sessions"), nil
+}
+
+// Manifest is fx's session.json: a projection of the session's committed state.
+//
+// EventLogBytes is the field this reader exists for. It is the length of the durable, committed
+// prefix of events.jsonl -- fx appends a frame, then advances this watermark, so the bytes past it
+// are a write in flight. Reading to the watermark rather than to EOF is what keeps a sweep from
+// decoding a half-written frame and counting it as corruption.
+type Manifest struct {
+ SchemaVersion int `json:"schema_version"`
+ StorageFormat string `json:"storage_format"`
+ ID string `json:"id"`
+ LogGeneration string `json:"log_generation"`
+ CreatedAtMS int64 `json:"created_at_ms"`
+ UpdatedAtMS int64 `json:"updated_at_ms"`
+ OriginWorkspaceRoot string `json:"origin_workspace_root"`
+ WorkspaceRoot string `json:"workspace_root"`
+ ConversationLang string `json:"conversation_language"`
+ HistoryLen int `json:"history_len"`
+ TotalInputTokens int64 `json:"total_input_tokens"`
+ TotalOutputTokens int64 `json:"total_output_tokens"`
+ LastEventSeq uint64 `json:"last_event_seq"`
+ EventLogBytes int64 `json:"event_log_bytes"`
+ Preferences *Preferences `json:"preferences"`
+}
+
+// SessionRef is one fx session on disk: where it is and, when the manifest could be read, what it
+// says. Manifest is nil when there is no readable manifest, which is normal for a session fx has
+// only just created.
+type SessionRef struct {
+ ID string
+ Dir string
+ EventsLog string
+ Manifest *Manifest
+ // ModTimeUnixMS is the events.jsonl modification time, used as the change signal when no
+ // manifest is available. It is a fallback, not the primary cursor: the collector's real
+ // idempotence comes from the per-session sequence cursor, not from a timestamp.
+ ModTimeUnixMS int64
+ // SizeBytes is the events.jsonl size on disk, including any uncommitted tail.
+ SizeBytes int64
+}
+
+// Store is a directory of fx sessions, normally ~/.fx/sessions.
+type Store struct {
+ Dir string
+}
+
+// NewStore points at dir, or at fx's default location when dir is empty.
+func NewStore(dir string) (*Store, error) {
+ if strings.TrimSpace(dir) != "" {
+ return &Store{Dir: dir}, nil
+ }
+ def, err := DefaultSessionsDir()
+ if err != nil {
+ return nil, err
+ }
+ return &Store{Dir: def}, nil
+}
+
+// Exists reports whether the sessions directory is present. A missing directory means fx has not
+// run for this user, which every caller reports rather than treats as a failure.
+func (s *Store) Exists() bool {
+ info, err := os.Stat(s.Dir)
+ return err == nil && info.IsDir()
+}
+
+// List returns every session directory that holds an events log, oldest change first.
+//
+// Ordering is by the session's own last-modified time so a sweep processes sessions in roughly the
+// order they were used, which keeps the resulting Beacon log close to chronological even before
+// per-event timestamps sort it.
+//
+// An unreadable session directory is skipped rather than failing the listing: fx creates the
+// directory before the log, another user's session may not be readable, and neither is a reason to
+// collect nothing from the sessions that are.
+func (s *Store) List() ([]SessionRef, error) {
+ entries, err := os.ReadDir(s.Dir)
+ if err != nil {
+ if errors.Is(err, fs.ErrNotExist) {
+ return nil, nil
+ }
+ return nil, fmt.Errorf("read fx sessions directory: %w", err)
+ }
+ refs := make([]SessionRef, 0, len(entries))
+ for _, entry := range entries {
+ if !entry.IsDir() {
+ continue
+ }
+ id := entry.Name()
+ if err := ValidateSessionID(id); err != nil {
+ continue
+ }
+ dir := filepath.Join(s.Dir, id)
+ logPath := filepath.Join(dir, EventsFileName)
+ info, err := os.Stat(logPath)
+ if err != nil || info.IsDir() {
+ continue
+ }
+ ref := SessionRef{
+ ID: id,
+ Dir: dir,
+ EventsLog: logPath,
+ ModTimeUnixMS: info.ModTime().UnixMilli(),
+ SizeBytes: info.Size(),
+ }
+ if manifest, err := ReadManifest(filepath.Join(dir, ManifestFileName)); err == nil {
+ ref.Manifest = manifest
+ }
+ refs = append(refs, ref)
+ }
+ sort.SliceStable(refs, func(i, j int) bool {
+ if refs[i].ModTimeUnixMS != refs[j].ModTimeUnixMS {
+ return refs[i].ModTimeUnixMS < refs[j].ModTimeUnixMS
+ }
+ return refs[i].ID < refs[j].ID
+ })
+ return refs, nil
+}
+
+// ValidateSessionID applies fx's own rule for a session id: non-empty, at most 255 bytes,
+// alphanumerics plus `.`, `_` and `-`, and never "." or "..".
+//
+// Beacon re-applies it because the id is a path segment and reaches this code from a directory
+// listing and from a state file that has been on disk between runs. A session id is also written
+// into every event, so a name carrying a separator would be both a traversal risk here and a
+// misleading identifier downstream.
+func ValidateSessionID(id string) error {
+ if id == "" || len(id) > 255 || id == "." || id == ".." {
+ return fmt.Errorf("invalid fx session id %q", id)
+ }
+ for i := 0; i < len(id); i++ {
+ c := id[i]
+ switch {
+ case c >= 'a' && c <= 'z', c >= 'A' && c <= 'Z', c >= '0' && c <= '9':
+ case c == '.' || c == '_' || c == '-':
+ default:
+ return fmt.Errorf("invalid fx session id %q", id)
+ }
+ }
+ return nil
+}
+
+// ReadManifest reads and validates a session.json.
+//
+// A manifest whose schema version or storage format this reader does not recognize is an error
+// rather than a partially-trusted value: its fields are what bound the log read, and reading the
+// log whole is a correct fallback while trusting a byte count from a format that moved is not.
+func ReadManifest(path string) (*Manifest, error) {
+ info, err := os.Stat(path)
+ if err != nil {
+ return nil, err
+ }
+ if info.Size() > MaxManifestBytes {
+ return nil, fmt.Errorf("fx manifest %s is %d bytes, over the %d-byte limit", path, info.Size(), MaxManifestBytes)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return nil, err
+ }
+ var manifest Manifest
+ if err := json.Unmarshal(data, &manifest); err != nil {
+ return nil, fmt.Errorf("fx manifest %s: %w", path, err)
+ }
+ if manifest.SchemaVersion != ManifestSchemaVersion {
+ return nil, fmt.Errorf("fx manifest %s: unsupported schema version %d", path, manifest.SchemaVersion)
+ }
+ if manifest.EventLogBytes < 0 {
+ return nil, fmt.Errorf("fx manifest %s: negative event_log_bytes", path)
+ }
+ return &manifest, nil
+}
+
+// Read decodes a session's events log, stopping at the manifest's committed watermark when there is
+// one.
+//
+// The watermark is clamped to the file's actual size rather than trusted outright. The manifest is
+// written after the log, so a manifest from a later state than the log on disk -- a restored
+// backup, a copied directory, a partial sync -- would otherwise make the decoder read past EOF and
+// report the whole session as unreadable.
+//
+// Events are returned in log order. The caller filters by cursor; this function has no opinion
+// about what has already been collected.
+func (s *Store) Read(ref SessionRef) ([]Event, Stats, error) {
+ file, err := os.Open(ref.EventsLog)
+ if err != nil {
+ return nil, Stats{}, err
+ }
+ defer file.Close()
+
+ limit := int64(0)
+ if ref.Manifest != nil && ref.Manifest.EventLogBytes > 0 {
+ limit = ref.Manifest.EventLogBytes
+ if info, err := file.Stat(); err == nil && info.Size() < limit {
+ limit = info.Size()
+ }
+ }
+
+ decoder := NewDecoder(file, limit)
+ var events []Event
+ for {
+ event, err := decoder.Next()
+ if errors.Is(err, io.EOF) {
+ break
+ }
+ if err != nil {
+ return events, decoder.Stats(), err
+ }
+ events = append(events, *event)
+ }
+ return events, decoder.Stats(), nil
+}
diff --git a/cli/beacon/internal/fxsession/store_test.go b/cli/beacon/internal/fxsession/store_test.go
new file mode 100644
index 00000000..6ee33ea1
--- /dev/null
+++ b/cli/beacon/internal/fxsession/store_test.go
@@ -0,0 +1,272 @@
+package fxsession
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestDefaultSessionsDirFollowsFxProfileLayout(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home) // os.UserHomeDir reads this one on Windows
+
+ dir, err := DefaultSessionsDir()
+ if err != nil {
+ t.Fatalf("DefaultSessionsDir: %v", err)
+ }
+ if want := filepath.Join(home, ".fx", "sessions"); dir != want {
+ t.Errorf("DefaultSessionsDir = %q, want %q", dir, want)
+ }
+ // Looking must not create anything. The directory's absence is Beacon's evidence that fx has
+ // not run for this user, and a probe that creates it destroys that evidence -- and leaves a
+ // stray directory in the home of someone who does not use fx.
+ if _, err := os.Stat(filepath.Join(home, ".fx")); !os.IsNotExist(err) {
+ t.Errorf("looking up the sessions directory created %s", filepath.Join(home, ".fx"))
+ }
+}
+
+func TestListReturnsOnlySessionDirectoriesThatHoldALog(t *testing.T) {
+ root := t.TempDir()
+ lines := []string{sessionStartedLine(1, "/repo")}
+ writeSession(t, root, "1770000000000-1-aaaa", lines, "")
+ // A directory fx created before writing the log: real, and nothing to read yet.
+ if err := os.MkdirAll(filepath.Join(root, "1770000000001-2-bbbb"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ // A stray file at the top level, and a name that is not a valid fx session id.
+ if err := os.WriteFile(filepath.Join(root, "notes.txt"), []byte("x"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ writeSession(t, root, "has spaces", lines, "")
+
+ store := &Store{Dir: root}
+ refs, err := store.List()
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ if len(refs) != 1 {
+ t.Fatalf("List returned %d sessions, want 1: %+v", len(refs), refs)
+ }
+ if refs[0].ID != "1770000000000-1-aaaa" {
+ t.Errorf("session id = %q", refs[0].ID)
+ }
+ if refs[0].SizeBytes != logBytes(lines) {
+ t.Errorf("size = %d, want %d", refs[0].SizeBytes, logBytes(lines))
+ }
+}
+
+// A missing sessions directory means fx has not run here. Callers report that; it is not an error
+// and must not read like one.
+func TestListOnAMissingDirectoryReturnsNothingAndNoError(t *testing.T) {
+ store := &Store{Dir: filepath.Join(t.TempDir(), "absent")}
+ refs, err := store.List()
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ if len(refs) != 0 {
+ t.Errorf("List returned %d sessions, want 0", len(refs))
+ }
+ if store.Exists() {
+ t.Error("Exists reported a directory that is not there")
+ }
+}
+
+func TestListOrdersSessionsByLastChange(t *testing.T) {
+ root := t.TempDir()
+ lines := []string{sessionStartedLine(1, "/repo")}
+ for _, id := range []string{"1770000000002-c-cccc", "1770000000000-a-aaaa", "1770000000001-b-bbbb"} {
+ writeSession(t, root, id, lines, "")
+ }
+ // Modification times, not names, are the ordering key: a session resumed today sorts after one
+ // created today and abandoned, whatever their ids say.
+ stamp := func(id string, unixMS int64) {
+ path := filepath.Join(root, id, EventsFileName)
+ when := os.Chtimes(path, timeFromMillis(unixMS), timeFromMillis(unixMS))
+ if when != nil {
+ t.Fatalf("chtimes: %v", when)
+ }
+ }
+ stamp("1770000000002-c-cccc", 1770000009000)
+ stamp("1770000000000-a-aaaa", 1770000007000)
+ stamp("1770000000001-b-bbbb", 1770000008000)
+
+ store := &Store{Dir: root}
+ refs, err := store.List()
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ got := []string{refs[0].ID, refs[1].ID, refs[2].ID}
+ want := []string{"1770000000000-a-aaaa", "1770000000001-b-bbbb", "1770000000002-c-cccc"}
+ for i := range want {
+ if got[i] != want[i] {
+ t.Fatalf("List order = %v, want %v", got, want)
+ }
+ }
+}
+
+func TestValidateSessionIDMatchesFxOwnRule(t *testing.T) {
+ for _, id := range []string{"a", "1770000000000-1770000000000000000-a1b2c3d4e5f60718", "session.v3", ".hidden", "a_b-c.d"} {
+ if err := ValidateSessionID(id); err != nil {
+ t.Errorf("ValidateSessionID(%q) = %v, want it accepted", id, err)
+ }
+ }
+ for _, id := range []string{"", ".", "..", "../outside", "/tmp/outside", "nested/session", `nested\session`, "a b", "a\x00b", strings.Repeat("a", 256)} {
+ if err := ValidateSessionID(id); err == nil {
+ t.Errorf("ValidateSessionID(%q) accepted a name that is not an fx session id", id)
+ }
+ }
+}
+
+// The manifest's byte count is the committed watermark: fx appends a frame and then advances it, so
+// bytes past it are a write in flight. Reading to the watermark rather than to EOF is what keeps a
+// sweep from decoding a frame fx has not finished writing.
+func TestReadStopsAtTheCommittedWatermark(t *testing.T) {
+ root := t.TempDir()
+ committed := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}
+ inFlight := usageCheckpointLine(3, 10, 5, 0.03)
+ all := append(append([]string{}, committed...), inFlight)
+ manifest := manifestJSON(testGeneration, logBytes(committed), 2, "/repo")
+ writeSession(t, root, testSessionID, all, manifest)
+
+ store := &Store{Dir: root}
+ refs, err := store.List()
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ if len(refs) != 1 || refs[0].Manifest == nil {
+ t.Fatalf("expected one session with a manifest, got %+v", refs)
+ }
+ events, stats, err := store.Read(refs[0])
+ if err != nil {
+ t.Fatalf("Read: %v", err)
+ }
+ if len(events) != 2 {
+ t.Fatalf("read %d events, want the 2 committed ones", len(events))
+ }
+ if events[1].Kind != KindHistoryTurnCommitted {
+ t.Errorf("second event kind = %q", events[1].Kind)
+ }
+ if stats.Malformed != 0 {
+ t.Errorf("stats.Malformed = %d, want 0", stats.Malformed)
+ }
+}
+
+// A manifest can describe more of the log than exists: a restored backup, a copied session
+// directory, an interrupted sync. Trusting the count outright would read past EOF and report a
+// readable session as unreadable, so the watermark is clamped to the file.
+func TestReadClampsAWatermarkThatOverrunsTheFile(t *testing.T) {
+ root := t.TempDir()
+ lines := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}
+ manifest := manifestJSON(testGeneration, logBytes(lines)*4, 9, "/repo")
+ writeSession(t, root, testSessionID, lines, manifest)
+
+ store := &Store{Dir: root}
+ refs, _ := store.List()
+ events, stats, err := store.Read(refs[0])
+ if err != nil {
+ t.Fatalf("Read: %v", err)
+ }
+ if len(events) != 2 {
+ t.Fatalf("read %d events, want 2", len(events))
+ }
+ if stats.Malformed != 0 {
+ t.Errorf("stats.Malformed = %d, want 0", stats.Malformed)
+ }
+}
+
+// No manifest at all is normal for a session fx has just created, and the log is still readable.
+// The whole file is read in that case, minus any unterminated tail.
+func TestReadWithoutAManifestFallsBackToTheWholeLog(t *testing.T) {
+ root := t.TempDir()
+ lines := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2), usageCheckpointLine(3, 1, 1, 0.0)}
+ writeSession(t, root, testSessionID, lines, "")
+
+ store := &Store{Dir: root}
+ refs, _ := store.List()
+ if refs[0].Manifest != nil {
+ t.Fatal("expected no manifest")
+ }
+ events, _, err := store.Read(refs[0])
+ if err != nil {
+ t.Fatalf("Read: %v", err)
+ }
+ if len(events) != 3 {
+ t.Fatalf("read %d events, want 3", len(events))
+ }
+}
+
+// A manifest whose schema version moved is not partially trusted. Its byte count is what bounds the
+// log read, and reading the log whole is a correct fallback while trusting a number from a format
+// that changed is not.
+func TestManifestFromAnotherSchemaVersionIsRejectedRatherThanGuessedAt(t *testing.T) {
+ root := t.TempDir()
+ lines := []string{sessionStartedLine(1, "/repo")}
+ manifest := strings.Replace(manifestJSON(testGeneration, logBytes(lines), 1, "/repo"), `"schema_version":3`, `"schema_version":4`, 1)
+ writeSession(t, root, testSessionID, lines, manifest)
+
+ if _, err := ReadManifest(filepath.Join(root, testSessionID, ManifestFileName)); err == nil {
+ t.Fatal("a manifest from an unknown schema version was accepted")
+ }
+
+ store := &Store{Dir: root}
+ refs, _ := store.List()
+ if refs[0].Manifest != nil {
+ t.Error("List attached an unreadable manifest")
+ }
+ events, _, err := store.Read(refs[0])
+ if err != nil || len(events) != 1 {
+ t.Fatalf("Read fell over on a session with an unreadable manifest: %d events, err %v", len(events), err)
+ }
+}
+
+func TestReadManifestRefusesAnOversizedFile(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, ManifestFileName)
+ if err := os.WriteFile(path, make([]byte, MaxManifestBytes+1), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := ReadManifest(path); err == nil {
+ t.Fatal("an oversized manifest was read")
+ }
+}
+
+func TestReadManifestRejectsANegativeWatermark(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, ManifestFileName)
+ manifest := strings.Replace(manifestJSON(testGeneration, 0, 1, "/repo"), `"event_log_bytes":0`, `"event_log_bytes":-1`, 1)
+ if err := os.WriteFile(path, []byte(manifest), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := ReadManifest(path); err == nil {
+ t.Fatal("a negative event_log_bytes was accepted")
+ }
+}
+
+func TestNewStoreDefaultsToFxProfileWhenNoDirectoryIsGiven(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+
+ store, err := NewStore("")
+ if err != nil {
+ t.Fatalf("NewStore: %v", err)
+ }
+ if want := filepath.Join(home, ".fx", "sessions"); store.Dir != want {
+ t.Errorf("store.Dir = %q, want %q", store.Dir, want)
+ }
+
+ explicit, err := NewStore("/somewhere/else")
+ if err != nil {
+ t.Fatalf("NewStore: %v", err)
+ }
+ if explicit.Dir != "/somewhere/else" {
+ t.Errorf("store.Dir = %q, want the caller's directory", explicit.Dir)
+ }
+}
+
+// timeFromMillis is a test helper rather than an import so the ordering test can stamp file times
+// without pulling a time dependency into the package's own code.
+func timeFromMillis(ms int64) time.Time { return time.UnixMilli(ms) }
diff --git a/cli/beacon/internal/fxsession/types.go b/cli/beacon/internal/fxsession/types.go
new file mode 100644
index 00000000..975c83a4
--- /dev/null
+++ b/cli/beacon/internal/fxsession/types.go
@@ -0,0 +1,434 @@
+// Package fxsession reads the session store that fx (vercel-labs/fx) keeps on disk and turns it
+// into Beacon endpoint telemetry.
+//
+// fx is the one supported runtime with no third-party observation surface at all. Its lifecycle
+// hooks are Zig handlers compiled into the binary rather than commands a settings file can point
+// at, it ships no OpenTelemetry export, and its plugin story is MCP -- which describes tools fx
+// calls, not what fx did. What it does have is a durable, append-only record of every session:
+//
+// ~/.fx/sessions/<session-id>/
+// events.jsonl append-only event log, one JSON envelope per line
+// session.json manifest projection: the committed prefix of events.jsonl, plus metadata
+//
+// So Beacon reads that. The consequence for anyone reading the resulting events is recorded on
+// every one of them as harness.collection_method=poll: Beacon sees what a turn produced once the
+// turn was committed, not the agent as it works. A pre-tool hook can hold a tool call; this cannot.
+//
+// This file declares the decoded shape of fx's records. The field names and enum spellings come
+// from fx's own writers (src/core/session/session_codec.zig and session_event.zig), which encode
+// JSON by hand rather than through a schema, so every name here was read off the writer that
+// produces it rather than inferred from the reader that consumes it.
+package fxsession
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "unicode/utf8"
+)
+
+// Event kinds fx writes into events.jsonl. The list is fx's complete Kind enum; Beacon decodes the
+// payload of the ones it maps and skips the rest by name rather than by absence, so a kind fx adds
+// later is skipped as unknown rather than mistaken for one of these.
+const (
+ KindSessionStarted = "session_started"
+ KindPreferencesChanged = "preferences_changed"
+ KindWorkspaceRebound = "workspace_rebound"
+ KindHistoryTurnCommitted = "history_turn_committed"
+ KindUsageCheckpointed = "usage_checkpointed"
+ KindRecoveryCheckpointSet = "recovery_checkpoint_set"
+ KindRecoveryCheckpointClear = "recovery_checkpoint_cleared"
+ KindStateReplacementStarted = "state_replacement_started"
+ KindStateReplacementChunk = "state_replacement_chunk"
+ KindStateReplacementCommited = "state_replacement_committed"
+)
+
+// SupportedSchemaVersion is the only events.jsonl envelope version fx writes, and the only one this
+// decoder accepts. fx itself rejects any other value rather than reading it leniently; Beacon skips
+// the line for the same reason, since a version bump means the fields below moved.
+const SupportedSchemaVersion = 1
+
+// Turn kinds. fx commits four shapes of history turn, and which one a turn is decides what is
+// present: only `assistant` and `background_command` carry a full execution record, `interrupted`
+// carries the tool call that was in flight when the user stopped it, and `compacted_summary` is
+// fx's own summary of turns it dropped rather than a turn the user ran.
+const (
+ TurnKindAssistant = "assistant"
+ TurnKindBackgroundCmd = "background_command"
+ TurnKindInterrupted = "interrupted"
+ TurnKindCompactedSummary = "compacted_summary"
+)
+
+// Tool result statuses (fx's PersistedToolStatus).
+const (
+ ToolStatusSuccess = "success"
+ ToolStatusFailure = "failure"
+)
+
+// File actions fx attributes to a tool call (fx's FileEvidenceAction).
+const (
+ FileActionRead = "read"
+ FileActionWrite = "write"
+ FileActionEdit = "edit"
+ FileActionDelete = "delete"
+ FileActionRename = "rename"
+ FileActionCopy = "copy"
+ FileActionSearch = "search"
+ FileActionList = "list"
+ FileActionUnknown = "unknown"
+)
+
+// Process outcome kinds fx records for a command (fx's CommandProcessPresentation). `value` carries
+// the exit status or signal number for the first two and is null for the others.
+const (
+ ProcessExitCode = "exit_code"
+ ProcessSignal = "signal"
+ ProcessTimedOut = "timed_out"
+ ProcessOutputCaptureFailed = "output_capture_failed"
+)
+
+// Envelope is one line of events.jsonl: fx's frame around a payload.
+//
+// Seq is monotonic within LogGeneration and restarts when fx compacts the log, which is why the
+// collector's cursor stores both. Payload stays raw so a caller can decode only the kinds it maps.
+type Envelope struct {
+ SchemaVersion int `json:"schema_version"`
+ LogGeneration string `json:"log_generation"`
+ Seq uint64 `json:"seq"`
+ EventID string `json:"event_id"`
+ TimestampMS int64 `json:"timestamp_ms"`
+ Kind string `json:"kind"`
+ Payload json.RawMessage `json:"payload"`
+}
+
+// Event is a decoded envelope. Exactly one of the payload pointers is set for a kind Beacon maps;
+// all of them are nil for a kind it skips, which is why Kind is kept on the struct rather than
+// implied by which pointer is non-nil.
+type Event struct {
+ Envelope
+ SessionStarted *SessionStarted
+ PreferencesChanged *Preferences
+ WorkspaceRebound *WorkspaceRebound
+ TurnCommitted *TurnCommitted
+ UsageCheckpointed *UsageSnapshot
+}
+
+// SessionStarted is fx's first event in a log. It also reappears as seq 1 of a *new* generation
+// after fx compacts the log, so a collector that emits a Beacon session.started for every one of
+// these emits a second start for a session that never restarted. See the cursor in collect.go.
+type SessionStarted struct {
+ ID string `json:"id"`
+ CreatedAtMS int64 `json:"created_at_ms"`
+ OriginWorkspaceRoot DurableString `json:"origin_workspace_root"`
+ WorkspaceRoot DurableString `json:"workspace_root"`
+ ConversationLang string `json:"conversation_language"`
+ Preferences *Preferences `json:"preferences"`
+ Usage *UsageSnapshot `json:"usage"`
+}
+
+// Preferences is the model configuration in force: fx's provider (gateway, codex, grok), the model
+// id as that provider names it, the reasoning effort, and whether fast mode is on.
+type Preferences struct {
+ Provider string `json:"provider"`
+ Model string `json:"model"`
+ Effort string `json:"effort"`
+ FastMode *bool `json:"fast_mode"`
+}
+
+// WorkspaceRebound is fx resuming a session in a different directory. Sessions are global in fx and
+// portable across workspaces, so the working directory of a session is not fixed for its lifetime.
+type WorkspaceRebound struct {
+ PreviousWorkspaceRoot DurableString `json:"previous_workspace_root"`
+ WorkspaceRoot DurableString `json:"workspace_root"`
+}
+
+// TurnCommitted is fx's record of one completed turn: the prompt, everything the agent did, and the
+// session's running token totals at that point.
+//
+// TotalInput/TotalOutputTokens are cumulative for the session, not for this turn. Per-turn tokens
+// live in Turn.Execution.TurnSummary.TokenProgress, and mixing the two up would report a session's
+// entire history as the cost of its last turn.
+type TurnCommitted struct {
+ ConversationLang string `json:"conversation_language"`
+ TotalInputTokens uint64 `json:"total_input_tokens"`
+ TotalOutputTokens uint64 `json:"total_output_tokens"`
+ WorkID string `json:"work_id"`
+ Turn Turn `json:"turn"`
+}
+
+// Turn is one entry of fx's conversation history. The four kinds share a user prompt and diverge
+// after it; see the TurnKind constants.
+type Turn struct {
+ Kind string `json:"kind"`
+ User *UserTurn `json:"user"`
+ Assistant *string `json:"assistant"`
+ Execution *Execution `json:"execution"`
+
+ // background_command
+ LogPath DurableString `json:"log_path"`
+ ExpectURL bool `json:"expect_url"`
+ URL *string `json:"url"`
+
+ // interrupted
+ ToolCall *ToolCall `json:"tool_call"`
+ CompletedToolNames []string `json:"completed_tool_names"`
+ TerminalReason string `json:"terminal_reason"`
+
+ // compacted_summary
+ Summary DurableString `json:"summary"`
+ RemovedTurnCount int `json:"removed_turn_count"`
+ CompactionCount int `json:"compaction_count"`
+}
+
+// UserTurn is the prompt as the user submitted it, plus any images attached to it.
+type UserTurn struct {
+ Text DurableString `json:"text"`
+ Images []UserImage `json:"images"`
+ WorkID string `json:"work_id"`
+}
+
+// UserImage is one attachment. Beacon records the path and media type, never the bytes: the image
+// itself is a file on the machine, and copying it into a log line would put unbounded binary
+// content into a stream meant to be greppable.
+type UserImage struct {
+ ID int64 `json:"id"`
+ Path DurableString `json:"path"`
+ MediaType DurableString `json:"media_type"`
+}
+
+// Execution is what the agent did during a turn: the model/tool steps it took, the files it
+// touched, and how long the turn ran.
+type Execution struct {
+ SchemaVersion int `json:"schema_version"`
+ ToolSteps []ToolStep `json:"tool_steps"`
+ Files []FileRecord `json:"files"`
+ TurnSummary *TurnSummary `json:"turn_summary"`
+}
+
+// ToolStep is one model step: the assistant text that preceded the calls, the calls it made, and
+// their results. Calls and results are separate lists linked by tool call id, and a call can be
+// present with no result when the turn ended before it completed.
+type ToolStep struct {
+ Assistant *string `json:"assistant"`
+ ToolCalls []ToolCall `json:"tool_calls"`
+ ToolResults []ToolResult `json:"tool_results"`
+}
+
+// ToolCall is one tool invocation as the model requested it. ID is fx's own identifier for the
+// call, which is what links it to its result and is what Beacon promotes to gen_ai.tool.call.id.
+type ToolCall struct {
+ ID DurableString `json:"id"`
+ Name DurableString `json:"name"`
+ ArgumentsJSON DurableString `json:"arguments_json"`
+ ProviderResult *string `json:"provider_result"`
+}
+
+// ToolResult is the outcome fx persisted for one call.
+//
+// Output is what fx stored, which is not always what the tool produced: OutputBytes is the true
+// size, StoredOutputBytes is what survived fx's own limit, and Truncated says the two differ. All
+// three are carried through to Beacon rather than collapsed, because a reader who cannot tell a
+// short output from a truncated one cannot tell what the agent actually saw.
+type ToolResult struct {
+ ToolCallID DurableString `json:"tool_call_id"`
+ ToolName DurableString `json:"tool_name"`
+ Status string `json:"status"`
+ Output DurableString `json:"output"`
+ OutputHandle *string `json:"output_handle"`
+ Preview *string `json:"preview"`
+ OutputBytes int64 `json:"output_bytes"`
+ StoredOutputBytes int64 `json:"stored_output_bytes"`
+ Truncated bool `json:"truncated"`
+ ProviderNative bool `json:"provider_native"`
+ CreatedAtMS int64 `json:"created_at_ms"`
+ PermissionFeedback []DurableString `json:"permission_feedback"`
+ CommittedFile *CommittedFile `json:"committed_file_presentation"`
+ CommandProcess *ProcessOutcome `json:"command_process_presentation"`
+ TerminalAction *TerminalOutcome `json:"terminal_action_presentation"`
+}
+
+// CommittedFile is the diff fx committed for a write or edit: the path, whether the file was added
+// or edited, the unified-diff lines, and the line counts.
+type CommittedFile struct {
+ Path DurableString `json:"path"`
+ Kind string `json:"kind"`
+ Lines []DiffLine `json:"lines"`
+ Additions int `json:"additions"`
+ Deletions int `json:"deletions"`
+ Truncated bool `json:"truncated"`
+ LifecycleD *Lifecycle `json:"lifecycle_id"`
+}
+
+// DiffLine is one line of fx's committed diff. Kind is context, addition, deletion, elision, or
+// notice -- the last two are fx's own markers for omitted regions, not file content.
+type DiffLine struct {
+ Kind string `json:"kind"`
+ OldLine *int `json:"old_line"`
+ NewLine *int `json:"new_line"`
+ Text DurableString `json:"text"`
+}
+
+// Lifecycle ties a committed file back to the turn and tool call that produced it.
+type Lifecycle struct {
+ TurnID int64 `json:"turn_id"`
+ CallID DurableString `json:"call_id"`
+}
+
+// ProcessOutcome is how a command ended: an exit code, a signal, a timeout, or a failure to capture
+// its output. Value is null for the last two, which is why it is a pointer.
+type ProcessOutcome struct {
+ Kind string `json:"kind"`
+ Value *int `json:"value"`
+}
+
+// TerminalOutcome is how a durable terminal action ended. fx uses durable terminal sessions for
+// long-lived work (servers, watchers), where "the command exited" is one outcome among several.
+type TerminalOutcome struct {
+ Kind string `json:"kind"`
+ Code string `json:"code"`
+ Outcome *TerminalReturns `json:"outcome"`
+}
+
+// TerminalReturns is the nested outcome of a returned terminal action: started, condition_met,
+// safety_ceiling, cancelled, exited (with a code), or signal (with a number).
+type TerminalReturns struct {
+ Kind string `json:"kind"`
+ Value *int `json:"value"`
+}
+
+// FileRecord is fx's per-turn evidence that a tool touched a file: which file, which call, what it
+// did, and whether it succeeded. It exists alongside CommittedFile because not every file action
+// produces a diff -- a read, a delete, or a failed write all leave a record here and nothing there.
+type FileRecord struct {
+ Path DurableString `json:"path"`
+ NewPath *string `json:"new_path"`
+ ToolCallID DurableString `json:"tool_call_id"`
+ ToolName DurableString `json:"tool_name"`
+ Action string `json:"action"`
+ Status string `json:"status"`
+ FullFileSeen bool `json:"model_view_covers_full_file"`
+ Stale bool `json:"stale"`
+}
+
+// TurnSummary is fx's timing and token accounting for one turn.
+//
+// InputExact/OutputExact matter: when a provider does not return usage, fx estimates the counts and
+// says so here. Beacon carries the flags through rather than presenting an estimate as a measured
+// number.
+type TurnSummary struct {
+ StartedAtMS int64 `json:"started_at_ms"`
+ CompletedAtMS int64 `json:"completed_at_ms"`
+ ThinkingDurationMS int64 `json:"thinking_duration_ms"`
+ TurnDurationMS int64 `json:"turn_duration_ms"`
+ TokenProgress TokenProgress `json:"token_progress"`
+}
+
+// TokenProgress is one turn's token counts. Unlike TurnCommitted's totals, these are per turn.
+type TokenProgress struct {
+ InputTokens int64 `json:"input_tokens"`
+ OutputTokens int64 `json:"output_tokens"`
+ InputExact bool `json:"input_exact"`
+ OutputExact bool `json:"output_exact"`
+}
+
+// UsageSnapshot is fx's cumulative usage for a session: tokens, cost, and per-model breakdown.
+//
+// Cumulative is the word that matters. Every checkpoint replaces the previous one rather than
+// adding to it, so emitting a snapshot's numbers as an event's gen_ai.usage would count a session's
+// whole history once per checkpoint in any rollup that sums events. The collector emits the
+// difference between consecutive snapshots instead; see usageDelta in mapper.go.
+type UsageSnapshot struct {
+ Billing string `json:"billing"`
+ APIDurationMS int64 `json:"api_duration_ms"`
+ WallDurationMS int64 `json:"wall_duration_ms"`
+ TotalCost float64 `json:"total_cost"`
+ InputTokens int64 `json:"input_tokens"`
+ OutputTokens int64 `json:"output_tokens"`
+ CacheReadTokens int64 `json:"cache_read_tokens"`
+ CacheWriteTokens int64 `json:"cache_write_tokens"`
+ BillableWebSearchCalls int64 `json:"billable_web_search_calls"`
+ LinesAdded int64 `json:"lines_added"`
+ LinesRemoved int64 `json:"lines_removed"`
+ Models []ModelUsage `json:"models"`
+}
+
+// ModelUsage is one model's share of a usage snapshot.
+type ModelUsage struct {
+ Model string `json:"model"`
+ TotalCost float64 `json:"total_cost"`
+ InputTokens int64 `json:"input_tokens"`
+ OutputTokens int64 `json:"output_tokens"`
+ CacheReadTokens int64 `json:"cache_read_tokens"`
+ CacheWriteTokens int64 `json:"cache_write_tokens"`
+ ReasoningTokens *int64 `json:"reasoning_tokens"`
+}
+
+// DurableString is a string field in fx's session records, which is either a JSON string or, when
+// the bytes are not valid UTF-8, the object {"encoding":"base64","data":"..."}.
+//
+// fx writes every user-supplied byte sequence this way -- a path, a prompt, a tool's output, a diff
+// line -- because those bytes come from a filesystem and a terminal, neither of which promises
+// UTF-8. A decoder that assumed a plain string would fail on exactly the sessions worth looking at:
+// the one that read a binary file or ran a command that emitted a stray 0x80.
+//
+// The decoded bytes are kept as-is rather than being re-encoded or rejected. Go strings hold
+// arbitrary bytes, and the JSON encoder that writes the Beacon event substitutes U+FFFD for
+// anything invalid at that point -- so the invalid byte is visible as a replacement character in
+// the log instead of failing the line or silently dropping the field.
+type DurableString string
+
+func (s DurableString) String() string { return string(s) }
+
+// UnmarshalJSON accepts both of fx's encodings. A null decodes to the empty string, which is what
+// the optional fields (an absent url, a nil assistant) mean.
+func (s *DurableString) UnmarshalJSON(data []byte) error {
+ if len(data) == 0 || string(data) == "null" {
+ *s = ""
+ return nil
+ }
+ if data[0] == '"' {
+ var text string
+ if err := json.Unmarshal(data, &text); err != nil {
+ return err
+ }
+ *s = DurableString(text)
+ return nil
+ }
+ var wrapper struct {
+ Encoding string `json:"encoding"`
+ Data string `json:"data"`
+ }
+ if err := json.Unmarshal(data, &wrapper); err != nil {
+ return fmt.Errorf("fx durable string: %w", err)
+ }
+ if wrapper.Encoding != "base64" {
+ return fmt.Errorf("fx durable string: unsupported encoding %q", wrapper.Encoding)
+ }
+ decoded, err := base64.StdEncoding.DecodeString(wrapper.Data)
+ if err != nil {
+ return fmt.Errorf("fx durable string: %w", err)
+ }
+ // fx only uses the base64 form for bytes that are not valid UTF-8, and rejects a base64 payload
+ // that decodes to valid UTF-8 as a malformed record. Beacon accepts it rather than failing the
+ // line: the bytes are unambiguous either way, and refusing them would drop a whole turn over a
+ // disagreement about how it was spelled.
+ *s = DurableString(decoded)
+ return nil
+}
+
+// MarshalJSON round-trips through the same two forms, so a decoded record re-encodes to something
+// fx would accept. Tests use it; nothing in the collector writes fx records back.
+func (s DurableString) MarshalJSON() ([]byte, error) {
+ if utf8.ValidString(string(s)) {
+ return json.Marshal(string(s))
+ }
+ return json.Marshal(struct {
+ Encoding string `json:"encoding"`
+ Data string `json:"data"`
+ }{Encoding: "base64", Data: base64.StdEncoding.EncodeToString([]byte(s))})
+}
+
+// ErrUnsupportedSchema is returned for an envelope whose schema_version is not the one this
+// decoder understands. Callers skip the line; see Decoder.Next.
+var ErrUnsupportedSchema = errors.New("unsupported fx event schema version")