Codex: surface standalone account/rateLimits/updated app-server events

[heavygee]

Context

The Codex usage indicator (#847) reads rate-limit data from `session.metadata.codexUsage`, which is populated by `normalizeCodexUsage` in `cli/src/codex/utils/codexUsage.ts`.

`normalizeCodexUsage` only extracts rate-limit data when it is piggy-backed on a `thread/tokenUsage/updated` event. The codex app-server also emits a separate `account/rateLimits/updated` event when subscription windows reset or when credits are added / spent, but `appServerEventConverter.ts` currently drops those:

```ts
// cli/src/codex/utils/appServerEventConverter.ts
case 'thread/tokenUsage/updated':
return makeTokenCountEvent(payload)
// account/rateLimits/updated is not handled - falls through, dropped
```

Impact

The indicator only updates rate-limit state when the user sends a turn. A user who blew their weekly window 4 hours ago and is waiting for it to reset will see stale '100%' on the gauge until they send a turn that triggers a token_count event - by which point they're already trying to send and getting blocked.

Fix shape

Two options:

1. Handle account/rateLimits/updated: add a converter that produces a synthetic token_count-shaped payload carrying only the rate-limit deltas, so `normalizeCodexUsage` can consume it without restructuring. The resulting `CodexUsage` patch keeps the existing fields and just refreshes `rateLimits`.

2. Split rate-limit extraction: extract rate-limit parsing into its own normalizer that can be called independently of token-count payloads. Cleaner but bigger refactor.

Option 1 is the minimum useful fix - one converter case plus a token_count payload synth.

Related

• Codex usage indicator with cross-flavor budget gauge shape (rebase of #537) #847 (the PR that introduces the current narrow-extraction shape)
• feat(web+cli+hub): cross-flavor agent budget/quota gauges in composer (umbrella) #846 (umbrella: cross-flavor agent budget gauges)

[github-actions]

Verified in the current tree: this report matches the code path. account/rateLimits/updated is explicitly ignored by the Codex app-server event converter, while thread/tokenUsage/updated is converted into a token_count event. Downstream, the web normalizer only processes Codex usage from token_count and currently requires token totals (inputTokens/outputTokens or snake_case equivalents), so a standalone rate-limit-only update would need either a synthetic compatible payload or a separate rate-limit normalizer.

Option 1 looks like the smallest change surface based on the current code: add a converter case for account/rateLimits/updated, produce an event shape the existing usage path can accept, and add converter/normalizer coverage for a rate-limit-only payload.

Relevant code:

• cli/src/codex/utils/appServerEventConverter.ts:589 - account/rateLimits/updated currently returns an empty event list.
• cli/src/codex/utils/appServerEventConverter.ts:699 - thread/tokenUsage/updated becomes { type: 'token_count', info }.
• cli/src/codex/codexRemoteLauncher.ts:2271 - parent token_count events are forwarded into the session message stream.
• web/src/chat/normalizeAgent.ts:54 - Codex usage normalization reads token usage from the token_count info payload.
• web/src/chat/normalizeAgent.ts:75 - normalization returns null if token totals are missing.
• web/src/chat/normalizeAgent.ts:633 - only data.type === 'token_count' enters this Codex usage normalization branch.
• cli/src/codex/utils/appServerEventConverter.test.ts:468 - existing test coverage covers scoped thread/tokenUsage/updated, but I did not find coverage for account/rateLimits/updated.

---

HAPI Bot