@wayner6/pi-usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wayne and Pi Usage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# Pi Usage
+
+**Real-time provider balances, quota windows, and rate limits for [Pi](https://github.com/earendil-works/pi-mono) and [pi-web](https://github.com/agegr/pi-web).**
+
+[简体中文文档](./README_zh.md)
+
+---
+
+## Supported Providers & Authentication Types
+
+| Provider / Target | Auth Type | Monitored Quota / Balance Data |
+| :--- | :--- | :--- |
+| **OpenAI Codex** | **OAuth** (ChatGPT Plus / Pro) | Official 5-hour and 7-day sliding quota windows with reset countdowns |
+| **xAI / Grok** | **OAuth** | Identity verification and active spending/credit limit status probe |
+| **Anthropic Claude** | **OAuth** / **API Key** | Claude Pro/Max OAuth subscription detection or official API Key rate limits via headers |
+| **DeepSeek Direct** | **API Key** | Exact account monetary balance (granted + topped-up in CNY/USD) |
+| **GLM / 智谱 BigModel** | **API Key** | Coding Plan multi-tier sliding windows (5h, 7d, MCP); notice displayed if using standard Pay-as-you-go key (official API only supports quota display for Coding Plan) |
+| **CLIProxyAPI Proxies** | **API Key / Bridge** | Upstream quota windows and reset intervals via server-side [`pi-bridge`](https://github.com/abix5/pi-cliproxyapi-bridge) |
+
+---
+
+## Key Features
+
+- **Real-Time Quota & Multi-Window Tracking**: Automatically monitors balances, subscription states, and multiple sliding windows (e.g. `Codex 5h 92% · 7d 85%`) tailored to your currently active model.
+- **Privacy & Security First**: Zero browser cookies, telemetry, or external proxies—reuses your local Pi credentials securely with strict same-origin protection.
+
+---
+
+## Installation
+
+### Method 1: Install in Pi (CLI / TUI)
+
+Run the following command directly in your terminal:
+
+```bash
+pi install npm:@wayner6/pi-usage
+```
+
+### Method 2: Install in pi-web (Web Interface)
+
+1. Open **Settings** (设置) at the bottom left -> **Plugins** (插件).
+2. Click **+ Add Plugin** (添加插件).
+3. In the **Source** input box, enter:
+```text
+npm:@wayner6/pi-usage
+```
+4. Choose `global` scope, then click **Install** (安装).
+
+---
+
+## Usage & Refresh Behavior
+
+### Refresh Mechanism
+1. **Automatic Refresh on Dialogue**:
+   - In both `pi` and `pi-web`, **starting a conversation (sending any prompt) automatically refreshes and streams the latest balance/quota** for the active model.
+2. **Model Switching in pi-web**:
+   - When switching models while the agent is idle, the footer quota updates **automatically on your next prompt**.
+   - To refresh immediately without sending a message, click **"Reload Session"** (重载会话) in the menu or sidebar.
+3. **Background Updates**:
+   - Polls and updates countdowns periodically in the background (default: every 120s).
+
+### Available Commands
+
+Type `/usage` or `/quota` in the chat input:
+
+| Command | Description |
+| :--- | :--- |
+| `/usage` | Show aggregated balance and quota details for all configured providers |
+| `/usage current` | Show usage details specifically for the currently active model |
+| `/usage refresh` | Force an immediate network refresh for the current provider |
+| `/usage doctor` | Diagnose adapter states, provider authentication, and bridge connectivity |
+| `/usage settings` | View or adjust configuration (status bar, widget, intervals) |
+
+### Configuration Options
+
+Adjust preferences directly in chat via `/usage settings`:
+```text
+/usage settings status on|off       # Toggle the compact footer status line (Default: on)
+/usage settings widget on|off       # Toggle the detailed persistent widget (Default: off)
+/usage settings interval <seconds>  # Set background polling interval (Default: 120s)
+/usage settings timeout <seconds>   # Set request timeout (Default: 10s)
+```
+Configuration is automatically saved to `~/.pi/agent/pi-usage/config.json`.
+
+---
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+Pi Usage runs as a Pi extension with the user's local permissions. Review extensions before installing them.
+
+## Credential policy
+
+- Provider credentials are resolved through Pi at runtime and are never written by Pi Usage.
+- CLIProxyAPI quota access uses an ordinary inference API key through `pi-bridge`; management keys are unsupported.
+- Authenticated requests stay on the configured provider origin. Cross-origin redirects are rejected.
+- Browser cookies, local storage, and private provider dashboard sessions are not read.
+- Quota responses are cached in memory only.
+
+## Reporting
+
+Do not include API keys, management passwords, full auth files, or raw Authorization headers in issues. Revoke exposed credentials immediately.

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@wayner6/pi-usage",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Provider balance and quota monitoring for Pi and pi-web",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["pi-package", "pi", "usage", "quota", "deepseek", "cliproxyapi"],
+  "files": ["index.ts", "src", "README.md", "LICENSE", "SECURITY.md"],
+  "pi": { "extensions": ["./index.ts"] },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "^24.10.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "verify": "npm run check && npm test",
+    "pack:check": "npm pack --dry-run"
+  }
+}

