@pify/usage 0.3.0 → 0.5.0

package/README.md

@@ -28,22 +28,50 @@ By project (all time)
 ```
 
 - **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.
+
+```
+Context window: 22.6k of 200.0k used (11%)
+  System prompt     ····························  <1%  11
+  Context files     ····························   1%  3.0k
+  Tool definitions  ····························  <1%  371
+  Tool results      ██··························   8%  16.8k
+  Conversation      ····························   1%  2.4k
+  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`.)
+
 - **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).
 
-## `/usage quota` (v0.3)
+## `/usage quota` (v0.5)
 
 The one command in this package that touches the network, and only when you run it:
 
 ```
-Quota (openrouter · sk-or-v1-395...563)
-  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 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. Providers you have not configured are simply not shown; they are not failures.
+
+**A credentialed request is pinned down** (v0.5), 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.
+
+**The key comes from pi** (v0.5): resolved through `modelRegistry`, not by 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 stale copy of pi's rules. Only the provider's own masked label is ever printed.
+
+An 8-second timeout per provider, and any failure renders as `unavailable — the provider rejected the key` rather than throwing.
 
-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).
+The hardening, the multi-provider shape, and the documented-APIs-only stance are from [`@imdlan/pi-usage`](https://github.com/imdlan/pi-usage), which supports Z.ai as well.
 
 ## License
 

package/extensions/usage.ts

@@ -18,6 +18,7 @@
  * is the one that reports a real balance rather than an opaque window.
  */
 import {
+  formatSkillsForPrompt,
   getAgentDir,
   type ExtensionAPI,
   type ExtensionContext,
@@ -27,8 +28,10 @@ import { join } from "node:path";
 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";
 
@@ -95,15 +98,74 @@ 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 direct = await registry.getApiKeyForProvider?.(provider);
+      if (direct) return direct;
+      const auth = await registry.getProviderAuth?.(provider);
+      if (auth?.auth?.apiKey) return auth.auth.apiKey;
+    } catch {
+      // an unconfigured provider is not an error here
+    }
+    return "";
+  }
+
+  /**
+   * Where the context window went, computed from what pi already holds:
+   * the assembled system prompt, the context files and skills embedded in
+   * it, the enabled tool definitions, and the entries that would be sent.
+   * No network, no model call — same rule as the rest of the package.
+   */
+  function contextBreakdown(ctx: UiContext): string {
+    const host = ctx as unknown as {
+      getSystemPrompt?: () => string;
+      getSystemPromptOptions?: () => {
+        contextFiles?: Array<{ path?: string; content?: string }>;
+        skills?: unknown[];
+        selectedTools?: string[];
+      };
+      getContextUsage?: () => { contextWindow?: number; used?: number; total?: number } | undefined;
+      sessionManager?: { buildContextEntries?: () => unknown[]; getBranch?: () => unknown[] };
+    };
+
+    const systemPrompt = host.getSystemPrompt?.() ?? "";
+    const options = host.getSystemPromptOptions?.() ?? {};
+    const selected = new Set(options.selectedTools ?? []);
+    const allTools = (pi as unknown as { getAllTools?: () => Array<{ name?: string }> }).getAllTools?.() ?? [];
+    const tools = selected.size > 0 ? allTools.filter((t) => selected.has(t.name ?? "")) : allTools;
+
+    let skillsText = "";
     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;
+      skillsText = formatSkillsForPrompt((options.skills ?? []) as never).trim();
     } catch {
-      // no auth.json, or unreadable — fall through to the environment
+      // A pi version that formats skills differently just reports 0 here.
     }
