Skip to content

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

feat(fx): map fx session records onto Beacon endpoint events

Claude16f481bfd447
diff --git a/cli/beacon/internal/fxsession/mapper.go b/cli/beacon/internal/fxsession/mapper.go
new file mode 100644
index 00000000..c12bb233
--- /dev/null
+++ b/cli/beacon/internal/fxsession/mapper.go
@@ -0,0 +1,849 @@
+package fxsession
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "path/filepath"
+ "strings"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// Harness is the canonical harness name on every event this package produces. It matches what
+// NormalizeHarnessName resolves every fx spelling to, so a query grouping by harness.name sees one
+// runtime rather than two.
+const Harness = "vercel_fx"
+
+// fx's own command tools. Both run operating-system processes; `run_command` is the foreground form
+// with a deadline and `terminal` is the durable session form fx uses for servers and watchers.
+const (
+ ToolRunCommand = "run_command"
+ ToolTerminal = "terminal"
+)
+
+// fx's built-in MCP control tools. They start with the same `mcp_` prefix fx gives to tools it
+// imports from an MCP server, and they are not calls to a server: they search the catalog, select a
+// tool, and report server features. Excluding them by name is what keeps the prefix a reliable
+// signal for "this call went to an external MCP server".
+var fxMCPControlTools = map[string]bool{
+ "mcp_search_tools": true,
+ "mcp_select_tool": true,
+ "mcp_features": true,
+}
+
+// MappedEvent pairs a Beacon event with the id that makes re-reading fx's log idempotent.
+//
+// The id is derived from the record's own coordinates -- session, log generation, sequence, and the
+// position within the turn -- rather than from the event's content, so the same fx record maps to
+// the same id on every sweep no matter how many times the log is read.
+type MappedEvent struct {
+ DedupID string
+ Event schema.Event
+}
+
+// MapOptions controls one mapping pass over a session's decoded log.
+type MapOptions struct {
+ // MinSeq is the last sequence already collected. Events at or below it still contribute to
+ // the mapper's running state -- the model in force, the workspace, the last usage snapshot --
+ // but produce no output. Re-deriving that state from the log each sweep, rather than storing
+ // it in the cursor, is what keeps a resumed sweep and a first sweep produce identical events.
+ MinSeq uint64
+ // SkipSessionStarted suppresses the session.started event. fx writes a fresh session_started
+ // at sequence 1 of every log generation, including the one it creates when it compacts a log,
+ // so a session that has already been reported as started must not be reported again.
+ SkipSessionStarted bool
+}
+
+// MapSession converts one session's decoded events into Beacon endpoint events, in log order.
+//
+// Everything here is written as an after-the-fact reading: harness.collection_method is `poll` on
+// every event, because Beacon read a committed record rather than observing the agent as it worked.
+// What that costs is worth stating plainly -- no approval can be held, no tool call can be blocked,
+// and nothing appears in the log until fx commits the turn.
+//
+// What it does not cost is fidelity about what happened. fx's record names the tool, the call id,
+// the file, the action, the exit code, and the diff, so almost every event here is
+// event.fidelity=observed. The exceptions are marked individually.
+func MapSession(ref SessionRef, events []Event, opts MapOptions) []MappedEvent {
+ m := &mapper{ref: ref, opts: opts}
+ if ref.Manifest != nil {
+ m.workspace = ref.Manifest.WorkspaceRoot
+ if ref.Manifest.Preferences != nil {
+ m.applyPreferences(ref.Manifest.Preferences)
+ }
+ }
+ for i := range events {
+ m.consume(&events[i])
+ }
+ return m.out
+}
+
+type mapper struct {
+ ref SessionRef
+ opts MapOptions
+ out []MappedEvent
+
+ workspace string
+ model string
+ provider string
+
+ // lastUsage is the previous cumulative usage snapshot, kept so a checkpoint can be emitted as
+ // the difference from the one before it. See usageEvent.
+ lastUsage *UsageSnapshot
+ // turnIndex counts committed turns, so a dedup id can name which turn an event came from even
+ // though fx numbers turns only within its own history.
+ turnIndex int
+}
+
+func (m *mapper) consume(event *Event) {
+ emit := event.Seq > m.opts.MinSeq
+ switch event.Kind {
+ case KindSessionStarted:
+ if event.SessionStarted == nil {
+ return
+ }
+ if root := event.SessionStarted.WorkspaceRoot.String(); root != "" {
+ m.workspace = root
+ }
+ m.applyPreferences(event.SessionStarted.Preferences)
+ // A session_started can carry the usage the session resumed with. Seeding the delta
+ // baseline from it stops the first checkpoint after a resume from being reported as if
+ // the whole prior session had happened just then.
+ if event.SessionStarted.Usage != nil {
+ m.lastUsage = event.SessionStarted.Usage
+ }
+ if emit && !m.opts.SkipSessionStarted {
+ m.emitSessionStarted(event)
+ }
+ case KindPreferencesChanged:
+ m.applyPreferences(event.PreferencesChanged)
+ if emit {
+ m.emitSessionContext(event, "preferences_changed", "fx session preferences changed")
+ }
+ case KindWorkspaceRebound:
+ if event.WorkspaceRebound != nil {
+ if root := event.WorkspaceRebound.WorkspaceRoot.String(); root != "" {
+ m.workspace = root
+ }
+ }
+ if emit {
+ m.emitSessionContext(event, "workspace_rebound", "fx session rebound to a new workspace")
+ }
+ case KindHistoryTurnCommitted:
+ if event.TurnCommitted == nil {
+ return
+ }
+ m.turnIndex++
+ if emit {
+ m.emitTurn(event)
+ }
+ case KindUsageCheckpointed:
+ if event.UsageCheckpointed == nil {
+ return
+ }
+ if emit {
+ m.emitUsage(event)
+ }
+ m.lastUsage = event.UsageCheckpointed
+ }
+}
+
+func (m *mapper) applyPreferences(prefs *Preferences) {
+ if prefs == nil {
+ return
+ }
+ if prefs.Model != "" {
+ m.model = prefs.Model
+ }
+ if prefs.Provider != "" {
+ m.provider = prefs.Provider
+ }
+}
+
+// base builds the event every fx record shares: the harness, the poll provenance, the local origin,
+// the session and its workspace, and the model in force at that point in the log.
+func (m *mapper) base(event *Event, action, category string, severity schema.Severity, fidelity, message string) schema.Event {
+ ev := schema.NewEvent(schema.NewEventOptions{
+ Action: action,
+ Category: category,
+ Severity: severity,
+ Fidelity: fidelity,
+ Message: message,
+ Origin: schema.OriginLocal,
+ Harness: schema.HarnessInfo{
+ Name: Harness,
+ // Poll, not hook: fx exposes no hook a third party can install and no OTLP export,
+ // so Beacon reads the session record fx committed. Recording that here is what keeps
+ // a consumer from reading these events as hook-grade coverage.
+ CollectionMethod: schema.CollectionMethodPoll,
+ },
+ })
+ if event.TimestampMS > 0 {
+ ev.Timestamp = schema.FormatTimestamp(millis(event.TimestampMS))
+ }
+ ev.Session = &schema.SessionInfo{ID: m.sessionID(), WorkingDirectory: m.workspace}
+ if m.model != "" {
+ ev.Model = m.model
+ }
+ if m.provider != "" {
+ ev.GenAI = &schema.GenAIInfo{Provider: &schema.GenAIProviderInfo{Name: m.provider}}
+ }
+ return ev
+}
+
+func (m *mapper) sessionID() string {
+ if m.ref.ID != "" {
+ return m.ref.ID
+ }
+ if m.ref.Manifest != nil {
+ return m.ref.Manifest.ID
+ }
+ return ""
+}
+
+func (m *mapper) emitSessionStarted(event *Event) {
+ started := event.SessionStarted
+ ev := m.base(event, "session.started", "session", schema.SeverityInfo, schema.FidelityObserved, "fx session started")
+ if started.CreatedAtMS > 0 {
+ ev.Timestamp = schema.FormatTimestamp(millis(started.CreatedAtMS))
+ }
+ raw := map[string]interface{}{
+ "session_id": started.ID,
+ "workspace_root": started.WorkspaceRoot.String(),
+ "origin_workspace_root": started.OriginWorkspaceRoot.String(),
+ "conversation_language": started.ConversationLang,
+ }
+ if started.Preferences != nil {
+ raw["effort"] = started.Preferences.Effort
+ if started.Preferences.FastMode != nil {
+ raw["fast_mode"] = *started.Preferences.FastMode
+ }
+ }
+ ev.Raw = map[string]interface{}{"fx": raw}
+ m.append(event, "session.started", ev)
+}
+
+// emitSessionContext records a change to the session's configuration -- the model or provider in
+// force, or the workspace it is bound to.
+//
+// session.context is the action the Codex integration already uses for "session metadata
+// observed", so an fx model switch lands in the same place a reader already looks rather than
+// under a new verb only fx produces.
+func (m *mapper) emitSessionContext(event *Event, change, message string) {
+ ev := m.base(event, "session.context", "session", schema.SeverityInfo, schema.FidelityObserved, message)
+ raw := map[string]interface{}{"change": change}
+ if event.PreferencesChanged != nil {
+ raw["provider"] = event.PreferencesChanged.Provider
+ raw["model"] = event.PreferencesChanged.Model
+ raw["effort"] = event.PreferencesChanged.Effort
+ if event.PreferencesChanged.FastMode != nil {
+ raw["fast_mode"] = *event.PreferencesChanged.FastMode
+ }
+ }
+ if event.WorkspaceRebound != nil {
+ raw["previous_workspace_root"] = event.WorkspaceRebound.PreviousWorkspaceRoot.String()
+ raw["workspace_root"] = event.WorkspaceRebound.WorkspaceRoot.String()
+ }
+ ev.Raw = map[string]interface{}{"fx": raw}
+ m.append(event, change, ev)
+}
+
+// emitTurn expands one committed turn into the events it justifies: the prompt, one event per tool
+// call, the assistant's reply, and the turn's token usage.
+func (m *mapper) emitTurn(event *Event) {
+ turn := event.TurnCommitted.Turn
+ if turn.User != nil {
+ if text := turn.User.Text.String(); text != "" {
+ m.emitPrompt(event, text, turn.User.Images)
+ }
+ }
+ if turn.Execution != nil {
+ for stepIndex, step := range turn.Execution.ToolSteps {
+ m.emitStep(event, turn, stepIndex, step)
+ }
+ }
+ // The tool call that was in flight when the user interrupted the turn has no result and sits
+ // outside the steps. Without this it would be the one action fx recorded that Beacon dropped --
+ // and an interrupted call is more interesting than a completed one, not less.
+ if turn.Kind == TurnKindInterrupted && turn.ToolCall != nil {
+ m.emitToolCallWithoutResult(event, *turn.ToolCall, "interrupted", -1, 0)
+ }
+ if turn.Assistant != nil && strings.TrimSpace(*turn.Assistant) != "" {
+ m.emitAssistantMessage(event, *turn.Assistant)
+ }
+ if turn.Kind == TurnKindCompactedSummary {
+ m.emitCompaction(event, turn)
+ }
+ m.emitTurnUsage(event, turn)
+}
+
+func (m *mapper) emitPrompt(event *Event, text string, images []UserImage) {
+ ev := m.base(event, "prompt.submitted", "prompt", schema.SeverityInfo, schema.FidelityObserved, "fx prompt submitted")
+ if summary := event.TurnCommitted.Turn.Execution; summary != nil && summary.TurnSummary != nil && summary.TurnSummary.StartedAtMS > 0 {
+ // The envelope is stamped when fx commits the turn, which is after the model has finished.
+ // The prompt happened when the turn started, and using the commit time for it would put
+ // every prompt after the tool calls it caused.
+ ev.Timestamp = schema.FormatTimestamp(millis(summary.TurnSummary.StartedAtMS))
+ }
+ ev.Prompt = &schema.PromptInfo{Text: text}
+ ev.Content = asymptoteobserve.RetainedContent(text, asymptoteobserve.DefaultStringLimit)
+ ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) {
+ genAI.Input = &schema.GenAIInputInfo{Messages: asymptoteobserve.TextInputMessages(text)}
+ })
+ if len(images) > 0 {
+ paths := make([]interface{}, 0, len(images))
+ for _, image := range images {
+ paths = append(paths, map[string]interface{}{
+ "path": image.Path.String(),
+ "media_type": image.MediaType.String(),
+ })
+ }
+ // Paths and media types, never the bytes: the image is a file on this machine, and copying
+ // it into a log line would put unbounded binary content into a stream meant to be read.
+ ev.Raw = mergeRaw(ev.Raw, map[string]interface{}{"images": paths})
+ }
+ m.append(event, fmt.Sprintf("turn.%d.prompt", m.turnIndex), ev)
+}
+
+func (m *mapper) emitAssistantMessage(event *Event, text string) {
+ ev := m.base(event, "agent.message", "session", schema.SeverityInfo, schema.FidelityObserved, "fx agent message")
+ ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) {
+ genAI.Output = &schema.GenAIOutputInfo{Messages: asymptoteobserve.TextOutputMessages(text)}
+ })
+ // gen_ai is sanitized at the raw string limit rather than the prompt limit, so the content
+ // marker has to describe that limit or it claims something about text nobody stored.
+ ev.Content = asymptoteobserve.RetainedContent(text, asymptoteobserve.DefaultRawStringLimit)
+ m.append(event, fmt.Sprintf("turn.%d.assistant", m.turnIndex), ev)
+}
+
+// emitCompaction records that fx dropped turns from its own history to reclaim context.
+//
+// Worth an event rather than a silent state change: the summary is what the model can still see of
+// the work it did, so a reader reconstructing a session needs to know where the record thins out.
+func (m *mapper) emitCompaction(event *Event, turn Turn) {
+ ev := m.base(event, "session.compacting", "session", schema.SeverityInfo, schema.FidelityObserved, "fx compacted session history")
+ ev.Raw = mergeRaw(ev.Raw, map[string]interface{}{
+ "removed_turn_count": turn.RemovedTurnCount,
+ "compaction_count": turn.CompactionCount,
+ "summary": turn.Summary.String(),
+ })
+ m.append(event, fmt.Sprintf("turn.%d.compaction", m.turnIndex), ev)
+}
+
+func (m *mapper) emitStep(event *Event, turn Turn, stepIndex int, step ToolStep) {
+ results := make(map[string]*ToolResult, len(step.ToolResults))
+ for i := range step.ToolResults {
+ results[step.ToolResults[i].ToolCallID.String()] = &step.ToolResults[i]
+ }
+ for callIndex, call := range step.ToolCalls {
+ result := results[call.ID.String()]
+ if result == nil {
+ m.emitToolCallWithoutResult(event, call, "no_result", stepIndex, callIndex)
+ continue
+ }
+ m.emitToolOutcome(event, turn, stepIndex, callIndex, call, *result)
+ }
+}
+
+// emitToolCallWithoutResult records a call fx asked for and never recorded an outcome for: the turn
+// was interrupted, or the process died between the call and its result.
+//
+// tool.invoked rather than a completion verb, because that is all that is known. The alternative --
+// dropping it -- would make an interrupted dangerous call invisible, which is the opposite of what
+// an endpoint log is for.
+func (m *mapper) emitToolCallWithoutResult(event *Event, call ToolCall, reason string, stepIndex, callIndex int) {
+ name := call.Name.String()
+ ev := m.base(event, "tool.invoked", "tool", schema.SeverityInfo, schema.FidelityObserved, "fx tool invoked without a recorded result")
+ ev.Tool = &schema.ToolInfo{Name: name}
+ m.applyToolArguments(&ev, name, call)
+ ev.Raw = mergeRaw(ev.Raw, map[string]interface{}{"result_missing": reason})
+ m.append(event, fmt.Sprintf("turn.%d.step.%d.call.%d.invoked", m.turnIndex, stepIndex, callIndex), ev)
+}
+
+// emitToolOutcome maps one completed call onto the single event that best describes what it did.
+//
+// The classification order is deliberate and one part of it is worth defending: a tool's failure
+// does not change what kind of action it was. fx marks a command that exits non-zero as
+// status=failure, so classifying failure first -- which is what the Grok and Qwen hook mappers do,
+// because their payloads carry a failure event type and no structured outcome -- would file every
+// failing command as tool.failed and hide it from every rule that matches command.executed. fx
+// gives an exit code, so a command that ran and failed is still command.executed, with the exit
+// code and a failure marker on it.
+func (m *mapper) emitToolOutcome(event *Event, turn Turn, stepIndex, callIndex int, call ToolCall, result ToolResult) {
+ name := firstNonEmpty(result.ToolName.String(), call.Name.String())
+ evidence := fileEvidenceFor(turn, result.ToolCallID.String(), name)
+
+ action, category, severity, message := classifyOutcome(name, result, evidence)
+ ev := m.base(event, action, category, severity, schema.FidelityObserved, message)
+ if result.CreatedAtMS > 0 {
+ // fx timestamps each result, so the events inside one turn keep the order they happened in
+ // rather than all landing on the turn's commit time.
+ ev.Timestamp = schema.FormatTimestamp(millis(result.CreatedAtMS))
+ }
+ ev.Tool = &schema.ToolInfo{Name: name}
+ m.applyToolArguments(&ev, name, call)
+
+ switch action {
+ case "command.executed":
+ m.applyCommand(&ev, result)
+ case "file.read", "file.modified", "file.created":
+ m.applyFile(&ev, result, evidence)
+ case "mcp.tool_invoked":
+ ev.MCP = &schema.MCPInfo{Tool: name}
+ }
+
+ if result.Status == ToolStatusFailure {
+ // Carried as an error marker on whatever the action was, rather than by rerouting the
+ // action, so a failed command is still findable as a command.
+ ev.Error = &schema.ErrorInfo{Type: "tool_execution_failed"}
+ }
+ ev.Raw = mergeRaw(ev.Raw, toolResultRaw(result))
+ m.append(event, fmt.Sprintf("turn.%d.step.%d.call.%d.result", m.turnIndex, stepIndex, callIndex), ev)
+}
+
+// classifyOutcome decides which endpoint action one completed tool call is.
+func classifyOutcome(name string, result ToolResult, evidence *FileRecord) (action, category string, severity schema.Severity, message string) {
+ lower := strings.ToLower(strings.TrimSpace(name))
+ switch {
+ case isMCPServerTool(lower):
+ return "mcp.tool_invoked", "mcp", schema.SeverityInfo, "fx MCP tool invoked"
+ case lower == ToolRunCommand || lower == ToolTerminal:
+ return "command.executed", "command", schema.SeverityInfo, "fx command executed"
+ case result.CommittedFile != nil:
+ if result.CommittedFile.Kind == "added" {
+ return "file.created", "file", schema.SeverityInfo, "fx file created"
+ }
+ return "file.modified", "file", schema.SeverityInfo, "fx file modified"
+ case evidence != nil:
+ switch evidence.Action {
+ case FileActionRead, FileActionSearch, FileActionList:
+ return "file.read", "file", schema.SeverityInfo, "fx file read"
+ case FileActionWrite:
+ return "file.created", "file", schema.SeverityInfo, "fx file created"
+ case FileActionEdit, FileActionDelete, FileActionRename, FileActionCopy:
+ // A delete, a rename and a copy are all mutations of the tree, and file.modified is
+ // the action every mutation rule matches on. file.operation carries which one it was,
+ // so nothing is lost by not inventing a verb per action -- while a new verb would be
+ // invisible to the rules that exist.
+ return "file.modified", "file", schema.SeverityInfo, "fx file modified"
+ }
+ }
+ if result.Status == ToolStatusFailure {
+ return "tool.failed", "tool", schema.SeverityHigh, "fx tool failed"
+ }
+ return "tool.completed", "tool", schema.SeverityInfo, "fx tool completed"
+}
+
+// isMCPServerTool reports whether a tool name is one fx imported from an MCP server.
+//
+// fx allocates those names itself as `mcp_<server>_<tool>`, sanitizing anything outside
+// [A-Za-z0-9_-] to an underscore, truncating to 64 bytes, and appending `_2` on a collision. The
+// prefix is therefore reliable; the server name is not recoverable from it, which is why the events
+// carry mcp.tool and leave mcp.server unset rather than guessing at a split that fx's own
+// sanitization makes ambiguous.
+func isMCPServerTool(lower string) bool {
+ return strings.HasPrefix(lower, "mcp_") && !fxMCPControlTools[lower]
+}
+
+// applyToolArguments promotes fx's own identifiers and the call's arguments.
+//
+// gen_ai.tool.call.id is the field that links a call to its result, an approval to what it
+// approved, and one runtime's record to another's, so fx's call id goes there on every tool event.
+func (m *mapper) applyToolArguments(ev *schema.Event, name string, call ToolCall) {
+ arguments := decodeArguments(call.ArgumentsJSON.String())
+ callID := call.ID.String()
+ ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) {
+ genAI.Operation = &schema.GenAIOperationInfo{Name: "execute_tool"}
+ tool := &schema.GenAIToolInfo{Name: name}
+ callInfo := &schema.GenAIToolCallInfo{ID: callID}
+ if arguments != nil {
+ callInfo.Arguments = arguments
+ }
+ tool.Call = callInfo
+ genAI.Tool = tool
+ })
+ if path := stringArg(arguments, "path", "file_path", "target_path"); path != "" {
+ if ev.Tool == nil {
+ ev.Tool = &schema.ToolInfo{Name: name}
+ }
+ ev.Tool.Path = path
+ }
+ if command := stringArg(arguments, "command", "cmd"); command != "" {
+ if ev.Tool == nil {
+ ev.Tool = &schema.ToolInfo{Name: name}
+ }
+ ev.Tool.Command = command
+ }
+}
+
+// applyCommand fills the command block from fx's own process outcome.
+//
+// The exit code is fx's, not a guess: fx records the process presentation as an exit code, a
+// signal, a timeout, or a failure to capture output, and each of those means something different
+// to a reader. Only the first is an exit code, so only the first is written as one; the rest are
+// named in raw rather than flattened into a number that would read as a real status.
+func (m *mapper) applyCommand(ev *schema.Event, result ToolResult) {
+ command := ""
+ if ev.Tool != nil {
+ command = ev.Tool.Command
+ }
+ info := &schema.CommandInfo{Command: command}
+ if output := result.Output.String(); output != "" {
+ info.Output = output
+ ev.Content = asymptoteobserve.RetainedContent(output, asymptoteobserve.DefaultStringLimit)
+ }
+ if result.CommandProcess != nil && result.CommandProcess.Kind == ProcessExitCode && result.CommandProcess.Value != nil {
+ code := *result.CommandProcess.Value
+ info.ExitCode = &code
+ }
+ ev.Command = info
+}
+
+// applyFile fills the file block: the path fx attributed to the call, the operation it performed,
+// and the diff it committed.
+func (m *mapper) applyFile(ev *schema.Event, result ToolResult, evidence *FileRecord) {
+ info := &schema.FileInfo{}
+ if evidence != nil {
+ info.Path = evidence.Path.String()
+ info.Operation = fileOperation(evidence.Action)
+ }
+ if result.CommittedFile != nil {
+ if path := result.CommittedFile.Path.String(); path != "" {
+ info.Path = path
+ }
+ if info.Operation == "" {
+ if result.CommittedFile.Kind == "added" {
+ info.Operation = "create"
+ } else {
+ info.Operation = "modify"
+ }
+ }
+ if diff := unifiedDiff(result.CommittedFile); diff != "" {
+ info.Diff = diff
+ info.DiffBytes = len(diff)
+ info.DiffHash = sha256Hex(diff)
+ ev.Content = asymptoteobserve.RetainedContent(diff, asymptoteobserve.DefaultStringLimit)
+ }
+ }
+ if info.Path == "" && ev.Tool != nil {
+ info.Path = ev.Tool.Path
+ }
+ if info.Path != "" {
+ info.Language = strings.TrimPrefix(filepath.Ext(info.Path), ".")
+ }
+ ev.File = info
+}
+
+// fileOperation maps fx's file action onto the operation vocabulary the hook path already writes:
+// read, create, modify. The actions with no counterpart there keep fx's own word rather than being
+// forced into one of the three, because "delete" is not a modification a reader should have to
+// infer from an action name.
+func fileOperation(action string) string {
+ switch action {
+ case FileActionRead, FileActionSearch, FileActionList:
+ return "read"
+ case FileActionWrite:
+ return "create"
+ case FileActionEdit:
+ return "modify"
+ case FileActionDelete, FileActionRename, FileActionCopy:
+ return action
+ default:
+ return ""
+ }
+}
+
+// unifiedDiff renders fx's committed diff lines back into unified-diff text.
+//
+// fx stores the diff as structured lines rather than as text, so this is a rendering rather than a
+// pass-through. The markers are the standard ones so an existing reader -- a rule matching on
+// file.diff, a person looking at the dashboard -- sees the shape it expects. fx's own elision and
+// notice lines become `...` and a comment, since they are fx's markers for omitted regions rather
+// than file content.
+func unifiedDiff(file *CommittedFile) string {
+ if file == nil || len(file.Lines) == 0 {
+ return ""
+ }
+ var b strings.Builder
+ for _, line := range file.Lines {
+ switch line.Kind {
+ case "addition":
+ b.WriteString("+")
+ case "deletion":
+ b.WriteString("-")
+ case "context":
+ b.WriteString(" ")
+ case "elision":
+ b.WriteString("...")
+ b.WriteString("\n")
+ continue
+ default:
+ b.WriteString("# ")
+ }
+ b.WriteString(line.Text.String())
+ b.WriteString("\n")
+ }
+ return b.String()
+}
+
+// emitTurnUsage reports the turn's own token counts.
+//
+// Per-turn counts, from fx's turn summary, rather than the session totals sitting beside them in
+// the same record: Beacon's rollups sum gen_ai.usage across events, so emitting the cumulative
+// totals once per turn would count a session's whole history once per turn.
+//
+// Only input and output tokens come from here. Cost and cache tokens exist only in fx's cumulative
+// usage snapshots and are emitted from those as deltas, in fields this event leaves unset -- so the
+// two sources add up rather than overlapping.
+func (m *mapper) emitTurnUsage(event *Event, turn Turn) {
+ if turn.Execution == nil || turn.Execution.TurnSummary == nil {
+ return
+ }
+ progress := turn.Execution.TurnSummary.TokenProgress
+ if progress.InputTokens <= 0 && progress.OutputTokens <= 0 {
+ return
+ }
+ ev := m.base(event, "token.usage", "metric", schema.SeverityInfo, schema.FidelityObserved, "fx token usage")
+ usage := &schema.GenAIUsageInfo{}
+ if progress.InputTokens > 0 {
+ input := progress.InputTokens
+ usage.InputTokens = &input
+ }
+ if progress.OutputTokens > 0 {
+ output := progress.OutputTokens
+ usage.OutputTokens = &output
+ }
+ ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) { genAI.Usage = usage })
+ // fx says when a count is its own estimate rather than the provider's number. Carrying the
+ // flags is what keeps a cost report from presenting an estimate as a measurement.
+ ev.Raw = mergeRaw(ev.Raw, map[string]interface{}{
+ "input_exact": progress.InputExact,
+ "output_exact": progress.OutputExact,
+ "turn_duration_ms": turn.Execution.TurnSummary.TurnDurationMS,
+ "thinking_duration_ms": turn.Execution.TurnSummary.ThinkingDurationMS,
+ })
+ m.append(event, fmt.Sprintf("turn.%d.usage", m.turnIndex), ev)
+}
+
+// emitUsage reports a usage checkpoint as the difference from the previous one.
+//
+// fx's snapshots are cumulative replacements: each one restates the session's whole usage. Emitting
+// a snapshot's numbers directly would count everything before it again in any rollup that sums
+// events, which is every rollup Beacon has. The difference is what actually happened since the last
+// checkpoint, so that is what the event carries.
+//
+// Token counts here are the cache buckets only. The input and output tokens are already reported
+// per turn from fx's turn summaries, and reporting them again from the cumulative side would double
+// every session's totals.
+func (m *mapper) emitUsage(event *Event) {
+ current := event.UsageCheckpointed
+ usage := &schema.GenAIUsageInfo{}
+ cacheRead := delta(current.CacheReadTokens, usageField(m.lastUsage, func(s *UsageSnapshot) int64 { return s.CacheReadTokens }))
+ cacheWrite := delta(current.CacheWriteTokens, usageField(m.lastUsage, func(s *UsageSnapshot) int64 { return s.CacheWriteTokens }))
+ cost := current.TotalCost
+ if m.lastUsage != nil {
+ cost -= m.lastUsage.TotalCost
+ }
+ if cacheRead > 0 {
+ usage.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: &cacheRead}
+ }
+ if cacheWrite > 0 {
+ usage.CacheCreation = &schema.GenAIUsageCacheCreationInfo{InputTokens: &cacheWrite}
+ }
+ // Runtime-reported cost only: fx computes it from the provider's own billing, and Beacon never
+ // derives cost from a local pricing table. A negative difference means the snapshot went
+ // backwards (a restored session, a reset window), which is not a cost and is dropped.
+ if cost > 0 {
+ usage.CostUSD = &cost
+ }
+ if usage.CacheRead == nil && usage.CacheCreation == nil && usage.CostUSD == nil {
+ return
+ }
+ ev := m.base(event, "token.usage", "metric", schema.SeverityInfo, schema.FidelityObserved, "fx usage checkpoint")
+ ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) { genAI.Usage = usage })
+ raw := map[string]interface{}{
+ "billing": current.Billing,
+ "cumulative_input_tokens": current.InputTokens,
+ "cumulative_output_tokens": current.OutputTokens,
+ "cumulative_cost_usd": current.TotalCost,
+ "billable_web_search_calls": current.BillableWebSearchCalls,
+ "cumulative_lines_added": current.LinesAdded,
+ "cumulative_lines_removed": current.LinesRemoved,
+ "reported_as_delta_from_prior": m.lastUsage != nil,
+ }
+ if len(current.Models) > 0 {
+ models := make([]interface{}, 0, len(current.Models))
+ for _, model := range current.Models {
+ models = append(models, map[string]interface{}{
+ "model": model.Model,
+ "input_tokens": model.InputTokens,
+ "output_tokens": model.OutputTokens,
+ "cost_usd": model.TotalCost,
+ })
+ }
+ raw["cumulative_models"] = models
+ }
+ ev.Raw = mergeRaw(ev.Raw, raw)
+ m.append(event, fmt.Sprintf("usage.%d", event.Seq), ev)
+}
+
+func (m *mapper) append(event *Event, suffix string, ev schema.Event) {
+ m.out = append(m.out, MappedEvent{
+ DedupID: fmt.Sprintf("%s:%s:%d:%s", m.sessionID(), event.LogGeneration, event.Seq, suffix),
+ Event: ev,
+ })
+}
+
+// withGenAI edits the event's gen_ai block in place, creating it when the event has none. The
+// provider set by base() has to survive every later addition, so nothing here replaces the block.
+func (m *mapper) withGenAI(genAI *schema.GenAIInfo, edit func(*schema.GenAIInfo)) *schema.GenAIInfo {
+ if genAI == nil {
+ genAI = &schema.GenAIInfo{}
+ }
+ edit(genAI)
+ return genAI
+}
+
+// fileEvidenceFor finds fx's own record of what a call did to a file.
+//
+// Matched on the call id rather than on the tool name, because one turn can read and edit the same
+// file through different calls, and the tool name would not tell them apart.
+func fileEvidenceFor(turn Turn, callID, toolName string) *FileRecord {
+ if turn.Execution == nil || callID == "" {
+ return nil
+ }
+ for i := range turn.Execution.Files {
+ record := &turn.Execution.Files[i]
+ if record.ToolCallID.String() == callID {
+ return record
+ }
+ }
+ // A call id fx did not record file evidence for is not a file action, even when the tool's
+ // name sounds like one.
+ _ = toolName
+ return nil
+}
+
+// toolResultRaw carries fx's own accounting of the result: its status, how much output there was
+// against how much survived fx's limit, and the permission feedback a person typed at a prompt.
+func toolResultRaw(result ToolResult) map[string]interface{} {
+ raw := map[string]interface{}{
+ "status": result.Status,
+ "output_bytes": result.OutputBytes,
+ "stored_output_bytes": result.StoredOutputBytes,
+ "truncated": result.Truncated,
+ "provider_native": result.ProviderNative,
+ }
+ if result.CommandProcess != nil {
+ raw["process_outcome"] = result.CommandProcess.Kind
+ if result.CommandProcess.Value != nil {
+ raw["process_value"] = *result.CommandProcess.Value
+ }
+ }
+ if result.TerminalAction != nil {
+ raw["terminal_outcome"] = result.TerminalAction.Kind
+ if result.TerminalAction.Outcome != nil {
+ raw["terminal_result"] = result.TerminalAction.Outcome.Kind
+ }
+ }
+ if len(result.PermissionFeedback) > 0 {
+ feedback := make([]interface{}, 0, len(result.PermissionFeedback))
+ for _, item := range result.PermissionFeedback {
+ feedback = append(feedback, item.String())
+ }
+ // What a person told the agent at a permission prompt. It is evidence about a decision,
+ // not the decision itself: fx does not persist an approve/deny record per call, so Beacon
+ // records the feedback where it belongs and does not synthesize an approval event from it.
+ // Same posture as the Cline and Pi integrations, for the same reason.
+ raw["permission_feedback"] = feedback
+ }
+ if result.CommittedFile != nil {
+ raw["diff_additions"] = result.CommittedFile.Additions
+ raw["diff_deletions"] = result.CommittedFile.Deletions
+ raw["diff_truncated"] = result.CommittedFile.Truncated
+ }
+ return map[string]interface{}{"fx": raw}
+}
+
+func decodeArguments(argumentsJSON string) map[string]interface{} {
+ if strings.TrimSpace(argumentsJSON) == "" {
+ return nil
+ }
+ var out map[string]interface{}
+ if err := json.Unmarshal([]byte(argumentsJSON), &out); err != nil {
+ // A tool's arguments are whatever the model sent; fx stores them verbatim without
+ // requiring them to be a JSON object. Keeping the raw text beats dropping the field.
+ return map[string]interface{}{"raw": argumentsJSON}
+ }
+ return out
+}
+
+func stringArg(arguments map[string]interface{}, keys ...string) string {
+ for _, key := range keys {
+ if value, ok := arguments[key].(string); ok && value != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func mergeRaw(existing map[string]interface{}, fields map[string]interface{}) map[string]interface{} {
+ if len(fields) == 0 {
+ return existing
+ }
+ if existing == nil {
+ existing = map[string]interface{}{}
+ }
+ nested, ok := existing["fx"].(map[string]interface{})
+ if !ok {
+ nested = map[string]interface{}{}
+ }
+ // A caller passing a pre-nested {"fx": ...} block merges into the same place as one passing
+ // bare fields, so raw.fx stays a single object rather than nesting fx inside fx.
+ if inner, ok := fields["fx"].(map[string]interface{}); ok && len(fields) == 1 {
+ fields = inner
+ }
+ for key, value := range fields {
+ nested[key] = value
+ }
+ existing["fx"] = nested
+ return existing
+}
+
+func usageField(snapshot *UsageSnapshot, get func(*UsageSnapshot) int64) int64 {
+ if snapshot == nil {
+ return 0
+ }
+ return get(snapshot)
+}
+
+// delta is the increase between two cumulative counters. A decrease means the snapshot went
+// backwards, which is not negative usage: it is a session restored from an earlier state, and
+// reporting it as a negative would subtract from a total that describes something else.
+func delta(current, previous int64) int64 {
+ if current <= previous {
+ return 0
+ }
+ return current - previous
+}
+
+func firstNonEmpty(values ...string) string {
+ for _, value := range values {
+ if strings.TrimSpace(value) != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func sha256Hex(value string) string {
+ sum := sha256.Sum256([]byte(value))
+ return hex.EncodeToString(sum[:])
+}
+
+// millis converts fx's millisecond timestamps into the instant the event writers stamp events with.
+func millis(value int64) time.Time { return time.UnixMilli(value) }
diff --git a/cli/beacon/internal/fxsession/mapper_test.go b/cli/beacon/internal/fxsession/mapper_test.go
new file mode 100644
index 00000000..eea4fb62
--- /dev/null
+++ b/cli/beacon/internal/fxsession/mapper_test.go
@@ -0,0 +1,668 @@
+package fxsession
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// mapFixture decodes lines and maps them the way a sweep does.
+func mapFixture(t *testing.T, lines []string, opts MapOptions) []MappedEvent {
+ t.Helper()
+ events, stats := decodeAll(t, strings.Join(lines, "\n")+"\n")
+ if stats.Malformed != 0 {
+ t.Fatalf("fixture produced %d malformed lines: %v", stats.Malformed, stats.FirstError)
+ }
+ return MapSession(SessionRef{ID: testSessionID}, events, opts)
+}
+
+func actions(mapped []MappedEvent) []string {
+ out := make([]string, 0, len(mapped))
+ for _, item := range mapped {
+ out = append(out, item.Event.Event.Action)
+ }
+ return out
+}
+
+func find(t *testing.T, mapped []MappedEvent, action string) schema.Event {
+ t.Helper()
+ for _, item := range mapped {
+ if item.Event.Event.Action == action {
+ return item.Event
+ }
+ }
+ t.Fatalf("no %q event in %v", action, actions(mapped))
+ return schema.Event{}
+}
+
+func findAll(mapped []MappedEvent, action string) []schema.Event {
+ var out []schema.Event
+ for _, item := range mapped {
+ if item.Event.Event.Action == action {
+ out = append(out, item.Event)
+ }
+ }
+ return out
+}
+
+// One turn is one prompt, three tool calls, one reply, and the turn's tokens. This asserts the
+// whole shape at once, because the failure that matters here is not a wrong field on one event --
+// it is an action that silently stops being produced.
+func TestOneTurnProducesTheEventsItJustifies(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+
+ want := []string{
+ "session.started",
+ "prompt.submitted",
+ "file.read",
+ "file.modified",
+ "command.executed",
+ "agent.message",
+ "token.usage",
+ }
+ got := actions(mapped)
+ if len(got) != len(want) {
+ t.Fatalf("actions = %v, want %v", got, want)
+ }
+ for i := range want {
+ if got[i] != want[i] {
+ t.Fatalf("actions = %v, want %v", got, want)
+ }
+ }
+}
+
+// Every event has to say how Beacon came to know it. fx has no hook and no OTLP export, so the
+// answer is always poll -- and a consumer that reads these as hook-grade coverage would believe
+// Beacon could have blocked something it never saw.
+func TestEveryEventCarriesPollProvenanceAndLocalOrigin(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2), usageCheckpointLine(3, 4200, 880, 0.5)}, MapOptions{})
+ if len(mapped) == 0 {
+ t.Fatal("no events mapped")
+ }
+ for _, item := range mapped {
+ ev := item.Event
+ if ev.Harness.Name != Harness {
+ t.Errorf("%s: harness = %q, want %q", ev.Event.Action, ev.Harness.Name, Harness)
+ }
+ if ev.Harness.CollectionMethod != schema.CollectionMethodPoll {
+ t.Errorf("%s: collection_method = %q, want poll", ev.Event.Action, ev.Harness.CollectionMethod)
+ }
+ if ev.Origin != schema.OriginLocal {
+ t.Errorf("%s: origin = %q, want local", ev.Event.Action, ev.Origin)
+ }
+ if ev.Event.Fidelity == "" {
+ t.Errorf("%s: no fidelity marker", ev.Event.Action)
+ }
+ if ev.Session == nil || ev.Session.ID != testSessionID {
+ t.Errorf("%s: session = %+v, want %q", ev.Event.Action, ev.Session, testSessionID)
+ }
+ if ev.Session != nil && ev.Session.WorkingDirectory != "/repo" {
+ t.Errorf("%s: working directory = %q, want /repo", ev.Event.Action, ev.Session.WorkingDirectory)
+ }
+ }
+}
+
+// The harness name has to survive normalization unchanged, or one fx session is recorded under two
+// names by the collector and by anything that re-normalizes on read.
+func TestHarnessNameIsTheCanonicalOne(t *testing.T) {
+ if got := asymptoteobserve.NormalizeHarnessName(Harness); got != Harness {
+ t.Fatalf("NormalizeHarnessName(%q) = %q; the mapper's harness name is not canonical", Harness, got)
+ }
+ if got := asymptoteobserve.NormalizeHarnessName("fx"); got != Harness {
+ t.Fatalf("NormalizeHarnessName(\"fx\") = %q, want %q", got, Harness)
+ }
+}
+
+// Every Beacon writer runs Validate before a line reaches the log. An event that fails it is
+// dropped with an error, so a mapper that produces one produces silence.
+func TestEveryMappedEventPassesSchemaValidation(t *testing.T) {
+ mapped := mapFixture(t, []string{
+ sessionStartedLine(1, "/repo"),
+ assistantTurnLine(2),
+ usageCheckpointLine(3, 4200, 880, 0.5),
+ }, MapOptions{})
+ for _, item := range mapped {
+ if err := item.Event.Validate(); err != nil {
+ t.Errorf("%s failed validation: %v", item.Event.Event.Action, err)
+ }
+ }
+}
+
+func TestPromptCarriesTextRetentionAndSemconvMessages(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ prompt := find(t, mapped, "prompt.submitted")
+
+ if prompt.Prompt == nil || prompt.Prompt.Text != "add a health endpoint and run the tests" {
+ t.Fatalf("prompt text = %+v", prompt.Prompt)
+ }
+ if prompt.Content == nil || !prompt.Content.Included || prompt.Content.Retention != schema.ContentRetentionFull {
+ t.Fatalf("content marker = %+v", prompt.Content)
+ }
+ if prompt.Content.Bytes != len("add a health endpoint and run the tests") {
+ t.Errorf("content bytes = %d", prompt.Content.Bytes)
+ }
+ if prompt.GenAI == nil || prompt.GenAI.Input == nil {
+ t.Fatal("prompt has no gen_ai.input.messages, so the semconv readers see nothing")
+ }
+}
+
+// The prompt happened when the turn started; the envelope is stamped when fx committed the turn,
+// after the model finished. Using the commit time for the prompt would put every prompt after the
+// tool calls it caused, which is exactly backwards for anyone reading a session in order.
+func TestPromptIsTimestampedAtTurnStartNotTurnCommit(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ prompt := find(t, mapped, "prompt.submitted")
+ command := find(t, mapped, "command.executed")
+
+ if prompt.Timestamp >= command.Timestamp {
+ t.Fatalf("prompt at %s is not before the command it caused at %s", prompt.Timestamp, command.Timestamp)
+ }
+ want := schema.FormatTimestamp(millis(1770000000500))
+ if prompt.Timestamp != want {
+ t.Errorf("prompt timestamp = %s, want the turn's start %s", prompt.Timestamp, want)
+ }
+}
+
+// A command that exits non-zero is still a command that ran. fx marks it status=failure, and a
+// mapper that classified on status would file it as tool.failed -- invisible to every rule that
+// matches command.executed, which is most of the rule corpus.
+func TestFailingCommandStaysACommandEvent(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ command := find(t, mapped, "command.executed")
+
+ if command.Command == nil {
+ t.Fatal("command block missing")
+ }
+ if command.Command.Command != "npm test" {
+ t.Errorf("command = %q, want %q", command.Command.Command, "npm test")
+ }
+ if command.Command.ExitCode == nil || *command.Command.ExitCode != 1 {
+ t.Fatalf("exit code = %+v, want 1", command.Command.ExitCode)
+ }
+ if command.Command.Output != "1 test failed" {
+ t.Errorf("output = %q", command.Command.Output)
+ }
+ if command.Error == nil || command.Error.Type == "" {
+ t.Error("a failed tool call must still be marked as an error on the event")
+ }
+ if len(findAll(mapped, "tool.failed")) != 0 {
+ t.Error("the failing command was also reported as tool.failed, double-counting one action")
+ }
+}
+
+// fx records four different process outcomes and only one of them is an exit code. Writing a signal
+// or a timeout as an exit code would put a number in a field that means something else -- a rule
+// matching exit_code == 0 would match a command that was killed.
+func TestOnlyAnExitCodeIsWrittenAsAnExitCode(t *testing.T) {
+ for _, outcome := range []struct {
+ name string
+ json string
+ }{
+ {"signal", `{"kind":"signal","value":9}`},
+ {"timed_out", `{"kind":"timed_out","value":null}`},
+ {"output_capture_failed", `{"kind":"output_capture_failed","value":null}`},
+ } {
+ t.Run(outcome.name, func(t *testing.T) {
+ line := strings.Replace(assistantTurnLine(2), `{"kind":"exit_code","value":1}`, outcome.json, 1)
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), line}, MapOptions{})
+ command := find(t, mapped, "command.executed")
+ if command.Command.ExitCode != nil {
+ t.Errorf("exit code = %d for a %s outcome, want none", *command.Command.ExitCode, outcome.name)
+ }
+ raw := rawFx(t, command)
+ if raw["process_outcome"] != outcome.name {
+ t.Errorf("raw.fx.process_outcome = %v, want %q", raw["process_outcome"], outcome.name)
+ }
+ })
+ }
+}
+
+func TestEditCarriesPathOperationAndRenderedDiff(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ edit := find(t, mapped, "file.modified")
+
+ if edit.File == nil || edit.File.Path != "src/server.ts" {
+ t.Fatalf("file = %+v", edit.File)
+ }
+ if edit.File.Operation != "modify" {
+ t.Errorf("operation = %q, want modify", edit.File.Operation)
+ }
+ if edit.File.Language != "ts" {
+ t.Errorf("language = %q, want ts", edit.File.Language)
+ }
+ if !strings.Contains(edit.File.Diff, "-export function serve() {}") ||
+ !strings.Contains(edit.File.Diff, "+export function serveHealth() {}") {
+ t.Fatalf("diff does not read as a unified diff:\n%s", edit.File.Diff)
+ }
+ if edit.File.DiffBytes != len(edit.File.Diff) || edit.File.DiffHash == "" {
+ t.Errorf("diff accounting = %d bytes hash %q", edit.File.DiffBytes, edit.File.DiffHash)
+ }
+ if edit.Content == nil || !edit.Content.Included {
+ t.Error("an edit that retained a diff has no content marker")
+ }
+ raw := rawFx(t, edit)
+ if raw["diff_additions"] == nil || raw["diff_deletions"] == nil {
+ t.Errorf("raw.fx lost fx's own line counts: %v", raw)
+ }
+}
+
+// fx says which call touched which file, keyed by call id. Reading that rather than guessing from
+// the tool's name is what keeps a turn that both reads and edits the same file from reporting two
+// events of the same kind.
+func TestFileActionsComeFromFxEvidenceNotToolNames(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ if len(findAll(mapped, "file.read")) != 1 {
+ t.Fatalf("file.read events = %d, want 1", len(findAll(mapped, "file.read")))
+ }
+ read := find(t, mapped, "file.read")
+ if read.File == nil || read.File.Path != "src/server.ts" || read.File.Operation != "read" {
+ t.Fatalf("read event file block = %+v", read.File)
+ }
+ if read.File.Diff != "" {
+ t.Error("a read carries a diff, which means the edit's evidence leaked onto it")
+ }
+}
+
+// The call id is the only thing that links a call to its result, an approval to what it approved,
+// and one runtime's record of an action to another's. Every tool event carries fx's own id.
+func TestToolCallIDIsPromotedOnEveryToolEvent(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ want := map[string]string{
+ "file.read": "call_read_1",
+ "file.modified": "call_edit_1",
+ "command.executed": "call_cmd_1",
+ }
+ for action, callID := range want {
+ ev := find(t, mapped, action)
+ if ev.GenAI == nil || ev.GenAI.Tool == nil || ev.GenAI.Tool.Call == nil {
+ t.Fatalf("%s has no gen_ai.tool.call block", action)
+ }
+ if ev.GenAI.Tool.Call.ID != callID {
+ t.Errorf("%s call id = %q, want %q", action, ev.GenAI.Tool.Call.ID, callID)
+ }
+ if ev.GenAI.Tool.Call.Arguments == nil {
+ t.Errorf("%s carries no tool arguments", action)
+ }
+ }
+}
+
+// The provider fx authenticated against is part of what a session cost and where its data went, and
+// it must survive every later edit to the gen_ai block.
+func TestProviderSurvivesTheRestOfTheGenAIBlock(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ for _, item := range mapped {
+ ev := item.Event
+ if ev.GenAI == nil || ev.GenAI.Provider == nil || ev.GenAI.Provider.Name != "gateway" {
+ t.Errorf("%s: gen_ai.provider = %+v, want gateway", ev.Event.Action, ev.GenAI)
+ }
+ if ev.Model != "anthropic/claude-opus-4" {
+ t.Errorf("%s: model = %q", ev.Event.Action, ev.Model)
+ }
+ }
+}
+
+// A tool imported from an MCP server is not the same event as a local file edit, and fx's own
+// naming (`mcp_<server>_<tool>`) is what says which is which.
+func TestMCPServerToolsAreReportedAsMCPCalls(t *testing.T) {
+ line := strings.NewReplacer(
+ `"name":"read_file","arguments_json":"{\"path\":\"src/server.ts\"}"`,
+ `"name":"mcp_github_get_issue","arguments_json":"{\"issue\":42}"`,
+ `"tool_call_id":"call_read_1","tool_name":"read_file"`,
+ `"tool_call_id":"call_read_1","tool_name":"mcp_github_get_issue"`,
+ `{"path":"src/server.ts","new_path":null,"tool_call_id":"call_read_1","tool_name":"read_file","action":"read"`,
+ `{"path":"src/server.ts","new_path":null,"tool_call_id":"unrelated","tool_name":"read_file","action":"read"`,
+ ).Replace(assistantTurnLine(2))
+
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), line}, MapOptions{})
+ mcp := find(t, mapped, "mcp.tool_invoked")
+ if mcp.MCP == nil || mcp.MCP.Tool != "mcp_github_get_issue" {
+ t.Fatalf("mcp block = %+v", mcp.MCP)
+ }
+ // fx sanitizes both halves of the name into the same underscore-separated string, so the server
+ // cannot be recovered from it. Asserting a server here would be a guess presented as a fact.
+ if mcp.MCP.Server != "" {
+ t.Errorf("mcp.server = %q; fx's naming cannot be split back into server and tool", mcp.MCP.Server)
+ }
+}
+
+// fx's own MCP control tools share the `mcp_` prefix and are not calls to a server. Reporting them
+// as MCP activity would put "the agent searched its tool catalog" in the same bucket as "the agent
+// called an external server".
+func TestFxOwnMCPControlToolsAreNotReportedAsServerCalls(t *testing.T) {
+ for _, name := range []string{"mcp_search_tools", "mcp_select_tool", "mcp_features"} {
+ t.Run(name, func(t *testing.T) {
+ line := strings.NewReplacer(
+ `"name":"read_file"`, `"name":"`+name+`"`,
+ `"tool_name":"read_file","status":"success"`, `"tool_name":"`+name+`","status":"success"`,
+ ).Replace(assistantTurnLine(2))
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), line}, MapOptions{})
+ if len(findAll(mapped, "mcp.tool_invoked")) != 0 {
+ t.Fatalf("%s was reported as an MCP server call", name)
+ }
+ })
+ }
+}
+
+// A call fx never recorded a result for is the one thing a poll-based reader could plausibly drop,
+// and it is the one least worth dropping: an interrupted call is more interesting than a completed
+// one, not less.
+func TestInterruptedTurnStillReportsTheCallInFlight(t *testing.T) {
+ payload := `{"conversation_language":"en","total_input_tokens":10,"total_output_tokens":2,"turn":{` +
+ `"kind":"interrupted","user":{"text":"delete the build cache","images":[]},"assistant":null,` +
+ `"tool_call":{"id":"call_rm_1","name":"run_command","arguments_json":"{\"command\":\"rm -rf build\"}","provider_result":null},` +
+ `"completed_tool_names":["read_file"],"terminal_reason":"user_interrupt"}}`
+ line := frame(2, 1770000006000, KindHistoryTurnCommitted, payload)
+
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), line}, MapOptions{})
+ invoked := find(t, mapped, "tool.invoked")
+ if invoked.Tool == nil || invoked.Tool.Name != "run_command" {
+ t.Fatalf("tool block = %+v", invoked.Tool)
+ }
+ if invoked.Tool.Command != "rm -rf build" {
+ t.Errorf("command = %q, want the interrupted command", invoked.Tool.Command)
+ }
+ if invoked.GenAI == nil || invoked.GenAI.Tool == nil || invoked.GenAI.Tool.Call.ID != "call_rm_1" {
+ t.Error("the interrupted call lost its call id")
+ }
+ if raw := rawFx(t, invoked); raw["result_missing"] == nil {
+ t.Errorf("raw.fx does not say why there is no result: %v", raw)
+ }
+}
+
+// Per-turn tokens, not the session totals sitting next to them in the same record. Beacon's rollups
+// sum usage across events, so emitting the cumulative totals per turn would report a session's
+// whole history once per turn.
+func TestTurnUsageReportsTheTurnNotTheSessionTotal(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ usage := find(t, mapped, "token.usage")
+
+ if usage.GenAI == nil || usage.GenAI.Usage == nil {
+ t.Fatal("no gen_ai.usage on the usage event")
+ }
+ if usage.GenAI.Usage.InputTokens == nil || *usage.GenAI.Usage.InputTokens != 1200 {
+ t.Errorf("input tokens = %+v, want the turn's 1200 rather than the session's 4200", usage.GenAI.Usage.InputTokens)
+ }
+ if usage.GenAI.Usage.OutputTokens == nil || *usage.GenAI.Usage.OutputTokens != 340 {
+ t.Errorf("output tokens = %+v, want the turn's 340", usage.GenAI.Usage.OutputTokens)
+ }
+ raw := rawFx(t, usage)
+ if raw["input_exact"] != true || raw["output_exact"] != false {
+ t.Errorf("raw.fx exactness = %v/%v, want fx's own flags carried through", raw["input_exact"], raw["output_exact"])
+ }
+}
+
+// fx's usage snapshots are cumulative replacements. Emitting one directly would re-count everything
+// before it on every checkpoint, so the event carries the difference from the previous snapshot.
+func TestUsageCheckpointsAreEmittedAsDeltas(t *testing.T) {
+ lines := []string{
+ sessionStartedLine(1, "/repo"),
+ usageCheckpointLine(2, 1000, 200, 0.10),
+ usageCheckpointLine(3, 3000, 700, 0.35),
+ }
+ mapped := mapFixture(t, lines, MapOptions{})
+ usage := findAll(mapped, "token.usage")
+ if len(usage) != 2 {
+ t.Fatalf("usage events = %d, want 2", len(usage))
+ }
+ if usage[0].GenAI.Usage.CostUSD == nil || *usage[0].GenAI.Usage.CostUSD != 0.10 {
+ t.Fatalf("first checkpoint cost = %+v, want 0.10", usage[0].GenAI.Usage.CostUSD)
+ }
+ second := usage[1].GenAI.Usage
+ if second.CostUSD == nil {
+ t.Fatal("second checkpoint has no cost")
+ }
+ if got := *second.CostUSD; got < 0.2499 || got > 0.2501 {
+ t.Errorf("second checkpoint cost = %v, want the 0.25 difference rather than the 0.35 total", got)
+ }
+ // The cumulative numbers are still readable, just not summed as if they were increments.
+ if raw := rawFx(t, usage[1]); raw["cumulative_cost_usd"] == nil {
+ t.Errorf("raw.fx dropped fx's cumulative figures: %v", raw)
+ }
+}
+
+// Turn usage and checkpoint usage both write gen_ai.usage, and Beacon's rollups sum every field
+// across every event. They must therefore fill disjoint fields: input/output from the turn, cache
+// and cost from the checkpoint. If they ever overlap, every fx session's totals double.
+func TestTurnAndCheckpointUsageDoNotOverlap(t *testing.T) {
+ lines := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2), usageCheckpointLine(3, 4200, 880, 0.5)}
+ mapped := mapFixture(t, lines, MapOptions{})
+ usage := findAll(mapped, "token.usage")
+ if len(usage) != 2 {
+ t.Fatalf("usage events = %d, want 2", len(usage))
+ }
+ turn, checkpoint := usage[0].GenAI.Usage, usage[1].GenAI.Usage
+
+ if turn.InputTokens == nil || turn.OutputTokens == nil {
+ t.Fatal("the turn event carries no token counts")
+ }
+ if turn.CostUSD != nil || turn.CacheRead != nil || turn.CacheCreation != nil {
+ t.Error("the turn event claims cost or cache tokens, which the checkpoint also reports")
+ }
+ if checkpoint.InputTokens != nil || checkpoint.OutputTokens != nil {
+ t.Error("the checkpoint event repeats input/output tokens already counted per turn")
+ }
+ if checkpoint.CacheRead == nil || checkpoint.CacheCreation == nil || checkpoint.CostUSD == nil {
+ t.Errorf("the checkpoint event dropped the fields only it can report: %+v", checkpoint)
+ }
+}
+
+// A snapshot that goes backwards is a session restored from an earlier state, not negative usage.
+// A negative delta would subtract from a total that describes something else entirely.
+func TestUsageThatGoesBackwardsIsNotReportedAsNegative(t *testing.T) {
+ lines := []string{
+ sessionStartedLine(1, "/repo"),
+ usageCheckpointLine(2, 3000, 700, 0.35),
+ usageCheckpointLine(3, 1000, 200, 0.10),
+ }
+ mapped := mapFixture(t, lines, MapOptions{})
+ usage := findAll(mapped, "token.usage")
+ if len(usage) != 1 {
+ t.Fatalf("usage events = %d, want only the first checkpoint", len(usage))
+ }
+}
+
+// A session resumed from earlier work starts with the usage it already had. Without seeding the
+// baseline from it, the first checkpoint after a resume reports the whole prior session as if it
+// had just happened.
+func TestResumedSessionDoesNotReplayPriorUsage(t *testing.T) {
+ started := strings.Replace(sessionStartedLine(1, "/repo"), `"usage":null`,
+ `"usage":{"billing":"complete","total_cost":5.0,"input_tokens":100000,"output_tokens":20000,`+
+ `"cache_read_tokens":800,"cache_write_tokens":100,"billable_web_search_calls":0,`+
+ `"lines_added":0,"lines_removed":0,"models":[]}`, 1)
+ lines := []string{started, usageCheckpointLine(2, 100500, 20100, 5.10)}
+
+ mapped := mapFixture(t, lines, MapOptions{})
+ usage := find(t, mapped, "token.usage")
+ if usage.GenAI.Usage.CostUSD == nil {
+ t.Fatal("no cost on the checkpoint")
+ }
+ if got := *usage.GenAI.Usage.CostUSD; got < 0.09 || got > 0.11 {
+ t.Errorf("cost = %v, want the 0.10 spent since the resume rather than the 5.10 total", got)
+ }
+ if usage.GenAI.Usage.CacheRead == nil || *usage.GenAI.Usage.CacheRead.InputTokens != 100 {
+ t.Errorf("cache read delta = %+v, want 100", usage.GenAI.Usage.CacheRead)
+ }
+}
+
+// MinSeq is what makes a second sweep cheap and quiet. Events at or below it still build the
+// mapper's state -- the model in force, the usage baseline -- but produce nothing.
+func TestAlreadyCollectedEventsBuildStateWithoutBeingEmittedAgain(t *testing.T) {
+ lines := []string{
+ sessionStartedLine(1, "/repo"),
+ usageCheckpointLine(2, 1000, 200, 0.10),
+ usageCheckpointLine(3, 3000, 700, 0.35),
+ }
+ mapped := mapFixture(t, lines, MapOptions{MinSeq: 2})
+ if len(mapped) != 1 {
+ t.Fatalf("mapped %d events, want only the one past the cursor: %v", len(mapped), actions(mapped))
+ }
+ usage := mapped[0].Event
+ if usage.GenAI.Usage.CostUSD == nil {
+ t.Fatal("no cost")
+ }
+ // The baseline came from the checkpoint before the cursor, which was never re-emitted.
+ if got := *usage.GenAI.Usage.CostUSD; got < 0.2499 || got > 0.2501 {
+ t.Errorf("cost = %v, want the 0.25 delta from the checkpoint the sweep skipped", got)
+ }
+ // The model was set by the session_started the sweep also skipped.
+ if usage.Model != "anthropic/claude-opus-4" {
+ t.Errorf("model = %q, want the one the skipped session_started set", usage.Model)
+ }
+}
+
+// fx writes a fresh session_started at sequence 1 of every log generation, including the one it
+// creates when it compacts a log. A second start for a session that never restarted would double
+// every session count on the dashboard.
+func TestSessionStartCanBeSuppressedForAnAlreadyStartedSession(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{SkipSessionStarted: true})
+ if len(findAll(mapped, "session.started")) != 0 {
+ t.Fatal("session.started was emitted for a session already known to have started")
+ }
+ // Suppressing the event must not suppress the state it carries.
+ prompt := find(t, mapped, "prompt.submitted")
+ if prompt.Model != "anthropic/claude-opus-4" || prompt.Session.WorkingDirectory != "/repo" {
+ t.Errorf("state from the suppressed session_started was lost: model %q dir %q",
+ prompt.Model, prompt.Session.WorkingDirectory)
+ }
+}
+
+// Dedup ids are what make re-reading fx's log idempotent, so the same record has to produce the
+// same id on every sweep, and two records must never share one.
+func TestDedupIDsAreStableAndUnique(t *testing.T) {
+ lines := []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2), usageCheckpointLine(3, 1, 1, 0.01)}
+ first := mapFixture(t, lines, MapOptions{})
+ second := mapFixture(t, lines, MapOptions{})
+
+ if len(first) != len(second) {
+ t.Fatalf("two passes produced %d and %d events", len(first), len(second))
+ }
+ seen := map[string]bool{}
+ for i := range first {
+ if first[i].DedupID != second[i].DedupID {
+ t.Fatalf("dedup id changed between passes: %q then %q", first[i].DedupID, second[i].DedupID)
+ }
+ if first[i].DedupID == "" {
+ t.Fatalf("event %s has no dedup id", first[i].Event.Event.Action)
+ }
+ if seen[first[i].DedupID] {
+ t.Fatalf("dedup id %q used twice", first[i].DedupID)
+ }
+ seen[first[i].DedupID] = true
+ }
+}
+
+// fx does not persist an approve/deny record per call -- what it keeps is the feedback a person
+// typed at a prompt. That is evidence about a decision, not the decision, and synthesizing an
+// approval event from it would put a fabricated decision in the field auditors count. Same posture
+// the Cline and Pi integrations already take.
+func TestPermissionFeedbackIsRecordedWithoutSynthesizingAnApproval(t *testing.T) {
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), assistantTurnLine(2)}, MapOptions{})
+ for _, item := range mapped {
+ if strings.HasPrefix(item.Event.Event.Action, "approval.") {
+ t.Fatalf("mapper synthesized %q from fx records that contain no decision", item.Event.Event.Action)
+ }
+ if item.Event.Approval != nil {
+ t.Fatalf("%s carries an approval block fx never recorded", item.Event.Event.Action)
+ }
+ }
+ command := find(t, mapped, "command.executed")
+ raw := rawFx(t, command)
+ feedback, ok := raw["permission_feedback"].([]interface{})
+ if !ok || len(feedback) != 1 {
+ t.Fatalf("raw.fx.permission_feedback = %v, want fx's feedback preserved", raw["permission_feedback"])
+ }
+}
+
+// A session's workspace can change: fx sessions are global and portable, and a resume in another
+// directory rebinds them. Later events have to follow the session to its new root, or a file path
+// gets read against the wrong tree.
+func TestWorkspaceRebindMovesLaterEventsToTheNewRoot(t *testing.T) {
+ rebound := frame(2, 1770000002000, KindWorkspaceRebound,
+ `{"previous_workspace_root":"/repo","workspace_root":"/other/checkout"}`)
+ lines := []string{sessionStartedLine(1, "/repo"), rebound, assistantTurnLine(3)}
+
+ mapped := mapFixture(t, lines, MapOptions{})
+ context := find(t, mapped, "session.context")
+ if raw := rawFx(t, context); raw["change"] != "workspace_rebound" {
+ t.Errorf("raw.fx.change = %v", raw["change"])
+ }
+ prompt := find(t, mapped, "prompt.submitted")
+ if prompt.Session.WorkingDirectory != "/other/checkout" {
+ t.Errorf("working directory = %q, want the rebound root", prompt.Session.WorkingDirectory)
+ }
+}
+
+// Switching model or provider mid-session changes what a session costs and where its prompts went.
+// It is recorded under session.context, the action the Codex integration already uses for session
+// metadata, rather than under a verb only fx produces.
+func TestPreferencesChangeIsRecordedAndAppliesToLaterEvents(t *testing.T) {
+ changed := frame(2, 1770000002000, KindPreferencesChanged,
+ `{"provider":"grok","model":"grok-4","effort":"high","fast_mode":true}`)
+ lines := []string{sessionStartedLine(1, "/repo"), changed, assistantTurnLine(3)}
+
+ mapped := mapFixture(t, lines, MapOptions{})
+ context := find(t, mapped, "session.context")
+ raw := rawFx(t, context)
+ if raw["change"] != "preferences_changed" || raw["model"] != "grok-4" {
+ t.Errorf("raw.fx = %v", raw)
+ }
+ prompt := find(t, mapped, "prompt.submitted")
+ if prompt.Model != "grok-4" {
+ t.Errorf("model on a later event = %q, want grok-4", prompt.Model)
+ }
+ if prompt.GenAI.Provider.Name != "grok" {
+ t.Errorf("provider on a later event = %q, want grok", prompt.GenAI.Provider.Name)
+ }
+}
+
+// fx compacting its own history means the record thins out from that point back, and a reader
+// reconstructing a session needs to see where.
+func TestHistoryCompactionIsRecorded(t *testing.T) {
+ payload := `{"conversation_language":"en","total_input_tokens":10,"total_output_tokens":2,"turn":{` +
+ `"kind":"compacted_summary","summary":"Earlier: set up the API and its tests.","removed_turn_count":12,"compaction_count":1}}`
+ lines := []string{sessionStartedLine(1, "/repo"), frame(2, 1770000007000, KindHistoryTurnCommitted, payload)}
+
+ mapped := mapFixture(t, lines, MapOptions{})
+ compaction := find(t, mapped, "session.compacting")
+ raw := rawFx(t, compaction)
+ if raw["removed_turn_count"] == nil {
+ t.Fatalf("raw.fx = %v, want the dropped-turn count", raw)
+ }
+}
+
+// Text that is not valid UTF-8 reaches Beacon as fx's base64 form, and it must survive into an
+// event rather than emptying the field or failing the line. An event that says a tool returned
+// nothing when it returned bytes is worse than one carrying a replacement character.
+func TestNonUTF8CommandOutputSurvivesIntoTheEvent(t *testing.T) {
+ line := strings.Replace(assistantTurnLine(2),
+ `"status":"failure","output":"1 test failed"`,
+ `"status":"failure","output":{"encoding":"base64","data":"/w=="}`, 1)
+ mapped := mapFixture(t, []string{sessionStartedLine(1, "/repo"), line}, MapOptions{})
+ command := find(t, mapped, "command.executed")
+ if command.Command.Output == "" {
+ t.Fatal("non-UTF-8 output was dropped, which reads as a command that printed nothing")
+ }
+ if command.Content == nil || command.Content.Bytes != 1 {
+ t.Errorf("content marker = %+v, want one byte retained", command.Content)
+ }
+}
+
+func rawFx(t *testing.T, ev schema.Event) map[string]interface{} {
+ t.Helper()
+ if ev.Raw == nil {
+ t.Fatalf("%s has no raw block", ev.Event.Action)
+ }
+ // Round-tripped so the assertions read the same shape a consumer of the log would.
+ data, err := json.Marshal(ev.Raw["fx"])
+ if err != nil {
+ t.Fatalf("marshal raw.fx: %v", err)
+ }
+ var out map[string]interface{}
+ if err := json.Unmarshal(data, &out); err != nil {
+ t.Fatalf("decode raw.fx: %v", err)
+ }
+ return out
+}