feat(usage): redeem Codex reset credits from the Limits tab

[juliusmarminge]

Follow-up to #9507, carrying over the reset-credit redemption from #9421.

Codex grants a reset credit when it has rate-limited an account unfairly ("Thanks for using Codex! You've been granted one free rate limit reset."). Redeeming one clears the current 5h/weekly windows. The Limits tab now shows how many are banked and when the next expires, with a confirmed Use a reset credit action.

How it works

• ServerProviderUsageLimits.resetCredits carries the count and soonest expiry; the Codex probe reads it from the same account/rateLimits/read it already makes.
• ProviderInstance.consumeResetCredit is a new optional hook — account-level, so it sits beside refreshModels rather than on the thread-routed adapter. The Codex driver implements it over a short-lived app-server (via withCodexAppServerClient, factored out of the status and skills probes which duplicated the setup), then re-probes.
• Single-flight per instance with one idempotency key kept until Codex reports an outcome, so a retry after a timeout does not open a second attempt.
• New provider.consumeResetCredit RPC under the operate scope; the outcome (reset / nothingToReset / noCredit / alreadyRedeemed) is shown inline.

Only Codex reports credits today. A provider without the hook gets a clear "does not bank reset credits" error; one without credits shows nothing.

Screenshots

The local Codex row with one banked credit (the same account via the CLIProxyAPI hub above it shows no credit, as expected — the hub does not relay them):

Close-up of the row:

Clicking it opens the confirmation; nothing is sent until Use credit:

Verification

• Mapper tests for the credit summary; provider, contract, and Usage page suites pass; typecheck clean.
• Verified against a real Codex Pro account holding one credit: summary and expiry render, the confirm dialog opens. Not redeemed — that would spend the credit.

Written by Claude Fable 5 via Claude Code; design and single-flight approach from @StiensWout's #9421.

---

Note

Medium Risk
Redemption spends real account credits over a new RPC; correctness depends on per-account locking and idempotency, though disabled instances and non-Codex providers are rejected explicitly.

Overview
Adds end-to-end redemption of banked Codex rate-limit reset credits from the Limits UI on web and mobile, backed by a new operate-scoped provider.consumeResetCredit RPC.

Contracts and server: ServerProviderUsageLimits can include resetCredits (count + next expiry). Codex probes attach that from account/rateLimits/read. Optional ProviderInstance.consumeResetCredit is implemented for Codex via a scoped app-server call to account/rateLimitResetCredit/consume, then a limits refresh. CodexResetCreditCoordinator serializes redemptions per Codex account directory, reuses one idempotency key until Codex returns an outcome, and times out hung requests. withCodexAppServerClient is extracted so status, skills, and redemption share the same short-lived app-server setup.

Clients: Limits rows show banked credits and a confirmed Use a reset credit action that calls serverEnvironment.consumeResetCredit and surfaces outcomes (reset, nothingToReset, etc.) or errors.

Web usage sources (same PR): Adding/removing CLIProxyAPI hubs and the add dialog target a selected connected environment (with picker when several are connected), gated by operate access—not only the primary environment.

^{Reviewed by Cursor Bugbot for commit 98f32e6. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Codex reset-credit redemption from the Usage Limits tab

• Adds a CodexResetCreditCoordinator service that serializes redemptions per account, reuses the idempotency key on failure, and clears it on success, bounded by a 20-second timeout.
• Adds the providerConsumeResetCredit WebSocket RPC, scoped to the orchestration operate authorization, which resolves a provider instance, invokes its reset-credit operation, and refreshes the usage snapshot.
• Maps Codex rate-limit reset-credit data into the provider usage-limit contract with an available count and earliest expiry.
• Adds reset-credit controls to both web and mobile Usage Limits views, gated by environment operate access, and reworks the web page to scope source add/remove and provider actions to the owning environment.
• Risk: CodexDriver.create now requires CodexResetCreditCoordinator in its service context; registry and runtime test layers in ProviderInstanceRegistryLive.test.ts, ProviderRegistry.test.ts, and server.ts were updated to provide it, but any out-of-tree provider driver composition will fail to build.

^{Macroscope summarized 98f32e6.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful main measurement shown below.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.5 KiB	13.7 KiB	+227 B (+1.6%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	−7 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.7 KiB	+234 B (+3.5%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.0 KiB	58.5 KiB	+1.5 KiB (+2.6%)	66.4 KiB	✅
Codex	Live turn messages	8	10	+2 (+25.0%)	21	✅
Claude	Total thread wire	13.8 KiB	13.7 KiB	−12 B (−0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	+10 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.7 KiB	6.7 KiB	−22 B (−0.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	59.3 KiB	59.3 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	10	10	0 (0.0%)	21	✅

Baseline: 3e2c1a6 · PR result: 98f32e6 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a new, irreversible Codex account action with server-side coordination, authorization, RPC plumbing, and new web/mobile controls. It also modifies the auth package and broadens environment settings edits, so the production and access-control behavior should receive human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

Backend behavior added here (driver-level reset-credit redemption plus the new provider.consumeResetCredit RPC) is currently covered only by the pure codexResetCreditsToContract unit test. Consider a focused test for the redemption path — single-flight under the semaphore, idempotency-key reuse across a failed attempt, and the follow-up snapshot.refresh — using the existing child-process test layers (see apps/server/src/provider/Layers/CodexProvider.test.ts / Drivers/AntigravityDriver.test.ts), so the external app-server is the only thing stubbed.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 3e6727c. Configure here.}