-    return process.env.OPENROUTER_API_KEY ?? "";
+
+    const entries = host.sessionManager?.buildContextEntries?.() ?? host.sessionManager?.getBranch?.() ?? [];
+    const usage = host.getContextUsage?.();
+    const contextWindow =
+      usage?.contextWindow ?? (ctx.model as { contextWindow?: number } | null)?.contextWindow ?? 0;
+
+    const breakdown = buildBreakdown({
+      systemPrompt,
+      contextFiles: options.contextFiles ?? [],
+      skillsText,
+      tools,
+      entries,
+      contextWindow,
+    });
+    const reported = typeof usage?.used === "number" ? usage.used : lastPromptTokens || null;
+    return formatBreakdown(breakdown, reported);
   }
 
   pi.registerCommand("usage", {
@@ -111,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,7 +1,7 @@
 {
   "name": "@pify/usage",
-  "version": "0.3.0",
-  "description": "Token and cost reporting for pi sessions: live footer, /usage dashboard over local session history, zero network",
+  "version": "0.5.0",
+  "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
     "@types/node": "^22.10.2",
     "typebox": "^1.1.38",
     "typescript": "^5.7.2"

package/src/context.ts

@@ -0,0 +1,193 @@
+/**
+ * Where the context window actually went (the idea, and the accounting
+ * discipline, are from minuque/pi-cc-extensions' /context).
+ *
+ * The rest of this package answers "what have I spent". This answers the
+ * other question you have at 60% context: "spent on WHAT". Both are computed
+ * from what pi already has in memory — no network, no model call — so the
+ * numbers are estimates (chars/4, the same estimate pi uses for compaction),
+ * not provider billing.
+ *
+ * Two rules keep the estimate honest:
+ *  - context files and skills are counted only when their text is actually
+ *    embedded in the assembled system prompt, so a file that was loaded but
+ *    not injected does not appear twice;
+ *  - the system-prompt row is the remainder after those are subtracted, so
+ *    the parts sum to the whole instead of overlapping.
+ */
+
+export interface ContextPart {
+  label: string;
+  tokens: number;
+}
+
+export interface ContextBreakdown {
+  parts: ContextPart[];
+  /** Sum of every attributed part. */
+  attributed: number;
+  contextWindow: number;
+}
+
+/** pi's own compaction estimate: four characters per token. */
+export function estimateTextTokens(value: unknown): number {
+  if (value === null || value === undefined || value === "") return 0;
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return Math.max(0, Math.ceil(text.length / 4));
+}
+
+/** Count a chunk only when the assembled prompt really contains it. */
+export function embeddedTokens(systemPrompt: string, chunk: string): number {
+  if (!chunk || !systemPrompt.includes(chunk)) return 0;
+  return estimateTextTokens(chunk);
+}
+
+export interface BreakdownInput {
+  systemPrompt: string;
+  /** Context files (AGENTS.md, CLAUDE.md, …) pi loaded for the prompt. */
+  contextFiles: Array<{ path?: string; content?: string }>;
+  /** Skills text as pi formats it into the prompt. */
+  skillsText: string;
+  /** Definitions of the tools actually enabled this turn. */
+  tools: Array<{ name?: string; description?: string; parameters?: unknown }>;
+  /** Entries pi would send as conversation this turn. */
+  entries: unknown[];
+  contextWindow: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Split the conversation into what the agent said and what tools returned.
+ * Tool results are the part that grows without anyone deciding it should,
+ * which is exactly why they deserve their own row.
+ */
+function foldEntries(entries: unknown[]): { conversation: number; toolResults: number } {
+  let conversation = 0;
+  let toolResults = 0;
+
+  for (const entry of entries) {
+    if (!isRecord(entry)) continue;
+    const message = isRecord(entry.message) ? entry.message : entry;
+    const role = typeof message.role === "string" ? message.role : null;
+
+    if (role === "toolResult" || role === "bashExecution") {
+      toolResults += estimateTextTokens(message.content ?? message.output ?? message);
+      continue;
+    }
+    if (role === "assistant" && Array.isArray(message.content)) {
+      for (const block of message.content as Array<Record<string, unknown>>) {
+        if (!isRecord(block)) continue;
+        if (block.type === "toolCall") {
+          conversation += estimateTextTokens(block.name) + estimateTextTokens(block.arguments);
+        } else if (block.type === "text") {
+          conversation += estimateTextTokens(block.text);
+        } else if (block.type === "thinking") {
+          conversation += estimateTextTokens(block.thinking);
+        }
+      }
+      continue;
+    }
+    if (typeof entry.summary === "string") {
+      conversation += estimateTextTokens(entry.summary);
+      continue;
+    }
+    if (typeof entry.content === "string" || Array.isArray(entry.content)) {
+      conversation += estimateTextTokens(entry.content);
+      continue;
+    }
+    if (role) conversation += estimateTextTokens(message.content ?? message);
+  }
+
+  return { conversation, toolResults };
+}
+
+export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
+  const memory = input.contextFiles.reduce(
+    (sum, file) => sum + embeddedTokens(input.systemPrompt, file.content ?? ""),
+    0,
+  );
+  const skills = embeddedTokens(input.systemPrompt, input.skillsText.trim());
+  const tools = input.tools.reduce(
+    (sum, tool) =>
+      sum +
+      estimateTextTokens({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      }),
+    0,
+  );
+  const { conversation, toolResults } = foldEntries(input.entries);
+  // Memory and skills live inside the prompt; subtract so rows do not overlap.
+  const system = Math.max(0, estimateTextTokens(input.systemPrompt) - memory - skills);
+
+  const parts: ContextPart[] = [
+    { label: "System prompt", tokens: system },
+    { label: "Context files", tokens: memory },
+    { label: "Skills", tokens: skills },
+    { label: "Tool definitions", tokens: tools },
+    { label: "Tool results", tokens: toolResults },
+    { label: "Conversation", tokens: conversation },
+  ];
+
+  return {
+    parts,
+    attributed: parts.reduce((sum, part) => sum + part.tokens, 0),
+    contextWindow: Math.max(0, input.contextWindow),
+  };
+}
+
+const BAR_WIDTH = 28;
+
+function bar(fraction: number): string {
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.round(fraction * BAR_WIDTH)));
+  return `${"█".repeat(filled)}${"·".repeat(BAR_WIDTH - filled)}`;
+}
+
+function pct(tokens: number, total: number): string {
+  if (total <= 0) return "  — ";
+  const value = (tokens / total) * 100;
+  if (value > 0 && value < 0.5) return " <1%";
+  return `${Math.round(value).toString().padStart(3)}%`;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+
+/**
+ * Render the breakdown. `reportedUsed` is the provider's own number for the
+ * last request when pi has one: it is authoritative, so anything it counts
+ * that the parts do not is shown as "Other" rather than silently dropped.
+ */
+export function formatBreakdown(breakdown: ContextBreakdown, reportedUsed: number | null): string {
+  const window = breakdown.contextWindow;
+  const used = Math.max(reportedUsed ?? 0, breakdown.attributed);
+  const other = Math.max(0, used - breakdown.attributed);
+  const free = window > 0 ? Math.max(0, window - used) : 0;
+
+  const rows = [...breakdown.parts];
+  if (other > 0) rows.push({ label: "Other", tokens: other });
+  if (window > 0) rows.push({ label: "Free space", tokens: free });
+
+  const width = rows.reduce((m, row) => Math.max(m, row.label.length), 0);
+  const denominator = window > 0 ? window : used;
+
+  const lines = [
+    window > 0
+      ? `Context window: ${formatTokens(used)} of ${formatTokens(window)} used (${pct(used, window).trim()})`
+      : `Context: ${formatTokens(used)} used (no window reported)`,
+  ];
+  for (const row of rows) {
+    if (row.tokens === 0 && row.label !== "Free space") continue;
+    lines.push(
+      `  ${row.label.padEnd(width)}  ${bar(denominator > 0 ? row.tokens / denominator : 0)} ${pct(row.tokens, denominator)}  ${formatTokens(row.tokens)}`,
+    );
+  }
+  lines.push("Estimated locally (≈4 chars/token); provider billing may differ.");
+  return lines.join("\n");
+}

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;
+}