From 83b60990d21234f744cb71426847125abf93e0f2 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 00:06:11 +0100 Subject: [PATCH] feat(codex): retain native session usage snapshots for chat Verify typed ThreadTokenUsage/TokenUsageBreakdown/Thread/Turn against openai/codex@6fb1c3903d42e3cc7da2c89e3a045fe0ce137af4. Use native totalTokens and latest-call context tokens without re-adding cached/reasoning subsets. Replay bounded per-connection snapshots and clear on room/source release. Cost stays unavailable: no subscription USD usage is reported by this notification. Throughput stays unavailable even with native Turn.durationMs because neither last-call nor cumulative-session output is a compatible turn-specific numerator. Thread readback exposes no token usage; no extra reads, resume, or live provider calls added. Checks: go test -race ./internal/codex; go vet ./internal/codex; go test ./internal/server ./internal/protocol; git diff --check. --- internal/codex/chat.go | 15 ++ .../codex/testdata/token-usage-updated.json | 26 +++ internal/codex/usage.go | 113 ++++++++++++ internal/codex/usage_test.go | 161 ++++++++++++++++++ 4 files changed, 315 insertions(+) create mode 100644 internal/codex/testdata/token-usage-updated.json create mode 100644 internal/codex/usage.go create mode 100644 internal/codex/usage_test.go diff --git a/internal/codex/chat.go b/internal/codex/chat.go index ecb2fcc5..bee57440 100644 --- a/internal/codex/chat.go +++ b/internal/codex/chat.go @@ -65,6 +65,8 @@ type Chat struct { connectionErr error compactions map[string]protocol.ChatEventFrame endedTurns map[string]string + usage map[string]usageSnapshot + usageOrder uint64 } type pendingForm struct { @@ -157,6 +159,7 @@ func (c *Chat) Close() { return } c.closed = true + c.usage = nil c.mu.Unlock() c.cancel() _ = c.conn.Close(websocket.StatusNormalClosure, "") @@ -197,6 +200,7 @@ func (c *Chat) readLoop() { func (c *Chat) failPending(err error) { c.mu.Lock() c.compactions = nil + c.usage = nil c.connectionErr = err c.approvals = nil c.forms = map[string]pendingForm{} @@ -274,6 +278,10 @@ func (c *Chat) respond(id json.RawMessage, result any) { func (c *Chat) emit(frame protocol.ChatEventFrame) { c.mu.Lock() + if frame.Kind == protocol.ChatEventUsage && !c.retainUsageLocked(frame) { + c.mu.Unlock() + return + } if frame.Kind == protocol.ChatEventCompaction { if frame.Compaction == nil { c.mu.Unlock() @@ -333,6 +341,9 @@ func (c *Chat) subscribe(id string) chan protocol.ChatEventFrame { c.subs[id] = map[chan protocol.ChatEventFrame]struct{}{} } c.subs[id][ch] = struct{}{} + if snapshot, ok := c.usage[id]; ok { + ch <- snapshot.frame + } if frame, ok := c.compactions[id]; ok { ch <- frame } @@ -715,6 +726,10 @@ func (c *Chat) handleServerRequest(msg rpcMessage) { } func (c *Chat) handleNotification(msg rpcMessage) { + if msg.Method == "thread/tokenUsage/updated" { + c.receiveUsage(msg.Params) + return + } if msg.Method == "serverRequest/resolved" { var p struct { ThreadID string `json:"threadId"` diff --git a/internal/codex/testdata/token-usage-updated.json b/internal/codex/testdata/token-usage-updated.json new file mode 100644 index 00000000..187ee3b8 --- /dev/null +++ b/internal/codex/testdata/token-usage-updated.json @@ -0,0 +1,26 @@ +{ + "method": "thread/tokenUsage/updated", + "params": { + "threadId": "thread", + "turnId": "turn_new", + "tokenUsage": { + "total": { + "totalTokens": 12000, + "inputTokens": 10000, + "cachedInputTokens": 7000, + "cacheWriteInputTokens": 1000, + "outputTokens": 2000, + "reasoningOutputTokens": 1500 + }, + "last": { + "totalTokens": 3500, + "inputTokens": 3000, + "cachedInputTokens": 2000, + "cacheWriteInputTokens": 100, + "outputTokens": 500, + "reasoningOutputTokens": 400 + }, + "modelContextWindow": 258400 + } + } +} diff --git a/internal/codex/usage.go b/internal/codex/usage.go new file mode 100644 index 00000000..46e97de2 --- /dev/null +++ b/internal/codex/usage.go @@ -0,0 +1,113 @@ +package codex + +import ( + "encoding/json" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Native types verified against openai/codex@6fb1c3903d42e3cc7da2c89e3a045fe0ce137af4: +// codex-rs/app-server-protocol/schema/typescript/v2/{ThreadTokenUsage, +// TokenUsageBreakdown,ThreadTokenUsageUpdatedNotification,Thread,Turn}.ts. +// Pointers deliberately tolerate older/partial payloads without inventing zeros. +type tokenUsageBreakdown struct { + TotalTokens *int64 `json:"totalTokens"` + InputTokens *int64 `json:"inputTokens"` + CachedInputTokens *int64 `json:"cachedInputTokens"` + CacheWriteInputTokens *int64 `json:"cacheWriteInputTokens"` + OutputTokens *int64 `json:"outputTokens"` + ReasoningOutputTokens *int64 `json:"reasoningOutputTokens"` +} + +type threadTokenUsage struct { + Total tokenUsageBreakdown `json:"total"` + Last tokenUsageBreakdown `json:"last"` + ModelContextWindow *int64 `json:"modelContextWindow"` +} + +func nonnegativeUsage(value *int64) *int64 { + if value == nil || *value < 0 { + return nil + } + return value +} + +func (c *Chat) receiveUsage(raw json.RawMessage) { + var p struct { + ThreadID string `json:"threadId"` + TurnID string `json:"turnId"` + Usage *threadTokenUsage `json:"tokenUsage"` + } + if json.Unmarshal(raw, &p) != nil || p.ThreadID == "" || p.Usage == nil { + return + } + u := &protocol.ChatUsage{ + Scope: "session", TotalTokens: nonnegativeUsage(p.Usage.Total.TotalTokens), + ContextTokens: nonnegativeUsage(p.Usage.Last.TotalTokens), + ContextWindow: nonnegativeUsage(p.Usage.ModelContextWindow), + } + if n := nonnegativeUsage(p.Usage.Total.InputTokens); n != nil { + u.InputTokens = int(*n) + } + if n := nonnegativeUsage(p.Usage.Total.OutputTokens); n != nil { + u.OutputTokens = int(*n) + } + // Native totalTokens is authoritative. Cached input and reasoning output + // are subsets, not additional usage. Last is the latest model call, not + // the whole turn: see TokenUsageInfo::append_last_usage in protocol.rs. + // Turn.durationMs cannot be paired with last.outputTokens (multi-call + // turns), or session outputTokens. No compatible turn total is exposed. + // Cost is not reported here either; subscription cost is not zero USD. + // Thread readback has no usage field, so do not add RPCs or resume a + // thread merely to fetch counters; reattach replays retained notifications. + c.emit(protocol.ChatEventFrame{SessionID: p.ThreadID, NativeTurnID: p.TurnID, Kind: protocol.ChatEventUsage, Usage: u}) +} + +const retainedUsageLimit = 256 + +type usageSnapshot struct { + frame protocol.ChatEventFrame + order uint64 +} + +// Called under mu. Each update replaces the full session snapshot, including +// unavailable fields. Native usage never modifies starting/turns/busy state. +func (c *Chat) retainUsageLocked(frame protocol.ChatEventFrame) bool { + if c.closed || c.connectionErr != nil || frame.SessionID == "" || frame.Usage == nil { + return false + } + if frame.NativeTurnID != "" { + current := c.turns[frame.SessionID] + if current == "" { + current = c.endedTurns[frame.SessionID] + } + if current != "" && current != frame.NativeTurnID { + return false + } + } + if c.usage == nil { + c.usage = map[string]usageSnapshot{} + } + c.usageOrder++ + c.usage[frame.SessionID] = usageSnapshot{frame: frame, order: c.usageOrder} + if len(c.usage) > retainedUsageLimit { + var oldest string + var order uint64 + for id, snapshot := range c.usage { + if oldest == "" || snapshot.order < order { + oldest, order = id, snapshot.order + } + } + delete(c.usage, oldest) + } + return true +} + +// ReleaseShells is the existing room/source ownership-release hook. Retain a +// snapshot across ordinary stream reattach, but not after the room is released. +func (c *Chat) ReleaseShells(sessionID string) { + c.mu.Lock() + delete(c.commands, sessionID) + delete(c.usage, sessionID) + c.mu.Unlock() +} diff --git a/internal/codex/usage_test.go b/internal/codex/usage_test.go new file mode 100644 index 00000000..a636d8e8 --- /dev/null +++ b/internal/codex/usage_test.go @@ -0,0 +1,161 @@ +package codex + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// Synthetic values in the current upstream typed notification shape; no live +// Codex process, provider, configuration, or session is used by these tests. +func usageFixture(t *testing.T) rpcMessage { + t.Helper() + raw, err := os.ReadFile("testdata/token-usage-updated.json") + if err != nil { + t.Fatal(err) + } + var msg rpcMessage + if err := json.Unmarshal(raw, &msg); err != nil { + t.Fatal(err) + } + return msg +} + +func usageTestChat() *Chat { + return &Chat{subs: map[string]map[chan protocol.ChatEventFrame]struct{}{}, turns: map[string]string{"thread": "turn_new"}, starting: map[string]bool{"thread": true}} +} + +func TestUsageNativeSnapshotAndDuplicate(t *testing.T) { + c := usageTestChat() + ch := c.subscribe("thread") + other := c.subscribe("other") + for range 2 { + c.handleNotification(usageFixture(t)) + f := <-ch + u := f.Usage + if f.Kind != protocol.ChatEventUsage || f.SessionID != "thread" || f.NativeTurnID != "turn_new" || f.MessageID != "" || f.Part != nil || f.Step != nil { + t.Fatalf("usage is not an item/step: %+v", f) + } + if u.Scope != "session" || *u.TotalTokens != 12000 || *u.ContextTokens != 3500 || *u.ContextWindow != 258400 || u.InputTokens != 10000 || u.OutputTokens != 2000 { + t.Fatalf("snapshot added subsets, cumulative context, or duplicate: %+v", u) + } + if u.CostUSD != nil || u.OutputTokensPerSecond != nil || u.RateBasis != "" { + t.Fatalf("unreported metrics invented: %+v", u) + } + } + if len(other) != 0 || c.turns["thread"] != "turn_new" || !c.starting["thread"] { + t.Fatal("usage leaked across threads or changed busy state") + } + c.handleNotification(rpcMessage{Method: "thread/tokenUsage/updated", Params: json.RawMessage(`{"threadId":"other","tokenUsage":{"total":{"totalTokens":42}}}`)}) + if len(ch) != 0 || (<-other).Usage.TotalTokens == nil { + t.Fatal("foreign session notification misrouted") + } +} + +func TestUsageMissingZeroAndInvalid(t *testing.T) { + c := usageTestChat() + ch := c.subscribe("thread") + for _, raw := range []string{ + `{}`, `{"threadId":"thread"}`, `{"threadId":"thread","tokenUsage":null}`, + `{"tokenUsage":{}}`, `{"threadId":"thread","tokenUsage":{"total":{"totalTokens":"bad"}}}`, + } { + c.handleNotification(rpcMessage{Method: "thread/tokenUsage/updated", Params: json.RawMessage(raw)}) + } + if len(ch) != 0 { + t.Fatal("missing or invalid source became fabricated usage") + } + c.handleNotification(usageFixture(t)) + <-ch + // A full sparse snapshot clears prior values instead of leaving stale values. + c.receiveUsage(json.RawMessage(`{"threadId":"thread","tokenUsage":{"total":{"totalTokens":0,"inputTokens":0,"outputTokens":0},"last":{"totalTokens":0},"modelContextWindow":0}}`)) + f := <-ch + if f.NativeTurnID != "" || f.Usage.TotalTokens == nil || *f.Usage.TotalTokens != 0 || f.Usage.ContextTokens == nil || *f.Usage.ContextTokens != 0 || f.Usage.ContextWindow == nil || *f.Usage.ContextWindow != 0 { + t.Fatalf("reported zero lost or turn invented: %+v", f) + } + c.receiveUsage(json.RawMessage(`{"threadId":"thread","tokenUsage":{"total":{"totalTokens":-1},"last":{},"modelContextWindow":null}}`)) + u := (<-ch).Usage + if u.TotalTokens != nil || u.ContextTokens != nil || u.ContextWindow != nil || u.CostUSD != nil || u.OutputTokensPerSecond != nil { + t.Fatalf("unavailable values became zero or stale: %+v", u) + } +} + +func TestUsageStaleTurnCannotRegressOrFreeBusySlot(t *testing.T) { + c := usageTestChat() + ch := c.subscribe("thread") + c.handleNotification(usageFixture(t)) + <-ch + c.receiveUsage(json.RawMessage(`{"threadId":"thread","turnId":"turn_old","tokenUsage":{"total":{"totalTokens":10}}}`)) + if len(ch) != 0 || *c.usage["thread"].frame.Usage.TotalTokens != 12000 || c.turns["thread"] != "turn_new" { + t.Fatal("stale native turn changed snapshot or busy state") + } + c.handleNotification(rpcMessage{Method: "turn/completed", Params: json.RawMessage(`{"threadId":"thread","turn":{"id":"turn_new","status":"completed","startedAt":100,"completedAt":110,"durationMs":10000}}`)}) + <-ch + // Even with native timing, neither session output nor last model-call + // output is a compatible whole-turn numerator. Do not fabricate a rate. + u := c.usage["thread"].frame.Usage + if u.OutputTokensPerSecond != nil || u.RateBasis != "" { + t.Fatal("duration paired with incompatible output counter") + } + c.receiveUsage(json.RawMessage(`{"threadId":"thread","turnId":"turn_old","tokenUsage":{"total":{"totalTokens":10}}}`)) + if len(ch) != 0 { + t.Fatal("old turn regressed completed turn usage") + } +} + +func TestUsageReattachRetainedWithoutExtraReadback(t *testing.T) { + reads := 0 + c := modelTestChat(t, func(method string, _ json.RawMessage) any { + if method != "thread/turns/list" { + t.Errorf("metrics added unexpected RPC: %s", method) + } + reads++ + return json.RawMessage(`{"data":[]}`) + }) + c.handleNotification(usageFixture(t)) + stop := errors.New("snapshot received") + for range 2 { + err := c.Stream(context.Background(), "thread", nil, func(f protocol.ChatEventFrame) error { + if f.Usage == nil || *f.Usage.TotalTokens != 12000 || *f.Usage.ContextTokens != 3500 { + t.Fatalf("reattach lost snapshot: %+v", f) + } + return stop + }) + if !errors.Is(err, stop) { + t.Fatal(err) + } + } + if reads != 2 { + t.Fatalf("metrics added reads: %d", reads) + } + c.ReleaseShells("thread") + ch := c.subscribe("thread") + if len(ch) != 0 || len(c.usage) != 0 { + t.Fatal("released room retained usage") + } +} + +func TestUsageRetentionBoundAndTransportLoss(t *testing.T) { + c := usageTestChat() + for i := range retainedUsageLimit + 10 { + c.receiveUsage(json.RawMessage(fmt.Sprintf(`{"threadId":"thread_%d","tokenUsage":{"total":{"totalTokens":%d}}}`, i, i))) + } + if len(c.usage) != retainedUsageLimit { + t.Fatalf("unbounded usage cache: %d", len(c.usage)) + } + if _, ok := c.usage["thread_0"]; ok { + t.Fatal("oldest usage was not evicted") + } + c.failPending(errors.New("transport lost")) + if len(c.usage) != 0 { + t.Fatal("transport ownership retained usage") + } + c.handleNotification(usageFixture(t)) + if len(c.usage) != 0 { + t.Fatal("lost source regained retained usage") + } +}