feat: track provider usage and project weekly quota

[Aditya190803]

What Changed

• Added provider usage normalization and merge utilities for Codex/Claude quota payloads.
• Extended provider snapshots and websocket config/update flow to carry normalized usage buckets.
• Fixed usage percent math to avoid double-scaling low percentages derived from usage/limit.
• Fixed usage cache merge behavior so stale cached usage is dropped when a newer provider snapshot omits usage.
• Added/updated tests covering usage normalization, merge behavior, and stale cache handling.

Why

Issue #228 asks for accurate quota visibility. This PR adds provider usage projection and makes it robust under incremental updates so UI quota values stay correct. The follow-up fixes address reviewer-reported edge cases that could misreport low usage percentages or retain stale usage after newer snapshots.

UI Changes

• Settings provider quota bars now render normalized usage/reset data from provider snapshots.
• No layout redesign.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Closes #228

Note

Track provider rate limit usage and display weekly quota in settings

• Adds ServerProviderUsage contract with fiveHour and weekly buckets, normalizing rate-limit payloads from both Claude and Codex providers into a standard shape via normalizeProviderUsageFromRateLimits in providerUsage.ts.
• Extends Claude and Codex provider status probes to collect account metadata and rate-limit snapshots, attaching account, rateLimits, and usage fields to provider snapshots.
• Adds probeCodexAccountState in codexAppServer.ts to request account/rateLimits/read alongside account data, with a grace window for missing rate-limit responses.
• Renders a ProviderUsageRows component in the settings panel showing a progress bar, remaining percentage, and reset timestamp for each provider quota bucket.
• Client in serverState.ts now eagerly requests a provider refresh on config snapshot receipt, applying results immediately without waiting for stream updates.

^{Macroscope summarized c44983f.}

---

Note

Medium Risk
Medium risk because it extends provider probing/status snapshots and client refresh behavior, which can affect provider startup/perf and the accuracy of displayed quota data across Codex/Claude.

Overview
Adds first-class provider quota tracking by introducing ServerProviderUsage (with normalized fiveHour/weekly buckets) and wiring it through provider status snapshots.

Updates Codex and Claude provider probes to collect account metadata plus rate-limit payloads, normalize them into usage, and include these fields on ServerProvider snapshots; Codex’s app-server probe now requests account/rateLimits/read with a short grace window for missing responses.

Surfaces the data in the web settings UI via quota progress rows, and updates the client to eagerly call refreshProviders() on initial config load/snapshot so quota/usage appears without waiting for stream updates. Tests are added/updated across contracts, provider registry/probes, ingestion activity projection, and usage normalization/merge edge cases.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d3cfd9df-b826-4476-b7a1-fb3de2204c9d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11eab91d87

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Drop stale usage cache when provider snapshot has no usage

In mergeUsageCacheFromProviders, stale entries are never evicted because mergeProviderUsage(cachedUsage, provider.usage) returns cachedUsage whenever the new snapshot omits usage, so the mergedUsage !== undefined branch always keeps the cache and bypasses shouldKeepCachedUsage. This means a newer provider snapshot (checkedAt later than cached updatedAt) can still be served with outdated quota buckets via serverGetConfig and server.providersUpdated.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid double-scaling low usage percentages

derivePercentFromUsage converts absolute usage to percent with (usage / limit) * 100, then passes that result to normalizePercent, which multiplies any value <= 1 by 100 again. For low-but-valid percentages (for example usage=1, limit=1000), this reports 10% instead of 0.1%, causing major quota misreporting near the start of a window.

Useful? React with 👍 / 👎.

[Aditya190803]

I cleaned up the branch history to reduce review noise and make the change set easier to reason about.

What changed:

1. Rebased onto latest main.
2. Removed merge/sync churn from feature history.
3. Squashed follow-up fixups into logical commits.
4. Kept implementation scope unchanged (no new feature surface beyond already discussed fixes).

Current commit structure:

1. feat(contracts): add normalized provider usage and quota bucket schemas
2. feat(server): normalize provider rate-limit usage and stabilize usage cache updates
3. feat(web): render provider quota usage buckets in settings

Behavior/correctness included in this cleaned history:

1. Fix low-percent double-scaling risk in usage normalization.
2. Drop stale cached usage when newer provider snapshots omit usage.
3. Clamp over-limit utilization and suppress no-op provider update pushes.
4. Preserve tests across contracts/server/web for quota projection and cache behavior.

Validation run locally:

1. bun fmt
2. bun lint
3. bun typecheck

No functional intent change; this is primarily a history hygiene pass for clearer review.

[juliusmarminge]

Please add screenshots

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces substantial new functionality for tracking and displaying provider usage quotas across Claude and Codex providers. There are unresolved review comments identifying potential bugs in usage percentage calculations and cache staleness handling that warrant human attention before merging.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[Aditya190803]

@juliusmarminge this branch got pretty janky and inconsistent so i rebuilt it cleanly

new PR here: #1732

closing this one to avoid confusion