feat(quota): expose per-account OAuth and API-key usage

[lidge-jun]

Summary

• Add credential-scoped quota reads for xAI, Cursor, Kimi and Command Code alongside existing Anthropic/Kiro/Antigravity readers; keep Meta Muse passive and cache-only.
• Expose probe/passive/unsupported capability on cheap account/key lists, with opt-in per-key enrichment reusing existing quota readers. Do not activate credentials, mutate the configured active key, or publish inactive-key readings into provider-wide caches.
• Bind new readings to credential/destination identity and recheck it at safe response projection. Preserve missing, failed, passive and measured-zero states.

Stack (merge bottom-up):

1. fix(usage): distinguish unresolved fallback models and reject missing policies #3582 — attribution/policy foundation.
2. This PR — credential-scoped quota API (base codex/provider-usage-attribution).
3. Current/all-account views — next child, consumes this API.

Depends on #3582. Review this layer's diff only. Most added lines are synthetic credential/race regression cases; the API contract and its readers stay together so no unsupported reader is advertised between layers.

Verification

• No local test, typecheck, build, lint or scan commands ran for this layer; user explicitly requires remote CI only.
• New route regressions cover cheap/no-probe lists, per-key values, unchanged active selection, removed/replaced identity, final projection guard, true zero, failure clearing and passive no-network.
• Provider regressions cover the four added OAuth readers, key isolation/cache/force behavior and pure legacy key listing.
• Independent implementation/security review passed, including the cache-age and async-failure repairs. The Kimi default-key-mode finding is fixed in768e5a004 and its review thread is resolved. All four backend shards and common gates passed on that exact head; remaining platform checks are still required before merge.
• Commit and push used --no-verify to avoid local suites/hooks.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Maintainer authorization: admin merge bottom-up only after successful exact-head CI; no release or live-runtime deployment. Lower stack branches are retained until the stack settles.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: d84be501-de2c-4c4e-98d4-1977b013d08c

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

---

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.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T02:44:49.204982Z	9792498	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 58 / 80

설명

이 PR은 provider-usage 스택의 두 번째 층입니다. 아래는 #3582(attribution/policy)이고, 위는 곧 올 current/all-account 뷰입니다. 지금 dev HEAD는 Windows 스위트 안정화(#3548/#3549/#3550/#3555) 쪽이 방금 들어갔고, 이 PR의 베이스는 codex/provider-usage-attribution이라 Windows 작업과 직접 겹치지는 않습니다. 다만 머지 순서는 반드시 #3582 → 이 PR → UI 층입니다.

하는 일을 쉽게 말하면 이렇습니다. 예전에는 Anthropic/Kiro/Antigravity 계정만 계정별 쿼터를 제대로 볼 수 있었습니다. 이제는 xAI, Cursor, Kimi, Command Code도 같은 방식으로 계정(또는 API 키)마다 사용량을 읽습니다. Meta Muse는 여전히 네트워크를 치지 않고 캐시에 남아 있는 값만 보여 줍니다(passive).

관리 API도 값이 싸게 동작하도록 나눴습니다. GET /api/oauth/accounts와 GET /api/providers/keys는 기본이 로컬 목록이고, 각 줄에 quotaMode만 붙입니다(probe / passive / unsupported). 진짜로 프로브하려면 ?quota=1을 붙이고, 캐시를 건너뛰려면 ?refresh=1을 붙입니다. 문서(docs-site/.../web-dashboard.md)에도 그 계약이 적혀 있습니다.

보안·정합성 쪽에서 눈에 띄는 장치는 두 가지입니다. 첫째, 레거시 단일 apiKey를 읽을 때 풀을 시드하지 않고 투영만 합니다. GET이 설정을 바꾸면 안 되니까 맞는 방향입니다. 둘째, OAuth/키 프로브 결과에 isCurrent() 가드를 달고, 응답 JSON으로 내보내기 직전에 다시 검사합니다. 프로브 중에 활성 키나 계정이 바뀌면 quota: null + quotaUnavailable: true로 떨어집니다. xAI fetch에는 redirect: "error"도 넣었습니다.

