@narumitw/pi-usage 0.60.3 → 0.60.6

package/docs/operations.md

@@ -0,0 +1,31 @@
+# Usage queries and reset redemption
+
+[Back to README](../README.md#-commands)
+
+## Choose a provider target
+
+A target is the provider-owned account, organization, project, team, or workspace used for one usage query.
+Providers without target discovery query immediately; a single returned target is selected automatically without saving settings.
+When several targets exist, `/usage` remembers an explicit selection by provider and reuses it only while it remains in a fresh listing.
+A missing remembered target reports **Selection required** instead of querying another target silently.
+Use **Select <target>…** for the current provider or **Change <target>…** for a ready current or individually viewed provider.
+
+Viewing another provider may open one target prompt after that provider is queried lazily.
+Cancelling changes nothing.
+Authentication and target membership are revalidated before saving an explicit selection, then resolved again before billing is queried.
+**View all configured providers…** never opens nested target prompts; view an unresolved provider individually to select its target.
+Background refresh also remains non-interactive and reports `selection required` until `/usage` completes the choice.
+Fireworks accounts are the first implementation of this provider-neutral flow.
+
+For credentials, endpoints, and provider-specific meanings, see the [provider reference](./providers.md).
+For selection storage and migration, see [Settings](../README.md#-settings).
+
+## Redeem a Codex usage reset
+
+For the current OpenAI Codex OAuth account, **Redeem usage limit reset…** checks fresh earned-reset details, lets you choose a reset, and previews its exact effect before confirmation.
+Custom or proxy origins are rejected before mutation.
+**No, go back** is the safe default, and cancellation before confirmation sends no mutation.
+
+After confirmation, the reset 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 handle an uncertain retry idempotently.
+Successful, already-completed, not-needed, and no-credit outcomes are reported separately, then usage and the statusline refresh for the still-current account.

package/docs/providers.md

@@ -0,0 +1,271 @@
+# Pi Usage provider reference
+
+[Back to README](../README.md)
+
+This reference preserves each provider's endpoint, authentication boundary, billing semantics, and contract evidence.
+The README contains the capability overview and shared security requirements.
+
+- [OpenAI Codex](#openai-codex)
+- [Kimi For Coding](#kimi-for-coding)
+- [Moonshot AI](#moonshot-ai-api-balance)
+- [MiniMax](#minimax-token-plan-and-api-balance)
+- [GitHub Copilot](#github-copilot)
+- [OpenRouter](#openrouter)
+- [DeepSeek](#deepseek-api-balance)
+- [Fireworks](#fireworks-api-spend)
+- [Vercel AI Gateway](#vercel-ai-gateway-credits)
+- [Baseten](#baseten-model-apis-spend)
+- [OpenCode Go](#opencode-go-zen)
+- [xAI](#xai-consumer-subscriptions)
+- [Z.AI](#zai-glm-coding-plan)
+
+## 📋 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.
+Quota errors use fixed English hints for the [documented Z.AI business error codes](https://docs.z.ai/api-reference/api-code), accepting nested `error.code` and the monitor endpoint's top-level `code` as strings or numbers.
+An explicit nested code takes precedence; when it is absent, the top-level code is used.
+For example, `1113` reports insufficient balance or no resource package, and `1309` reports an expired GLM Coding Plan.
+When a failed HTTP response has no business error code, the hint uses its HTTP status; unknown business codes use a generic API failure message.
+The monitor's top-level `code: 500` is not a documented business code and is not treated as HTTP 500 or proof that the credential has no Coding Plan.
+Error classification never matches or echoes provider `msg` or `error.message` text, which may contain credentials.
+Quota errors and missing or malformed quota data remain query failures with a statusline error hint, a 30-second request backoff, and scheduled retries; they no longer clear the statusline as unsupported.
+An accepted Z.AI query failure discards the matching cached report, so the next turn after backoff expires retries instead of restoring stale usage.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-usage",
-	"version": "0.60.3",
+	"version": "0.60.6",
 	"description": "Pi extension that shows current-account usage and DeepSeek API balance for supported providers.",
 	"type": "module",
 	"license": "MIT",
@@ -35,6 +35,7 @@
 	"files": [
 		"src",
 		"dist",
+		"docs",
 		"README.md",
 		"LICENSE"
 	],
@@ -57,10 +58,10 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.11",
-		"@earendil-works/pi-ai": "0.84.4",
-		"@earendil-works/pi-coding-agent": "0.84.4",
-		"@earendil-works/pi-tui": "0.84.4",
-		"@types/node": "26.4.0",
+		"@earendil-works/pi-ai": "0.85.0",
+		"@earendil-works/pi-coding-agent": "0.85.0",
+		"@earendil-works/pi-tui": "0.85.0",
+		"@types/node": "26.4.1",
 		"esbuild": "0.28.2",
 		"typescript": "7.0.2"
 	},

package/src/core.ts

@@ -36,6 +36,10 @@ export class UsageCache {
 		this.entries.set(key, { createdAt: now, report });
 	}
 
+	delete(providerId: string, fingerprint: string): void {
+		this.entries.delete(cacheKey(providerId, fingerprint));
+	}
+
 	clearProvider(providerId: string): void {
 		for (const key of this.entries.keys()) {
 			if (key.startsWith(`${providerId}:`)) this.entries.delete(key);

package/src/providers/zai-errors.ts

@@ -0,0 +1,94 @@
+// Fixed messages from https://docs.z.ai/api-reference/api-code. Never interpolate provider text:
+// error messages and their template parameters can contain credentials or terminal controls.
+const ERROR_MESSAGES: Readonly<Record<string, string>> = {
+	"1000": "Authentication failed. Check your API key.",
+	"1001": "Authentication header missing. Check your API key.",
+	"1003": "Authentication token expired. Obtain a new token.",
+	"1005": "Two-factor authentication required.",
+	"1113": "Insufficient balance or no resource package. Recharge your account.",
+	"1200": "API call error. Try again later.",
+	"1210": "Invalid API parameter. Check the API documentation.",
+	"1211": "Unknown model. Check the model ID.",
+	"1212": "This model does not support the requested method.",
+	"1213": "A required parameter is missing.",
+	"1214": "Invalid parameter. Check the API documentation.",
+	"1215": "Conflicting parameters. Check the API documentation.",
+	"1220": "Access denied. Check your permissions.",
+	"1221": "This API has been taken offline.",
+	"1222": "This API does not exist.",
+	"1230": "API processing error. Try again later.",
+	"1234": "Network error. Try again later.",
+	"1261": "Prompt too long. Reduce the input length.",
+	"1301": "Content rejected by the safety policy.",
+	"1302": "Request rate limit reached. Try again later.",
+	"1305": "Service overloaded. Try again later.",
+	"1308": "Usage limit reached. Wait for the quota reset.",
+	"1309": "GLM Coding Plan expired. Renew your subscription.",
+	"1310": "Weekly or monthly limit exhausted. Wait for the quota reset.",
+	"1311": "Your subscription does not include this model.",
+	"1313": "Request frequency restricted by the Fair Usage Policy. Contact support.",
+	"1314": "Enterprise package expired. Contact your administrator.",
+	"1315": "This API key requires an enterprise coding package scenario. Replace the key.",
+	"1316": "5-hour limit reached; insufficient balance for extra usage. Wait for reset.",
+	"1317": "7-day limit reached; insufficient balance for extra usage. Wait for reset.",
+	"1318": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+	"1319": "7-day limit reached; extra usage blocked by monthly spend limit.",
+	"1320": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+	"1321": "7-day limit reached; extra usage blocked by monthly spend limit.",
+};
+
+const HTTP_MESSAGES: Readonly<Record<number, string>> = {
+	400: "Invalid request. Check the API documentation.",
+	401: "Authentication failed. Check your API key.",
+	403: "Access denied. Check your permissions.",
+	429: "Request or usage limit reached. Try again later.",
+	500: "Internal error. Try again later.",
+};
+
+export function zaiPayloadError(payload: unknown): string | undefined {
+	const object = asObject(payload);
+	if (!object) return undefined;
+	const nested = asObject(object.error);
+	// Missing nested metadata must not hide a top-level code; explicit nested values retain priority.
+	const rawCode = nested?.code === undefined ? object.code : nested.code;
+	const code = errorCode(rawCode);
+	if (
+		object.error === undefined &&
+		object.success !== false &&
+		(rawCode === undefined || code === "0" || code === "200")
+	) {
+		return undefined;
+	}
+	return code && code !== "0" && code !== "200"
+		? `Z.AI ${code}: ${ERROR_MESSAGES[code] ?? "API request failed."}`
+		: "Z.AI: API request failed.";
+}
+
+export function zaiResponseError(status: number, text: string): string | undefined {
+	let payload: unknown;
+	try {
+		payload = JSON.parse(text) as unknown;
+	} catch {
+		// Do not expose JSON parser excerpts, response bodies, or statusText.
+		if (status >= 200 && status < 300) return "Z.AI: Invalid JSON response.";
+	}
+	const error = zaiPayloadError(payload);
+	if (error) return error;
+	if (status < 200 || status >= 300) {
+		return `Z.AI HTTP ${status}: ${HTTP_MESSAGES[status] ?? "API request failed."}`;
+	}
+	return undefined;
+}
+
+function errorCode(value: unknown): string | undefined {
+	if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 9999) {
+		return String(value);
+	}
+	return typeof value === "string" && /^(?:0|[1-9]\d{0,3})$/u.test(value) ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}

package/src/providers/zai.ts

@@ -8,6 +8,8 @@ import type {
 	ZaiSubscriptionPayload,
 } from "../types.js";
 
+import { zaiPayloadError } from "./zai-errors.js";
+
 const FIVE_HOUR_WINDOW_MINUTES = 300;
 const WEEKLY_WINDOW_MINUTES = 10_080;
 
@@ -18,6 +20,8 @@ export function normalizeZaiQuotaPayload(
 	capturedAt: number,
 	plan?: ZaiPlanInfo,
 ): UsageReport {
+	const error = zaiPayloadError(payload);
+	if (error) throw new Error(error);
 	const data = asObject(payload.data);
 	if (!data) throw new Error("Z.AI quota response data was not an object.");
 	const limits = Array.isArray(data.limits) ? (data.limits as unknown[]) : [];
@@ -81,10 +85,7 @@ export function normalizeZaiQuotaPayload(
 export function normalizeZaiSubscriptionPayload(
 	payload: ZaiSubscriptionPayload,
 ): ZaiPlanInfo | undefined {
-	if (payload.success === false) return undefined;
-	if (typeof payload.code === "number" && payload.code !== 0 && payload.code !== 200) {
-		return undefined;
-	}
+	if (zaiPayloadError(payload)) return undefined;
 	if (!Array.isArray(payload.data)) return undefined;
 
 	const candidates: Array<{

package/src/query.ts

@@ -24,6 +24,7 @@ import { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
 import { normalizeVercelAIGatewayCreditsPayload } from "./providers/vercel-ai-gateway.js";
 import { normalizeXaiBillingPayload } from "./providers/xai.js";
 import { normalizeZaiQuotaPayload, normalizeZaiSubscriptionPayload } from "./providers/zai.js";
+import { zaiResponseError } from "./providers/zai-errors.js";
 import type {
 	BasetenBillingUsagePayload,
 	CodexBackendPayload,
@@ -261,6 +262,7 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 	{
 		id: "zai",
 		displayName: "Z.AI",
+		invalidateCacheOnFailure: true,
 		semantics: { kind: "consumer-subscription", label: "GLM Coding Plan usage" },
 		async query(auth, signal, timeoutMs, guard) {
 			return queryZaiUsage("zai", "Z.AI", auth, signal, timeoutMs, guard);
@@ -269,6 +271,7 @@ export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
 	{
 		id: "zai-coding-cn",
 		displayName: "Z.AI Coding CN",
+		invalidateCacheOnFailure: true,
 		semantics: { kind: "consumer-subscription", label: "GLM Coding Plan usage" },
 		async query(auth, signal, timeoutMs, guard) {
 			return queryZaiUsage("zai-coding-cn", "Z.AI Coding CN", auth, signal, timeoutMs, guard);
@@ -627,6 +630,7 @@ export async function fetchProviderJson(
 		body?: Record<string, unknown>;
 		redirect?: RequestRedirect;
 		userAgent?: boolean;
+		responseError?: (status: number, text: string) => string | undefined;
 	} = {},
 ): Promise<Record<string, unknown>> {
 	const controller = new AbortController();
@@ -665,6 +669,8 @@ export async function fetchProviderJson(
 		);
 		if (controller.signal.aborted)
 			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+		const responseError = request.responseError?.(response.status, text);
+		if (responseError) throw new Error(responseError);
 		if (!response.ok) {
 			throw new Error(
 				`${description} returned ${response.status} ${response.statusText}: ${redactUsageError(text, auth.secrets)}`,
@@ -1101,6 +1107,7 @@ async function queryZaiUsage(
 		signal,
 		remainingTimeout(timeoutMs, startedAt, `fetching ${providerName} quota`),
 		`${providerName} quota endpoint`,
+		{ responseError: zaiResponseError },
 	)) as ZaiQuotaPayload;
 	await guard();
 	const planTimeoutMs = timeoutMs - (Date.now() - startedAt);
@@ -1125,6 +1132,7 @@ async function fetchZaiPlan(
 			signal,
 			timeoutMs,
 			`${providerName} plan endpoint`,
+			{ responseError: zaiResponseError },
 		)) as ZaiSubscriptionPayload;
 		return normalizeZaiSubscriptionPayload(payload);
 	} catch (error) {

package/src/types.ts

@@ -91,6 +91,8 @@ export interface UsageProviderAdapter {
 	displayName: string;
 	semantics: UsageSemantics;
 	publishesStatusline?: boolean;
+	/** Invalidate the matching ready report when the latest query fails; default preserves it. */
+	invalidateCacheOnFailure?: boolean;
 	targets?: UsageTargetResolver;
 	query(
 		auth: ResolvedUsageAuth,
@@ -191,10 +193,14 @@ export type OpenCodeZenPayload = {
 };
 
 export type ZaiQuotaPayload = {
+	error?: unknown;
+	code?: unknown;
+	success?: unknown;
 	data?: unknown;
 };
 
 export type ZaiSubscriptionPayload = {
+	error?: unknown;
 	code?: unknown;
 	success?: unknown;
 	data?: unknown;

package/src/usage.ts

@@ -484,6 +484,7 @@ export default function usageExtension(
 				if (failure.until <= now) failureBackoff.delete(key);
 			}
 			if (queryId === undefined || latestQueries.get(failureKey) === queryId) {
+				if (adapter.invalidateCacheOnFailure) cache.delete(adapter.id, queryFingerprint);
 				setBoundedMap(
 					failureBackoff,
 					failureKey,