@narumitw/pi-usage 0.60.3 → 0.60.4

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,264 @@
+# 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.
+A credential with no coding plan answers HTTP 200 without a data object; that is reported as `Unsupported` rather than a query failure, so the statusline stays empty.
+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.4",
 	"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

@@ -198,6 +198,10 @@ export function errorMessage(error: unknown): string {
 	return sanitizeDisplayText(error instanceof Error ? error.message : String(error), 600);
 }
 
+// A credential the provider cannot meter is not a query failure: it is reported as unsupported, so
+// the statusline stays empty instead of holding an error chip that no retry will clear.
+export class UsageUnsupportedError extends Error {}
+
 export function abortError(): Error {
 	return Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
 }

package/src/providers/zai.ts

@@ -1,4 +1,4 @@
-import { sanitizeDisplayText } from "../core.js";
+import { sanitizeDisplayText, UsageUnsupportedError } from "../core.js";
 import type {
 	UsageBucket,
 	UsageMetric,
@@ -19,7 +19,14 @@ export function normalizeZaiQuotaPayload(
 	plan?: ZaiPlanInfo,
 ): UsageReport {
 	const data = asObject(payload.data);
-	if (!data) throw new Error("Z.AI quota response data was not an object.");
+	// A credential with no coding plan answers HTTP 200 with no data object:
+	// {"code":500,"msg":"当前用户不存在coding plan","success":false}. API usage is not metered.
+	if (!data) {
+		const reason = asString(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 as unknown[]) : [];
 
 	const buckets: UsageBucket[] = [];

package/src/query.ts

@@ -2,7 +2,12 @@
 // separating that security boundary would duplicate request and redaction policy across providers.
 import { randomBytes } from "node:crypto";
 import { type ExtensionContext, readStoredCredential } from "@earendil-works/pi-coding-agent";
-import { errorMessage, fingerprintResolvedAuth, redactUsageError } from "./core.js";
+import {
+	errorMessage,
+	fingerprintResolvedAuth,
+	redactUsageError,
+	UsageUnsupportedError,
+} from "./core.js";
 import {
 	fallbackOAuthCredentialCandidates,
 	type OAuthCredentialCandidateReader,
@@ -547,7 +552,11 @@ export async function queryProviderUsage(
 		);
 	} catch (error) {
 		if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
-		throw new Error(redactUsageError(errorMessage(error), auth.secrets));
+		const message = redactUsageError(errorMessage(error), auth.secrets);
+		// Redaction rebuilds the error, so the unsupported signal has to be carried across.
+		throw error instanceof UsageUnsupportedError
+			? new UsageUnsupportedError(message)
+			: new Error(message);
 	}
 }
 

package/src/types.ts

@@ -191,6 +191,7 @@ export type OpenCodeZenPayload = {
 };
 
 export type ZaiQuotaPayload = {
+	msg?: unknown;
 	data?: unknown;
 };
 

package/src/usage.ts

@@ -28,6 +28,7 @@ import {
 	errorMessage,
 	runWithConcurrency,
 	UsageCache,
+	UsageUnsupportedError,
 } from "./core.js";
 import { formatProviderStates, formatUsageStatusline } from "./format.js";
 import { createOAuthCredentialCandidateReader } from "./oauth-credential-source.js";
@@ -110,7 +111,10 @@ export default function usageExtension(
 	const createRedemptionId = dependencies.createRedemptionId ?? randomUUID;
 	const settingsRuntime = dependencies.settingsRuntime ?? createUsageSettingsRuntime();
 	const cache = new UsageCache(CACHE_TTL_MS);
-	const failureBackoff = new Map<string, { until: number; message: string }>();
+	const failureBackoff = new Map<
+		string,
+		{ until: number; message: string; status: "query-failed" | "unsupported" }
+	>();
 	const latestQueries = new Map<string, number>();
 	const activeControllers = new Set<AbortController>();
 	let querySequence = 0;
@@ -359,7 +363,7 @@ export default function usageExtension(
 						providerId: adapter.id,
 						providerName,
 						displayState,
-						status: "query-failed",
+						status: previousDiscoveryFailure.status,
 						message: previousDiscoveryFailure.message,
 					},
 					fingerprint: auth.fingerprint,
@@ -420,7 +424,7 @@ export default function usageExtension(
 						providerId: adapter.id,
 						providerName,
 						displayState,
-						status: "query-failed",
+						status: previousFailure.status,
 						message: previousFailure.message,
 					},
 					fingerprint: auth.fingerprint,
@@ -479,15 +483,18 @@ export default function usageExtension(
 				);
 			}
 			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);
 			}
+			// Unsupported is throttled like a failure, so a credential the provider cannot meter does
+			// not re-query on every turn; the entry carries its status so the replay stays unsupported.
 			if (queryId === undefined || latestQueries.get(failureKey) === queryId) {
 				setBoundedMap(
 					failureBackoff,
 					failureKey,
-					{ until: now + FAILURE_BACKOFF_MS, message },
+					{ until: now + FAILURE_BACKOFF_MS, message, status },
 					MAX_ACCOUNT_STATES,
 				);
 			}
@@ -496,7 +503,7 @@ export default function usageExtension(
 					providerId: adapter.id,
 					providerName,
 					displayState,
-					status: "query-failed",
+					status,
 					message,
 				},
 				fingerprint: auth.fingerprint,