@narumitw/pi-usage 0.60.3 → 0.60.4

package/README.md

@@ -9,17 +9,7 @@ xAI OAuth subscription reporting follows the reviewed Grok Build contract and ru
 ## ✨ Features
 
 - Shows active-account usage and next actions through `/usage`.
-- Reports OpenAI Codex subscription windows, credits, resets, and model-specific buckets.
-- Reports Kimi For Coding plan windows, resets, and separately labeled booster-wallet currency.
-- Reports Moonshot AI Global and China API account balances in their native currencies.
-- Reports MiniMax Global and China Token Plan windows or pay-as-you-go API balance.
-- Reports GitHub Copilot allowances and OpenRouter per-key limits and spending windows.
-- Reports exact DeepSeek API balances with separate CNY and USD values.
-- Reports OpenCode Go plan windows and Z.AI Coding Plan quotas.
-- Reports Fireworks rated API spend for the last 30 days with per-series subtotals and account selection.
-- Reports Vercel AI Gateway credit balance and lifetime spend.
-- Reports Baseten organization Model APIs spend after credits for the last 30 days.
-- Reports xAI OAuth subscription allowances and credits.
+- Reports subscription allowances, API balances, and spending for the supported providers listed below without mixing their billing semantics.
 - Toggles persistent Codex Fast routing through `/fast` or the usage menu.
 - Redeems eligible Codex resets only after fresh account matching and explicit confirmation.
 - Refreshes one or all configured providers with bounded concurrency while preserving partial results.
@@ -61,51 +51,18 @@ Run `/fast` to toggle Fast mode for a supported active Codex model.
 
 ## 💬 Commands
 
-Open the manager with:
+| Command | Purpose |
+| --- | --- |
+| `/usage` | Query the active provider's usage, then manage provider queries, preferences, or eligible Codex resets. |
+| `/fast` | Toggle Fast mode for the active supported Codex model. |
 
