The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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")