package/src/core/cache.ts

@@ -0,0 +1,44 @@
+import type { UsageSnapshot } from "./types.ts";
+
+export class UsageCache {
+  private snapshots = new Map<string, UsageSnapshot>();
+  private pending = new Map<string, Promise<UsageSnapshot>>();
+
+  get(key: string): UsageSnapshot | undefined {
+    return this.snapshots.get(key);
+  }
+
+  values(): UsageSnapshot[] {
+    return [...this.snapshots.values()];
+  }
+
+  async coalesce(key: string, operation: () => Promise<UsageSnapshot>): Promise<UsageSnapshot> {
+    const existing = this.pending.get(key);
+    if (existing) return existing;
+    const promise = operation()
+      .then((snapshot) => {
+        this.snapshots.set(key, snapshot);
+        return snapshot;
+      })
+      .catch((error) => {
+        const old = this.snapshots.get(key);
+        if (!old) throw error;
+        const stale: UsageSnapshot = {
+          ...old,
+          state: "stale",
+          stale: true,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        this.snapshots.set(key, stale);
+        return stale;
+      })
+      .finally(() => this.pending.delete(key));
+    this.pending.set(key, promise);
+    return promise;
+  }
+
+  clear(): void {
+    this.snapshots.clear();
+    this.pending.clear();
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,77 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface UsageConfig {
+  display: { status: boolean; widget: boolean; detailsDefault: "all" | "current" };
+  refresh: { intervalSeconds: number; timeoutSeconds: number };
+  adapters: {
+    deepseek: { enabled: boolean };
+    cliproxyPiBridge: { enabled: boolean };
+    openaiCodex: { enabled: boolean };
+    xai: { enabled: boolean };
+    anthropic: { enabled: boolean };
+    glm: { enabled: boolean };
+  };
+  providerOverrides: Record<string, "deepseek" | "cliproxy-pi-bridge" | "openai-codex" | "xai" | "anthropic" | "glm" | "disabled">;
+  modelMappings: Array<{ provider: string; modelPattern: string; quotaProvider: string }>;
+}
+
+export const DEFAULT_CONFIG: UsageConfig = {
+  display: { status: true, widget: false, detailsDefault: "all" },
+  refresh: { intervalSeconds: 120, timeoutSeconds: 10 },
+  adapters: {
+    deepseek: { enabled: true },
+    cliproxyPiBridge: { enabled: true },
+    openaiCodex: { enabled: true },
+    xai: { enabled: true },
+    anthropic: { enabled: true },
+    glm: { enabled: true },
+  },
+  providerOverrides: {},
+  modelMappings: [],
+};
+
+export function configPath(): string {
+  return join(getAgentDir(), "pi-usage", "config.json");
+}
+
+function clamp(value: unknown, min: number, max: number, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+export async function loadConfig(): Promise<UsageConfig> {
+  try {
+    const raw = await readFile(configPath(), "utf8");
+    const parsed = JSON.parse(raw) as Partial<UsageConfig>;
+    return {
+      display: {
+        status: parsed.display?.status ?? DEFAULT_CONFIG.display.status,
+        widget: parsed.display?.widget ?? DEFAULT_CONFIG.display.widget,
+        detailsDefault: parsed.display?.detailsDefault === "current" ? "current" : "all",
+      },
+      refresh: {
+        intervalSeconds: clamp(parsed.refresh?.intervalSeconds, 10, 86400, DEFAULT_CONFIG.refresh.intervalSeconds),
+        timeoutSeconds: clamp(parsed.refresh?.timeoutSeconds, 2, 60, DEFAULT_CONFIG.refresh.timeoutSeconds),
+      },
+      adapters: {
+        deepseek: { enabled: parsed.adapters?.deepseek?.enabled ?? DEFAULT_CONFIG.adapters.deepseek.enabled },
+        cliproxyPiBridge: { enabled: parsed.adapters?.cliproxyPiBridge?.enabled ?? DEFAULT_CONFIG.adapters.cliproxyPiBridge.enabled },
+        openaiCodex: { enabled: parsed.adapters?.openaiCodex?.enabled ?? DEFAULT_CONFIG.adapters.openaiCodex.enabled },
+        xai: { enabled: parsed.adapters?.xai?.enabled ?? DEFAULT_CONFIG.adapters.xai.enabled },
+        anthropic: { enabled: parsed.adapters?.anthropic?.enabled ?? DEFAULT_CONFIG.adapters.anthropic.enabled },
+        glm: { enabled: parsed.adapters?.glm?.enabled ?? DEFAULT_CONFIG.adapters.glm.enabled },
+      },
+      providerOverrides: parsed.providerOverrides ?? {},
+      modelMappings: Array.isArray(parsed.modelMappings) ? parsed.modelMappings : [],
+    };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+export async function saveConfig(config: UsageConfig): Promise<void> {
+  const file = configPath();
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/src/core/security.ts

@@ -0,0 +1,49 @@
+const SENSITIVE_KEYS = /authorization|api[-_]?key|token|secret|password/i;
+
+export function normalizeOrigin(baseUrl: string): URL | undefined {
+  try {
+    return new URL(baseUrl);
+  } catch {
+    return undefined;
+  }
+}
+
+export function bridgeUrl(baseUrl: string, path: "capabilities" | "usage", force = false): URL {
+  const base = new URL(baseUrl);
+  const result = new URL(`/v0/resource/plugins/pi-bridge/${path}`, base.origin);
+  if (force && path === "usage") result.searchParams.set("refresh", "1");
+  return result;
+}
+
+export async function sameOriginFetch(
+  url: URL,
+  init: RequestInit,
+  fetchFn: typeof fetch,
+  expectedOrigin: string,
+  redirects = 0,
+): Promise<Response> {
+  if (url.origin !== expectedOrigin) throw new Error("Refusing to send credentials across origins");
+  const response = await fetchFn(url, { ...init, redirect: "manual" });
+  if (response.status >= 300 && response.status < 400) {
+    if (redirects >= 3) throw new Error("Too many redirects");
+    const location = response.headers.get("location");
+    if (!location) return response;
+    const next = new URL(location, url);
+    if (next.origin !== expectedOrigin) throw new Error("Refusing cross-origin authenticated redirect");
+    return sameOriginFetch(next, init, fetchFn, expectedOrigin, redirects + 1);
+  }
+  return response;
+}
+
+export function redact(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, SENSITIVE_KEYS.test(key) ? "[REDACTED]" : redact(item)]));
+  }
+  return value;
+}
+
+export function safeError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]").replace(/sk-[A-Za-z0-9_-]+/g, "sk-…");
+}

package/src/core/types.ts

@@ -0,0 +1,67 @@
+import type { Api, AuthResult, Model, Provider } from "@earendil-works/pi-ai";
+
+export type UsageState =
+  | "ok"
+  | "empty"
+  | "stale"
+  | "unsupported"
+  | "not-installed"
+  | "unauthorized"
+  | "incompatible"
+  | "unavailable";
+
+export type Metric =
+  | { kind: "balance"; id: string; label: string; amount: number; currency: string; detail?: string }
+  | { kind: "quota-window"; id: string; label: string; remainingFraction: number; resetAt?: string; detail?: string }
+  | { kind: "credits"; id: string; label: string; remaining: number; unit: string; detail?: string }
+  | { kind: "usage-limit"; id: string; label: string; used: number; limit: number; unit: string; detail?: string }
+  | { kind: "rate-limit"; id: string; label: string; value: number; unit: string; detail?: string }
+  | { kind: "status"; id: string; label: string; value: string; detail?: string }
+  | { kind: "custom"; id: string; label: string; value: string; detail?: string };
+
+export interface UsageAccount {
+  id: string;
+  provider: string;
+  label: string;
+  status?: string;
+  disabled?: boolean;
+  unavailable?: boolean;
+  metrics: Metric[];
+  rawGroups?: unknown;
+  error?: string;
+}
+
+export interface UsageSnapshot {
+  adapterId: string;
+  sourceProviderId: string;
+  displayName: string;
+  state: UsageState;
+  fetchedAt: string;
+  stale?: boolean;
+  accounts: UsageAccount[];
+  summary?: string;
+  error?: string;
+  diagnostic?: string;
+}
+
+export interface ProviderTarget {
+  providerId: string;
+  model?: Model<Api>;
+  provider?: Provider<Api>;
+  baseUrl?: string;
+  auth?: AuthResult;
+}
+
+export interface FetchContext {
+  target: ProviderTarget;
+  signal: AbortSignal;
+  force: boolean;
+  fetchFn: typeof fetch;
+}
+
+export interface UsageAdapter {
+  id: string;
+  label: string;
+  canHandle(target: ProviderTarget): boolean;
+  fetch(context: FetchContext): Promise<UsageSnapshot>;
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { loadConfig, type UsageConfig } from "./core/config.ts";
+import type { UsageSnapshot } from "./core/types.ts";
+import { ProviderUsageController } from "./modules/provider/controller.ts";
+import { showDetails } from "./ui/details.ts";
+import { compactSnapshot, snapshotLines } from "./ui/format.ts";
+import { handleSettings } from "./settings.ts";
+
+const STATUS_ID = "pi-usage";
+const WIDGET_ID = "pi-usage-provider";
+
+export default function (pi: ExtensionAPI) {
+  let config: UsageConfig;
+  let controller: ProviderUsageController;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let modelWatchTimer: ReturnType<typeof setInterval> | undefined;
+  let lastContext: ExtensionContext | undefined;
+  let observedModelKey: string | undefined;
+  let renderGeneration = 0;
+
+  function modelKey(model: Model<Api> | undefined): string | undefined {
+    return model ? `${model.provider}/${model.id}/${model.baseUrl}` : undefined;
+  }
+
+  function liveModel(ctx: ExtensionContext): Model<Api> | undefined {
+    return ctx.model;
+  }
+
+  function render(ctx: ExtensionContext, snapshot?: UsageSnapshot, model: Model<Api> | undefined = ctx.model): void {
+    const current = controller.currentView(ctx, snapshot, model);
+    ctx.ui.setStatus(STATUS_ID, config.display.status ? ctx.ui.theme.fg(current?.state === "ok" ? "success" : current?.state === "stale" ? "warning" : "dim", compactSnapshot(current)) : undefined);
+    ctx.ui.setWidget(WIDGET_ID, config.display.widget && current ? snapshotLines(current) : undefined, { placement: "belowEditor" });
+  }
+
+  async function refreshCurrent(ctx: ExtensionContext, force = false, model: Model<Api> | undefined = liveModel(ctx)): Promise<UsageSnapshot | undefined> {
+    lastContext = ctx;
+    const generation = ++renderGeneration;
+    try {
+      // If we already have a cached snapshot for this provider, render it immediately
+      // with group recalculation so model switches are instant without flicker.
+      const cached = model ? controller.cache.values().find((item) => item.sourceProviderId === model.provider) : undefined;
+      render(ctx, cached, model);
+      const snapshot = await controller.refreshCurrent(ctx, force, model);
+      if (generation === renderGeneration) render(ctx, snapshot, model);
+      return snapshot;
+    } catch (error) {
+      const fallback = model ? controller.cache.values().find((item) => item.sourceProviderId === model.provider) : undefined;
+      if (generation === renderGeneration) render(ctx, fallback, model);
+      return fallback;
+    }
+  }
+
+  function startTimer(ctx: ExtensionContext): void {
+    if (timer) clearInterval(timer);
+    timer = setInterval(() => { if (lastContext) void refreshCurrent(lastContext); }, config.refresh.intervalSeconds * 1000);
+    timer.unref?.();
+    lastContext = ctx;
+    observedModelKey = modelKey(liveModel(ctx));
+
+    // pi-web versions can update ctx.model without reliably delivering model_select
+    // to package extensions. This watcher performs no network I/O unless the model
+    // identity actually changes, and keeps the footer honest during that gap.
+    if (modelWatchTimer) clearInterval(modelWatchTimer);
+    modelWatchTimer = setInterval(() => {
+      if (!lastContext) return;
+      const nextModel = liveModel(lastContext);
+      const nextKey = modelKey(nextModel);
+      if (nextKey === observedModelKey) return;
+      observedModelKey = nextKey;
+      void refreshCurrent(lastContext, false, nextModel);
+    }, 750);
+    modelWatchTimer.unref?.();
+  }
+
+  async function command(args: string, ctx: ExtensionCommandContext): Promise<void> {
+    const [action = config.display.detailsDefault, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+    if (action === "settings") {
+      config = await handleSettings(rest.join(" "), ctx, config);
+      controller.setConfig(config);
+      startTimer(ctx);
+      await refreshCurrent(ctx);
+      return;
+    }
+    if (action === "doctor") {
+      const current = await controller.refreshCurrent(ctx, false);
+      const deepSeekAuth = ctx.modelRegistry.getProviderAuthStatus("deepseek");
+      const lines = [
+        `Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}`,
+        `Provider base URL: ${ctx.model?.baseUrl ? new URL(ctx.model.baseUrl).origin : "not exposed by model"}`,
+        `Current adapter: ${current?.adapterId ?? "none"}`,
+        `Current state: ${current?.state ?? "unavailable"}`,
+        `Current auth: ${current?.state === "unauthorized" ? "missing or rejected" : "resolved without displaying secret"}`,
+        `DeepSeek auth: ${deepSeekAuth.configured ? `configured${deepSeekAuth.source ? ` (${deepSeekAuth.source})` : ""}` : "not configured"}`,
+        `Hint: /usage current shows only ${ctx.model?.provider ?? "the active provider"}; use /usage all for DeepSeek plus other configured providers.`,
+        ...(current?.error ? [`Problem: ${current.error}`] : []),
+        ...(current?.state === "not-installed" ? ["Fix: install and enable pi-bridge on the CLIProxyAPI server."] : []),
+      ];
+      ctx.ui.notify(lines.join("\n"), current?.state === "ok" || current?.state === "stale" ? "info" : "warning");
+      return;
+    }
+    if (action === "refresh") {
+      const snapshot = await refreshCurrent(ctx, true);
+      await showDetails(ctx, snapshot ? [controller.currentView(ctx, snapshot) ?? snapshot] : []);
+      return;
+    }
+    if (action === "current") {
+      const snapshot = await refreshCurrent(ctx);
+      await showDetails(ctx, snapshot ? [controller.currentView(ctx, snapshot) ?? snapshot] : []);
+      return;
+    }
+    const snapshots = await controller.refreshAll(ctx, false);
+    await showDetails(ctx, snapshots);
+  }
+
+  pi.registerCommand("usage", { description: "Show provider balances and quota windows", handler: command });
+  pi.registerCommand("quota", { description: "Alias for /usage", handler: command });
+
+  pi.on("session_start", async (_event, ctx) => {
+    config = await loadConfig();
+    controller = new ProviderUsageController(config);
+    startTimer(ctx);
+    await refreshCurrent(ctx);
+  });
+
+  pi.on("model_select", async (event, ctx) => {
+    observedModelKey = modelKey(event.model);
+    const cached = event.model ? controller.cache.values().find((item) => item.sourceProviderId === event.model.provider) : undefined;
+    render(ctx, cached, event.model);
+    await refreshCurrent(ctx, false, event.model);
+  });
+  pi.on("session_shutdown", async () => {
+    if (timer) clearInterval(timer);
+    if (modelWatchTimer) clearInterval(modelWatchTimer);
+    timer = undefined;
+    modelWatchTimer = undefined;
+    observedModelKey = undefined;
+    renderGeneration++;
+    lastContext = undefined;
+    controller?.cache.clear();
+  });
+}