Quota Provider Adapter Notes

Provider Adapters & Quirks

This reference details the credential sources, endpoint contracts, quota window structures, error handling, and vendor-specific quirks for the providers with dedicated sections below. Muse has no section here; its specification lives in the README provider notes.

---

1. Anthropic Claude (claude)

• Credential Sources (evaluated in order):
  1. env (CLAUDE_CODE_OAUTH_TOKEN): Takes top precedence because Claude Code resolves environment tokens before opening local stores. It has no expiresAt or refresh token; never invent either and never route it through delegated refresh. claudeEnvOauthToken in src/lib/claude-profile.ts is the single reader. claudeCredentialContextId includes an env marker to prevent serving stored-credential cache snapshots for environment sessions.
  2. oauth-file: Reads the local profile credentials file.
  3. keychain: macOS Keychain item matching Claude Code's validated user account selector. Ambiguous service-only queries are forbidden. Value reads require an existing non-secret access marker (0600) or --allow-keychain-prompt. Keychain failures (including exit 44) must never retire the cache.
• Quota Windows:
  • Windows can include five_hour, seven_day, seven_day_opus, and extra_usage.
  • When the OAuth usage payload includes a limits array, that array is authoritative over top-level fields. It exposes active limits, including model-scoped limits (e.g. Fable) via scope.model.display_name, assigned window ID model:<slug>.
• Soft Expiry: A stored-expired, refreshable Claude token definitively rejected by the endpoint produces authStatus: expired_refreshable (a soft failure retaining cache), never auth_required.
• Native Quota Probe: Bounded opt-in native inference quota probe lives in src/providers/claude-native-quota.ts. Keep it distinct from delegated refresh.
• Delegated Refresh: Permitted via claude doctor only when no Claude Code process is running (src/lib/running-processes.ts).

---

2. OpenAI Codex (codex)

• Credential Sources (evaluated in order):
  1. Native $CODEX_HOME/auth.json or ~/.codex/auth.json OAuth.
  2. Pi openai-codex and any sibling openai-codex-* entries in the same Pi auth.json.
  3. CLI fallback via the app-server JSON-RPC probe.
• Multi-Account Lanes:
  • src/providers/accounts.ts collects distinct Pi entries and the native codex-home lane.
  • Accounts are matched and deduplicated on the ChatGPT account ID reported by the probe/store, never on email or token strings.
  • If a native reading matches an existing Pi lane account ID, it collapses into that lane, publishing whichever reading is fresher; coalescing never removes the shared codex-home cache slot by name, so another account's snapshot cannot be discarded. Contract: README Multiple accounts.
• Authorization Rules: OAuth access token is authoritative. An expired id_token alone must never mark auth-json expired or skip the bearer probe. Never send OPENAI_API_KEY to ChatGPT quota endpoints.
• Bound Conflict: Codex model windows are metered separately as additional_rate_limits/rateLimitsByLimitId. If an inherited base weekly window reads zero while a model window retains allowance, quota-axi publishes effectiveAvailability[].boundConflict and reports scope unknown rather than asserting exhaustion.
• Delegated Refresh: Codex app-server JSON-RPC probe acts as both CLI fallback and delegated refresh.

---

3. Cursor (cursor)

• Credential Sources:
  1. Editor state-vscdb: Reads $CURSOR_STATE_DB or local Cursor state database via sqlite3 -readonly for cursorAuth values. If sqlite3 is missing, report sqlite3_unavailable without attempting package installation.
  2. Cursor CLI (cursor-agent in src/providers/cursor-cli-credential.ts): macOS uses cli-keychain; Linux uses cli-authfile reading accessToken from $CURSOR_CLI_CONFIG or XDG cursor/auth.json.
  • Both sources operate independently; Cursor Desktop is not required.
  • Never read refreshToken or cursor-refresh-token. No delegated refresh exists for Cursor.
• Quota Windows:
  • Windows from GetCurrentPeriodUsage: included_usage, auto_usage, api_usage, spend_limit.
  • Grok Bot from GetSandUsageStatus: Metered separately under scope grok_bot. Kept off the IDE all_models bound. Do not invoke trial, banked-reset, or machine registration RPCs.
• Monthly Billing Cycle Calculation:
  • Resets on subscription renewal date. startsAt is calculated from billingCycleStart or by stepping billingCycleEnd back one calendar month (clamped to the shorter month).
  • Never substitute a fixed 30-day duration.

---

4. GitHub Copilot (copilot)

