@narumitw/pi-usage 0.52.3 → 0.54.0

package/README.md

@@ -2,15 +2,18 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-usage)](https://www.npmjs.com/package/@narumitw/pi-usage) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-Check the limits and usage for the provider account Pi is actually using, and toggle Fast mode for supported OpenAI Codex models.
+Check the limits and usage for the provider account Pi is actually using, toggle Fast mode for supported OpenAI Codex models, and report xAI OAuth subscription usage.
 
 The extension reports each provider's native semantics instead of presenting unlike quotas as equivalent.
+xAI reporting defaults On and follows the current official Grok Build implementation.
 
 ## ✨ Features
 
 - Shows current-account usage and next actions through `/usage`.
 - Supports OpenAI Codex subscription windows, credits, resets, and model-specific buckets.
+- Supports Kimi For Coding plan windows, resets, and separately labeled booster-wallet currency.
 - Supports GitHub Copilot allowances and OpenRouter per-key limits and spend windows.
+- Supports xAI OAuth subscription allowance and credit reporting.
 - Toggles persistent Codex Fast routing through `/fast` or the contextual usage menu.
 - Redeems eligible Codex resets only after fresh account matching and explicit confirmation.
 - Refreshes one or all configured providers with bounded concurrency and partial-result preservation.
@@ -58,6 +61,7 @@ In TUI or RPC mode, the standard menu first queries the current model provider a
 
 ```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…
@@ -79,13 +83,22 @@ Successful, already-completed, not-needed, and no-credit outcomes are reported s
 
 ## ⚙️ Settings
 
+Choose **Settings** in `/usage` to edit Codex Fast mode and xAI usage through Pi's settings-list interaction in TUI mode.
+RPC mode reports the active manual settings path instead of opening terminal UI.
+
+Both preferences live in Pi's user agent directory as `pi-usage.json`, normally `~/.pi/agent/pi-usage.json`.
+The file reloads at every session start and is not created until the first successful save.
+Changes save immediately in input order inside one Pi process.
+Unknown JSON fields are preserved, writes use a private temporary file plus rename, and malformed or invalid files remain untouched.
+A failed save restores the prior displayed and effective value, while shutdown waits for queued writes.
+Separate Pi processes are not mutually locked.
+
 ### Codex Fast mode
 
 Run bare `/fast` to toggle Fast for the active supported Codex model, or use **Turn Fast mode on/off** in `/usage`.
 
 Fast is about 1.5× faster and uses more of your plan allowance.
-The preference defaults to Off and is saved as `codexFastMode` in Pi's user agent directory as `pi-usage.json`, normally `~/.pi/agent/pi-usage.json`.
-The extension reloads this file at every session start and does not create it until the first successful toggle.
+The `codexFastMode` preference defaults to Off.
 
 Fast currently applies only to official `openai-codex-responses` requests for `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna` at `https://chatgpt.com`.
 It sends `service_tier: "priority"` while enabled and explicit `service_tier: "default"` otherwise.
@@ -94,10 +107,24 @@ 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.
-Settings operations are serialized inside one Pi process, but separate Pi processes are not mutually locked.
-Unknown JSON fields are preserved, writes use a private temporary file plus rename, and a malformed or invalid file is never overwritten.
 Repair or remove an invalid file, then run `/reload` before trying the toggle again.
 
+### xAI usage
+
+The `xaiUsage` preference defaults to `true` when the settings file or field is absent.
+Turn it Off in the TUI Settings screen or edit the active user file manually, then run `/reload`:
+
+```json
+{
+  "xaiUsage": false
+}
+```
+
+While enabled, xAI is available only through explicit `/usage` current, configured-provider, or all-provider actions.
+It does not schedule xAI requests or publish xAI data to the statusline.
+The disabled, malformed, and invalid-settings states perform no xAI usage auth resolution or consumer requests.
+Turning it Off clears xAI cache state and prevents stale in-flight results from being published.
+
 ## 📋 Provider semantics
 
 ### OpenAI Codex
@@ -118,6 +145,29 @@ API-key credentials, configured-but-not-current Codex accounts, account changes
 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 data: the weekly plan summary, returned sub-windows such as five-hour or daily limits, used and remaining request percentages, valid reset times, wallet 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.
+
 ### GitHub Copilot
 
 - Provider ID: `github-copilot`
@@ -154,6 +204,54 @@ OpenRouter documents the distinction between credit and rate limits in its [API
 
 The fixed endpoint is queried only when the candidate OpenCode Go model and the resolved provider-auth base URL, when present, use the official `https://opencode.ai` origin; other origins fail before sending the credential.
 
+### 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 percentage or legacy monetary limit, weekly or monthly 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 while xAI usage is enabled
+
+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`.
+`XAI_API_KEY`, duplicate or conflicting OAuth candidates, account mismatches, incomplete OAuth records, custom origins, and proxy-resolved origins fail 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 disposable-or-maintainer-account protocol smoke used only Pi's OAuth bearer, read no Grok-local files, and 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 an object `config` with period and distinct on-demand and prepaid wrappers, without retaining field values.
+
+Disable `xaiUsage` to stop all xAI consumer usage traffic while preserving other provider behavior.
+
+### 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: Z.AI's undocumented `GET {origin}/api/monitor/usage/quota/limit` endpoint, also used by its official coding plugin, with the origin derived from the model base URL (`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 reported plan level. Windows that report only a percentage remain percent-based
+- Statusline: not published; Z.AI is queried only through `/usage` actions
+
+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 the raw API key without a `Bearer` prefix, so the extension strips a `Bearer` prefix from the resolved authorization before sending it to the monitor endpoint.
+Fingerprinting and redaction keep using the original resolved credential.
+Only the official `api.z.ai` and `open.bigmodel.cn` origins are queried; other origins fail before sending the credential.
+
 ## 🧭 Current and configured accounts
 
 `Current` means the provider and credential used by Pi's selected model.
@@ -168,8 +266,9 @@ After the active runtime credential changes, the next command, turn, or schedule
 
 ## 📊 Statusline behavior
 
-The `usage` status item is active only for the selected model provider.
-It refreshes every five minutes while the session remains on a supported provider and is cleared when the model changes to an unsupported provider.
+The `usage` status item is active only for selected providers that publish statusline usage.
+It refreshes every five minutes while the session remains on such a provider and is cleared when the model changes to an unsupported or menu-only provider.
+xAI is always menu-only and never starts a scheduled status refresh.
 
 Manual another-provider and all-provider queries never publish to the statusline.
 `@narumitw/pi-statusline` supplies the default `📊` icon; `pi-usage` publishes text-only values.
@@ -205,8 +304,9 @@ Protocol v1 interoperability is characterized for the repository's supported Pi
 ## 🚧 Limitations
 
 - Only providers with a meaningful usage source and verifiable Pi runtime auth are supported.
-- GitHub Copilot quota and OpenAI Codex reset redemption use undocumented provider endpoints that may change without notice.
+- GitHub Copilot quota, Kimi managed usage, Z.AI quota, and OpenAI Codex reset redemption rely on provider-owned endpoints that may change without notice.
 - Codex reset redemption requires a current ChatGPT OAuth credential from Pi's login or a compatible credential source; Codex API keys cannot redeem earned subscription resets.
+- xAI usage supports only a uniquely matched Pi OAuth subscription credential; xAI API keys and Management API credentials are unsupported.
 - Credentials resolved for custom provider base URLs are never forwarded to the providers' official usage endpoints; effective auth origin validation requires Pi 0.81.0 or newer.
 - Provider reports are snapshots and may themselves be delayed by the provider.
 - OpenRouter successful inference responses do not expose proactive request-rate counters; `/usage` reports the documented per-key credit/spend fields instead.
@@ -226,6 +326,7 @@ packages/pi-usage/
 ├── 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
@@ -235,7 +336,7 @@ packages/pi-usage/
 │   ├── 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/     # Codex, GitHub Copilot, and OpenRouter normalization adapters
+│   ├── providers/     # Provider-specific usage normalization adapters
 │   └── types.ts       # Common presentation and adapter contracts
 ├── test/
 ├── README.md
@@ -250,7 +351,7 @@ The generated runtime is built from the authoritative `src/index.ts` graph and d
 
 ## 🔎 Keywords
 
-Pi extension, Pi coding agent, usage, quota, OpenAI Codex usage, ChatGPT subscription limits, GitHub Copilot AI credits, GitHub Copilot premium requests, OpenRouter credits, API-key spend limits, TypeScript Pi package, npm Pi extension.
+Pi extension, Pi coding agent, usage, quota, OpenAI Codex usage, ChatGPT subscription limits, Kimi For Coding, Kimi Coding Plan usage, GitHub Copilot AI credits, GitHub Copilot premium requests, OpenRouter credits, xAI OAuth usage, Grok subscription allowance, API-key spend limits, TypeScript Pi package, npm Pi extension.
 
 ## 📄 License