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): map fx session records onto Beacon endpoint events
Claude16f481bfd447
diff --git a/cli/beacon/internal/fxsession/mapper.go b/cli/beacon/internal/fxsession/mapper.gonew file mode 100644index 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.gonew file mode 100644index 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+}