feat(codex): retain native session usage snapshots for chat

Verify typed ThreadTokenUsage/TokenUsageBreakdown/Thread/Turn against openai/codex@6fb1c3903d. 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.
This commit is contained in:
2026-10-21 00:06:11 +01:00
parent 3e62ed7979
commit 83b60990d2
4 changed files with 315 additions and 0 deletions
+15
View File
@@ -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"`
+26
View File
@@ -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
}
}
}
+113
View File
@@ -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()
}
+161
View File
@@ -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")
}
}