@narumitw/pi-usage 0.59.0 → 0.60.1

package/README.md

@@ -3,7 +3,6 @@
 [![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)
 
 Inspect usage and DeepSeek API balance for Pi's active provider account, query other configured providers, and toggle Fast mode for supported OpenAI Codex models.
-
 The extension keeps each provider's native quota, allowance, and spending semantics instead of treating unlike values as equivalent.
 xAI OAuth subscription reporting follows the reviewed Grok Build contract and runs only after an explicit `/usage` action.
 
@@ -17,7 +16,7 @@ xAI OAuth subscription reporting follows the reviewed Grok Build contract and ru
 - 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.
+- 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.
@@ -57,6 +56,7 @@ The package declares `dist/index.ts`, so an unbuilt local checkout must run the
 ## 🚀 Quick start
 
 Run `/usage` in TUI or RPC mode to inspect the active provider, refresh its usage, or choose another configured provider.
+When a provider exposes several billing targets, `/usage` asks for one target before querying usage.
 Run `/fast` to toggle Fast mode for a supported active Codex model.
 
 ## 💬 Commands
@@ -85,6 +85,21 @@ 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.
@@ -94,7 +109,7 @@ Successful, already-completed, not-needed, and no-credit outcomes are reported s
 
 ## ⚙️ Settings
 
-Choose **Settings** in `/usage` to edit Codex Fast mode, the Codex reset countdown, and the Fireworks account selector through Pi's settings-list interaction in TUI mode.
+Choose **Settings** in `/usage` to edit Codex Fast mode and the Codex reset countdown through Pi's settings-list interaction in TUI mode.
 RPC mode reports the active manual settings path instead of opening terminal UI.
 
 These preferences live in `pi-usage.json` under Pi's user agent directory, normally `~/.pi/agent/pi-usage.json`.
@@ -105,24 +120,13 @@ 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.
 
-### Fireworks account
-
-A Fireworks key that can see one account needs no setting.
-For a key that can see several accounts, choose **Fireworks account** in the TUI Settings screen, or set the exact visible account slug in `pi-usage.json` and run `/reload`:
-
-```json
-{
-  "fireworksAccountId": "acme"
-}
-```
-
-The `fireworksAccountId` setting is validated as a URL-safe account slug and then checked against the official account listing before billing data is requested.
-Submit a blank value from the TUI input, or remove the JSON field and run `/reload`, to restore single-account auto-selection.
+Target selections are stored only as IDs in the provider-neutral `selectedTargets` object in this file and are managed through `/usage`, not the Settings screen.
+The former `fireworksAccountId` field remains read-compatible: it supplies `selectedTargets.fireworks` in memory only when the generic value is absent.
+A successful explicit Fireworks account selection writes the generic field and removes the legacy field atomically; ordinary reads do not rewrite the file.
 
 ### Codex Fast mode
 
 Run `/fast` without arguments 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 `codexFastMode` preference defaults to Off.
 
@@ -138,7 +142,6 @@ Repair or remove an invalid file, then run `/reload` before trying the toggle ag
 ### Codex statusline reset countdown
 
 The `codexStatusResetCountdown` preference defaults to `true`. It replaces the window labels with the time remaining until each returned limit resets.
-
 Turn **Codex reset countdown** Off in the TUI Settings screen, or set it to `false` in `pi-usage.json` and run `/reload`, to restore the legacy `5h` and `wk` labels:
 
 ```json
@@ -282,7 +285,8 @@ DeepSeek Harness `cd5ef8148158c3a752a658978873241fdf8e2bbc` reports only per-req
 - 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; a key that can see several accounts must set `fireworksAccountId` in `pi-usage.json` to one of the listed account slugs, and the slug must remain visible to the key.
+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.
@@ -374,9 +378,9 @@ xAI identity and billing requests occur only after an explicit current, configur
 
 - 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
+- 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 reported plan level
+- 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`
 
@@ -385,6 +389,7 @@ The extension classifies both forms by the provider's window unit and does not l
 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.
 
 ## 🧭 Current and configured accounts
@@ -392,8 +397,8 @@ Only the official `api.z.ai` and `open.bigmodel.cn` origins are queried; other o
 `Current` identifies the provider and credential used by Pi's selected model.
 `Configured` identifies runtime auth for another supported provider, not an active provider.
 
-The extension does not enumerate multiple accounts inside one provider and does not switch accounts.
-Account selection remains owned by Pi or an account-management extension.
+The extension selects one provider target for one query and never flattens targets into provider rows or aggregates every visible target.
+Provider adapters own target discovery and validation; core owns one-target selection, persistence, cache identity, cancellation, and UI.
 A compatible credential owner may offer the verified active named account through the versioned process-local protocol without exposing its account label or storage.
 Without such an owner, `pi-usage` retains its standalone Pi `auth.json` behavior.
 An older or incompatible owner degrades to the existing authentication-unavailable result when the stored login does not match runtime auth.
@@ -459,7 +464,7 @@ An absent or incompatible peer preserves standalone fallback and fail-closed mis
 - 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.
 - DeepSeek reports current API balance only; it does not expose historical usage, quota windows, reset times, or account-wide token totals through the balance endpoint.
-- Fireworks reports rated 30-day spend only; credit balance and spend caps are visible only in the Fireworks web console, and keys that can see several accounts must set `fireworksAccountId` in `pi-usage.json`.
+- Fireworks reports rated 30-day spend only; credit balance and spend caps are visible only in the Fireworks web console, and `/usage` must select one visible account before querying a multi-account key.
 - Moonshot AI reports current API balance only; it does not expose historical spend, aggregate token usage, quota windows, or reset times through the balance endpoint.
 - Vercel AI Gateway reports current team credits and lifetime spend only; Custom Reporting and request-rate counters are not queried.
 - MiniMax Token Plan field semantics have changed over time; contradictory counts and percentages are reported as unavailable rather than guessed.
@@ -486,6 +491,7 @@ packages/pi-usage/
 │   ├── 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
@@ -501,7 +507,6 @@ packages/pi-usage/
 ```
 
 `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`.
 
 ## 🔎 Keywords