@pify/usage 0.4.0 → 0.5.1

package/README.md

@@ -1,13 +1,22 @@
 # @pify/usage
 
-Token and cost reporting for [pi](https://github.com/earendil-works/pi) sessions — a live footer, a `/usage` dashboard, and an agent-callable status tool. Entirely local: no network calls, no LLM tokens spent asking about tokens.
+Token and cost reporting for [pi](https://github.com/earendil-works/pi) sessions — a live footer, a `/usage` dashboard, and an agent-callable status tool. Local by default: no network calls, and no LLM tokens spent asking about tokens.
 
 Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install usage`](https://github.com/pifydev/cli) or `pi install npm:@pify/usage`.
 
-## What it does
+## Why
 
-- **Live footer**: `📊 12.3k tok · $0.45` — folded from each message's `usage.cost` that pi already computes; survives `/reload` by replaying the session branch.
-- **`/usage` dashboard**:
+Spend is invisible until the invoice arrives, and by then you cannot tell which session did it. Everything needed to answer that is already on disk — pi writes usage and cost into every session file — so the answer should cost nothing to produce.
+
+## Live footer
+
+```
+📊 12.3k tok · $0.45
+```
+
+Folded from each message's `usage.cost`, which pi already computes. It survives `/reload` by replaying the session branch rather than keeping a running total in memory.
+
+## `/usage`
 
 ```
 Session
@@ -27,8 +36,11 @@ By project (all time)
   D--project-shop-api       $6.60 · 3.6M tok
 ```
 
-- **History done right** (tmustier's lessons): counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result/compaction usage pi 0.81+ persists; negative/NaN fields clamp to zero; days are your local calendar days; a per-file mtime cache keeps repeat scans instant.
-- **Where the window went** (v0.4): `/usage context` breaks the context window into system prompt, context files, skills, tool definitions, tool results, and conversation — so "why am I at 60%?" has an answer that is usually "one `read` of a 4,000-line file", not a mystery.
+History counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result and compaction usage pi persists — so a session's total matches what you were billed rather than what the visible messages add up to. Negative and NaN fields clamp to zero, days are your **local** calendar days, and a per-file mtime cache keeps repeat scans instant.
+
+Per-project totals come for free: pi stores sessions one directory per project, so the dashboard can show where the money actually went.
+
+## `/usage context`
 
 ```
 Context window: 22.6k of 200.0k used (11%)
@@ -40,24 +52,42 @@ Context window: 22.6k of 200.0k used (11%)
   Free space        █████████████████████████···  89%  177.4k
 ```
 
-  Computed from what pi already holds — the assembled system prompt, the files and skills embedded in it, the enabled tool definitions, and the entries that would be sent. No network, no model call. Context files and skills are counted only when their text is genuinely embedded in the prompt, and the system-prompt row is the remainder after subtracting them, so the rows sum to the whole instead of double-counting. When the provider reports more than we can attribute, the difference is shown as **Other** rather than dropped. (The idea is from [`pi-cc-extensions`](https://github.com/minuque/pi-cc-extensions)' `/context`.)
+"Why am I at 60%?" usually has a boring answer — one `read` of a 4,000-line file — and this is where you find it.
 
-- **Per-project spend** (v0.2): pi stores sessions one directory per project, so the dashboard can show where the money actually went — the top 5 projects by cost, all time.
-- **`usage_status` tool**: the agent can check session + today totals before committing to expensive work (subagent fan-outs, large reads).
+Computed entirely from what pi already holds: the assembled system prompt, the files and skills embedded in it, the enabled tool definitions, and the entries that would be sent. No network, no model call.
 
-## `/usage quota` (v0.3)
+Context files and skills are counted only when their text is genuinely embedded in the prompt, and the system-prompt row is the remainder after subtracting them, so the rows sum to the whole instead of double-counting. When the provider reports more than can be attributed, the difference is shown as **Other** rather than quietly dropped.
 
-The one command in this package that touches the network, and only when you run it:
+## `/usage quota`
+
+The one command here that touches the network, and only when you run it:
 
 ```
-Quota (openrouter · sk-or-v1-abc...xyz)
-  spent    $0.32 (no credit limit on this key)
-  window   day $0.32 · week $0.32 · month $0.32
+Quota (OpenRouter · sk-or-v1-abc...xyz)
+  spent    $0.33 (no credit limit on this key)
+  window   day $0.01 · week $0.33 · month $0.33
+
+Quota (DeepSeek · granted 10 · topped up 100)
+  balance  CNY 110.00
 ```
 
-The key is read from the same `~/.pi/agent/auth.json` pi already uses (or `OPENROUTER_API_KEY`) — no second place to configure credentials — and only the provider's own masked label is ever printed. An 8-second timeout, and any failure renders as `unavailable — HTTP 401` rather than throwing.
+**Documented endpoints only.** OpenRouter's `/api/v1/key` and DeepSeek's `/user/balance` are published APIs that report a real balance. The subscription-quota endpoints available for some other providers are undocumented private APIs reverse-engineered from vendor CLIs — they break without notice and were never offered to third parties, so this package does not call them. A provider you have not configured is simply not shown; that is not a failure.
+
+**A credentialed request is pinned down**, because it carries your provider key:
+
+- HTTPS only, and the host must be on that provider's allowlist.
+- Redirects are refused outright. Following one lets whatever answered choose where the next request goes, with the header already attached.
+- A non-2xx body is **never read**. Error bodies echo request details back, and an echoed `Authorization` header pasted into a notification is exactly the leak this must not cause — the status alone becomes the message.
+- Raw exception text is dropped rather than shown, and everything printed passes a redactor as a last line of defence.
+- An 8-second timeout per provider; any failure renders as `unavailable — the provider rejected the key` rather than throwing.
+
+**The key comes from pi**, resolved through `modelRegistry` rather than by reading `auth.json`. pi owns credential storage — env precedence, OAuth, whatever it grows next — and parsing that file here would mean handling secrets this package has no business touching, using a stale copy of pi's rules. Only the provider's own masked label is ever printed.
+
+## Tool
+
+### `usage_status`
 
-Only OpenRouter is implemented. The other providers report opaque rate-limit windows rather than a balance, and chasing all of them costs ~18k lines of per-provider contract maintenance (see `@narumitw/pi-usage` if you need them today).
+No parameters. Returns session and today's totals, so the agent can check the cost before committing to expensive work — a wide subagent fan-out, a large read — instead of finding out afterwards.
 
 ## License
 

package/extensions/usage.ts

@@ -30,7 +30,8 @@ import { readFileSync } from "node:fs";
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 import { buildBreakdown, formatBreakdown } from "../src/context.ts";
 import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
-import { fetchOpenRouterQuota, quotaBlock } from "../src/quota.ts";
+import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
+import { redact } from "../src/redact.ts";
 import { scanSessions } from "../src/sessions.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
@@ -97,15 +98,26 @@ export default function usage(pi: ExtensionAPI) {
    * The key pi itself uses, read from the same auth.json — no second place to
    * configure credentials, and no key is ever printed.
    */
-  function providerKey(provider: string): string {
+  /**
+   * Ask pi for the key rather than reading auth.json. pi owns credential
+   * storage — env precedence, OAuth, whatever it grows next — and parsing
+   * that file here meant handling secrets this package has no business
+   * touching, with a copy of pi's rules that would quietly go stale.
+   */
+  async function providerKey(ctx: UiContext, provider: string): Promise<string> {
+    const registry = ctx.modelRegistry as unknown as {
+      getApiKeyForProvider?: (id: string) => Promise<string | undefined>;
+      getProviderAuth?: (id: string) => Promise<{ auth?: { apiKey?: string } } | undefined>;
+    };
     try {
-      const auth = JSON.parse(readFileSync(join(getAgentDir(), "auth.json"), "utf8")) as Record<string, unknown>;
-      const entry = auth[provider];
-      if (isRecord(entry) && typeof entry.key === "string") return entry.key;
+      const direct = await registry.getApiKeyForProvider?.(provider);
+      if (direct) return direct;
+      const auth = await registry.getProviderAuth?.(provider);
+      if (auth?.auth?.apiKey) return auth.auth.apiKey;
     } catch {
-      // no auth.json, or unreadable — fall through to the environment
+      // an unconfigured provider is not an error here
     }
-    return process.env.OPENROUTER_API_KEY ?? "";
+    return "";
   }
 
   /**
@@ -161,10 +173,24 @@ export default function usage(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
       if ((args ?? "").trim().toLowerCase() === "quota") {
-        // The one networked call in this package, and only when asked for.
-        ctx.ui.notify("Checking provider quota…", "info");
-        const result = await fetchOpenRouterQuota(providerKey("openrouter"));
-        ctx.ui.notify(quotaBlock(result), result.ok ? "info" : "warning");
+        // The one networked path in this package, and only when asked for.
+        // Providers with no key are skipped entirely rather than reported as
+        // broken: an unconfigured provider is not a failure.
+        const configured: Array<{ provider: (typeof QUOTA_PROVIDERS)[number]; key: string }> = [];
+        for (const provider of QUOTA_PROVIDERS) {
+          const key = await providerKey(ctx, provider.id);
+          if (key) configured.push({ provider, key });
+        }
+        if (configured.length === 0) {
+          ctx.ui.notify(quotaReport([]), "info");
+          return;
+        }
+        ctx.ui.notify(`Checking quota for ${configured.map((c) => c.provider.displayName).join(", ")}…`, "info");
+        const results: QuotaResult[] = [];
+        for (const { provider, key } of configured) {
+          results.push(await fetchQuota(provider, key));
+        }
+        ctx.ui.notify(redact(quotaReport(results)), results.every((r) => r.ok) ? "info" : "warning");
         return;
       }
       ctx.ui.notify(dashboard(ctx), "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",

package/skills/usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: usage
-description: Use when cost or token consumption matters to a decision - before expensive operations (large reads, many subagents, long loops) or when the user asks about spend - explains usage_status and /usage
+description: Use when cost or token consumption matters to a decision - before expensive operations (large reads, many subagents, long loops) or when the user asks about spend
 ---
 
 # Usage awareness

package/src/http.ts

@@ -0,0 +1,134 @@
+/**
+ * The one networked path in this package, made boring on purpose.
+ *
+ * A quota call carries the user's provider key in an Authorization header, so
+ * the request has to be pinned down rather than merely aimed at the right URL:
+ *
+ *  - HTTPS only, and the host must be on the caller's allowlist. A typo or a
+ *    future edit cannot point a credentialed request somewhere new.
+ *  - Redirects are refused outright (`redirect: "error"`). Following one means
+ *    a provider — or anything that can answer as one — chooses where the next
+ *    request goes, with the header already attached.
+ *  - A non-2xx body is never read. Error bodies echo request details back, and
+ *    an echoed Authorization header pasted into a notification is exactly the
+ *    leak this package must not cause. The status alone is the message.
+ *  - Everything is classified into a small set of reasons, so the caller can
+ *    say something useful without carrying provider text around.
+ *
+ * `fetchImpl` is injectable so tests never touch the network.
+ *
+ * (Structure and the no-body-on-error rule are from imdlan/pi-usage.)
+ */
+
+export type HttpFailureKind =
+  | "unsafe-url"
+  | "not-allowed"
+  | "auth"
+  | "forbidden"
+  | "rate-limited"
+  | "server"
+  | "http"
+  | "timeout"
+  | "network"
+  | "invalid-json";
+
+export interface HttpFailure {
+  ok: false;
+  kind: HttpFailureKind;
+  reason: string;
+  status?: number;
+}
+
+export interface HttpSuccess<T> {
+  ok: true;
+  status: number;
+  data: T;
+}
+
+export type HttpResult<T> = HttpSuccess<T> | HttpFailure;
+
+export interface ControlledGetOptions {
+  url: string;
+  headers?: Record<string, string>;
+  timeoutMs: number;
+  allowlist: readonly string[];
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+const TIMEOUT_SENTINEL = "pify-usage-timeout";
+
+function fail(kind: HttpFailureKind, reason: string, status?: number): HttpFailure {
+  return { ok: false, kind, reason, ...(status === undefined ? {} : { status }) };
+}
+
+/** Reject anything that is not an allowlisted HTTPS host before dialling. */
+export function checkUrl(url: string, allowlist: readonly string[]): HttpFailure | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return fail("unsafe-url", "invalid url");
+  }
+  if (parsed.protocol !== "https:") return fail("unsafe-url", "refused a non-HTTPS url");
+  if (!allowlist.includes(parsed.hostname)) {
+    return fail("not-allowed", `host ${parsed.hostname} is not on the allowlist`);
+  }
+  return null;
+}
+
+export function classifyStatus(status: number): HttpFailure {
+  if (status === 401) return fail("auth", "the provider rejected the key", status);
+  if (status === 403) return fail("forbidden", "the key is not allowed to read usage", status);
+  if (status === 429) return fail("rate-limited", "rate limited by the provider", status);
+  if (status >= 500) return fail("server", "the provider is having trouble", status);
+  return fail("http", `HTTP ${status}`, status);
+}
+
+/** GET JSON from an allowlisted host. Never throws; failure is a value. */
+export async function controlledGetJson<T = unknown>(opts: ControlledGetOptions): Promise<HttpResult<T>> {
+  const urlProblem = checkUrl(opts.url, opts.allowlist);
+  if (urlProblem) return urlProblem;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(TIMEOUT_SENTINEL)), opts.timeoutMs);
+  if (opts.signal) {
+    if (opts.signal.aborted) controller.abort();
+    else opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  const doFetch = opts.fetchImpl ?? (globalThis.fetch as typeof fetch);
+
+  let response: Response;
+  try {
+    response = await doFetch(opts.url, {
+      method: "GET",
+      headers: opts.headers ?? {},
+      signal: controller.signal,
+      redirect: "error",
+    });
+  } catch (err) {
+    if (controller.signal.aborted) {
+      const timedOut = String(controller.signal.reason ?? "").includes(TIMEOUT_SENTINEL);
+      return timedOut ? fail("timeout", "the provider did not answer in time") : fail("network", "request aborted");
+    }
+    const message = String((err as { message?: unknown })?.message ?? err).toLowerCase();
+    if (message.includes("redirect")) return fail("unsafe-url", "the provider tried to redirect us");
+    if (message.includes("timeout") || message.includes("timed out")) {
+      return fail("timeout", "the provider did not answer in time");
+    }
+    // The raw error is deliberately dropped: it can carry the request, and the
+    // request carries the key.
+    return fail("network", "could not reach the provider");
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (response.status >= 200 && response.status < 300) {
+    try {
+      return { ok: true, status: response.status, data: (await response.json()) as T };
+    } catch {
+      return fail("invalid-json", "the provider sent something that is not JSON", response.status);
+    }
+  }
+  return classifyStatus(response.status);
+}

package/src/quota.ts

@@ -1,20 +1,25 @@
 /**
- * Provider quota (v0.3). Everything else in this package is computed from
- * local files — this is the one place that talks to a network, so it is
- * opt-in per call, short-timeout, and never blocks the dashboard: a provider
- * that is slow or down shows as unavailable next to the local numbers.
+ * Provider quota. Everything else in this package is computed from local
+ * files; this is the one place that talks to a network, so it is opt-in per
+ * call, short-timeout, pinned to allowlisted HTTPS hosts, and never blocks the
+ * dashboard: a provider that is slow or down shows as unavailable next to the
+ * local numbers.
  *
- * Only OpenRouter is implemented. @narumitw/pi-usage shows what the full set
- * costs — roughly 18k lines of per-provider contract chasing — and OpenRouter
- * is the one endpoint that reports a real balance rather than an opaque
- * rate-limit window.
+ * Documented endpoints only. OpenRouter's `/api/v1/key` and DeepSeek's
+ * `/user/balance` are both published APIs that report a real balance. The
+ * subscription-quota endpoints some plugins use for OpenAI, Anthropic and
+ * Gemini are undocumented private APIs reverse-engineered from vendor CLIs;
+ * they break without notice and were never offered to third parties, so this
+ * package does not call them. (That line is imdlan/pi-usage's, and it is a
+ * better reason than the maintenance cost this package cited before.)
  */
 
+import { controlledGetJson, type HttpResult } from "./http.ts";
 import { finite, isRecord } from "./types.ts";
 
 export interface QuotaInfo {
   provider: string;
-  /** Spend on this key, in USD, as the provider reports it. */
+  /** Spend on this key, in the provider's currency, as it reports it. */
   used: number | null;
   /** Hard credit limit, when the key has one. */
   limit: number | null;
@@ -25,6 +30,8 @@ export interface QuotaInfo {
   monthly: number | null;
   label: string | null;
   freeTier: boolean | null;
+  /** Currency for the amounts above; USD unless the provider says otherwise. */
+  currency: string;
 }
 
 export type QuotaResult =
@@ -37,6 +44,29 @@ function num(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/** "110.00" — DeepSeek reports money as strings. */
+function numeric(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string" || !value.trim()) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function emptyQuota(provider: string): QuotaInfo {
+  return {
+    provider,
+    used: null,
+    limit: null,
+    remaining: null,
+    daily: null,
+    weekly: null,
+    monthly: null,
+    label: null,
+    freeTier: null,
+    currency: "USD",
+  };
+}
+
 /**
  * Shape the /api/v1/key payload. OpenRouter reports `limit: null` for keys
  * with no cap, so "no limit" and "limit of zero" must not collapse together.
@@ -53,7 +83,7 @@ export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
   const remaining = num(data.limit_remaining) ?? (limit !== null && used !== null ? limit - used : null);
 
   return {
-    provider: "openrouter",
+    ...emptyQuota("openrouter"),
     used: used === null ? null : finite(used),
     limit,
     remaining,
@@ -65,60 +95,134 @@ export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
   };
 }
 
-export type Fetcher = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
-  ok: boolean;
-  status: number;
-  json(): Promise<unknown>;
-}>;
+/**
+ * DeepSeek's documented `/user/balance`: a list of per-currency balances. The
+ * first available one is reported; a key with no available balance is still a
+ * successful answer, showing zero rather than an error.
+ */
+export function parseDeepSeekBalance(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload)) return null;
+  const infos = payload.balance_infos;
+  if (!Array.isArray(infos)) return null;
+
+  const first = infos.find((entry) => isRecord(entry) && numeric(entry.total_balance) !== null);
+  if (!isRecord(first)) {
+    return { ...emptyQuota("deepseek"), remaining: 0 };
+  }
+  const total = numeric(first.total_balance);
+  const granted = numeric(first.granted_balance);
+  const topped = numeric(first.topped_up_balance);
+  const parts = [
+    granted === null ? null : `granted ${granted}`,
+    topped === null ? null : `topped up ${topped}`,
+  ].filter((part): part is string => part !== null);
+
+  return {
+    ...emptyQuota("deepseek"),
+    remaining: total,
+    currency: typeof first.currency === "string" ? first.currency : "USD",
+    label: parts.length > 0 ? parts.join(" · ") : null,
+    freeTier: payload.is_available === false ? null : null,
+  };
+}
 
-/** Fetch the OpenRouter key status. Never throws — failure is a result. */
-export async function fetchOpenRouterQuota(
+export interface QuotaProvider {
+  /** pi's provider id, which is also how the key is looked up. */
+  id: string;
+  displayName: string;
+  url: string;
+  allowlist: readonly string[];
+  parse(payload: unknown): QuotaInfo | null;
+}
+
+export const QUOTA_PROVIDERS: readonly QuotaProvider[] = [
+  {
+    id: "openrouter",
+    displayName: "OpenRouter",
+    url: "https://openrouter.ai/api/v1/key",
+    allowlist: ["openrouter.ai"],
+    parse: parseOpenRouterKey,
+  },
+  {
+    id: "deepseek",
+    displayName: "DeepSeek",
+    url: "https://api.deepseek.com/user/balance",
+    allowlist: ["api.deepseek.com"],
+    parse: parseDeepSeekBalance,
+  },
+];
+
+export function findProvider(id: string): QuotaProvider | undefined {
+  return QUOTA_PROVIDERS.find((provider) => provider.id === id.trim().toLowerCase());
+}
+
+/**
+ * Query one provider. Never throws — failure is a result, and its reason is
+ * this package's own wording, never the provider's response text.
+ */
+export async function fetchQuota(
+  provider: QuotaProvider,
   apiKey: string,
-  fetcher: Fetcher = globalThis.fetch as unknown as Fetcher,
+  fetchImpl?: typeof fetch,
   timeoutMs = QUOTA_TIMEOUT_MS,
 ): Promise<QuotaResult> {
-  if (!apiKey.trim()) return { ok: false, provider: "openrouter", reason: "no API key configured" };
-  try {
-    const response = await fetcher("https://openrouter.ai/api/v1/key", {
-      headers: { Authorization: `Bearer ${apiKey.trim()}` },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!response.ok) {
-      return { ok: false, provider: "openrouter", reason: `HTTP ${response.status}` };
-    }
-    const quota = parseOpenRouterKey(await response.json());
-    if (!quota) return { ok: false, provider: "openrouter", reason: "unexpected response shape" };
-    return { ok: true, quota };
-  } catch (err) {
-    return {
-      ok: false,
-      provider: "openrouter",
-      reason: err instanceof Error ? err.message : String(err),
-    };
-  }
+  if (!apiKey.trim()) return { ok: false, provider: provider.id, reason: "no API key configured" };
+
+  const result: HttpResult<unknown> = await controlledGetJson({
+    url: provider.url,
+    headers: { Authorization: `Bearer ${apiKey.trim()}`, Accept: "application/json" },
+    timeoutMs,
+    allowlist: provider.allowlist,
+    fetchImpl,
+  });
+  if (!result.ok) return { ok: false, provider: provider.id, reason: result.reason };
+
+  const quota = provider.parse(result.data);
+  if (!quota) return { ok: false, provider: provider.id, reason: "the response did not match the documented shape" };
+  return { ok: true, quota };
 }
 
-function money(value: number | null): string {
+function money(value: number | null, currency = "USD"): string {
   if (value === null) return "—";
-  if (value === 0) return "$0";
-  if (Math.abs(value) < 0.01) return "<$0.01";
-  return `$${value.toFixed(2)}`;
+  const symbol = currency === "USD" ? "$" : `${currency} `;
+  if (value === 0) return `${symbol}0`;
+  if (Math.abs(value) < 0.01) return `<${symbol}0.01`;
+  return `${symbol}${value.toFixed(2)}`;
 }
 
 export function quotaBlock(result: QuotaResult): string {
-  if (!result.ok) {
-    return `Quota (${result.provider})\n  unavailable — ${result.reason}`;
-  }
+  const id = result.ok ? result.quota.provider : result.provider;
+  const name = findProvider(id)?.displayName ?? id;
+  if (!result.ok) return `Quota (${name})\n  unavailable — ${result.reason}`;
+
   const q = result.quota;
-  const lines = [`Quota (${q.provider}${q.label ? ` · ${q.label}` : ""})`];
-  lines.push(
-    q.limit === null
-      ? `  spent    ${money(q.used)} (no credit limit on this key)`
-      : `  spent    ${money(q.used)} of ${money(q.limit)} · ${money(q.remaining)} left`,
-  );
+  const lines = [`Quota (${name}${q.label ? ` · ${q.label}` : ""})`];
+  if (q.used !== null || q.limit !== null) {
+    lines.push(
+      q.limit === null
+        ? `  spent    ${money(q.used, q.currency)} (no credit limit on this key)`
+        : `  spent    ${money(q.used, q.currency)} of ${money(q.limit, q.currency)} · ${money(q.remaining, q.currency)} left`,
+    );
+  } else if (q.remaining !== null) {
+    lines.push(`  balance  ${money(q.remaining, q.currency)}`);
+  }
   if (q.daily !== null || q.weekly !== null || q.monthly !== null) {
-    lines.push(`  window   day ${money(q.daily)} · week ${money(q.weekly)} · month ${money(q.monthly)}`);
+    lines.push(
+      `  window   day ${money(q.daily, q.currency)} · week ${money(q.weekly, q.currency)} · month ${money(q.monthly, q.currency)}`,
+    );
   }
   if (q.freeTier) lines.push("  tier     free");
   return lines.join("\n");
 }
+
+/** What `/usage quota` prints: every provider that has a key, and nothing else. */
+export function quotaReport(results: QuotaResult[]): string {
+  if (results.length === 0) {
+    return [
+      "No provider with a quota endpoint is configured.",
+      `Supported: ${QUOTA_PROVIDERS.map((p) => p.displayName).join(", ")}.`,
+      "Only documented endpoints are used — OpenAI, Anthropic and Gemini publish none for subscription quota.",
+    ].join("\n");
+  }
+  return results.map(quotaBlock).join("\n\n");
+}

package/src/redact.ts

@@ -0,0 +1,41 @@
+/**
+ * Defence in depth for anything this package prints.
+ *
+ * Nothing here is supposed to see a secret: keys come from pi's own auth
+ * resolution and go straight into a header, error bodies are never read, and
+ * raw exception text is dropped rather than shown. This scrubber exists for
+ * the case where one of those is wrong — a key in a message costs the user a
+ * rotation, and the cost of running a regex over a notification is nothing.
+ *
+ * The patterns describe what to REMOVE. They are never used to find or store
+ * a secret. (Idea from imdlan/pi-usage.)
+ */
+
+const REDACTED = "[redacted]";
+
+const RULES: ReadonlyArray<{ re: RegExp; replacement: string }> = [
+  // Provider key shapes, longest-prefix first.
+  { re: /\bsk-or-v1-[A-Za-z0-9]{16,}/g, replacement: REDACTED },
+  { re: /\bsk-ant-[A-Za-z0-9_-]{16,}/g, replacement: REDACTED },
+  { re: /\bsk-[A-Za-z0-9_-]{16,}/g, replacement: REDACTED },
+  { re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, replacement: REDACTED },
+  { re: /\bAIza[0-9A-Za-z_-]{20,}/g, replacement: REDACTED },
+  { re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, replacement: REDACTED },
+  { re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, replacement: REDACTED },
+  // Headers and assignments that name a secret, whatever the value looks like.
+  // To end of line, not to the first space: "Bearer <token>" is two words and
+  // stopping early leaves exactly the half that matters.
+  { re: /\b(?:proxy-)?authorization\s*[:=]\s*[^\r\n;,]+/gi, replacement: `authorization: ${REDACTED}` },
+  {
+    re: /\b(api[_-]?key|access[_-]?token|auth[_-]?token|secret|password)\b\s*[:=]\s*["']?[^\s"',;]+/gi,
+    replacement: `$1=${REDACTED}`,
+  },
+  // A URL's query string can carry a token; the path is enough to identify it.
+  { re: /(https?:\/\/[^\s?]+)\?[^\s]*/gi, replacement: "$1?[redacted]" },
+];
+
+export function redact(text: string): string {
+  let out = text ?? "";
+  for (const { re, replacement } of RULES) out = out.replace(re, replacement);
+  return out;
+}