fix(server): show limits for Claude setup-token accounts#24128

Claude setup-token usage responses and streamed rate-limit windows now update usage-limit state. Complete updates can replace a failed probe state. The documentation describes when setup-token limits appear and how long the last reading remains available.

Changes: Claude usage-limit ingestion

Layer / File(s)	Summary
Complete update contract and state handling packages/contracts/src/providerUsageLimits.ts, packages/provider-core/src/server/usageLimits.ts, packages/provider-core/src/server/usageLimits.test.ts	Usage-limit updates now support an optional complete flag. Applying a complete update clears the unavailable status. Tests cover replacing probeFailed, initializing state, and retaining unsupported.
Claude setup-token limit ingestion apps/server/src/provider/claudeUsageLimits.ts, apps/server/src/provider/ClaudeProvider.ts, apps/server/src/provider/claudeUsageLimits.test.ts, docs/user/usage.md	Streamed unifiedWindows entries are mapped, with the event’s own value taking precedence for a matching window. Setup-token unavailable responses report probeFailed, and provider paths pass tokenSource. Tests and documentation cover these behaviors.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

mermaid

1	sequenceDiagram
2	participant ClaudeCLI
3	participant ClaudeProvider
4	participant claudeUsageResponseToLimits
5	participant claudeRateLimitEventToUpdate
6	participant applyUsageLimitsUpdate
7	ClaudeProvider->>claudeUsageResponseToLimits: get_usage response and tokenSource
8	claudeUsageResponseToLimits-->>ClaudeProvider: probeFailed for unavailable setup-token limits
9	ClaudeCLI->>ClaudeProvider: rate_limit_info with unifiedWindows
10	ClaudeProvider->>claudeRateLimitEventToUpdate: streamed rate-limit event
11	claudeRateLimitEventToUpdate-->>ClaudeProvider: complete windows update
12	ClaudeProvider->>applyUsageLimitsUpdate: apply complete update

Possibly related PRs

• pingdotgg/t3code#24119: Targets the same setup-token usage-limit flow with alternative controls for streamed limits and update completeness.
• pingdotgg/t3code#24412: Changes the same Claude unifiedWindows event parsing and window mapping.

Suggested reviewers: macroscopeapp

A partial streamed update may remove the unavailable notice before a weekly reading exists. This remains a bounded issue to address or explicitly accept before merging.

^Failed Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Description check	Warning	The description clearly explains the problem, change, scope, and verification. However, it does not include explicit maintainer approval for the linked issue or explain why this change qualifies as a …	Add the Scope and approval section. Link the maintainer approval comment for the issue or discussion, or explain why this focused fix qualifies as an obvious bug fix that does not need prior approval.

^Passed Passed checks: 3 passed

Check name	Status	Explanation
Title check	Passed	The title is concise, specific, and accurately describes the primary change: displaying usage limits for Claude setup-token accounts.
Linked Issues check	Passed	Issue #24114 requires setup-token Claude accounts to show a notice before a turn, show streamed session and weekly limits after a turn, and retain those limits between turns. The PR maps both setup-to…
Out of Scope Changes check	Passed	The changes support issue #24114. The complete contract field and provider-core handling support reliable application of Claude streamed windows. Tests and usage documentation cover the requested be…

Full details: Linked Issues check

Explanation

Issue #24114 requires setup-token Claude accounts to show a notice before a turn, show streamed session and weekly limits after a turn, and retain those limits between turns. The PR maps both setup-token sources to probeFailed with a next-turn notice, decodes all valid unifiedWindows entries, applies the event window override, and marks the update complete. Provider-core handling clears probeFailed for complete updates and preserves published windows after later failed probes. Tests cover the source gate, streamed windows, malformed entries, override behavior, persistence, and unsupported accounts.

Full details: Out of Scope Changes check

Explanation

The changes support issue #24114. The complete contract field and provider-core handling support reliable application of Claude streamed windows. Tests and usage documentation cover the requested behavior. Other Claude authentication sources retain unsupported handling. No unrelated change is demonstrated.

Full details: Description check

Explanation

The description clearly explains the problem, change, scope, and verification. However, it does not include explicit maintainer approval for the linked issue or explain why this change qualifies as a small, obvious fix without prior approval, as the template requires.

Resolution

Add the Scope and approval section. Link the maintainer approval comment for the issue or discussion, or explain why this focused fix qualifies as an obvious bug fix that does not need prior approval.

🧪 Generate unit tests (beta)

• Create a new PR

Verified in a real dev environment

Partial verification only. The Claude setup-token fix remains unverified because this VM has no authenticated Claude account. No code changes or pushes.

• Read the description, diff, and discussion. Checked GitHub main 15fe2832727893cbdd2214383f9f971474849695 in a separate worktree, installed with vp i, and started the real dev server in the background. Added a local project through the web UI pointing at the real repository. A real Codex gpt-6.1-sol turn returned VERIFY_MAIN_OK.
• Stopped main before starting exact PR head 18ffef8e17c10b3778eedecb99f0adf0beb928da, again with vp i and isolated state. Used Playwright from the repository and /usr/bin/google-chrome to add the project, select gpt-6.1-sol, and send two real turns. Responses were VERIFY_PR_OK and VERIFY_FOLLOWUP_OK in the same thread.
• Settings → Providers → Refresh provider status completed. Codex remained available; Claude correctly remained unauthenticated. Usage → Limits opened on both revisions. Both showed Codex: Codex could not read usage (JSON-RPC -32600)., so this proxy cannot prove Codex limit readings either.
• Ran the existing focused tests through Blacksmith: vp test run apps/server/src/provider/claudeUsageLimits.test.ts packages/provider-core/src/server/usageLimits.test.ts. Both files passed, 20 tests total. These are supporting checks, not proof of the live Claude path.

Runtime transcript:

Real Codex follow-up, trimmed to the turn and response; playback and seeking checked after upload:

real gpt-6.1-sol follow-up on the exact pr head

Claude authentication blocker in the running PR client:

claude is unauthenticated in the running pr client

Not verified

• The original setup-token bug could not be reproduced on main. No CLAUDE_CODE_OAUTH_TOKEN or file-descriptor token is configured, and claude auth status reports no login.
• Consequently, the PR startup notice, Session/Weekly bars from a real Claude unifiedWindows event, preservation after provider refresh, and restart behavior remain unverified. A real subscription setup token is needed to run that scenario. No mocks, fabricated events, fixtures, or demo turns were used.
• Subscription-login Claude, API-key/Bedrock/proxy Claude limits, and Codex subscription limits were not exercised with valid accounts.
• Native iOS/Android, Electron, macOS, Windows, remote relay, and tunnel behavior were not exercised on this Linux web-client run.

Verdict: unable to verify the changed behavior here. Passing focused tests and successful Codex turns do not establish that the Claude fix works.