새 파일 src/providers/quota-key-accounts.ts는 키별 쿼터 캐시를 프로세스 로컬로만 둡니다. 라우팅용 provider 캐시에 절대 안 섞는다고 명시되어 있고, 로스터는 최대 4개 동시 워커로 읽습니다. clearProviderQuotaCache()가 키 캐시도 같이 비우도록 연결돼 있습니다.

테스트는 tests/providers/provider-account-quota.test.ts, provider-api-keys.test.ts, tests/server/provider-account-quota-routes.test.ts에 합성 credential/race 케이스가 많이 추가됐습니다. 레이아웃 JSON에도 라우트 테스트가 등록됐습니다. 본문대로 로컬 스위트는 돌리지 않았고(--no-verify 푸시), 원격 CI만 봅니다. 지금 체크 스냅샷 기준으로 gates와 test 3/4가 실패한 상태라, exact-head CI가 초록이 되기 전에는 머지하면 안 됩니다.

라인 단위로 보면 아래가 확인·판단 포인트입니다.

src/providers/quota-key-accounts.ts - 새 모듈. 키 캐시/로스터/identity/isCurrent 계약의 중심. provider-wide 캐시와 섞이면 안 된다는 주석과 구현이 맞는지 유지보수 시 계속 지켜야 한다
src/providers/api-keys.ts listProviderApiKeys - 레거시 apiKey를 GET에서 시드하지 않고 투영만 함. 첫 mutation에서만 시드되는 기존 약속과 맞는지 확인
src/providers/quota.ts supportsPerAccountQuota / explicitAccountReader - xai·cursor·kimi·command-code를 probe 집합에 추가. meta-muse는 passive로 분리 유지
src/providers/quota.ts fetchXaiQuota - 시그니처가 accessToken 컨텍스트 주입형으로 바뀜. 계정 스코프 리더와 메인 리포트 경로가 같은 헬퍼를 쓰는지 회귀 주의
src/server/management/oauth-account-routes.ts GET /api/oauth/accounts - wantQuota가 quotaMode===probe로 바뀜. 투영 직전 isCurrent/provider 참조 가드 추가
src/server/management/oauth-account-routes.ts GET /api/providers/keys - quota=1일 때만 fetchProviderApiKeyQuotas. DTO에 isCurrent를 넣지 않음
CI gates / test 3/4 - 현재 fail. exact-head 재실행·원인 확인 전 머지 금지

메인테이너의 판단이 필요한 지점

• #3582가 아직 open인데, 이 PR을 스택으로 먼저 리뷰만 할지, fix(usage): distinguish unresolved fallback models and reject missing policies #3582 머지 후에만 손댈지
• 로컬 스위트 금지(원격 CI만) 정책을 이 층에서도 그대로 유지할지
• Windows 스위트(test: budget every sub-floor internal wait that gates on a child or server (Windows stack 5/5) #3558/ci(windows): six shards instead of four, ceiling unchanged (Windows stack 6/6) #3572 등)와 provider-usage 스택 중 어느 쪽을 dev 머지 우선으로 둘지
• CI gates/test 3/4 실패가 이 층 회귀인지, 베이스(fix(usage): distinguish unresolved fallback models and reject missing policies #3582) 잔여인지

너의 추천

• 지금은 머지하지 말고, #3582가 dev에 안착한 뒤 bottom-up으로만 머지하세요.
• 그 전에 exact-head CI에서 gates와 test 3/4 실패를 먼저 고치거나 원인 댓글을 남기세요.
• 리뷰 범위는 이 층의 diff(쿼터 API·라우트·키 캐시)만 보면 됩니다. UI 층은 다음 PR로 미루세요.

이 댓글은 grok-bot이 작성했습니다

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9792498520

ℹ️ 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".