Codex usage indicator with cross-flavor budget gauge shape (rebase of #537)

[heavygee]

What

Rebases @dsus4wang's stalled #537 onto current main (179 commits caught up since April), then extends the indicator to handle premium-credits accounts, fix unit-rendering bugs, and lay a flavor-agnostic shape for the cross-flavor budget gauge umbrella (#846).

Original PR by @dsus4wang. The first 3 commits on this branch preserve his authorship intact:

• 8f5f164e Add Codex session list/resume flow to web new-session UI
• 3f4f33dc restore Codex session history
• 2f32998b add Codex usage indicator

The remaining 4 commits are follow-up work on top:

• 753b51b8 feat: surface credits + rate_limit_reached_type for premium accounts
• c448e537 fix: drop $ prefix + format credit balance (rate-card-correct rendering)
• b0fad40e fix: ring shows worst constraint, not just context
• 97dc5414 refactor: split ring meaning - centre = context, colour = effective state

Why the extension

Operator-tested @dsus4wang's indicator against a live Codex Pro account on 2026-06-09. Three issues surfaced that the original PR couldn't have caught on a Plus-tier test account:

1. Premium-credits accounts have no time-window rate limits. When subscription is exhausted and billing falls back to credits, codex emits rate_limits.primary=null + secondary=null + credits.has_credits=false. The original indicator was silent on this entire state - showed only the context-window % even when the account was hard-blocked.

2. Ring semantics drifted between states. The same circle meant 'context fill' in the normal case but 'usage exhaustion' when blocked. Operator caught it: 'the circle that WAS showing you context now shows you red 100 meaning no more usage'.

3. A Pro account that exhausts the subscription window but tops up credits is not blocked - codex falls back to credit billing transparently. The original would have read this as 'weekly 100%, red, you're done' even though the user can keep sending. False alarm vs false safety in the same widget.

What changed

Premium-credits support

• CodexUsageSchema (shared) gains credits (hasCredits / unlimited / balance) plus optional rateLimitReachedType / planType / limitId. JSON-only, no SCHEMA_VERSION bump.
• normalizeCodexUsage (cli) extracts those fields from the token_count payload's rate_limits root.
• Credits rendered as a bare count, no $ prefix. Codex's rate card (reference) makes credits a token-mix-dependent billing unit (~$0.04/credit at Pro tier, not 1:1 USD). String-to-number parser handles the precision-preserving balance shapes codex sends ("250.0000000000", "0", "0.0000000000").

Ring metaphor: centre = task room, colour = account constraint

• New AgentBudgetState shape under shared/src/agentBudget.ts. Flavor-agnostic - declares only axes (each with pressure 0-100), an operationalAxisId (which axis the centre number shows), and an effective state (green / amber / red / blocked) computed per-flavor.
• AgentBudgetIndicator (web) is a flavor-agnostic renderer that consumes the state. The Codex adapter (codexBudgetAdapter.ts) is the only Codex-specific module on the web side.
• Adapter encodes the Codex-Pro covering rule: subscription window at cap AND credits > 0 → amber, not red, with the credits axis flagged covering. The popover renders a left-accent on the covering axis so the user sees why the gauge isn't red.
• Centre number is always the operational axis (context for LLM agents). Ring colour is always the effective state. The two no longer fight; the centre number never silently changes meaning.

Cross-flavor seed (umbrella #846)

• AgentBudgetState is intentionally not Codex-specific. A toClaudeBudgetState adapter (or Cursor / Gemini equivalents) can drop in without touching the indicator. The Codex adapter is the reference implementation; Claude is queued next.

Visual change

State	Before	After
Context 80%, no rate-limit data	Ring 80 blue	Ring 80 blue (unchanged)
Context 80%, weekly 100%, credits 246	Ring 80 blue (silently hides the weekly cap)	Ring 80 amber; popover shows 1 Week Usage 100% (dominant, accented) and Credits 246 covering exhausted subscription window (blue accent)
Context 80%, no windows, credits 0 (blocked)	Ring 80 blue (silently misrepresents block)	Ring 80 red; tooltip 'Blocked: subscription window and credits both exhausted'; popover shows Credits 0 subscription / top-up exhausted (critical, dominant)

Testing

• bun typecheck + bun run test: 114 test files, 958 tests, all pass on this branch
• Manual: validated against a live Codex Pro account on the operator's session - weekly at 100%, 246 credits, indicator correctly reads amber with covering accent
• New test coverage: 13 tests in codexBudgetAdapter.test.ts covering the operator-caught scenarios (premium-credits shape, covering / blocked / red transitions, transition-window edge where both subscription axes are present at 100 + credits 0, unlimited credits exemption, etc); plus refreshed codexUsageSchema.test.ts and codexUsage.test.ts for the cli normalizer

Known follow-ups (out of scope for this PR)

• i18n: the indicator strings ('Context Window', '5h Usage', 'Credits', 'subscription / top-up exhausted', etc) are English-only. The original PR was English-only as well; the cross-flavor refactor preserves that. Should route through t() in a follow-up so zh-CN locale gets coverage too.
• account/rateLimits/updated standalone events: appServerEventConverter.ts currently only surfaces rate limits when piggy-backed on thread/tokenUsage/updated. Standalone rate-limit-update events from the codex app-server are dropped. Worth surfacing in a follow-up so rate-limit transitions reach the UI without waiting for the next turn.
• Claude / Cursor / Gemini adapters: the AgentBudgetState shape is the cross-flavor foundation. Claude adapter is queued next (depends on confirming Anthropic ratelimit headers reach HAPI's hook stream); Cursor is data-blocked until they expose telemetry; Gemini follows.

Related

• Original PR: [codex] add Codex usage indicator #537 (by @dsus4wang)
• Umbrella issue: feat(web+cli+hub): cross-flavor agent budget/quota gauges in composer (umbrella) #846

Made with Cursor

[github-actions]

Findings

• [Major] Codex history import flag is dropped before runner launch — the new web resume flow sends importHistory: true and the hub includes it in the machine RPC payload, but the machine-side SpawnHappySession handler never reads or forwards that field into spawnSession. As a result, remote web resumes execute hapi codex resume <thread> without --hapi-import-history, so the newly selected Codex transcript history is not imported into the fresh HAPI session. Evidence: hub/src/sync/rpcGateway.ts:142, with the drop at cli/src/api/apiMachine.ts:252-277.
  Suggested fix:

  const {
      directory,
      sessionId,
      resumeSessionId,
      machineId,
      approvedNewDirectoryCreation,
      agent,
      model,
      effort,
      modelReasoningEffort,
      yolo,
      permissionMode,
      token,
      sessionType,
      worktreeName,
      importHistory
  } = params || {}
  
  const result = await spawnSession({
      directory,
      sessionId,
      resumeSessionId,
      importHistory,
      machineId,
      approvedNewDirectoryCreation,
      agent,
      model,
      effort,
      modelReasoningEffort,
      yolo,
      permissionMode,
      token,
      sessionType,
      worktreeName
  })

Questions

• None.

Summary

• Review mode: initial
• Found one Major issue in the remote Codex resume/import path. Residual risk: I did not run the full test suite in this automation pass; add a machine RPC boundary test that asserts importHistory reaches spawnSession.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

[Major] This adds importHistory to the hub-to-machine RPC payload, but the machine-side SpawnHappySession handler never destructures or forwards it into spawnSession, so the runner never emits --hapi-import-history for web-selected Codex resumes. That means the new session selector resumes the Codex thread but does not import the existing transcript history.

Suggested fix:

const {
    directory,
    sessionId,
    resumeSessionId,
    machineId,
    approvedNewDirectoryCreation,
    agent,
    model,
    effort,
    modelReasoningEffort,
    yolo,
    permissionMode,
    token,
    sessionType,
    worktreeName,
    importHistory
} = params || {}

const result = await spawnSession({
    directory,
    sessionId,
    resumeSessionId,
    importHistory,
    machineId,
    approvedNewDirectoryCreation,
    agent,
    model,
    effort,
    modelReasoningEffort,
    yolo,
    permissionMode,
    token,
    sessionType,
    worktreeName
})