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
package fxsession
import (
"crypto/sha1"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"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
SourceSeq uint64
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
// lastTotals is the session's cumulative token count as of the previous committed turn, used
// to derive a turn's own usage on fx builds that write no turn summary. See emitTurnUsage.
lastTotals struct {
input int64
output int64
seen bool
}
// 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 both delta
// baselines from it stops the first checkpoint and the first turn 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
m.lastTotals.input = event.SessionStarted.Usage.InputTokens
m.lastTotals.output = event.SessionStarted.Usage.OutputTokens
m.lastTotals.seen = true
}
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)
}
// After emitting, and for every turn including the ones this sweep skips. The token
// fallback in emitTurnUsage measures against this baseline, so a resumed sweep has to
// carry it forward over the turns it is not re-emitting -- otherwise the first turn it
// does emit reports the session's entire history as its own usage.
m.recordTotals(event.TurnCommitted)
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 != "" {
// Canonicalized on the way in, like the harness name, so fx's spelling of a model
// groups with the same model reported by a hook or OTLP runtime in the BY MODEL
// rollup. Only the name is normalized here: fx reports its provider separately
// below, and a runtime naming its own provider beats one parsed out of a model
// string, so nothing is derived from a prefix on this path.
m.model = asymptoteobserve.NormalizeModelName(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)
if info, ok := asymptoteobserve.ParseHandoffMarker(text); ok {
link := m.base(event, "session.handoff", "session", schema.SeverityInfo, schema.FidelityObserved, "Session continued from a "+info.SourceHarness+" session")
link.Timestamp = ev.Timestamp
link.Handoff = &info
m.append(event, fmt.Sprintf("turn.%d.handoff", m.turnIndex), link)
}
}
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
ev.Content, info.DiffHash, info.DiffBytes = asymptoteobserve.RetainedDiff(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.
//
// Two sources for the per-turn counts, because fx has shipped both shapes. A build that writes a
// turn summary is read from it, flags and durations included. A build that writes none -- fx 0.0.7
// omits the summary entirely, which is how this was found: a real session through the released
// binary produced no token usage at all -- falls back to the difference between this turn's
// cumulative session totals and the previous turn's. Same discipline as the checkpoint deltas, and
// the same reason: the alternative is either no usage or a session's whole history counted once per
// turn. raw.fx.token_source says which was used, because an exact per-turn count and a difference
// of two running totals are not equally trustworthy.
func (m *mapper) emitTurnUsage(event *Event, turn Turn) {
usage := &schema.GenAIUsageInfo{}
raw := map[string]interface{}{}
summary := (*TurnSummary)(nil)
if turn.Execution != nil {
summary = turn.Execution.TurnSummary
}
switch {
case summary != nil && (summary.TokenProgress.InputTokens > 0 || summary.TokenProgress.OutputTokens > 0):
progress := summary.TokenProgress
if progress.InputTokens > 0 {
input := progress.InputTokens
usage.InputTokens = &input
}
if progress.OutputTokens > 0 {
output := progress.OutputTokens
usage.OutputTokens = &output
}
// 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.
raw["token_source"] = "turn_summary"
raw["input_exact"] = progress.InputExact
raw["output_exact"] = progress.OutputExact
raw["turn_duration_ms"] = summary.TurnDurationMS
raw["thinking_duration_ms"] = summary.ThinkingDurationMS
default:
input := delta(int64(event.TurnCommitted.TotalInputTokens), m.lastTotals.input)
output := delta(int64(event.TurnCommitted.TotalOutputTokens), m.lastTotals.output)
if input > 0 {
usage.InputTokens = &input
}
if output > 0 {
usage.OutputTokens = &output
}
raw["token_source"] = "session_totals_delta"
}
if usage.InputTokens == nil && usage.OutputTokens == nil {
return
}
ev := m.base(event, "token.usage", "metric", schema.SeverityInfo, schema.FidelityObserved, "fx token usage")
ev.GenAI = m.withGenAI(ev.GenAI, func(genAI *schema.GenAIInfo) { genAI.Usage = usage })
ev.Raw = mergeRaw(ev.Raw, raw)
m.append(event, fmt.Sprintf("turn.%d.usage", m.turnIndex), ev)
}
// recordTotals advances the cumulative baseline the fallback above measures against. Its caller
// runs it for every committed turn, including ones this sweep is not emitting, so a resumed sweep
// measures the first turn it emits against the turn before it rather than against zero.
func (m *mapper) recordTotals(committed *TurnCommitted) {
if committed == nil {
return
}
m.lastTotals.input = int64(committed.TotalInputTokens)
m.lastTotals.output = int64(committed.TotalOutputTokens)
m.lastTotals.seen = true
}
// 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) {
dedupID := fmt.Sprintf("%s:%s:%d:%s", m.sessionID(), event.LogGeneration, event.Seq, suffix)
ev.Event.ID = fxEventID(dedupID)
m.out = append(m.out, MappedEvent{
DedupID: dedupID,
SourceSeq: event.Seq,
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.CommandOutputReplay != nil && result.CommandOutputReplay.Handle != "" {
// The full captured output of a command is not in the record: fx keeps it in a framed
// replay file beside the session and puts the handle here. Beacon cannot read that framing,
// so it carries the handle rather than pretending the stored text is the whole output.
raw["command_output_handle"] = result.CommandOutputReplay.Handle.String()
raw["command_output_framed_bytes"] = result.CommandOutputReplay.FramedBytes
}
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 ""
}
// fxIDNamespace is the fixed UUID namespace for fx dedup-coordinate event IDs.
// It is distinct from the content-based namespace in asymptoteobserve so the two
// derivations can never collide.
var fxIDNamespace = [16]byte{
0x3a, 0x7c, 0x1f, 0x4b, 0x5a, 0x2c, 0x8e, 0x6d,
0x0d, 0x3f, 0x61, 0x9b, 0x2a, 0x8c, 0x5e, 0x14,
}
// fxEventID derives a deterministic UUID v5 from a dedup coordinate, so the same
// fx record always produces the same event ID regardless of how many times it is
// read. The coordinate encodes session, generation, sequence and position within
// the turn, which is everything that identifies one mapped event.
func fxEventID(dedupID string) string {
digest := sha1.New()
digest.Write(fxIDNamespace[:])
io.WriteString(digest, dedupID)
var id [16]byte
copy(id[:], digest.Sum(nil))
id[6] = (id[6] & 0x0f) | 0x50 // version 5
id[8] = (id[8] & 0x3f) | 0x80 // RFC 4122 variant
out := make([]byte, 32)
hex.Encode(out, id[:])
return fmt.Sprintf("%s-%s-%s-%s-%s", out[0:8], out[8:12], out[12:16], out[16:20], out[20:32])
}
// 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) }