From 3e62ed797916936ab7ca21d7c2d6d06457e549f7 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 00:01:17 +0100 Subject: [PATCH] feat(protocol): distinguish reported chat metrics from unavailable values --- internal/protocol/chat.go | 19 +++++++++++++++---- internal/protocol/chat_usage_test.go | 22 ++++++++++++++++++++++ 2 files changed, 37 insertions(+), 4 deletions(-) create mode 100644 internal/protocol/chat_usage_test.go diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index 91e82e5e..3816a201 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -461,11 +461,22 @@ type ChatStep struct { Intermediate bool `json:"intermediate,omitempty"` } -// ChatUsage is the token and cost total of a turn. +// ChatUsage carries native usage snapshots. Rich metrics are pointers so zero +// reported by a harness remains distinguishable from an unavailable value. +// Session snapshots replace previous values; consumers must not sum updates. type ChatUsage struct { - InputTokens int `json:"input_tokens,omitempty"` - OutputTokens int `json:"output_tokens,omitempty"` - Cost float64 `json:"cost,omitempty"` + InputTokens int `json:"input_tokens,omitempty"` + OutputTokens int `json:"output_tokens,omitempty"` + Cost float64 `json:"cost,omitempty"` + Scope string `json:"scope,omitempty"` + TotalTokens *int64 `json:"total_tokens,omitempty"` + ContextTokens *int64 `json:"context_tokens,omitempty"` + ContextWindow *int64 `json:"context_window,omitempty"` + CostUSD *float64 `json:"cost_usd,omitempty"` + OutputTokensPerSecond *float64 `json:"output_tokens_per_second,omitempty"` + // RateBasis distinguishes a generation interval from a whole turn (which + // can include tools/waits). Never estimate tokens from text/character counts. + RateBasis string `json:"rate_basis,omitempty"` } // ChatShell is the state of one shell command the agent started, carried by a diff --git a/internal/protocol/chat_usage_test.go b/internal/protocol/chat_usage_test.go new file mode 100644 index 00000000..dfd5e1f7 --- /dev/null +++ b/internal/protocol/chat_usage_test.go @@ -0,0 +1,22 @@ +package protocol + +import ( + "encoding/json" + "strings" + "testing" +) + +func TestChatUsageUnknownAndReportedZeroAreDistinct(t *testing.T) { + unknown, _ := json.Marshal(ChatUsage{}) + if strings.Contains(string(unknown), "total_tokens") || strings.Contains(string(unknown), "cost_usd") { + t.Fatal("unknown metrics became zero") + } + zeroTokens := int64(0) + zeroCost := float64(0) + known, _ := json.Marshal(ChatUsage{Scope: "session", TotalTokens: &zeroTokens, CostUSD: &zeroCost}) + for _, want := range []string{`"total_tokens":0`, `"cost_usd":0`, `"scope":"session"`} { + if !strings.Contains(string(known), want) { + t.Fatalf("missing %s in %s", want, known) + } + } +}