-```text
-/usage
-```
+Both commands support TUI and RPC, accept no arguments, and reject print and JSON modes.
+Cross-provider queries require an explicit interactive choice; there are no provider-ID, `--refresh`, or `--all` arguments.
+Requests use the matched provider credentials; see [Security and privacy](#-security-and-privacy).
+Fast mode uses more plan allowance; see [Codex Fast mode](#codex-fast-mode) for eligibility and when changes apply.
 
-In TUI or RPC mode, the menu first queries the active model provider and then offers these actions:
-
-```text
-Refresh current usage
-Settings
-Turn Fast mode on/off       # Supported current Codex models only
-Redeem usage limit reset…   # Current Codex OAuth accounts only
-View another configured provider…
-View all configured providers…
-Close
-```
-
-`/usage` accepts no arguments, including `--refresh`, a provider ID, or `--all`.
-Cross-provider requests require an explicit interactive choice.
-Escape returns from provider selection or closes the root menu.
-Print and JSON modes reject `/usage` because they cannot host the interactive flow.
-The extension owns the cancellable live-query progress view because it streams provider work and supports in-flight abort.
-
-### Provider targets
-
-A target is the provider-owned account, organization, project, team, or workspace used for one usage query.
-Providers without target discovery query immediately, and a single returned target is selected automatically without writing settings.
-When several targets are available, `/usage` remembers an explicit selection by provider and reuses it only while it remains in a fresh listing.
-A missing remembered target returns **Selection required** instead of querying another target silently.
-The current provider then offers **Select <target>…**, while a ready current or individually viewed provider offers **Change <target>…**.
-
-Selecting another provider may open one Pi target prompt after that provider is queried lazily.
-Cancelling the prompt changes nothing.
-Auth and target membership are revalidated before an explicit selection is saved, then both are resolved again before billing is queried.
-**View all configured providers…** never opens nested target prompts: unresolved providers remain visible with guidance to view them individually.
-Background status refresh also stays non-interactive and shows `selection required` until `/usage` completes the choice.
-Fireworks accounts are the first implementation of this provider-neutral flow.
-
-For the current OpenAI Codex provider, **Redeem usage limit reset…** first checks fresh earned-reset details.
-When details are available, you select a reset and review its exact effect before confirmation.
-**No, go back** is the safe default and cancellation before confirmation sends no mutation.
-After confirmation, the reset operation cannot be cancelled from its progress view; session replacement or shutdown still aborts owned work.
-A transport failure offers **Try again** with the same redemption request ID so the backend can treat an uncertain retry idempotently.
-Successful, already-completed, not-needed, and no-credit outcomes are reported separately, then usage and the statusline are refreshed for the still-current account.
+Codex reset redemption requires a freshly matched current OAuth account and explicit confirmation; **after confirmation, its progress view cannot cancel the reset**.
+Read the [query and reset guide](./docs/operations.md) for target selection, cancellation, and safe retry behavior.
 
 ## ⚙️ Settings
 
@@ -135,7 +92,6 @@ It sends `service_tier: "priority"` while enabled and explicit `service_tier: "d
 The statusline adds `fast` only while the preference is effective, for example `codex fast 59% ↻ 2h30m` with the default reset countdown.
 Unsupported models and custom or proxy origins are left unchanged.
 
-`/fast` supports TUI and RPC mode, accepts no arguments, and rejects print or JSON mode before mutation.
 A toggle affects provider requests whose payload hook starts after the save; a request already sent is unchanged.
 Repair or remove an invalid file, then run `/reload` before trying the toggle again.
 
@@ -152,245 +108,27 @@ Turn **Codex reset countdown** Off in the TUI Settings screen, or set it to `fal
 
 ## 📋 Provider semantics
 
-### OpenAI Codex
-
-- Provider ID: `openai-codex`
-- Semantics: ChatGPT consumer subscription limits
-- Source: the Codex usage and earned-reset endpoints using Pi's resolved runtime authorization
-- Displayed data: returned duration-based windows, resets, credits, earned usage-limit resets, and additional model buckets
-- Reset mutation: `POST /wham/rate-limit-reset-credits/consume` with a unique redemption request ID and, when available, the selected opaque credit ID
-- Statusline examples: `codex 59% ↻ 2h30m 61% ↻ 2d15m`, `codex fast 59% ↻ 2h30m`, or `codex spark 100% ↻ 2h30m`. Set `codexStatusResetCountdown` to `false` for the legacy `5h` and `wk` labels.
-
-The statusline selects a returned bucket that matches the current Codex model when one is available.
-Unlike `pi-codex-usage`, this successor intentionally has no Codex CLI fallback because the CLI may be logged into a different account than Pi's active runtime account.
-
-Reset redemption is available only when Codex is the current provider.
-Pi's freshly resolved access token must exactly match an OAuth credential from Pi's stored login or a compatible credential source.
-`pi-usage` forwards only the bearer authorization and matching `chatgpt-account-id` to the official ChatGPT origin.
-API-key credentials, configured-but-not-current Codex accounts, account changes during the flow, and custom/proxy origins fail before mutation.
-Backend-provided titles and descriptions are sanitized for terminal display.
-Opaque credit and account IDs are never shown or persisted by the extension.
-
-### Kimi For Coding
-
-- Provider ID: `kimi-coding`
-- Semantics: Kimi Coding Plan request windows plus a separate Extra Usage booster wallet
-- Source: `GET https://api.kimi.com/coding/v1/usages` using Pi's freshly resolved runtime Bearer credential
-- Displayed plan data: the weekly summary, returned sub-windows, used and remaining request percentages, and valid reset times
-- Displayed wallet data: balance, monthly spend, and monthly charge limit
-- Statusline examples: `kimi 99% 5h 96% wk` or `kimi 95% 1d`
-
-Both Pi API-key credentials and Pi OAuth credentials are accepted because current Pi resolves each form as Bearer authorization for the same official Kimi inference origin.
-The extension queries the fixed usage endpoint only when both the selected model origin and the effective resolved-auth origin are `https://api.kimi.com`.
-Custom and proxy origins fail before network access, redirects are rejected, and the credential is never sent to an override from Kimi Code's environment-specific development path.
-
-Plan buckets remain integer request counts and are rendered with their source-defined windows.
-Unknown units, duplicate windows, missing counts, invalid timestamps, and malformed rows remain unavailable rather than receiving guessed semantics.
-Booster-wallet `amount` and `amountLeft` values use Kimi's first-party conversion of 1,000,000 fixed-point units per cent, while monthly values already arrive in cents.
-Wallet values retain their currency and stay separate from plan requests and percentages in reports and the statusline.
-Wallet fields remain unavailable unless the response supplies one consistent currency; missing monthly values are omitted, and an enabled zero cap is shown as zero.
-
-The contract was revalidated on 2026-08-27 against [Pi `c49906ec77788625aacbdc53ebca6fbe65bd20f5`](https://github.com/earendil-works/pi/tree/c49906ec77788625aacbdc53ebca6fbe65bd20f5), including [`kimi-coding.ts`](https://github.com/earendil-works/pi/blob/c49906ec77788625aacbdc53ebca6fbe65bd20f5/packages/ai/src/providers/kimi-coding.ts) and [`auth/oauth/kimi-coding.ts`](https://github.com/earendil-works/pi/blob/c49906ec77788625aacbdc53ebca6fbe65bd20f5/packages/ai/src/auth/oauth/kimi-coding.ts).
-It was also revalidated against [Kimi Code `676e4d82240855044fe809fea89ce1dbe8e512cf`](https://github.com/MoonshotAI/kimi-code/tree/676e4d82240855044fe809fea89ce1dbe8e512cf), including [`managed-usage.ts`](https://github.com/MoonshotAI/kimi-code/blob/676e4d82240855044fe809fea89ce1dbe8e512cf/packages/oauth/src/managed-usage.ts) and its [tests](https://github.com/MoonshotAI/kimi-code/blob/676e4d82240855044fe809fea89ce1dbe8e512cf/packages/oauth/test/managed-usage.test.ts).
-The pinned Pi source at `e86823096c5bad39e1ca282ec24bc5eb9bec745b` has no changes in either reviewed Kimi file at the selected revision.
-The pinned Kimi managed-usage source at `cd7c97b377a77f7ae1b9d541cafe314e986ec074` is an ancestor of that selected revision and has no changes in the reviewed source or tests.
-
-### Moonshot AI API balance
-
-- Provider IDs: `moonshotai` and `moonshotai-cn`
-- Semantics: current API account balance, not Kimi For Coding subscription usage
-- Global source: `GET https://api.moonshot.ai/v1/users/me/balance`
-- China source: `GET https://api.moonshot.cn/v1/users/me/balance`
-- Displayed data: available, voucher, and cash balance in USD for Global or CNY for China
-- Statusline examples: `moonshot USD 49.58894` or `moonshot CNY 49.58894`
-
-Each endpoint uses Pi's resolved inference Bearer key for the matching region.
-Pi maps both built-in providers to `MOONSHOT_API_KEY`, so that shared environment credential is eligible only for the currently selected region.
-Querying the sibling region requires a provider-specific stored, runtime, or `models.json` credential.
-The extension rejects custom, proxy, and cross-region origins before network access and refuses redirects.
-Available and voucher balances must be nonnegative, while cash balance may be negative when the account owes money.
-The endpoint does not provide historical spend, token totals, quota windows, or reset times.
-These API-platform balances are independent from the `kimi-coding` subscription and booster wallet.
-
-The contracts were verified on 2026-08-30 against the official [Global balance reference](https://platform.kimi.ai/docs/api/balance), [China balance reference](https://platform.moonshot.cn/docs/api/balance), and first-party [`MoonshotAI-Cookbook` balance client and DTO](https://github.com/MoonshotAI/MoonshotAI-Cookbook/tree/25a9e46d2391dd4817d28ab980dac69eb59b582c/examples/golang_demo).
-### MiniMax Token Plan and API balance
-
-- Provider IDs: `minimax` and `minimax-cn`
-- Token Plan source: `GET {region-api-root}/v1/token_plan/remains`
-- Pay-as-you-go source: `GET {region-api-root}/account/query_balance`
-- Region API roots: `https://api.minimax.io` and `https://api.minimaxi.com`
-- Statusline examples: `minimax 15% 5h 80% wk` or `minimax USD 98.00001`
-
-Pi's resolved MiniMax API key selects exactly one endpoint before network access.
-Keys with the first-party `sk-api-` prefix query pay-as-you-go balance; other MiniMax API keys query Token Plan quota.
-The extension never probes both endpoints with one credential.
-Token Plan reports preserve provider rows, rolling and weekly windows, counts, reset times, unlimited status, and first-party handling for legacy versus current `*_usage_count` semantics.
-Pay-as-you-go reports keep available, cash, voucher, credit, and owed amounts separate in USD for Global or CNY for China.
-Custom, proxy, and cross-region origins fail before network access, and redirects are rejected.
-
-The contract was verified on 2026-08-30 against MiniMax's [Token Plan FAQ](https://platform.minimax.io/docs/token-plan/faq#how-to-check-token-plan-usage) and the first-party [`MiniMax-AI/cli`](https://github.com/MiniMax-AI/cli/tree/b78eccea80a0f9692e186d98906cff26931464f3), including endpoint selection, response types, quota normalization, and SDK tests.
-
-### GitHub Copilot
-
-- Provider ID: `github-copilot`
-- Semantics: the allowance reported for the active Copilot plan
-- Allowance labels: AI credits for usage-based billing, premium requests for legacy annual billing, or chat requests for Copilot Free
-- Source: GitHub's undocumented `GET /copilot_internal/user` endpoint
-- Displayed data: entitlement, remaining allowance, percentage, reset time, plan, and any additional usage beyond the included allowance
-- Statusline examples: `copilot credits 1200/1500 80%`, `copilot 245/300 82%`, or `copilot chat 40/50 80%`
-
-GitHub's quota endpoint requires the original GitHub OAuth token rather than the short-lived Copilot inference token exposed by runtime auth.
-`pi-usage` supports Copilot accounts created through Pi's `/login` flow and named accounts offered by a compatible `oauth:credential-source:v1` owner.
-It uses a candidate only when its short-lived access token exactly matches the freshly resolved active runtime credential.
-Duplicate equivalent candidates are harmless, while conflicting matches fail closed without choosing by extension load order.
-API-key credentials, account mismatches, GitHub Enterprise accounts, and proxy/custom provider origins fail closed.
-The detailed report follows the endpoint's `token_based_billing` marker so AI credits are not mislabeled as legacy premium requests.
-It reports overage without treating a negative included balance as malformed.
-
-### OpenRouter
-
-- Provider ID: `openrouter`
-- Semantics: API-key spend and per-key credit limits—not consumer subscription quota
-- Source: OpenRouter's documented [`GET /api/v1/key`](https://openrouter.ai/docs/api/api-reference/api-keys/get-current-api-key) endpoint using Pi's resolved inference API key
-- Displayed data: key label when safely returned, optional per-key limit and remaining amount, reset period, and daily/weekly/monthly/all-time spend
-- Statusline examples: `openrouter $74.50 left` or `openrouter $25.50 used`
-
-The extension does not call OpenRouter's account-level `/credits` endpoint because that operation requires a separate management key.
-OpenRouter documents the distinction between credit and rate limits in its [API limits guide](https://openrouter.ai/docs/api_reference/limits).
-
-### DeepSeek API balance
-
-- Provider ID: `deepseek`
-- Semantics: current API account balance, not historical usage or quota
-- Source: documented `GET https://api.deepseek.com/user/balance` using Pi's freshly resolved runtime API key
-- Displayed data: whether API calls are available plus separate total, granted, and topped-up balances for each returned CNY or USD currency
-- Statusline examples: `deepseek CNY 110.00` or `deepseek CNY 110.00 · USD 20.00`
-
-The extension queries the fixed balance endpoint only when the selected model origin is `https://api.deepseek.com` and any resolved-auth origin override, when present, has the same official origin.
-Pi's built-in DeepSeek API-key resolver does not attach a redundant auth origin, so the validated model origin remains authoritative when no override exists.
-Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded from Pi's runtime auth.
-Monetary decimal strings remain exact from the response through display.
-CNY and USD stay separate and are never converted or added together.
-The balance endpoint does not provide historical spend, request windows, reset times, or aggregate token usage, so `pi-usage` does not claim those DeepSeek capabilities.
-
-The contract was verified on 2026-08-28 against [DeepSeek's Get User Balance documentation](https://api-docs.deepseek.com/api/get-user-balance) and Pi's [`deepseek.ts`](https://github.com/earendil-works/pi/blob/c49906ec77788625aacbdc53ebca6fbe65bd20f5/packages/ai/src/providers/deepseek.ts) at `c49906ec77788625aacbdc53ebca6fbe65bd20f5`.
-DeepSeek Harness `cd5ef8148158c3a752a658978873241fdf8e2bbc` reports only per-request model token usage and does not provide account balance data.
-
-### Fireworks API spend
-
-- Provider ID: `fireworks`
-- Semantics: rated 30-day account spend, not credit balance or spend-cap quota
-- Source: documented `GET https://api.fireworks.ai/v1/accounts` account discovery and `GET https://api.fireworks.ai/v1/accounts/{account_id}/billing/summary` rated costs using Pi's resolved inference API key
-- Displayed data: exact rated spend per currency with serverless, dedicated-deployment, and training subtotals for the trailing 30 days
-- Statusline example: `fireworks USD 12.345678901`
-
-The extension queries the fixed endpoints only when the selected model origin is `https://api.fireworks.ai` and any resolved-auth origin override, when present, has the same official origin.
-The account slug is discovered through the documented account listing.
-One visible account is selected automatically; several visible accounts use the remembered selection or ask through `/usage`, and a disappeared selection returns **Selection required** without a billing request.
-Monetary `units` and `nanos` values are summed exactly with integer arithmetic and stay exact through display.
-Fireworks does not expose credit balance, spend caps, per-window quota, or reset times through its API, so `pi-usage` does not claim those Fireworks capabilities; the web console remains the authoritative balance source.
-Rated line items may differ from the final invoice once credits or adjustments are applied.
-
-The contract was verified on 2026-07-31 against Fireworks' [Usage & Cost Breakdown](https://docs.fireworks.ai/accounts/exporting-usage-and-costs), [Get billing summary](https://docs.fireworks.ai/api-reference/get-billing-summary), and [List Accounts](https://docs.fireworks.ai/api-reference/list-accounts) API references.
-
-### Vercel AI Gateway credits
-
-- Provider ID: `vercel-ai-gateway`
-- Semantics: current team credit balance and lifetime spend, not rate-limit quota
-- Source: documented `GET https://ai-gateway.vercel.sh/v1/credits` using Pi's resolved AI Gateway API key
-- Displayed data: exact decimal-string credit balance and lifetime spend in USD
-- Statusline example: `vercel USD 95.50 left`
-
-The extension queries the fixed endpoint only when the selected model origin and any resolved-auth origin are `https://ai-gateway.vercel.sh`.
-Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded.
-The credits endpoint does not provide reset times, request-rate counters, or date-window usage, so `pi-usage` does not claim those capabilities.
-Vercel's separate Custom Reporting API is limited to eligible paid plans and is intentionally outside this first integration.
-
-The contract was verified on 2026-08-30 against Vercel's [REST API Reference](https://vercel.com/docs/ai-gateway/sdks-and-apis/rest-api#check-credit-balance) and the first-party [`vercel/ai` Gateway implementation](https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/gateway/src/gateway-fetch-metadata.ts).
-
-### Baseten Model APIs spend
-
-- Provider ID: `baseten`
-- Semantics: organization-wide Model APIs spend, not per-key quota or account balance
-- Source: `GET https://api.baseten.co/v1/billing/usage_summary` using Pi's resolved Baseten API key
-- Displayed data: trailing 30-day gross usage, credits used, and net subtotal in USD
-- Statusline example: `baseten USD 166.15 net`
-
-The extension intentionally ignores Dedicated deployment and Training categories because they do not represent Pi's Model APIs provider usage.
-The query window is a precise trailing 30 days and stays below the endpoint's 31-day maximum.
-The fixed Management API endpoint is queried only for an official `https://inference.baseten.co` model and an official resolved-auth origin.
-Custom and proxy origins fail before network access, redirects are rejected, and only the resolved Bearer credential is forwarded.
-An empty `model_apis_usage` result is reported as no Model APIs usage rather than zero account-wide spend.
-
-The contract was verified on 2026-08-30 against Baseten's [Billing and usage](https://docs.baseten.co/organization/billing#view-usage), [Model APIs usage](https://docs.baseten.co/inference/model-apis/pricing-and-limits#usage), first-party [`baseten-go` Management OpenAPI](https://github.com/basetenlabs/baseten-go/blob/f028e27beb4bde106d984833313c055ddd6fefa4/internal/tools/apigen/specs/management.json), and [`baseten-cli` billing behavior](https://github.com/basetenlabs/baseten-cli/blob/e3d002b465f49a7295ea44b5988dbfeb8197896d/internal/cmd/command.org.go).
-
-### OpenCode Go (Zen)
-
-- Provider ID: `opencode-go`
-- Semantics: OpenCode Zen plan usage windows—rolling, weekly, and monthly
-- Source: `GET https://opencode.ai/zen/go/v1/usage` using Pi's resolved inference API key
-- Displayed data: used percentage and reset time for each window
-- Status handling: `rate-limited` windows remain visible, while unknown statuses become unavailable notes
-- Statusline examples: `zen 0% r 4% w 2% m`
-
-The fixed endpoint is queried only when the OpenCode Go model uses the official `https://opencode.ai` origin.
-When resolved provider auth includes a base URL, that URL must use the same origin.
-Other origins fail before the credential is sent.
-
-### xAI consumer subscriptions
-
-- Provider ID: `xai`
-- Semantics: consumer subscription allowance and credits, not xAI API-team billing
-- Identity route: `GET https://cli-chat-proxy.grok.com/v1/user?include=subscription`
-- Billing route: `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits`
-- Displayed data: included allowance or legacy monetary limit, period and reset, on-demand spend and cap, prepaid balance, and a sanitized optional plan tier
-- Statusline: not published; xAI is queried only through an explicit `/usage` action
-
-The adapter accepts only the official Pi inference origin `https://api.x.ai` and a freshly resolved bearer that exactly matches one complete Pi OAuth credential.
-Pi's reviewed OAuth scope is `openid profile email offline_access grok-cli:access api:access`.
-The adapter rejects `XAI_API_KEY`, duplicate or conflicting OAuth candidates, account mismatches, and incomplete OAuth records.
-It also rejects custom or proxy-resolved origins before consumer-proxy access.
-API-key users can review API-team spend through [console.x.ai](https://console.x.ai/) instead.
-The public Management API requires a separate management key and team ID and is intentionally outside this runtime-credential integration.
-
-The identity response supplies a transient proxy-canonical `userId` that is validated and sent as `x-userid` only on the billing request.
-The extension sends the matched bearer as `Authorization` plus Grok Build's source-defined non-secret `X-XAI-Token-Auth`, client-version, and interactive client-mode headers.
-It does not read Grok Build files, device state, names, email, or other profile fields.
-Responses are body-bounded, redirects are rejected, raw identity and billing payloads are not retained, and secrets are redacted from errors.
-Included allowance, on-demand usage, and prepaid balance remain distinct because they represent different billing concepts.
-
-The current official Grok Build implementation is the ground truth for the xAI integration contract.
-The implementation contract was verified against these first-party revisions:
-
-- Pi [`providers/xai.ts`](https://github.com/earendil-works/pi/blob/e86823096c5bad39e1ca282ec24bc5eb9bec745b/packages/ai/src/providers/xai.ts) and [`auth/oauth/xai.ts`](https://github.com/earendil-works/pi/blob/e86823096c5bad39e1ca282ec24bc5eb9bec745b/packages/ai/src/auth/oauth/xai.ts) at `e868230`, revalidated byte-for-byte for those files at [`ccfe79e`](https://github.com/earendil-works/pi/tree/ccfe79ed238674f760c986e3a61493aab794000a).
-- Grok Build [`UserInfo`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-shell/src/auth/model.rs), [`subscription_check.rs`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-shell/src/agent/subscription_check.rs), [`billing.rs`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-shell/src/extensions/billing.rs), [`auth/config.rs`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-shell/src/auth/config.rs), [`xai-grok-http`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-http/src/lib.rs), and [`xai-grok-version`](https://github.com/xai-org/grok-build/blob/9684fa3cdbf2995e30ea8b9b637f1db008f144fc/crates/codegen/xai-grok-version/Cargo.toml) at `9684fa3`.
-- [xAI Management API team billing boundary at `723dd2a`](https://github.com/xai-org/xai-proto/blob/723dd2aa22d17be35617463837dc47cda008d90e/proto/xai/management_api/v1/billing.proto).
-
-The approved 2026-08-27 protocol smoke used only Pi's OAuth bearer and read no Grok-local files.
-A disposable or maintainer account received HTTP 200 without redirects from both routes.
-The implementation also sends the non-secret client headers present on both routes in current Grok Build source, with `x-userid` added only for billing.
-The sanitized identity shape contained a string `userId` and nullable `subscriptionTier`.
-The billing shape contained a `config` object with period and distinct on-demand and prepaid wrappers, without retaining field values.
-
-xAI identity and billing requests occur only after an explicit current, configured-provider, or all-provider `/usage` action.
-
-### Z.AI (GLM Coding Plan)
-
-- Provider ID: `zai` and `zai-coding-cn`
-- Semantics: GLM Coding Plan quota windows—the rolling 5-hour and weekly plan-usage windows plus the monthly MCP allowance
-- Source: the undocumented `GET {origin}/api/monitor/usage/quota/limit` endpoint also used by Z.AI's official coding plugin, plus the undocumented `GET {origin}/api/biz/subscription/list` plan endpoint
-- Allowed origins: the model base URL must resolve to `https://api.z.ai` or `https://open.bigmodel.cn`
-- Displayed data: explicit used and remaining values, reset times, provider-reported per-tool MCP details, and the plan name with its renewal date
-- Percentage-only windows remain percent-based
-- Statusline: publishes remaining plan percentages such as `zai 87% 5h 76% wk`; monthly MCP details remain available through `/usage`
-
-The monitor endpoint is not a published API contract and may return legacy `TOKENS_LIMIT` or newer `CREDIT_LIMIT` window names.
-The extension classifies both forms by the provider's window unit and does not label provider-reported counts as tokens or calls.
-The quota monitor expects a raw API key without a `Bearer` prefix.
-The extension removes that prefix from resolved authorization before sending it to the monitor endpoint.
-Fingerprinting and redaction keep using the original resolved credential.
-The plan endpoint only contributes the plan name and renewal date; when it is unavailable or fails, the quota windows remain reported and the plan note falls back to the quota response's plan level.
-Only the official `api.z.ai` and `open.bigmodel.cn` origins are queried; other origins fail before sending the credential.
+Usage is provider-specific: a subscription allowance, current balance, and rated spend are not interchangeable.
+Currencies and billing targets remain separate.
+
+| Provider | Reported data |
+| --- | --- |
+| OpenAI Codex | Subscription windows, credits, resets, and model buckets |
+| Kimi For Coding | Plan request windows and a separate booster wallet |
+| Moonshot AI Global/China | Current API balance in USD/CNY |
+| MiniMax Global/China | Token Plan windows or pay-as-you-go API balance |
+| GitHub Copilot | AI credits, premium requests, or Free-plan chat allowance |
+| OpenRouter | Per-key credit limits and spending windows |
+| DeepSeek | Exact current CNY and USD API balances |
+| Fireworks | Rated trailing 30-day spend for one selected account |
+| Vercel AI Gateway | Team credit balance and lifetime spend |
+| Baseten | Organization-wide trailing 30-day Model APIs spend after credits |
+| OpenCode Go | Rolling, weekly, and monthly plan windows |
+| xAI | OAuth subscription allowance and credits; explicit menu queries only |
+| Z.AI | Coding Plan quota windows, MCP allowance, plan name, and renewal date |
+
+Read the [provider reference](./docs/providers.md) for provider IDs, exact endpoints, authentication requirements, normalization rules, statusline examples, limitations, and pinned contract evidence.
+Codex reset redemption requires a freshly matched current OAuth account and explicit confirmation; custom or proxy origins fail before mutation.
 
 ## 🧭 Current and configured accounts
 
@@ -478,36 +216,19 @@ An absent or incompatible peer preserves standalone fallback and fail-closed mis
 
 ## 🗂️ Package layout
 
-```txt
+```text
 packages/pi-usage/
-├── dist/                  # Generated TypeScript runtime loaded by Jiti
-├── scripts/
-│   └── build-runtime.mjs  # Deterministic runtime builder and boundary validator
-├── src/
-│   ├── index.ts       # Pi package entrypoint and helper export barrel
-│   ├── usage.ts       # Menu, cache, and usage lifecycle orchestration
-│   ├── usage-settings-ui.ts # Pi SettingsList interaction and save rollback
-│   ├── codex-fast.ts  # Fast eligibility, request tier, and cost correction
-│   ├── codex-fast-runtime.ts # Fast command, persistence lifecycle, and request hooks
-│   ├── settings.ts    # Validated user settings and atomic persistence
-│   ├── usage-helpers.ts # Small orchestration helpers
-│   ├── usage-targets.ts # Provider-neutral target resolution and safe picker descriptors
-│   ├── query.ts       # Runtime auth resolution and bounded provider queries
-│   ├── oauth-credential-source.ts # Ephemeral OAuth candidate collection
-│   ├── codex-resets.ts # Codex reset auth, API contracts, and normalization
-│   ├── format.ts      # Provider-aware notifications and statusline text
-│   ├── core.ts        # Cache, concurrency, fingerprint, and redaction helpers
-│   ├── providers/     # Provider-specific usage normalization adapters
-│   └── types.ts       # Common presentation and adapter contracts
-├── test/
-├── README.md
-├── LICENSE
-├── tsconfig.json
-└── package.json
+├── src/                               # Provider adapters, auth, settings, and presentation
+│   ├── index.ts                       # Thin Pi entrypoint
+│   └── usage.ts                       # Provider queries, cache, and menu
+├── dist/                              # Generated Jiti runtime
+├── scripts/build-runtime.mjs          # Runtime builder
+├── docs/                              # Published reference documentation
+└── test/                              # Behavior and lifecycle coverage
 ```
 
-`index.ts` is the Pi entrypoint and forwards the default factory from `usage.ts` while retaining the package's named helper exports; other source modules are internal.
-The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
+`src/index.ts` forwards the default factory from `usage.ts` and retains the package's named helper exports; other source modules are internal.
+The generated runtime is built from `src/index.ts` and does not import back into `src`.
 
 ## 🔎 Keywords
 

package/dist/index.ts

@@ -239,6 +239,8 @@ function redactUsageError(value, secrets = []) {
 function errorMessage(error) {
   return sanitizeDisplayText(error instanceof Error ? error.message : String(error), 600);
 }
+var UsageUnsupportedError = class extends Error {
+};
 function abortError() {
   return Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
 }
@@ -1735,7 +1737,12 @@ var FIVE_HOUR_WINDOW_MINUTES2 = 300;
 var WEEKLY_WINDOW_MINUTES2 = 10080;
 function normalizeZaiQuotaPayload(providerId, providerName, payload, capturedAt, plan) {
   const data = asObject11(payload.data);
-  if (!data) throw new Error("Z.AI quota response data was not an object.");
+  if (!data) {
+    const reason = asString5(payload.msg);
+    throw new UsageUnsupportedError(
+      `No GLM Coding Plan on this Z.AI credential; API usage is not metered.${reason ? ` Z.AI reported: ${reason}` : ""}`
+    );
+  }
   const limits = Array.isArray(data.limits) ? data.limits : [];
   const buckets = [];
   const metrics = [];
@@ -2448,7 +2455,8 @@ async function queryProviderUsage(adapter, auth, signal, timeoutMs, guard, targe
     );
   } catch (error) {
     if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
-    throw new Error(redactUsageError(errorMessage(error), auth.secrets));
+    const message = redactUsageError(errorMessage(error), auth.secrets);
+    throw error instanceof UsageUnsupportedError ? new UsageUnsupportedError(message) : new Error(message);
   }
 }
 function providerIsConfigured(ctx, providerId) {
@@ -4560,7 +4568,7 @@ function usageExtension(pi, dependencies = {}) {
             providerId: adapter.id,
             providerName,
             displayState,
-            status: "query-failed",
+            status: previousDiscoveryFailure.status,
             message: previousDiscoveryFailure.message
           },
           fingerprint: auth.fingerprint,
@@ -4619,7 +4627,7 @@ function usageExtension(pi, dependencies = {}) {
             providerId: adapter.id,
             providerName,
             displayState,
-            status: "query-failed",
+            status: previousFailure.status,
             message: previousFailure.message
           },
           fingerprint: auth.fingerprint,
@@ -4672,6 +4680,7 @@ function usageExtension(pi, dependencies = {}) {
         );
       }
       const message = errorMessage(error);
+      const status = error instanceof UsageUnsupportedError ? "unsupported" : "query-failed";
       const now = Date.now();
       for (const [key, failure] of failureBackoff) {
         if (failure.until <= now) failureBackoff.delete(key);
@@ -4680,7 +4689,7 @@ function usageExtension(pi, dependencies = {}) {
         setBoundedMap(
           failureBackoff,
           failureKey,
-          { until: now + FAILURE_BACKOFF_MS, message },
+          { until: now + FAILURE_BACKOFF_MS, message, status },
           MAX_ACCOUNT_STATES
         );
       }
@@ -4689,7 +4698,7 @@ function usageExtension(pi, dependencies = {}) {
           providerId: adapter.id,
           providerName,
           displayState,
-          status: "query-failed",
+          status,
           message
         },
         fingerprint: auth.fingerprint,