• Credential Sources (COPILOT_SOURCE_ORDER):
  1. api: $GITHUB_COPILOT_APPS_JSON or local github-copilot/apps.json.
  2. copilot-cli:keychain: Native secure store for standalone Copilot CLI (macOS Keychain or Windows Credential Manager via src/lib/windows-credential.ts).
  3. gh:hosts.yml: Narrow block-mapping reader in src/providers/gh-cli-credential.ts that extracts only the github.com host oauth_token. Never read the gh keyring or GH_TOKEN/GITHUB_TOKEN.
• Scope & Entitlement:
  • Public GitHub tokens only. Enterprise tokens are treated as unavailable on the public endpoint.
  • Quota snapshot windows include chat, completions, and premium_interactions.
  • If the endpoint returns entitlement without numeric quota windows, return a fresh report with windows: [] rather than inventing numbers or percentages.
  • Native CLI readings (source: cli) are never cached.

---

5. xAI Grok (grok)

• Credential Sources:
  1. Grok CLI session auth: $GROK_AUTH_JSON, inline $GROK_AUTH, $GROK_AUTH_PATH, or ~/.grok/auth.json. Recognizes official Grok Build OIDC records scoped to auth.x.ai with auth_mode: oidc.
  2. Pi xai entry: $PI_CODING_AGENT_DIR/auth.json (OAuth or API key).
• Usability & Fallback:
  • Usable if either CLI or Pi source is usable. True sign-out requires all applicable sources unavailable or rejected.
  • Consumer credits are fetched via GetGrokCreditsConfig. If rejected by an official Build/Pi OAuth token, probe the no-spend model catalog (cli-chat-proxy.grok.com/v1/models for Build, api.x.ai/v1/models for Pi), discard the response body, and report authStatus: usable with empty windows. Never derive quota from model presence.
  • Pi API key establishes usable, unmeasurable model auth.
  • Delegated refresh: Permitted via grok models. Cache fallback accepts only web source snapshots.

---

6. Moonshot Kimi (kimi)

• Quota Windows:
  • /usages returns a map (limit_5h, limit_7d, limit_month_total, limit_month_code) or legacy usage + limits[]. Ratios are read strictly from used_ratio.
  • limit_month_code is the code-typed share of limit_month_total, not a separate cap. It carries percentUsed and shareOf: month_total. It never bounds a scope or derives a remaining allowance. Default TOON formats it as an attention share row; TUI displays percent used of parent.
  • Any declared entry lacking a usable ratio is marked in state.untrustedWindowIds (usages:<key>), degrading the bound to partial.
• Dual Deployment Environments:
  • src/providers/kimi-code-config.ts reads config.toml (storage, key, oauth_host, base_url).
  • Region allowlist restricts requests to Kimi Code's two official deployments (global vs mainland China). Never pair one deployment's token with another's host origin.
  • If configuration cannot be parsed conclusively, mark environment_unconfirmed and open no credential to avoid cross-environment cache corruption.
• Pi Source & Expiry:
  • Pi kimi-coding entry (api_key or oauth). Refreshable expired credentials produce non-definitive failures preserving cache. Refresh token values are never read or exchanged.

---

7. Z.AI GLM (zai)

• Credential Sources: Pi auth.json zai api_key first (source pi:zai), then opencode auth.json (zai-coding-plan or alias).
• Endpoint: Single GET to /api/monitor/usage/quota/limit with the key in a Bearer Authorization header.
• Window Decoding: Tolerant schema mapping using magic numbers:
  • TOKENS_LIMIT / CREDIT_LIMIT: unit: 3, number: 5 -> five_hour; unit: 6, number: 1 -> weekly.
  • TIME_LIMIT -> mcp_month.
  • Unrecognized or duplicate limits degrade to kind: "unknown" windows named in state.untrustedWindowIds.
• Bound Separation: zaiSemantics keeps usage windows under all_models bound and mcp_month under tools bound.

---

8. OpenCode Go (opencode-go)

• Quota Semantics: Rolling 5-hour ($12), weekly ($30), and monthly ($60) stacked plan caps jointly bind all_models. Requests are blocked when any cap is hit.
• Limitations: The endpoint supplies no cycle duration of its own, so plan-declared cycle lengths fill in when the payload carries none (a payload-supplied duration still wins) and pace, runway, and selection are measurable. The endpoint provides no Zen balance. An exhausted plan window with balance fallback reports plan-exhausted with fallback named in prose.
• Sources: defaultOpenCodeGoCredentialSources (supports opt-in Pi auth). Read-only; no refresh delegate.

---