pi-myusage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-myusage 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,151 @@
+# 📊 pi-myusage — Provider Usage, API Balance, and Codex Fast Mode for Pi
+
+[![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 windows and API balances for Pi's active provider account, query every other configured provider, and toggle persistent Fast routing for OpenAI Codex models.
+The extension keeps each provider's native quota, allowance, and billing semantics instead of treating unlike values as equivalent, and resolves credentials current-model-first so any number of custom providers in `models.json` — with plain API keys or OAuth — report correctly.
+
+## ✨ Features
+
+- Shows the active provider's usage windows or balance on a single statusline line, each window carrying its own reset countdown.
+- `/usage` reports every provider that has both a usage adapter and resolvable credentials; unconfigured providers are skipped instead of surfacing auth noise.
+- Toggles persistent Fast and Ultrafast routing for `gpt-*` models on any OpenAI-compatible provider through `/fast` and `/ultrafast`.
+- Matches adapters from the active model itself (provider id aliases, base URL origin, id family) — no fixed provider-id assumptions, no official-origin refusals.
+- Resolves credentials through Pi's runtime auth chain (`getApiKeyAndHeaders` → provider auth → stored credentials), with a 30-second memo for static keys only; OAuth paths always re-resolve so token refresh keeps working.
+- Refreshes after every completed turn (bounded to one fetch per 30 s), on model switch, on session start, and on a configurable timer; in-flight requests are deduplicated and aborted on shutdown.
+- Multi-request providers (Cline, OpenRouter) fetch independent endpoints in parallel; failed lookups degrade to per-provider snapshots instead of failing the report.
+
+## 📦 Install
+
+Requires Pi 0.84.0 or newer (`getApiKeyAndHeaders`, `before_provider_request` payload replacement).
+
+```bash
+pi install npm:pi-myusage
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:pi-myusage
+```
+
+Or point Pi at a local checkout — the package ships raw TypeScript and needs no build step:
+
+```bash
+pi install ./pi-myusage
+```
+
+## 🚀 Quick start
+
+Start Pi and wait a moment: the statusline shows the active provider's windows, for example `GLM 5h 56% (2m) · 7d 82% (3d 4h)` or `$12.34 · DeepSeek`.
+Run `/usage` for every configured provider's details, `/usage refresh` to force a fresh fetch, and `/fast` (on a supported Codex model) to toggle Fast routing.
+
+## 💬 Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/usage` | Report usage for every provider with an adapter and configured credentials. |
+| `/usage refresh` | Force a fresh fetch of the active provider. |
+| `/usage fast` | Same as `/fast`. |
+| `/usage ultrafast` | Same as `/ultrafast`. |
+| `/fast` | Toggle persistent Fast routing (`service_tier: priority`) for the active `gpt-*` model. |
+| `/ultrafast` | Toggle persistent Ultrafast routing (`service_tier: ultrafast`), the separate Cerebras-backed tier. |
+
+## ⚙️ Settings
+
+Preferences live in `pi-myusage.json` under Pi's user agent directory, normally `~/.pi/agent/pi-myusage.json`.
+It holds a single field — `codexFastMode`: `false`, `"fast"`, or `"ultrafast"` — written by `/fast` and `/ultrafast` and read at every session start (`true` from older versions is read as `"fast"`).
+The statusline auto-refresh interval is fixed at 300 seconds; usage always refreshes after each completed turn as well.
+
+### Fast and Ultrafast modes
+
+Two independent service tiers, mutually exclusive, each toggled by its own command:
+
+- **Fast** (`/fast`) sends `service_tier: "priority"` — about 1.5× faster (up to 2.5× on `gpt-5.6-sol`), uses more of your plan allowance; message costs are corrected ×2 (×2.5 for `gpt-5.5`) on the official Codex endpoint.
+- **Ultrafast** (`/ultrafast`) sends `service_tier: "ultrafast"` — the separate Cerebras-backed tier (up to 14× faster). No model restriction is imposed here: any `gpt-*` model can request it, and OpenAI falls back or errors per account entitlement and model support. Costs are shown as returned — no multiplier is applied.
+
+Both apply to every `gpt-*` model on an OpenAI-family API — `openai-completions`, `openai-responses`, or `openai-codex-responses` — including relays and gateways. Disabling either sends an explicit `service_tier: "default"`.
+The statusline appends `· fast` or `· ultrafast` whenever the active mode is effective — even when no usage window is displayed.
+Non-gpt models and non-OpenAI APIs are never rewritten.
+
+## 📋 Provider semantics
+
+Usage is provider-specific: a subscription window, a prepaid balance, and rated spend are not interchangeable.
+
+| Provider | Reported data |
+| --- | --- |
+| OpenAI Codex | 5h/7d subscription windows with per-window resets, credits balance |
+| Anthropic Claude | OAuth subscription windows (5h/7d/per-model); API keys report pay-as-you-go status |
+| Kimi / Moonshot | Coding Plan usage windows, or platform API balance (USD/CNY) |
+| OpenRouter | Per-key usage limit and account credit balance |
+| OpenCode Zen | Rolling, weekly, and monthly plan windows |
+| MiniMax Global/China | Token Plan windows (JWT keys) or pay-as-you-go balance |
+| GLM / Zhipu / Z.AI | Coding Plan quota windows (5h/weekly, any `TOKENS_LIMIT` window echoed), MCP allowance, plan level |
+| DeepSeek | Exact current CNY and USD API balances |
+| xAI / Grok | OAuth subscription windows and credits; API keys report userinfo status |
+| Google Vertex AI | Status only — billing lives in GCP, quota is not queryable via model credentials |
+| Gemini API / AI Studio | Key validation and model count — no public quota endpoint exists |
+| Vercel AI Gateway | Credit balance and lifetime spend |
+| CLIProxyAPI | Per-api-user request counts via the management API (`CLIPROXY_MANAGEMENT_KEY`), else proxy status |
+| GitHub Copilot | Plan entitlements and quota snapshots |
+| Fireworks | Rated trailing 30-day spend |
+| Baseten | Trailing 30-day Model APIs spend after credits |
+| Cline | ClinePass five-hour/weekly/monthly utilization windows and credit balance (micro-USD) |
+
+## 🧭 Matching and credentials
+
+The adapter is chosen from the **current model**: provider id aliases first, then base URL origin, then id families (for example any `glm-*` provider without a base URL).
+Credentials resolve through Pi's runtime chain and are memoized for 30 s only when static — OAuth results always re-resolve.
+A provider id whose base URL points elsewhere never sends its credential to the official origin (the `glm-` prefix rule requires no base URL for exactly this reason).
+
+## 📊 Statusline behavior
+
+The status item key is `pi-myusage`.
+All usage windows render on one line with per-window reset suffixes; providers without windows render balances (`$0.50 · Cline`, `¥12.34 · DeepSeek`).
+The line refreshes after each completed turn, on model switch, and on the interval timer; chain-timeout failures are reported without pinning the cache, so the next trigger retries immediately.
+With [`pi-cc-extensions`](https://www.npmjs.com/package/pi-cc-extensions) installed, the chip lands on footer line 1 next to the token stats — the key deliberately avoids that extension's reserved `pi-usage` status key, which it erases when its own usage pull is empty.
+
+## 🔒 Security and privacy
+
+Credentials resolve in memory, are never logged or persisted by this extension, and error text is scrubbed of token-like fragments before display.
+Every provider call is a read-only `GET` to the provider's official usage endpoint with `redirect: "error"`, carrying only that provider's resolved credential.
+Usage endpoints are queried with exactly the credential the model itself uses — nothing is sent anywhere the active provider doesn't already send it.
+Pi extensions run with the user's process privileges; install only trusted extensions.
+
+## 🚧 Limitations
+
+- Providers without a public quota API (Vertex, Gemini, CLIProxyAPI without a management key) degrade to status metrics instead of inventing numbers.
+- Provider reports are snapshots and may lag the provider's own accounting.
+- Fireworks and Baseten expose rated 30-day spend only; balances and caps live in their web consoles.
+- MiniMax window counts are historically ambiguous (used vs remaining); contradictory payloads are reported as unavailable rather than guessed.
+- Cline balance is micro-USD; the dashboard's credit figure equals `balance / 1,000,000`.
+- Kimi Coding and Cline usage-limits rely on provider-owned endpoints that may change without notice.
+- A later-loaded extension can still rewrite the final provider payload, so arbitrary third-party payload conflicts cannot be prevented.
+
+## 🗂️ Package layout
+
+```text
+pi-myusage/
+├── index.ts          # Pi entrypoint: commands, events, timers, statusline, Fast routing
+├── src/
+│   ├── adapters/     # One file per provider (17 adapters)
+│   ├── auth.ts       # Credential resolution chain and memo
+│   ├── match.ts      # Adapter registry and current-model-first matching
+│   ├── codex-fast.ts # Fast tier rewrite and cost correction (pure logic)
+│   ├── format.ts     # Window summaries, bars, relative times
+│   ├── http.ts       # fetchJson with timeout/abort, safe error redaction
+│   ├── settings.ts   # pi-myusage.json load/save
+│   └── types.ts      # Snapshot, metric, adapter, target contracts
+└── test/selfcheck.ts # Assert-based self-check for pure logic
+```
+
+## 🔎 Verify
+
+```bash
+npm run verify   # tsc --noEmit (strict, noUnused*) + tsx test/selfcheck.ts
+```
+
+## 📄 License
+
+MIT.
+See [`LICENSE`](./LICENSE).

package/index.ts

@@ -0,0 +1,307 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  codexFastAvailability,
+  correctCodexFastMessage,
+  fastModeIsEffective,
+  fastSuffix,
+  rewriteServiceTierPayload,
+  tierForMode,
+  type FastMode,
+} from "./src/codex-fast.ts";
+import { compactStatus, detailLines } from "./src/format.ts";
+import { safeError } from "./src/http.ts";
+import { adapterFor, configuredTargets, currentTarget, withCredentials } from "./src/match.ts";
+import type { ProviderTarget, UsageAdapter, UsageSnapshot } from "./src/types.ts";
+
+const REFRESH_INTERVAL_S = 300;
+
+function fastModePath(): string {
+  return join(getAgentDir(), "pi-myusage.json");
+}
+
+function loadFastMode(): FastMode {
+  try {
+    const raw = (JSON.parse(readFileSync(fastModePath(), "utf8")) as { codexFastMode?: unknown }).codexFastMode;
+    if (raw === true || raw === "fast") return "fast";
+    if (raw === "ultrafast") return "ultrafast";
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function saveFastMode(mode: FastMode): void {
+  const path = fastModePath();
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ codexFastMode: mode }, null, 2)}\n`);
+}
+
+const STATUS_ID = "pi-myusage";
+
+interface CacheEntry {
+  snapshot: UsageSnapshot;
+  at: number;
+}
+
+interface PendingFast {
+  tier: string;
+  model: Model<Api>;
+}
+
+export default function usagePlus(pi: ExtensionAPI) {
+  let fastMode = loadFastMode();
+  const cache = new Map<string, CacheEntry>();
+  const inflight = new Map<string, Promise<UsageSnapshot | undefined>>();
+  const pendingFast = new Map<string, PendingFast>();
+  const liveControllers = new Set<AbortController>();
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let lastContext: ExtensionContext | undefined;
+  let postTurnTimer: ReturnType<typeof setTimeout> | undefined;
+  let lastPostTurnFetch = 0;
+
+  const POST_TURN_DELAY_MS = 1_500;
+  const POST_TURN_MIN_GAP_MS = 30_000;
+
+  function schedulePostTurnRefresh(): void {
+    if (postTurnTimer) return;
+    postTurnTimer = setTimeout(() => {
+      postTurnTimer = undefined;
+      const ctx = lastContext;
+      if (!ctx) return;
+      if (Date.now() - lastPostTurnFetch < POST_TURN_MIN_GAP_MS) return;
+      lastPostTurnFetch = Date.now();
+      void refresh(ctx, true).catch(() => {});
+    }, POST_TURN_DELAY_MS);
+    postTurnTimer.unref?.();
+  }
+
+  const modelKey = (model: Model<Api> | undefined): string | undefined =>
+    model ? `${model.provider}:${model.id}` : undefined;
+
+  function render(ctx: ExtensionContext, snapshot: UsageSnapshot | undefined): void {
+    let text = compactStatus(snapshot);
+    const suffix = fastModeIsEffective(ctx.model, fastMode) ? fastSuffix(fastMode) : undefined;
+    if (suffix) text = text ? `${text} · ${suffix}` : suffix;
+    ctx.ui.setStatus(STATUS_ID, text);
+  }
+
+  async function fetchSnapshot(ctx: ExtensionContext, force: boolean): Promise<UsageSnapshot | undefined> {
+    const target = currentTarget(ctx);
+    const adapter = adapterFor(target);
+    if (!target || !adapter) return undefined;
+    const key = `${target.providerId}:${target.model?.id ?? ""}`;
+    const cached = cache.get(key);
+    if (!force && cached && Date.now() - cached.at < REFRESH_INTERVAL_S * 1000) return cached.snapshot;
+
+    const existing = inflight.get(key);
+    if (existing) return existing;
+
+    const controller = new AbortController();
+    const chainSignal = AbortSignal.any([controller.signal, AbortSignal.timeout(20_000)]);
+    liveControllers.add(controller);
+    const request = (async (): Promise<UsageSnapshot | undefined> => {
+      try {
+        const prepared = await withCredentials(ctx, target);
+        const snapshot = await adapter.fetch({ target: prepared, signal: chainSignal, force });
+        cache.set(key, { snapshot, at: Date.now() });
+        return snapshot;
+      } catch (error) {
+        if (controller.signal.aborted) return undefined;
+        const snapshot: UsageSnapshot = {
+          adapterId: adapter.id,
+          sourceProviderId: target.providerId,
+          displayName: adapter.label,
+          state: "unavailable",
+          fetchedAt: new Date().toISOString(),
+          accounts: [],
+          error: safeError(error),
+        };
+        if (!chainSignal.aborted) cache.set(key, { snapshot, at: Date.now() });
+        return snapshot;
+      } finally {
+        inflight.delete(key);
+        liveControllers.delete(controller);
+        if (lastContext && modelKey(lastContext.model) === key) {
+          render(lastContext, cache.get(key)?.snapshot);
+        }
+      }
+    })();
+    inflight.set(key, request);
+    return request;
+  }
+
+  async function refresh(ctx: ExtensionContext, force = false): Promise<UsageSnapshot | undefined> {
+    try {
+      lastContext = ctx;
+      const key = modelKey(ctx.model);
+      const snapshot = await fetchSnapshot(ctx, force);
+      if (!snapshot) {
+        render(ctx, undefined);
+        return undefined;
+      }
+      if (modelKey(ctx.model) === key) render(ctx, snapshot);
+      return snapshot;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async function refreshConfigured(ctx: ExtensionContext): Promise<UsageSnapshot[]> {
+    const prepared = await Promise.all(
+      configuredTargets(ctx).map(async (target) => {
+        const adapter = adapterFor(target);
+        if (!adapter) return undefined;
+        try {
+          return { target: await withCredentials(ctx, target), adapter };
+        } catch {
+          return undefined;
+        }
+      }),
+    );
+    const entries = prepared
+      .filter(
+        (entry): entry is { target: ProviderTarget; adapter: UsageAdapter } =>
+          entry !== undefined && Boolean(entry.target.credentials?.apiKey),
+      )
+      .slice(0, 20);
+    const results = await Promise.all(
+      entries.map(async ({ target, adapter }) => {
+        try {
+          return await adapter.fetch({ target, signal: AbortSignal.timeout(20_000), force: true });
+        } catch (error) {
+          return {
+            adapterId: adapter.id,
+            sourceProviderId: target.providerId,
+            displayName: adapter.label,
+            state: "unavailable" as const,
+            fetchedAt: new Date().toISOString(),
+            accounts: [],
+            error: safeError(error),
+          } satisfies UsageSnapshot;
+        }
+      }),
+    );
+    return results;
+  }
+
+  function startTimers(ctx: ExtensionContext): void {
+    if (timer) clearInterval(timer);
+    timer = setInterval(() => {
+      if (lastContext) void refresh(lastContext).catch(() => {});
+    }, REFRESH_INTERVAL_S * 1000);
+    timer.unref?.();
+    lastContext = ctx;
+  }
+
+  async function usageCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+    const action = args.trim().split(/\s+/)[0] ?? "";
+    if (action === "refresh") {
+      const snapshot = await refresh(ctx, true);
+      if (snapshot) ctx.ui.notify(detailLines(snapshot).join("\n"), "info");
+      else ctx.ui.notify("Active provider has no usage adapter.", "warning");
+      return;
+    }
+    if (action === "fast" || action === "ultrafast") {
+      await fastCommand(action, ctx);
+      return;
+    }
+    if (action) {
+      ctx.ui.notify("Usage: /usage [refresh|fast]", "warning");
+      return;
+    }
+    const snapshots = await refreshConfigured(ctx);
+    if (!snapshots.length) {
+      ctx.ui.notify("No configured providers with usage support found.", "warning");
+      return;
+    }
+    ctx.ui.notify(snapshots.map(detailLines).map((lines) => lines.join("\n")).join("\n\n"), "info");
+  }
+
+  async function fastCommand(mode: "fast" | "ultrafast", ctx: ExtensionCommandContext): Promise<void> {
+    const availability = codexFastAvailability(ctx.model, fastMode);
+    if (availability.kind === "unavailable") {
+      ctx.ui.notify(availability.reason, "warning");
+      return;
+    }
+    fastMode = fastMode === mode ? false : mode;
+    try {
+      saveFastMode(fastMode);
+    } catch (error) {
+      ctx.ui.notify(`Could not save fast mode: ${safeError(error)}`, "error");
+      return;
+    }
+    const label = mode === "ultrafast" ? "Ultrafast" : "Fast";
+    ctx.ui.notify(
+      fastMode === mode
+        ? `${label} enabled (persistent). ${label === "Ultrafast" ? "Up to 14× faster." : "~1.5× faster, uses more of your plan allowance."}`
+        : `${label} disabled; standard routing.`,
+      "info",
+    );
+    await refresh(ctx);
+  }
+
+  pi.registerCommand("usage", {
+    description: "Provider usage, quota and balance (/usage [refresh|fast|ultrafast])",
+    handler: usageCommand,
+  });
+  pi.registerCommand("fast", {
+    description: "Toggle persistent Fast routing (service_tier: priority)",
+    handler: (_args, ctx) => fastCommand("fast", ctx),
+  });
+  pi.registerCommand("ultrafast", {
+    description: "Toggle persistent Ultrafast routing (service_tier: ultrafast)",
+    handler: (_args, ctx) => fastCommand("ultrafast", ctx),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    fastMode = loadFastMode();
+    cache.clear();
+    startTimers(ctx);
+    await refresh(ctx);
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    await refresh(ctx);
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    await refresh(ctx);
+  });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    const rewritten = rewriteServiceTierPayload(event.payload, ctx.model, fastMode);
+    const key = ctx.model ? `${ctx.sessionManager.getSessionId()}:${ctx.model.provider}/${ctx.model.id}` : undefined;
+    if (key && ctx.model) {
+      pendingFast.set(key, { tier: tierForMode(fastMode), model: ctx.model });
+    }
+    return rewritten;
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message as Record<string, unknown> | undefined;
+    if (!message || message.role !== "assistant") return undefined;
+    if (typeof message.provider !== "string" || typeof message.model !== "string") return undefined;
+    schedulePostTurnRefresh();
+    const key = `${ctx.sessionManager.getSessionId()}:${message.provider}/${message.model}`;
+    const pending = pendingFast.get(key);
+    pendingFast.delete(key);
+    if (!pending) return undefined;
+    return correctCodexFastMessage(event.message, pending.model, pending.tier) as { message: never } | undefined;
+  });
+
+  pi.on("session_shutdown", async () => {
+    if (postTurnTimer) clearTimeout(postTurnTimer);
+    postTurnTimer = undefined;
+    for (const controller of liveControllers) controller.abort();
+    liveControllers.clear();
+    if (timer) clearInterval(timer);
+    timer = undefined;
+    lastContext = undefined;
+    pendingFast.clear();
+    inflight.clear();
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-myusage",
+  "version": "0.1.0",
+  "description": "Provider usage, quota and balance extension for Pi: current-model-first matching, 17 providers, persistent Codex Fast routing.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "usage",
+    "quota",
+    "balance"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
+    "@types/node": "^24.10.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx test/selfcheck.ts",
+    "verify": "npm run check && npm test"
+  }
+}