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
fix(claude): count each API response's token usage once in claude sync
Claude4c5781f99dc8
diff --git a/cli/beacon/internal/claudesession/collect.go b/cli/beacon/internal/claudesession/collect.goindex ce069c1a..7d4e2282 100644--- a/cli/beacon/internal/claudesession/collect.go+++ b/cli/beacon/internal/claudesession/collect.go@@ -153,8 +153,9 @@ func CollectOnce(opts CollectOptions) (summary Summary, err error) {guard = &writer.RetentionGuard{}}var errs []error+ responses := responseLedger{}for i, ref := range refs {- changed, collectErr := collectSession(store, ref, state, opts, guard, &summary)+ changed, collectErr := collectSession(store, ref, state, opts, guard, responses, &summary)if errors.Is(collectErr, writer.ErrRetentionWindowFull) {// Not a failed session: this one and the rest are simply left for the next sweep,// with cursors that have not moved past anything that was not written.@@ -203,7 +204,7 @@ func countChanged(refs []SessionRef, state *State) int {return n}-func collectSession(store *Store, ref SessionRef, state *State, opts CollectOptions, guard *writer.RetentionGuard, summary *Summary) (bool, error) {+func collectSession(store *Store, ref SessionRef, state *State, opts CollectOptions, guard *writer.RetentionGuard, responses responseLedger, summary *Summary) (bool, error) {cursor := state.cursor(ref.Path)if ref.SizeBytes < cursor.SizeBytes {cursor.LastLine = 0@@ -220,7 +221,7 @@ func collectSession(store *Store, ref SessionRef, state *State, opts CollectOptiif err != nil {return false, err}- mapped := MapSession(ref, records, MapOptions{MinLine: cursor.LastLine, SkipSessionStarted: cursor.Started})+ mapped := MapSession(ref, records, MapOptions{MinLine: cursor.LastLine, SkipSessionStarted: cursor.Started, responses: responses})if len(mapped) == 0 {advanceCursor(cursor, ref, stats.Lines)return false, nil@@ -248,7 +249,8 @@ func advanceCursor(cursor *Cursor, ref SessionRef, lines int) {// advanceCursorPartial moves the cursor past source lines whose mapped events// were all emitted, so the next sweep retries only from the source line that// failed. failedIdx is the index into mapped of the event whose emit returned-// an error.+// an error. It never moves the cursor to or past the RetryFrom line of an event that was not+// written, so the source lines that event accounts for are read again.func advanceCursorPartial(cursor *Cursor, mapped []MappedEvent, failedIdx int) {var lastCompleteLine intfound := false@@ -264,6 +266,14 @@ func advanceCursorPartial(cursor *Cursor, mapped []MappedEvent, failedIdx int) {if !found {return}+ for _, item := range mapped[failedIdx:] {+ if item.RetryFrom > 0 && lastCompleteLine >= item.RetryFrom {+ lastCompleteLine = item.RetryFrom - 1+ }+ }+ if lastCompleteLine < cursor.LastLine {+ return+ }cursor.LastLine = lastCompleteLine}diff --git a/cli/beacon/internal/claudesession/mapper.go b/cli/beacon/internal/claudesession/mapper.goindex cc91da16..373920aa 100644--- a/cli/beacon/internal/claudesession/mapper.go+++ b/cli/beacon/internal/claudesession/mapper.go@@ -18,11 +18,19 @@ type MappedEvent struct {DedupID stringSourceLine intEvent schema.Event+ // RetryFrom, when set, is the earliest source line this event accounts for. A sweep that+ // stops before writing it must not leave its cursor at or past that line, or the next sweep+ // would treat what the event counts as already counted. Only token.usage events set it: one+ // response's usage event can account for block lines before its own (see usage.go).+ RetryFrom int}type MapOptions struct {MinLine intSkipSessionStarted bool+ // responses is what this sweep has already counted for each API response across the files+ // it read before this one. Nil maps the file on its own.+ responses responseLedger}type toolCall struct {@@ -36,10 +44,12 @@ type mapper struct {opts MapOptionsout []MappedEventtools map[string]toolCall+ usage map[int]usagePlan}func MapSession(ref SessionRef, records []Record, opts MapOptions) []MappedEvent {m := &mapper{ref: ref, opts: opts, tools: map[string]toolCall{}}+ m.usage = planUsage(ref, records, opts.MinLine, opts.responses)for i := range records {m.consume(records[i])}@@ -146,8 +156,8 @@ func (m *mapper) consumeAssistant(record Record, emit bool) {if text := strings.TrimSpace(strings.Join(reasoningParts, "\n")); text != "" {m.emitAgentReasoning(record, text)}- if usage := usageFromMessage(entry.Message); usage != nil {- m.emitUsage(record, usage)+ if plan, ok := m.usage[record.Line]; ok {+ m.emitUsage(record, plan)}}}@@ -242,11 +252,12 @@ func (m *mapper) emitToolResult(record Record, block int, result map[string]inte}}-func (m *mapper) emitUsage(record Record, usage *schema.GenAIUsageInfo) {+func (m *mapper) emitUsage(record Record, plan usagePlan) {ev := m.base(record, "token.usage", "metric", schema.SeverityInfo, schema.FidelityObserved, "Claude Code token usage observed")- ev.GenAI = mergeGenAI(ev.GenAI, &schema.GenAIInfo{Usage: usage})+ ev.GenAI = mergeGenAI(ev.GenAI, &schema.GenAIInfo{Usage: plan.usage})m.applyResponse(&ev, record.Entry)- m.append(record, "usage", ev)+ ev.Event.ID = claudeEventID(plan.coordinate)+ m.out = append(m.out, MappedEvent{DedupID: ev.Event.ID, SourceLine: record.Line, Event: ev, RetryFrom: plan.retryFrom})}func (m *mapper) emitSummary(record Record) {@@ -299,7 +310,7 @@ func (m *mapper) base(record Record, action, category string, severity schema.Se}func (m *mapper) append(record Record, suffix string, ev schema.Event) {- coordinate := firstNonEmpty(record.Entry.UUID, m.ref.Path+":"+itoa(record.Line)) + ":" + suffix+ coordinate := recordCoordinate(m.ref, record) + ":" + suffixev.Event.ID = claudeEventID(coordinate)m.out = append(m.out, MappedEvent{DedupID: ev.Event.ID, SourceLine: record.Line, Event: ev})}diff --git a/cli/beacon/internal/claudesession/usage.go b/cli/beacon/internal/claudesession/usage.gonew file mode 100644index 00000000..b82c6017--- /dev/null+++ b/cli/beacon/internal/claudesession/usage.go@@ -0,0 +1,217 @@+package claudesession++import (+ "strings"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+)++// Token usage is counted per API response, not per transcript record.+//+// Claude Code writes one streamed response as one line per content block -- a thinking line, a+// text line, a tool_use line -- each its own record with its own uuid, all sharing the response's+// message.id and requestId and each carrying a copy of message.usage. A line written before the+// stream's final message_delta carries the message_start snapshot, whose output_tokens is a+// placeholder, and the tool a tool_use line names can run and write its result before the next+// block line of the same response arrives. Counting usage per record therefore counted each+// response once per block, and could count a placeholder as if it were a response of its own.+//+// So every usage-bearing record is grouped by the response it belongs to: (message.id, requestId),+// message.id alone when there is no requestId, and the record itself when there is neither. Each+// response gets one token.usage event carrying its largest-output snapshot (on a tie, the later+// record's), placed on the first record that reports that count, under an event id derived from+// the response rather than from the record.+//+// Sweeps are incremental, and one can land between two block lines of a response. The mapper+// always sees the whole file (MinLine only gates emission), so the part of a response at or+// before the cursor is what earlier sweeps counted: the largest snapshot among those records.+// That holds because the usage event sits on the first record reporting the count it carries,+// and because a sweep that stops partway never leaves the cursor between a response's first+// uncounted record and its unwritten usage event (MappedEvent.RetryFrom). A later sweep that+// finds a larger snapshot emits only the difference, under an id derived from the response and+// the record carrying it; one that finds nothing larger emits nothing. Rerunning a sweep, or+// sweeping the finished file from scratch, cannot count a response twice.+//+// A forked or resumed session can replay earlier records, same message.id and requestId, into+// another file. Within one sweep a responseLedger carries what every file read so far has counted,+// so a replayed response is counted only where it was first seen. Across sweeps the ledger is+// not kept -- it would grow with every response ever made -- so a replay into a file first read+// in a later sweep than its original is counted again there, under the same response-derived+// event id the original carries.++// responseLedger is what one sweep has counted for each response, keyed by responseKey.+type responseLedger map[string]*schema.GenAIUsageInfo++// usagePlan is one token.usage event to emit on a record line.+type usagePlan struct {+ usage *schema.GenAIUsageInfo+ coordinate string+ retryFrom int+}++type responseUsage struct {+ key string+ coordinate string+ counted *schema.GenAIUsageInfo+ best *schema.GenAIUsageInfo+ bestRecord Record+ lines []lineOutput+}++type lineOutput struct {+ line int+ output int64+}++// responseKey names the API response a record belongs to, or "" when the record does not say.+func responseKey(entry Entry) string {+ id := strings.TrimSpace(stringValue(entry.Message["id"]))+ if id == "" {+ return ""+ }+ if request := strings.TrimSpace(entry.RequestID); request != "" {+ return "response:" + id + "\x00" + request+ }+ return "response:" + id+}++// planUsage decides, before any record is mapped, which record lines carry a token.usage event and+// what each one counts. ledger may be nil.+func planUsage(ref SessionRef, records []Record, minLine int, ledger responseLedger) map[int]usagePlan {+ var order []*responseUsage+ byKey := map[string]*responseUsage{}+ for _, record := range records {+ if record.Entry.Type != "assistant" {+ continue+ }+ usage := usageFromMessage(record.Entry.Message)+ if usage == nil {+ continue+ }+ key := responseKey(record.Entry)+ group := byKey[key]+ if key == "" || group == nil {+ group = &responseUsage{key: key, coordinate: key}+ if key == "" {+ // The event id every record-keyed usage event has always had.+ group.coordinate = recordCoordinate(ref, record)+ } else {+ byKey[key] = group+ }+ order = append(order, group)+ }+ output := outputTokens(usage)+ if record.Line <= minLine {+ if group.counted == nil || output >= outputTokens(group.counted) {+ group.counted = usage+ }+ continue+ }+ group.lines = append(group.lines, lineOutput{line: record.Line, output: output})+ switch {+ case group.best == nil || output > outputTokens(group.best):+ group.best = usage+ group.bestRecord = record+ case output == outputTokens(group.best):+ // Same count, later record: take its snapshot, keep the event where the count+ // first appeared.+ group.best = usage+ }+ }++ plans := map[int]usagePlan{}+ for _, group := range order {+ prior := group.counted+ if group.key != "" && ledger != nil {+ if seen := ledger[group.key]; seen != nil && (prior == nil || outputTokens(seen) > outputTokens(prior)) {+ prior = seen+ }+ }+ if group.best != nil {+ plan := usagePlan{retryFrom: group.lines[0].line}+ switch {+ case prior == nil:+ plan.usage = group.best+ plan.coordinate = group.coordinate + ":usage"+ case outputTokens(group.best) > outputTokens(prior):+ plan.usage = usageDelta(group.best, prior)+ plan.coordinate = group.coordinate + ":usage:" + recordCoordinate(ref, group.bestRecord)+ for _, lo := range group.lines {+ if lo.output > outputTokens(prior) {+ plan.retryFrom = lo.line+ break+ }+ }+ }+ if plan.usage != nil {+ plans[group.bestRecord.Line] = plan+ }+ }+ if group.key != "" && ledger != nil {+ for _, usage := range []*schema.GenAIUsageInfo{prior, group.best} {+ if usage != nil && (ledger[group.key] == nil || outputTokens(usage) > outputTokens(ledger[group.key])) {+ ledger[group.key] = usage+ }+ }+ }+ }+ return plans+}++func recordCoordinate(ref SessionRef, record Record) string {+ return firstNonEmpty(record.Entry.UUID, ref.Path+":"+itoa(record.Line))+}++// outputTokens orders snapshots of one response. A snapshot without an output count sorts below+// every snapshot that has one.+func outputTokens(usage *schema.GenAIUsageInfo) int64 {+ if usage == nil || usage.OutputTokens == nil {+ return -1+ }+ return *usage.OutputTokens+}++// usageDelta is what best adds to an already-counted snapshot of the same response, field by+// field. Only output grows over a stream, but every field is differenced so nothing is counted+// twice whichever does.+func usageDelta(best, prior *schema.GenAIUsageInfo) *schema.GenAIUsageInfo {+ sub := func(next, counted *int64) *int64 {+ if next == nil {+ return nil+ }+ v := *next+ if counted != nil {+ v -= *counted+ }+ if v < 0 {+ v = 0+ }+ return &v+ }+ out := &schema.GenAIUsageInfo{+ InputTokens: sub(best.InputTokens, prior.InputTokens),+ OutputTokens: sub(best.OutputTokens, prior.OutputTokens),+ }+ if best.CacheCreation != nil {+ var counted *int64+ if prior.CacheCreation != nil {+ counted = prior.CacheCreation.InputTokens+ }+ out.CacheCreation = &schema.GenAIUsageCacheCreationInfo{InputTokens: sub(best.CacheCreation.InputTokens, counted)}+ }+ if best.CacheRead != nil {+ var counted *int64+ if prior.CacheRead != nil {+ counted = prior.CacheRead.InputTokens+ }+ out.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: sub(best.CacheRead.InputTokens, counted)}+ }+ if best.Reasoning != nil {+ var counted *int64+ if prior.Reasoning != nil {+ counted = prior.Reasoning.OutputTokens+ }+ out.Reasoning = &schema.GenAIUsageReasoningInfo{OutputTokens: sub(best.Reasoning.OutputTokens, counted)}+ }+ return out+}diff --git a/cli/beacon/internal/claudesession/usage_test.go b/cli/beacon/internal/claudesession/usage_test.gonew file mode 100644index 00000000..8ab367fe--- /dev/null+++ b/cli/beacon/internal/claudesession/usage_test.go@@ -0,0 +1,408 @@+package claudesession++import (+ "encoding/json"+ "path/filepath"+ "strings"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"+)++// Claude Code writes a streamed API response as one transcript line per content block: a thinking+// line, a text line, a tool_use line, each its own record with its own uuid, all sharing the+// response's message.id and requestId, and each carrying a copy of message.usage. A line written+// before the stream's final message_delta carries the message_start snapshot, whose output_tokens+// is a placeholder. These fixtures reproduce that layout field for field.++type streamed struct {+ session string+ uuid string+ parent string+ msgID string+ requestID string+ block map[string]interface{}+ output int64+ sidechain bool+ agentID string+}++func (s streamed) line() string {+ usage := map[string]interface{}{+ "input_tokens": 4,+ "cache_creation_input_tokens": 1200,+ "cache_read_input_tokens": 30000,+ "cache_creation": map[string]interface{}{+ "ephemeral_5m_input_tokens": 0,+ "ephemeral_1h_input_tokens": 1200,+ },+ "output_tokens": s.output,+ "service_tier": "standard",+ }+ message := map[string]interface{}{+ "model": "claude-sonnet-4-5",+ "type": "message",+ "role": "assistant",+ "content": []interface{}{s.block},+ "stop_reason": nil,+ "stop_sequence": nil,+ "usage": usage,+ }+ if s.msgID != "" {+ message["id"] = s.msgID+ }+ record := map[string]interface{}{+ "parentUuid": nullable(s.parent),+ "isSidechain": s.sidechain,+ "userType": "external",+ "cwd": "/tmp/repo",+ "sessionId": s.session,+ "version": "2.1.154",+ "gitBranch": "main",+ "message": message,+ "type": "assistant",+ "uuid": s.uuid,+ "timestamp": "2026-09-19T22:00:01.000Z",+ }+ if s.requestID != "" {+ record["requestId"] = s.requestID+ }+ if s.agentID != "" {+ record["agentId"] = s.agentID+ }+ data, _ := json.Marshal(record)+ return string(data)+}++func nullable(s string) interface{} {+ if s == "" {+ return nil+ }+ return s+}++func thinkingBlock(text string) map[string]interface{} {+ return map[string]interface{}{"type": "thinking", "thinking": text, "signature": "EqoBCkYIBxgCKkA"}+}++func textBlock(text string) map[string]interface{} {+ return map[string]interface{}{"type": "text", "text": text}+}++func bashBlock(id, command string) map[string]interface{} {+ return map[string]interface{}{"type": "tool_use", "id": id, "name": "Bash", "input": map[string]interface{}{"command": command, "description": "run"}}+}++// splitResponse is one API response written the way Claude Code writes it: thinking, text and a+// Bash call on three lines, the first two carrying the message_start placeholder of 8 output tokens+// and the last the final count, followed by the tool's result.+func splitResponse(session, prefix, msgID, requestID string, final int64) []string {+ return []string{+ streamed{session: session, uuid: prefix + "-think", parent: prefix + "-prompt", msgID: msgID, requestID: requestID, block: thinkingBlock("Check the tests first."), output: 8}.line(),+ streamed{session: session, uuid: prefix + "-text", parent: prefix + "-think", msgID: msgID, requestID: requestID, block: textBlock("I'll run the tests."), output: 8}.line(),+ streamed{session: session, uuid: prefix + "-tool", parent: prefix + "-text", msgID: msgID, requestID: requestID, block: bashBlock("toolu_"+prefix, "npm test"), output: final}.line(),+ toolResultLine(session, prefix+"-result", "toolu_"+prefix, "ok", false),+ }+}++func usageEvents(mapped []MappedEvent) []MappedEvent {+ var out []MappedEvent+ for _, item := range mapped {+ if item.Event.Event.Action == "token.usage" {+ out = append(out, item)+ }+ }+ return out+}++func outputOf(t *testing.T, ev schema.Event) int64 {+ t.Helper()+ if ev.GenAI == nil || ev.GenAI.Usage == nil || ev.GenAI.Usage.OutputTokens == nil {+ t.Fatalf("usage event without output tokens: %+v", ev.GenAI)+ }+ return *ev.GenAI.Usage.OutputTokens+}++func sumOutput(t *testing.T, mapped []MappedEvent) int64 {+ t.Helper()+ var total int64+ for _, item := range usageEvents(mapped) {+ total += outputOf(t, item.Event)+ }+ return total+}++func countActions(mapped []MappedEvent) map[string]int {+ out := map[string]int{}+ for _, item := range mapped {+ out[item.Event.Event.Action]+++ }+ return out+}++func TestSplitResponseUsageIsCountedOnceWithTheFinalSnapshot(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl", ProjectPath: "/tmp/repo"}+ lines := append([]string{userLine("sess-1", "r1-prompt", "run the tests")}, splitResponse("sess-1", "r1", "msg_01A", "req_01A", 312)...)+ mapped := MapSession(ref, decodeFixture(t, lines), MapOptions{})++ usage := usageEvents(mapped)+ if len(usage) != 1 {+ t.Fatalf("token.usage events = %d, want 1 for one API response written on three lines: %v", len(usage), actions(mapped))+ }+ ev := usage[0].Event+ if got := outputOf(t, ev); got != 312 {+ t.Fatalf("output_tokens = %d, want the final snapshot's 312", got)+ }+ u := ev.GenAI.Usage+ if *u.InputTokens != 4 || *u.CacheRead.InputTokens != 30000 || *u.CacheCreation.InputTokens != 1200 {+ t.Fatalf("usage = %+v, want the response's input, cache read and cache creation counted once", u)+ }+ if ev.GenAI.Response == nil || ev.GenAI.Response.ID != "msg_01A" {+ t.Fatalf("response = %+v, want msg_01A", ev.GenAI.Response)+ }+ if err := ev.Validate(); err != nil {+ t.Fatalf("usage event invalid: %v", err)+ }++ // The other per-block emissions are per record and stay that way: each block line is its own+ // reasoning, message or tool call.+ counts := countActions(mapped)+ for action, want := range map[string]int{"agent.reasoning": 1, "agent.message": 1, "tool.invoked": 1, "command.executed": 1, "prompt.submitted": 1} {+ if counts[action] != want {+ t.Errorf("%s = %d, want %d (%v)", action, counts[action], want, actions(mapped))+ }+ }+ command := findAction(t, mapped, "command.executed")+ if command.Command == nil || command.Command.Command != "npm test" {+ t.Errorf("command = %+v, want the split tool_use line's command joined to its result", command.Command)+ }+}++func TestSplitResponseUsageNeverTakesAStaleSnapshot(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl"}+ // The largest count wins wherever it sits, including ahead of a smaller one.+ lines := []string{+ streamed{session: "sess-1", uuid: "a", msgID: "msg_01B", requestID: "req_01B", block: thinkingBlock("x"), output: 7}.line(),+ streamed{session: "sess-1", uuid: "b", parent: "a", msgID: "msg_01B", requestID: "req_01B", block: textBlock("y"), output: 120}.line(),+ streamed{session: "sess-1", uuid: "c", parent: "b", msgID: "msg_01B", requestID: "req_01B", block: bashBlock("toolu_b", "ls"), output: 40}.line(),+ }+ usage := usageEvents(MapSession(ref, decodeFixture(t, lines), MapOptions{}))+ if len(usage) != 1 || outputOf(t, usage[0].Event) != 120 {+ t.Fatalf("usage = %d events, want one carrying 120", len(usage))+ }+}++func TestDistinctResponsesAreEachCounted(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl"}+ lines := []string{userLine("sess-1", "r1-prompt", "go")}+ lines = append(lines, splitResponse("sess-1", "r1", "msg_01C", "req_01C", 50)...)+ lines = append(lines, splitResponse("sess-1", "r2", "msg_01D", "req_01D", 80)...)+ mapped := MapSession(ref, decodeFixture(t, lines), MapOptions{})+ usage := usageEvents(mapped)+ if len(usage) != 2 {+ t.Fatalf("token.usage events = %d, want 2", len(usage))+ }+ if usage[0].Event.Event.ID == usage[1].Event.Event.ID {+ t.Fatal("two responses share an event id")+ }+ if got := sumOutput(t, mapped); got != 130 {+ t.Fatalf("output total = %d, want 50+80", got)+ }+}++func TestUsageWithoutAResponseIDIsCountedPerRecord(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl"}+ lines := []string{+ // No message.id: nothing ties these together, so each record is its own response, under+ // the event id it always had.+ streamed{session: "sess-1", uuid: "n1", block: textBlock("one"), output: 11}.line(),+ streamed{session: "sess-1", uuid: "n2", parent: "n1", block: textBlock("two"), output: 13}.line(),+ // message.id without requestId still identifies the response.+ streamed{session: "sess-1", uuid: "m1", parent: "n2", msgID: "msg_01E", block: thinkingBlock("x"), output: 2}.line(),+ streamed{session: "sess-1", uuid: "m2", parent: "m1", msgID: "msg_01E", block: textBlock("z"), output: 21}.line(),+ }+ usage := usageEvents(MapSession(ref, decodeFixture(t, lines), MapOptions{}))+ if len(usage) != 3 {+ t.Fatalf("token.usage events = %d, want 3", len(usage))+ }+ if usage[0].Event.Event.ID != claudeEventID("n1:usage") || usage[1].Event.Event.ID != claudeEventID("n2:usage") {+ t.Fatal("records without a message id changed event id")+ }+ if got := outputOf(t, usage[2].Event); got != 21 {+ t.Fatalf("message-id-only response output = %d, want 21", got)+ }+}++// A sweep can land between two block lines of one response. The cursor advances past what it read,+// and the next sweep must count only what the earlier one did not -- so the total is the final+// snapshot's, once, however the response is split across sweeps.+func TestIncrementalMapCountsASplitResponseOnce(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl"}+ lines := []string{userLine("sess-1", "p", "go")}+ lines = append(lines, splitResponse("sess-1", "r1", "msg_01F", "req_01F", 300)...)+ records := decodeFixture(t, lines)+ // Every split point: after the prompt, after each block line, after the result.+ for cut := 1; cut <= len(records); cut++ {+ first := MapSession(ref, records[:cut], MapOptions{})+ second := MapSession(ref, records, MapOptions{MinLine: records[cut-1].Line, SkipSessionStarted: true})+ total := sumOutput(t, first) + sumOutput(t, second)+ if total != 300 {+ t.Errorf("cut after line %d: output counted %d, want 300", records[cut-1].Line, total)+ }+ var input int64+ for _, item := range append(usageEvents(first), usageEvents(second)...) {+ if in := item.Event.GenAI.Usage.InputTokens; in != nil {+ input += *in+ }+ }+ if input != 4 {+ t.Errorf("cut after line %d: input counted %d, want 4", records[cut-1].Line, input)+ }+ }+}++func TestSplitResponseAcrossSweepsOnDiskTotalsOnceAndIsIdempotent(t *testing.T) {+ dir := t.TempDir()+ projects := filepath.Join(dir, "projects")+ sessionPath := filepath.Join(projects, "-tmp-repo", "sess-1.jsonl")+ statePath := filepath.Join(dir, "state", "claude.json")+ logPath := filepath.Join(dir, "runtime.jsonl")+ opts := CollectOptions{ProjectsDir: projects, StatePath: statePath, LogPath: logPath, Write: true, UserMode: true}++ all := []string{userLine("sess-1", "r1-prompt", "run the tests")}+ all = append(all, splitResponse("sess-1", "r1", "msg_01G", "req_01G", 312)...)+ all = append(all, splitResponse("sess-1", "r2", "msg_01H", "req_01H", 95)...)++ // Sweep one sees the first two block lines of the first response: the placeholder snapshot.+ writeFile(t, sessionPath, strings.Join(all[:3], "\n")+"\n")+ if _, err := CollectOnce(opts); err != nil {+ t.Fatalf("first sweep: %v", err)+ }+ // Sweep two sees the rest, including the line that carries the final count.+ writeFile(t, sessionPath, strings.Join(all, "\n")+"\n")+ if _, err := CollectOnce(opts); err != nil {+ t.Fatalf("second sweep: %v", err)+ }+ // Sweep three has nothing new.+ again, err := CollectOnce(opts)+ if err != nil {+ t.Fatalf("third sweep: %v", err)+ }+ if again.EventsEmitted != 0 {+ t.Fatalf("idempotent re-run emitted %d events", again.EventsEmitted)+ }++ report := tokens.Aggregate(readLog(t, logPath), tokens.Options{})+ want := tokens.Usage{InputTokens: 8, OutputTokens: 312 + 95, CacheReadInputTokens: 60000, CacheCreationInputTokens: 2400}+ if got := report.Totals; got.InputTokens != want.InputTokens || got.OutputTokens != want.OutputTokens ||+ got.CacheReadInputTokens != want.CacheReadInputTokens || got.CacheCreationInputTokens != want.CacheCreationInputTokens {+ t.Fatalf("report totals = %+v, want %+v", got, want)+ }++ // A from-scratch sweep over the finished file names the same response the same way and+ // reports the same totals.+ freshLog := filepath.Join(dir, "fresh.jsonl")+ if _, err := CollectOnce(CollectOptions{ProjectsDir: projects, StatePath: filepath.Join(dir, "fresh-state.json"), LogPath: freshLog, Write: true, UserMode: true}); err != nil {+ t.Fatalf("fresh sweep: %v", err)+ }+ fresh := readLog(t, freshLog)+ freshReport := tokens.Aggregate(fresh, tokens.Options{})+ if freshReport.Totals.OutputTokens != want.OutputTokens || freshReport.Totals.InputTokens != want.InputTokens || freshReport.EventsWithUsage != 2 {+ t.Fatalf("fresh totals = %+v (events %d), want %+v over 2 events", freshReport.Totals, freshReport.EventsWithUsage, want)+ }+ // Response-derived ids: the from-scratch event for each response is the one the incremental+ // sweeps wrote first, so the two logs agree on what to call it.+ incrementalIDs := map[string]bool{}+ for _, ev := range readLog(t, logPath) {+ if ev.Event.Action == "token.usage" {+ incrementalIDs[ev.Event.ID] = true+ }+ }+ for _, ev := range fresh {+ if ev.Event.Action == "token.usage" && !incrementalIDs[ev.Event.ID] {+ t.Errorf("from-scratch usage event %s (response %+v) was not written by the incremental sweeps", ev.Event.ID, ev.GenAI.Response)+ }+ }+}++func TestSidechainAndForkedTranscriptsCountEachResponseOnce(t *testing.T) {+ dir := t.TempDir()+ projects := filepath.Join(dir, "projects")+ project := filepath.Join(projects, "-tmp-repo")+ logPath := filepath.Join(dir, "runtime.jsonl")++ main := append([]string{userLine("sess-1", "r1-prompt", "explore")}, splitResponse("sess-1", "r1", "msg_01M", "req_01M", 200)...)+ writeFile(t, filepath.Join(project, "sess-1.jsonl"), strings.Join(main, "\n")+"\n")++ // A subagent's own API calls live in its own file, split the same way.+ sub := []string{+ streamed{session: "sess-1", uuid: "s-think", msgID: "msg_01S", requestID: "req_01S", block: thinkingBlock("look"), output: 3, sidechain: true, agentID: "a1"}.line(),+ streamed{session: "sess-1", uuid: "s-tool", parent: "s-think", msgID: "msg_01S", requestID: "req_01S", block: bashBlock("toolu_s", "ls"), output: 40, sidechain: true, agentID: "a1"}.line(),+ }+ subPath := filepath.Join(project, "sess-1", "subagents", "agent-a1.jsonl")+ writeFile(t, subPath, strings.Join(sub, "\n")+"\n")++ // A forked session replays the original's lines -- same message.id and requestId under a new+ // session id and new uuids -- and then continues with a response of its own.+ fork := append(splitResponse("sess-2", "f1", "msg_01M", "req_01M", 200), splitResponse("sess-2", "f2", "msg_01N", "req_01N", 60)...)+ forkPath := filepath.Join(project, "sess-2.jsonl")+ writeFile(t, forkPath, strings.Join(fork, "\n")+"\n")++ if _, err := CollectOnce(CollectOptions{ProjectsDir: projects, StatePath: filepath.Join(dir, "state.json"), LogPath: logPath, Write: true, UserMode: true}); err != nil {+ t.Fatalf("CollectOnce: %v", err)+ }+ events := readLog(t, logPath)+ report := tokens.Aggregate(events, tokens.Options{})+ if report.Totals.OutputTokens != 200+40+60 || report.EventsWithUsage != 3 {+ t.Fatalf("totals = %+v over %d events, want 300 output over 3 responses", report.Totals, report.EventsWithUsage)+ }+ var sawSubagent bool+ for _, ev := range events {+ if ev.Event.Action == "token.usage" && ev.GenAI != nil && ev.GenAI.Response != nil && ev.GenAI.Response.ID == "msg_01S" {+ sawSubagent = ev.GenAI.Agent != nil && ev.GenAI.Agent.ID == "a1" && outputOf(t, ev) == 40+ }+ }+ if !sawSubagent {+ t.Fatal("subagent response usage missing or not attributed to its agent")+ }+}++// When a sweep stops partway through a session (the retention window), the cursor must not land+// between a response's first counted line and the line its usage event sits on, or the next sweep+// would treat the response as already counted.+func TestPartialSweepDoesNotStrandAResponsesUsage(t *testing.T) {+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl"}+ lines := []string{+ userLine("sess-1", "p", "go"),+ streamed{session: "sess-1", uuid: "a", msgID: "msg_01P", requestID: "req_01P", block: bashBlock("toolu_a", "ls"), output: 8}.line(),+ // Claude Code runs a tool while the response is still streaming, so its result can land+ // between two block lines of the same response.+ toolResultLine("sess-1", "ra", "toolu_a", "ok", false),+ streamed{session: "sess-1", uuid: "b", parent: "ra", msgID: "msg_01P", requestID: "req_01P", block: bashBlock("toolu_b", "pwd"), output: 300}.line(),+ }+ records := decodeFixture(t, lines)+ mapped := MapSession(ref, records, MapOptions{})+ failed := -1+ for i, item := range mapped {+ if item.Event.Event.Action == "token.usage" {+ failed = i+ }+ }+ if failed < 0 {+ t.Fatalf("no usage event: %v", actions(mapped))+ }+ cursor := &Cursor{}+ advanceCursorPartial(cursor, mapped, failed)+ retry := MapSession(ref, records, MapOptions{MinLine: cursor.LastLine, SkipSessionStarted: true})+ if got := sumOutput(t, retry); got != 300 {+ t.Fatalf("after a stop at the usage event (cursor %d), the retry counted %d output tokens, want 300", cursor.LastLine, got)+ }+ var input int64+ for _, item := range usageEvents(retry) {+ input += *item.Event.GenAI.Usage.InputTokens+ }+ if input != 4 {+ t.Fatalf("retry counted %d input tokens, want 4", input)+ }+}diff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdxindex b9e056e3..8aa8556d 100644--- a/docs/runtimes/claude-code.mdx+++ b/docs/runtimes/claude-code.mdx@@ -122,6 +122,8 @@ Detailed tool inputs can contain sensitive command arguments, paths, URLs, searc`beacon endpoint claude sync` reads committed Claude Code transcripts after Claude has written them. The cursor is stored in Beacon endpoint state, not in Claude's directory, and tracks files by line so scheduled runs do not re-append the same records. A partly written trailing record is left for the next sweep.+Claude Code writes one streamed API response as several transcript lines, one per content block (thinking, text, each tool call), and every line carries a copy of the response's `message.usage`. The sync emits one `token.usage` event per response, not per line: lines are grouped by `message.id` and `requestId`, and the event carries the snapshot with the largest output count, because lines written before the stream finished carry a placeholder output count. When a sweep lands between two lines of one response, the next sweep adds only what the later lines report beyond what was already counted, so the total is the same however the response is split across sweeps. A forked or resumed session that replays earlier responses into another file is counted once when both files are read in the same sweep.+Run `beacon endpoint claude sync --watch`, or schedule one-shot sweeps, if you want the poll path to stay current. The live OTLP and hook paths remain the real-time integrations; the poll path is for backfill and catch-up.### Large backfills and log rotation