@pify/usage 0.12.1 → 0.14.0

package/README.md

@@ -20,10 +20,21 @@ Folded from each message's `usage.cost`, which pi already computes. It survives
 
 When [`@pify/subagent`](https://github.com/pifydev/subagent), [`@pify/swarm`](https://github.com/pifydev/swarm) or [`@pify/workflow`](https://github.com/pifydev/workflow) run child agents, those children are separate in-memory sessions whose spend never reaches this branch — a session that delegates used to look cheaper than it was. Those packages now add every child message's cost to a process-wide tally, and the footer shows it as a separate ` · agents $0.12` beside the session's own figure (the `/usage` session block has the same line, with tokens). It is kept apart on purpose: the session numbers stay what the branch says, and the agents figure is what the delegation cost on top. The tally survives `/reload` and starts over with a new session.
 
-On a Claude subscription (OAuth Pro/Max) the footer also carries the wall you are approaching: the headers `/usage quota` reads were already captured on every response, but only that command showed them, so the weekly or 5-hour limit used to arrive as a stalled turn. Now a `⚠ 7d 8% · resets 14:05` segment appears once the binding window is below 15%, or whenever Anthropic marks the subscription as anything but allowed, and stays out of the way otherwise. Other providers carry no such headers, so they never show it.
+On a Claude subscription (OAuth Pro/Max) the footer also carries the wall you are approaching: the headers `/usage quota` reads were already captured on every response, but only that command showed them, so the weekly or 5-hour limit used to arrive as a stalled turn. Now a `⚠ 7d 8% · resets 14:05` segment appears once the binding window is below 15%, or whenever Anthropic marks the subscription as anything but allowed, and stays out of the way otherwise. This passive warning uses Anthropic's own response headers. Copilot and Codex subscription quotas are fetched explicitly, as described below.
 
 The gauge on the right is how full the context window is — the third mid-session question, next to tokens and cost. It was computed for the `/usage` dashboard but shown only there; now it is live. It appears once there is a window to measure against (so not under `-p`) and turns to `⚠` past 90%, the point where "how full" stops being trivia and becomes a decision. For the breakdown of what filled it, run `/context`.
 
+After `/usage quota`, the active Copilot or Codex provider also shows its cached remaining quota, before the session figures so compact status lines keep it visible:
+
+```
+Copilot premium 49% left · cached · 📊 12.3k tok · $0.45
+Codex 5h 75% left · 7d 40% left · cached · 📊 12.3k tok · $0.45
+```
+
+There is no background polling. Values live only in memory, are cleared on session start/reload, and are marked `stale` on the next footer redraw after fifteen minutes or a reported reset. Run the command again to refresh; the dashboard gives reset times in UTC. Missing or rejected data is not shown as zero remaining. Only the active provider's quota is displayed when switching models.
+
+The status key is namespaced as `pify-usage`. `/pify-usage` is an alias for every `/usage` subcommand, so a second extension registering `/usage` need not make this dashboard inaccessible. Pi disambiguates conflicting commands as `/usage:1`, `/usage:2`, etc.; bare `/usage` is unavailable in that case. `/pify-usage` stays unambiguous, while `/usage` remains backward compatible when this is the only usage extension.
+
 ## `/usage`
 
 ```
@@ -64,10 +75,20 @@ Context window: 22.6k of 200.0k used (11%)
   Tool results      ██··························   8%  16.8k
   Conversation      ····························   1%  2.4k
   Free space        █████████████████████████···  89%  177.4k
+
+Heaviest tool schemas (14 tools, ~3.9k of the prefix):
+  mcp__docs__search     1.6k  mcp:docs
+  workflow              520
+  mcp__docs__fetch      410   mcp:docs
+  bash                  290
+  … and 10 more, ~1.1k
+  by source: mcp:docs ~2.0k, builtin/ext ~1.9k
 ```
 
 "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.
 
+The **Tool definitions** row is broken out below the window into its heaviest tools, biggest first, so a fat MCP schema or a costly server is nameable rather than a lump: every active tool's `name + description + parameters` is a prefix cost paid on *every* request, and the `by source` line totals the builtins and extensions against each MCP server. (This is the live, per-session version of what the cross-harness "subagent-tax" measures.)
+
 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.
 
 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. Image blocks (a `read` of a screenshot, a pasted image) are charged at pi's flat 4,800 chars each, not at the size of their base64 bytes, so one screenshot no longer reads as hundreds of thousands of tokens.
@@ -91,7 +112,11 @@ Quota (DeepSeek · granted 10 · topped up 100)
   balance  CNY 110.00
 ```
 
-**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.
+**Balances and subscription windows are different.** OpenRouter's `/api/v1/key` and DeepSeek's `/user/balance` are published balance APIs. Copilot premium interactions (or AI credits when token-based billing is reported) and Codex's primary/secondary windows are percentages **remaining**, not money or per-request rate limits. Unlimited quota is labelled explicitly. Only the active model's provider is checked; unused configured keys (for example an OpenRouter key) are not inspected or queried. Missing or unsupported credentials for that active provider produce an explicit unavailable reason.
+
+Copilot uses `https://api.github.com/copilot_internal/user`, published as `entitlementUrl` in [Microsoft's contributor documentation](https://github.com/microsoft/vscode-copilot-chat/blob/main/CONTRIBUTING.md). Codex uses `https://chatgpt.com/backend-api/wham/usage`, as implemented in [OpenAI's client](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client.rs). OpenAI separately documents the [app-server `account/rateLimits/read` interface](https://developers.openai.com/codex/app-server/#auth-endpoints); that is not a versioned contract for the direct HTTP route. These published client endpoints may change without notice. An unrecognized response renders as unavailable rather than guessing a balance.
+
+`/usage quota` (or `/pify-usage quota`) is explicit consent for one quota request to the active provider's endpoint, with no recurring refresh. Sessions, model changes, `usage_status`, and footer redraws do not make quota requests.
 
 **Rate limits, for free.** OpenAI, Anthropic and Gemini publish no balance API, but every completion response carries rate-limit headers, and pi hands them to extensions through `after_provider_response` — before the stream is read, at no cost when unsubscribed. So `/usage quota` also shows what the current provider reported on its last call — requests and tokens left in the window, and for an Anthropic OAuth (Pro/Max) subscription the two unified windows it actually reports: the fraction of the 5-hour and 7-day windows still free (from the `-5h-utilization` / `-7d-utilization` headers, which state the fraction *used*), which of the two is currently binding, an `allowed_warning` / `rejected` status when the window is under pressure, and the reset time. All captured passively from calls the session already made, with no extra request and no credential to handle.
 
@@ -101,9 +126,9 @@ Quota (DeepSeek · granted 10 · topped up 100)
 - 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.
+- An 8-second timeout per quota HTTP request; any failure renders as unavailable rather than throwing. Pi's own OAuth refresh may take additional time.
 
-**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.
+**Credentials come from pi's public APIs**, not a second credential store or a package-owned `auth.json` parser. Balances use `modelRegistry` resolution. Both subscription endpoints require Pi OAuth login: Copilot uses the original GitHub login token obtained with Pi's `readStoredCredential` API, **never** the Copilot inference token. The token and endpoint are resolved together: public GitHub uses `api.github.com`, and GitHub Enterprise Cloud data-residency logins on `<tenant>.ghe.com` use only `api.<tenant>.ghe.com`. The allowlist contains that matching API host alone; Enterprise credentials never fall back to public GitHub. Other/custom Enterprise authorities are reported as unsupported without sending a request; Codex resolves its OAuth access token through Pi, which may refresh and persist it. Ordinary API keys are not sent to these subscription endpoints. The Codex account-id header is extracted locally from the access token's account-id claim; no other JWT claims or inference headers are forwarded. Credentials are never printed or persisted by this package, and no `gh` subprocess is involved.
 
 ## Tool
 

package/extensions/usage.ts

@@ -10,16 +10,14 @@
  * tmustier's lesson) with a per-file mtime cache. The usage_status tool
  * lets the agent itself check consumption mid-session.
  *
- * Everything above is local: no network, no LLM tokens. The single exception
- * is /usage quota (v0.3), which asks OpenRouter what this key has spent —
- * opt-in per call, 8s timeout, and a failure prints as "unavailable" beside
- * the local numbers. Other providers stay out: @narumitw/pi-usage shows the
- * full set costs ~18k lines of per-provider contract chasing, and OpenRouter
- * is the one that reports a real balance rather than an opaque window.
+ * Everything above is local: no network, no LLM tokens. The exception is
+ * /usage quota: opt-in balance/subscription requests, 8s timeout per provider.
+ * The footer shows cached Copilot/Codex percentages, never background polling.
  */
 import {
   formatSkillsForPrompt,
   getAgentDir,
+  readStoredCredential,
   SettingsManager,
   type ExtensionAPI,
   type ExtensionContext,
@@ -29,14 +27,15 @@ import { join } from "node:path";
 import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
-import { buildBreakdown, contextTokensFromUsage, formatBreakdown, resolveUsedTokens } from "../src/context.ts";
+import { buildBreakdown, contextTokensFromUsage, formatBreakdown, formatToolTax, resolveUsedTokens } from "../src/context.ts";
 import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { childSpendTotal, onChildSpend, resetChildSpend } from "../src/child-cost.ts";
 import { buildByDayCsv, buildByModelCsv, buildByProjectCsv, buildTotalsJson } from "../src/export.ts";
 import { emptyCacheHealth, observeCacheHealth } from "../src/cache-health.ts";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
+import { QUOTA_PROVIDERS, fetchQuota, quotaReport, quotaFooter, type QuotaResult } from "../src/quota.ts";
+import { resolveQuotaAuth } from "../src/quota-auth.ts";
 import { redact } from "../src/redact.ts";
 import { scanSessions, persistScanCache, restoreScanCache } from "../src/sessions.ts";
 import { parseRateLimit, formatRateLimit, type RateLimitSnapshot, footerQuotaSegment } from "../src/ratelimit.ts";
@@ -58,6 +57,7 @@ export default function usage(pi: ExtensionAPI) {
    * free from responses the session already made, no extra network call.
    */
   const rateLimits = new Map<string, RateLimitSnapshot>();
+  const quotas = new Map<string, { result: QuotaResult; fetchedAt: number }>();
 
   // after_provider_response carries the status and full headers of every
   // provider call, before the stream is read; gated on hasHandlers, so
@@ -82,15 +82,14 @@ export default function usage(pi: ExtensionAPI) {
   function updateFooter(ctx: UiContext): void {
     if (!ctx.hasUI) return;
     const base = footerText(session, childSpendTotal());
-    if (!base) {
-      ctx.ui.setStatus("usage", undefined);
-      return;
-    }
-    const gauge = contextGauge(contextInfo(ctx).pct);
-    // The subscription wall, from the headers already captured for this
-    // provider: quiet while healthy, a short warning once it is close.
-    const quota = footerQuotaSegment(rateLimits.get((ctx.model as { provider?: string } | null)?.provider ?? ""));
-    ctx.ui.setStatus("usage", [base, gauge, quota].filter(Boolean).join(" · "));
+    const gauge = base ? contextGauge(contextInfo(ctx).pct) : "";
+    const provider = ctx.model?.provider ?? "";
+    const cached = quotas.get(provider);
+    const subscription = quotaFooter(cached?.result, cached?.fetchedAt ?? 0);
+    const passive = footerQuotaSegment(rateLimits.get(provider));
+    // Quota first: compact footers may truncate the rest. Namespace our status
+    // so another usage extension cannot overwrite or clear it.
+    ctx.ui.setStatus("pify-usage", [subscription, base, gauge, passive].filter(Boolean).join(" · ") || undefined);
   }
 
   /**
@@ -158,7 +157,10 @@ export default function usage(pi: ExtensionAPI) {
     updateFooter(ctx);
   });
 
+  pi.on("model_select", async (_event, ctx) => updateFooter(ctx));
+
   pi.on("session_start", async (event, ctx) => {
+    quotas.clear();
     // Rebuild the session totals from the branch so /reload keeps the count.
     session = emptyTotals();
     lastPromptTokens = 0;
@@ -212,37 +214,12 @@ export default function usage(pi: ExtensionAPI) {
     stopChildSpend?.();
     stopChildSpend = null;
     footerCtx = null;
-    if (ctx.hasUI) ctx.ui.setStatus("usage", undefined);
+    quotas.clear();
+    if (ctx.hasUI) ctx.ui.setStatus("pify-usage", undefined);
   });
 
   // ── Command & tool ───────────────────────────────────────────────────
 
-  /**
-   * The key pi itself uses, read from the same auth.json — no second place to
-   * configure credentials, and no key is ever printed.
-   */
-  /**
-   * 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
@@ -281,7 +258,8 @@ export default function usage(pi: ExtensionAPI) {
     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 allTools =
+      (pi as unknown as { getAllTools?: () => Array<{ name?: string; description?: string; parameters?: unknown }> }).getAllTools?.() ?? [];
     const tools = selected.size > 0 ? allTools.filter((t) => selected.has(t.name ?? "")) : allTools;
 
     let skillsText = "";
@@ -316,10 +294,13 @@ export default function usage(pi: ExtensionAPI) {
       providerTokens: lastPromptTokens || null,
       estimate: breakdown.attributed,
     });
-    return formatBreakdown(breakdown, reported);
+    // Break the "Tool definitions" row into its heaviest tools, biggest first,
+    // so a costly MCP server or a fat schema is nameable rather than a lump.
+    const taxLines = formatToolTax(tools);
+    return taxLines.length > 0 ? `${formatBreakdown(breakdown, reported)}\n\n${taxLines.join("\n")}` : formatBreakdown(breakdown, reported);
   }
 
-  pi.registerCommand("usage", {
+  const usageCommand: Parameters<ExtensionAPI["registerCommand"]>[1] = {
     description: "Token and cost dashboard: /usage [context | quota | export]",
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
@@ -356,39 +337,34 @@ export default function usage(pi: ExtensionAPI) {
         return;
       }
       if ((args ?? "").trim().toLowerCase() === "quota") {
-        // 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) {
-          const passive = [...rateLimits.values()]
-            .map((s) => formatRateLimit(s))
-            .filter((line): line is string => line !== null);
-          ctx.ui.notify(
-            passive.length > 0 ? redact(`${passive.join("\n")}\n\n${quotaReport([])}`) : quotaReport([]),
-            "info",
-          );
+        // Only the active provider: a configured balance key does not mean it is in use.
+        const id = ctx.model?.provider ?? "";
+        const provider = QUOTA_PROVIDERS.find(p => p.id === id);
+        const snapshot = rateLimits.get(id);
+        const passive = snapshot ? formatRateLimit(snapshot) : null;
+        if (!provider) {
+          updateFooter(ctx);
+          ctx.ui.notify(redact(passive ?? "No quota endpoint is available for the active provider."), "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));
+        const auth = await resolveQuotaAuth(provider, ctx.modelRegistry, readStoredCredential);
+        let result: QuotaResult;
+        if (auth.ok) {
+          ctx.ui.notify(`Checking quota for ${provider.displayName}…`, "info");
+          result = await fetchQuota(auth.provider, auth.apiKey);
+        } else {
+          result = auth;
         }
-        const passive = [...rateLimits.values()]
-          .map((s) => formatRateLimit(s))
-          .filter((line): line is string => line !== null);
-        const passiveBlock = passive.length > 0 ? `${passive.join("\n")}\n\n` : "";
-        ctx.ui.notify(redact(passiveBlock + quotaReport(results)), results.every((r) => r.ok) ? "info" : "warning");
+        quotas.set(id, { result, fetchedAt: Date.now() });
+        updateFooter(ctx);
+        ctx.ui.notify(redact((passive ? `${passive}\n\n` : "") + quotaReport([result])), result.ok ? "info" : "warning");
         return;
       }
       ctx.ui.notify(dashboard(ctx), "info");
     },
-  });
+  };
+  pi.registerCommand("usage", usageCommand);
+  pi.registerCommand("pify-usage", usageCommand);
 
   pi.registerCommand("context", {
     description: "Where the context window went: /context",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.12.1",
+  "version": "0.14.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",

package/skills/usage/SKILL.md

@@ -17,9 +17,13 @@ This project has the `@pify/usage` extension installed: a live footer
 
 ## Notes
 
-- All numbers are computed locally from pi's session files and the current
-  session's message usage — no network, no tokens spent asking.
-- `/usage` (user command) shows the full dashboard: session breakdown,
-  today/7d/30d history, and per-model totals.
+- Session/history metrics are computed locally from pi's session files and
+  the current session's message usage — no network, no tokens spent asking.
+- `/usage` (or `/pify-usage` when another extension owns `/usage`) shows
+  the full dashboard: session breakdown, today/7d/30d history, and per-model totals.
+- `/usage quota` is explicitly opt-in network access, not part of
+  `usage_status`. It checks only the active provider, including Pi OAuth
+  Copilot (GitHub.com or matching GHE Cloud tenant)/Codex quotas; the active subscription's cached percentage remaining
+  appears in the footer. Do not run quota checks just to report local costs.
 - Costs come from pi's own per-message usage.cost; if a model has no price
   configured, its cost reads as $0 while tokens still count.

package/src/context.ts

@@ -170,6 +170,62 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
   return { conversation, toolResults, thinking };
 }
 
+/** One tool's share of the schema tax: its estimated token cost and where it came from. */
+export interface ToolTax {
+  name: string;
+  tokens: number;
+  /** "builtin/ext", or "mcp:<server>" for an MCP tool. */
+  source: string;
+}
+
+/** The server an MCP tool belongs to (mcp__<server>__<tool>), or null. */
+export function mcpServerOf(name: string): string | null {
+  const m = /^mcp__(.+?)__/.exec(name);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Every active tool ranked by the tokens its schema (name + description +
+ * parameters) adds to the prefix of every request. The "Tool definitions" row
+ * in the breakdown is this sum; this says which tools make it up, biggest
+ * first — the live, per-session answer to what @pify-adjacent "subagent-tax"
+ * measures across harnesses. Same chars/4 estimate as everything else here.
+ */
+export function toolTax(tools: BreakdownInput["tools"]): ToolTax[] {
+  return tools
+    .map((tool) => {
+      const name = String(tool.name ?? "");
+      const server = mcpServerOf(name);
+      return {
+        name,
+        tokens: estimateTextTokens({ name, description: tool.description, parameters: tool.parameters }),
+        source: server ? `mcp:${server}` : "builtin/ext",
+      };
+    })
+    .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+}
+
+/** A compact "heaviest tool schemas" block: the top `max`, then a by-source subtotal. */
+export function formatToolTax(tools: BreakdownInput["tools"], max = 8): string[] {
+  const ranked = toolTax(tools);
+  if (ranked.length === 0) return [];
+  const total = ranked.reduce((sum, t) => sum + t.tokens, 0);
+  const width = Math.min(ranked.length, max) > 0 ? ranked.slice(0, max).reduce((m, t) => Math.max(m, t.name.length), 0) : 0;
+  const lines = [`Heaviest tool schemas (${ranked.length} ${ranked.length === 1 ? "tool" : "tools"}, ~${formatTokens(total)} of the prefix):`];
+  for (const t of ranked.slice(0, max)) {
+    lines.push(`  ${t.name.padEnd(width)}  ${formatTokens(t.tokens).padStart(6)}  ${t.source === "builtin/ext" ? "" : t.source}`.trimEnd());
+  }
+  if (ranked.length > max) {
+    const rest = ranked.slice(max).reduce((sum, t) => sum + t.tokens, 0);
+    lines.push(`  … and ${ranked.length - max} more, ~${formatTokens(rest)}`);
+  }
+  const bySource = new Map<string, number>();
+  for (const t of ranked) bySource.set(t.source, (bySource.get(t.source) ?? 0) + t.tokens);
+  const subtotals = [...bySource.entries()].sort((a, b) => b[1] - a[1]).map(([s, n]) => `${s} ~${formatTokens(n)}`);
+  if (subtotals.length > 1) lines.push(`  by source: ${subtotals.join(", ")}`);
+  return lines;
+}
+
 export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
   const memory = input.contextFiles.reduce(
     (sum, file) => sum + embeddedTokens(input.systemPrompt, file.content ?? ""),

package/src/quota-auth.ts

@@ -0,0 +1,65 @@
+import { isRecord } from "./types.ts";
+import type { QuotaProvider } from "./quota.ts";
+
+interface QuotaRegistry {
+  getApiKeyForProvider?: (id: string) => Promise<string | undefined>;
+  getProviderAuth?: (id: string) => Promise<{ auth?: { apiKey?: string } } | undefined>;
+}
+
+export type QuotaAuthResult =
+  | { ok: true; provider: QuotaProvider; apiKey: string }
+  | { ok: false; provider: string; reason: string };
+
+/** Bind login authority to API authority; never infer it from an inference token. */
+function githubQuotaHost(value: unknown): string | null {
+  if (value === undefined || value === null || value === "") return "api.github.com";
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value.includes("://") ? value : `https://${value}`);
+    if (url.protocol !== "https:" || url.username || url.password || url.port ||
+      url.pathname !== "/" || url.search || url.hash) return null;
+    if (url.hostname === "github.com") return "api.github.com";
+    if (/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.ghe\.com$/.test(url.hostname)) return `api.${url.hostname}`;
+  } catch {
+    // An unsupported authority must not fall back to public GitHub.
+  }
+  return null;
+}
+
+/** Resolve token AND endpoint together through Pi's public credential APIs. */
+export async function resolveQuotaAuth(
+  provider: QuotaProvider,
+  registry: QuotaRegistry,
+  readCredential: (provider: string) => unknown,
+): Promise<QuotaAuthResult> {
+  const unavailable = (reason: string): QuotaAuthResult => ({ ok: false, provider: provider.id, reason });
+  try {
+    if (provider.id === "github-copilot" || provider.id === "openai-codex") {
+      const credential = readCredential(provider.id);
+      if (!isRecord(credential) || credential.type !== "oauth") return unavailable("Pi OAuth login is required for this subscription quota");
+      if (provider.id === "github-copilot") {
+        const host = githubQuotaHost(credential.enterpriseUrl);
+        if (!host) return unavailable("unsupported GitHub OAuth authority; no quota request was sent");
+        // Pi stores the GitHub login token in refresh; access is the inference token.
+        const apiKey = typeof credential.refresh === "string" ? credential.refresh.trim() : "";
+        if (!apiKey) return unavailable("GitHub OAuth login token is unavailable; the inference token cannot be used");
+        return { ok: true, apiKey, provider: {
+          ...provider, url: `https://${host}/copilot_internal/user`, allowlist: [host],
+        } };
+      }
+    }
+    const direct = await registry.getApiKeyForProvider?.(provider.id);
+    const apiKey = direct || (await registry.getProviderAuth?.(provider.id))?.auth?.apiKey || "";
+    if (!apiKey.trim()) return unavailable("Pi has no credential for the active provider");
+    if (provider.id === "openai-codex") {
+      // A stored login must not authorize forwarding an unrelated resolved API key.
+      const refreshed = readCredential(provider.id);
+      if (!isRecord(refreshed) || refreshed.type !== "oauth" || refreshed.access !== apiKey) {
+        return unavailable("resolved credential does not match the Codex OAuth login; no quota request was sent");
+      }
+    }
+    return { ok: true, apiKey, provider };
+  } catch {
+    return unavailable("Pi credential resolution failed; no quota request was sent");
+  }
+}

package/src/quota.ts

@@ -5,19 +5,25 @@
  * dashboard: a provider that is slow or down shows as unavailable next to the
  * local numbers.
  *
- * 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.)
+ * OpenRouter and DeepSeek expose balance APIs. Copilot and Codex expose
+ * subscription quotas through endpoints published by their official clients,
+ * without the same versioned REST contract. All four are opt-in per call;
+ * polling is never started by a session, a model change, or a footer redraw.
  */
 
 import { controlledGetJson, type HttpResult } from "./http.ts";
 import { finite, isRecord } from "./types.ts";
 
+export interface QuotaWindow {
+  label: string;
+  remainingPercent: number | null;
+  resetAt: number | null;
+  unlimited: boolean;
+}
+
 export interface QuotaInfo {
+  /** Subscription windows are percentages, not monetary balances. */
+  windows?: QuotaWindow[];
   provider: string;
   /** Spend on this key, in the provider's currency, as it reports it. */
   used: number | null;
@@ -126,6 +132,61 @@ export function parseDeepSeekBalance(payload: unknown): QuotaInfo | null {
   };
 }
 
+/** Copilot premium interactions (or AI credits on token-based billing). */
+export function parseCopilotQuota(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload) || !isRecord(payload.quota_snapshots)) return null;
+  const snapshot = payload.quota_snapshots.premium_interactions;
+  if (!isRecord(snapshot)) return null;
+  const remaining = num(snapshot.quota_remaining) ?? num(snapshot.remaining);
+  const limit = num(snapshot.entitlement);
+  const percent = num(snapshot.percent_remaining) ??
+    (remaining !== null && limit !== null && limit > 0 ? remaining / limit * 100 : null);
+  const unlimited = snapshot.unlimited === true || (remaining === 0 && limit === 0 && percent === 100);
+  if (percent === null && !unlimited) return null;
+  const reset = payload.quota_reset_date ?? payload.quota_reset_date_utc;
+  const resetAt = typeof reset === "string" ? Date.parse(reset) : Number.NaN;
+  return {
+    ...emptyQuota("github-copilot"),
+    windows: [{
+      label: payload.token_based_billing === true ? "credits" : "premium",
+      remainingPercent: percent === null || unlimited ? null : Math.max(0, Math.min(100, percent)),
+      resetAt: Number.isFinite(resetAt) ? resetAt : null,
+      unlimited,
+    }],
+  };
+}
+
+/** The ChatGPT-authenticated Codex client's primary and secondary windows. */
+export function parseCodexQuota(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload) || !isRecord(payload.rate_limit)) return null;
+  const windows: QuotaWindow[] = [];
+  for (const [key, fallback] of [["primary_window", "primary"], ["secondary_window", "secondary"]] as const) {
+    const window = payload.rate_limit[key];
+    if (!isRecord(window)) continue;
+    const used = num(window.used_percent);
+    if (used === null || used < 0) continue;
+    const seconds = num(window.limit_window_seconds);
+    const label = seconds !== null && seconds > 0 && seconds % 86400 === 0 ? `${seconds / 86400}d` :
+      seconds !== null && seconds > 0 && seconds % 3600 === 0 ? `${seconds / 3600}h` : fallback;
+    const epoch = num(window.reset_at);
+    const resetAt = epoch === null ? Number.NaN : epoch * 1000;
+    windows.push({ label, remainingPercent: Math.max(0, Math.min(100, 100 - used)),
+      resetAt: Number.isFinite(new Date(resetAt).getTime()) ? resetAt : null, unlimited: false });
+  }
+  return windows.length > 0 ? { ...emptyQuota("openai-codex"), windows } : null;
+}
+
+function codexAccountId(accessToken: string): string | undefined {
+  try {
+    const payload: unknown = JSON.parse(Buffer.from(accessToken.split(".")[1] ?? "", "base64url").toString("utf8"));
+    if (!isRecord(payload) || !isRecord(payload["https://api.openai.com/auth"])) return undefined;
+    const account = payload["https://api.openai.com/auth"].chatgpt_account_id;
+    return typeof account === "string" && account.length > 0 && !/[\r\n]/.test(account) ? account : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export interface QuotaProvider {
   /** pi's provider id, which is also how the key is looked up. */
   id: string;
@@ -136,6 +197,20 @@ export interface QuotaProvider {
 }
 
 export const QUOTA_PROVIDERS: readonly QuotaProvider[] = [
+  {
+    id: "github-copilot",
+    displayName: "GitHub Copilot",
+    url: "https://api.github.com/copilot_internal/user",
+    allowlist: ["api.github.com"],
+    parse: parseCopilotQuota,
+  },
+  {
+    id: "openai-codex",
+    displayName: "Codex",
+    url: "https://chatgpt.com/backend-api/wham/usage",
+    allowlist: ["chatgpt.com"],
+    parse: parseCodexQuota,
+  },
   {
     id: "openrouter",
     displayName: "OpenRouter",
@@ -168,9 +243,18 @@ export async function fetchQuota(
 ): Promise<QuotaResult> {
   if (!apiKey.trim()) return { ok: false, provider: provider.id, reason: "no API key configured" };
 
+  const headers: Record<string, string> = { Authorization: `Bearer ${apiKey.trim()}`, Accept: "application/json" };
+  if (provider.id === "github-copilot") {
+    headers["X-GitHub-Api-Version"] = "2022-11-28";
+    headers["User-Agent"] = "pify-usage";
+  }
+  if (provider.id === "openai-codex") {
+    const accountId = codexAccountId(apiKey.trim());
+    if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+  }
   const result: HttpResult<unknown> = await controlledGetJson({
     url: provider.url,
-    headers: { Authorization: `Bearer ${apiKey.trim()}`, Accept: "application/json" },
+    headers,
     timeoutMs,
     allowlist: provider.allowlist,
     fetchImpl,
@@ -211,17 +295,41 @@ export function quotaBlock(result: QuotaResult): string {
       `  window   day ${money(q.daily, q.currency)} · week ${money(q.weekly, q.currency)} · month ${money(q.monthly, q.currency)}`,
     );
   }
+  for (const window of q.windows ?? []) {
+    const remaining = windowRemaining(window);
+    lines.push(`  ${window.label}  ${remaining}${window.resetAt === null ? "" : ` · resets ${new Date(window.resetAt).toISOString()}`}`);
+  }
   if (q.freeTier) lines.push("  tier     free");
   return lines.join("\n");
 }
 
-/** What `/usage quota` prints: every provider that has a key, and nothing else. */
+function windowRemaining(window: QuotaWindow): string {
+  return window.unlimited ? "unlimited" : window.remainingPercent === null ? "unknown" : `${Math.round(window.remainingPercent)}% left`;
+}
+
+/** Cached subscription data never masquerades as a live counter. No network here. */
+export function quotaFooter(result: QuotaResult | undefined, fetchedAt: number, now = Date.now()): string {
+  if (!result) return "";
+  const id = result.ok ? result.quota.provider : result.provider;
+  const name = id === "github-copilot" ? "Copilot" : id === "openai-codex" ? "Codex" : null;
+  if (!name) return "";
+  if (!result.ok) return `${name} quota unavailable`;
+  const windows = result.quota.windows;
+  if (!windows?.length) return "";
+  if (now - fetchedAt >= 15 * 60 * 1000 || windows.some(w => w.resetAt !== null && now >= w.resetAt)) {
+    return `${name} quota stale · /pify-usage quota`;
+  }
+  const parts = windows.map(w => `${w.label} ${windowRemaining(w)}`);
+  return `${name} ${parts.join(" · ")} · cached`;
+}
+
+/** What `/usage quota` prints: every provider that has suitable credentials. */
 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 balance endpoints are polled. OpenAI, Anthropic and Gemini publish no balance API, but their rate-limit headers are read passively from ordinary responses — shown above when the session has made a call.",
+      "Balances use documented endpoints and API keys. Copilot and Codex use published client endpoints and require Pi OAuth login; their contracts may change. Quota requests are opt-in, with no background polling. Rate-limit headers are read passively from ordinary responses — shown above when the session has made a call.",
     ].join("\n");
   }
   return results.map(quotaBlock).join("\n\n");