@pify/usage 0.5.2 → 0.7.0

package/README.md

@@ -11,11 +11,13 @@ Spend is invisible until the invoice arrives, and by then you cannot tell which
 ## Live footer
 
 ```
-📊 12.3k tok · $0.45
+📊 12.3k tok · $0.45 · ctx ▰▰▰▱▱▱ 34%
 ```
 
 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.
 
+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`.
+
 ## `/usage`
 
 ```
@@ -40,7 +42,7 @@ History counts every usage-bearing entry in pi's session JSONL — assistant tur
 
 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` (or `/usage context`)
 
 ```
 Context window: 22.6k of 200.0k used (11%)
@@ -73,6 +75,8 @@ Quota (DeepSeek · granted 10 · topped up 100)
 
 **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.
 
+**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 subscription the unified-window percentage — captured passively from calls the session already made, with no extra request and no credential to handle.
+
 **A credentialed request is pinned down**, because it carries your provider key:
 
 - HTTPS only, and the host must be on that provider's allowlist.

package/extensions/usage.ts

@@ -29,10 +29,11 @@ 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 { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.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 { parseRateLimit, formatRateLimit, type RateLimitSnapshot } from "../src/ratelimit.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
 type UiContext = ExtensionContext;
@@ -41,10 +42,33 @@ export default function usage(pi: ExtensionAPI) {
   let session: UsageTotals = emptyTotals();
   /** input+cacheRead of the most recent assistant message ≈ context size. */
   let lastPromptTokens = 0;
+  /**
+   * The latest rate-limit headers seen per provider — passive quota, captured
+   * free from responses the session already made, no extra network call.
+   */
+  const rateLimits = new Map<string, RateLimitSnapshot>();
+
+  // after_provider_response carries the status and full headers of every
+  // provider call, before the stream is read; gated on hasHandlers, so
+  // subscribing costs nothing per request. The event does not name the
+  // provider, so it is read from the model in context.
+  pi.on("after_provider_response", async (event, ctx) => {
+    const provider = (ctx as { model?: { provider?: string } }).model?.provider;
+    if (!provider) return;
+    const evt = event as unknown as { headers?: Record<string, string> };
+    const snap = parseRateLimit(provider, evt.headers ?? {}, Date.now());
+    if (snap) rateLimits.set(provider, snap);
+  });
 
   function updateFooter(ctx: UiContext): void {
     if (!ctx.hasUI) return;
-    ctx.ui.setStatus("usage", footerText(session));
+    const base = footerText(session);
+    if (!base) {
+      ctx.ui.setStatus("usage", undefined);
+      return;
+    }
+    const gauge = contextGauge(contextPct(ctx));
+    ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
   }
 
   function contextPct(ctx: UiContext): number | null {
@@ -169,9 +193,15 @@ export default function usage(pi: ExtensionAPI) {
   }
 
   pi.registerCommand("usage", {
-    description: "Token and cost dashboard: /usage [quota]",
+    description: "Token and cost dashboard: /usage [context | quota]",
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
+      if ((args ?? "").trim().toLowerCase() === "context") {
+        // Documented since the breakdown landed, but never wired — the handler
+        // only knew "quota", so `/usage context` quietly showed the dashboard.
+        ctx.ui.notify(contextBreakdown(ctx), "info");
+        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
@@ -182,7 +212,13 @@ export default function usage(pi: ExtensionAPI) {
           if (key) configured.push({ provider, key });
         }
         if (configured.length === 0) {
-          ctx.ui.notify(quotaReport([]), "info");
+          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",
+          );
           return;
         }
         ctx.ui.notify(`Checking quota for ${configured.map((c) => c.provider.displayName).join(", ")}…`, "info");
@@ -190,13 +226,27 @@ export default function usage(pi: ExtensionAPI) {
         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");
+        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");
         return;
       }
       ctx.ui.notify(dashboard(ctx), "info");
     },
   });
 
+  pi.registerCommand("context", {
+    description: "Where the context window went: /context",
+    handler: async (_args, ctx) => {
+      // The live footer gauge says how full the window is; this says spent on
+      // WHAT — the breakdown was built for the /usage dashboard's one-line note
+      // but the full bar view had no command to reach it until now.
+      if (ctx.hasUI) ctx.ui.notify(contextBreakdown(ctx), "info");
+    },
+  });
+
   pi.registerTool({
     name: "usage_status",
     label: "Usage status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.5.2",
+  "version": "0.7.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/src/format.ts

@@ -19,6 +19,25 @@ export function footerText(session: UsageTotals): string | undefined {
   return `📊 ${formatTokens(session.totalTokens)} tok · ${formatCost(session.cost)}`;
 }
 
+const GAUGE_CELLS = 6;
+
+/**
+ * A compact live context gauge for the footer: a filled/empty bar and the
+ * percentage of the window in use. The footer already carries tokens and cost;
+ * this answers the third question you have mid-session — how close am I to the
+ * wall — which was computed for the /usage dashboard but never shown live. It
+ * warns once the window is nearly full, because that is when the number stops
+ * being trivia and starts being a decision. Empty when there is no window to
+ * measure against (e.g. under `-p`, or before the first response).
+ */
+export function contextGauge(pct: number | null): string {
+  if (pct === null || !Number.isFinite(pct)) return "";
+  const clamped = Math.max(0, Math.min(100, pct));
+  const filled = Math.round((clamped / 100) * GAUGE_CELLS);
+  const bar = "▰".repeat(filled) + "▱".repeat(GAUGE_CELLS - filled);
+  return `${clamped >= 90 ? "⚠ " : ""}ctx ${bar} ${Math.round(clamped)}%`;
+}
+
 export function sessionBlock(session: UsageTotals, contextPct: number | null): string {
   const lines = [
     "Session",

package/src/quota.ts

@@ -221,7 +221,7 @@ export function quotaReport(results: QuotaResult[]): string {
     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.",
+      "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.",
     ].join("\n");
   }
   return results.map(quotaBlock).join("\n\n");

package/src/ratelimit.ts

@@ -0,0 +1,133 @@
+/**
+ * Rate-limit quota from the headers the provider already sent.
+ *
+ * The polling path in quota.ts asks OpenRouter and DeepSeek what a key has
+ * spent, over an extra credentialed GET, and tells the user OpenAI/Anthropic/
+ * Gemini "publish none". That last part is only true of the *balance* APIs.
+ * Every one of them returns rate-limit headers on the ordinary completion
+ * response, and pi hands extensions the full header set of every provider call
+ * through `after_provider_response` — status + headers, emitted before the
+ * stream is read, free when nobody subscribes. So this is per-request quota
+ * with zero extra network calls and zero credentials to handle.
+ *
+ * Pure: the extension captures the latest snapshot per provider and this turns
+ * one header bag into it. Unknown providers and empty bags return null, so a
+ * response that carries nothing simply leaves the last snapshot untouched.
+ */
+
+export interface RateLimitSnapshot {
+  provider: string;
+  /** Requests left in the current window, when the provider reports it. */
+  requestsRemaining: number | null;
+  /** Tokens left in the current window, when reported. */
+  tokensRemaining: number | null;
+  /** When the window resets — provider's own string (seconds, ISO, or duration). */
+  resets: string | null;
+  /** A unified subscription-window fraction 0..1 remaining, Anthropic OAuth only. */
+  unifiedRemaining: number | null;
+  /** Which header family this came from, for the report line. */
+  source: "anthropic" | "openai" | "openrouter";
+  capturedAtMs: number;
+}
+
+function intOf(headers: Record<string, string>, key: string): number | null {
+  const raw = headers[key] ?? headers[key.toLowerCase()];
+  if (raw === undefined) return null;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+function strOf(headers: Record<string, string>, key: string): string | null {
+  const raw = headers[key] ?? headers[key.toLowerCase()];
+  return raw === undefined || raw === "" ? null : String(raw);
+}
+
+/**
+ * Parse a header bag for a given provider id. `nowMs` is passed in rather than
+ * read from the clock, so this stays pure and testable.
+ */
+export function parseRateLimit(
+  provider: string,
+  headers: Record<string, string>,
+  nowMs: number,
+): RateLimitSnapshot | null {
+  // Header keys can arrive in any case; normalise once so lookups are stable.
+  const h: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers ?? {})) h[k.toLowerCase()] = v;
+
+  const family = provider.includes("anthropic")
+    ? "anthropic"
+    : provider.includes("openrouter")
+      ? "openrouter"
+      : provider.includes("openai") || provider.includes("azure")
+        ? "openai"
+        : null;
+  if (!family) return null;
+
+  let snap: RateLimitSnapshot | null = null;
+
+  if (family === "anthropic") {
+    const reqs = intOf(h, "anthropic-ratelimit-requests-remaining");
+    const toks = intOf(h, "anthropic-ratelimit-tokens-remaining");
+    // The OAuth Pro/Max unified subscription window, reported as a percentage.
+    const unifiedRaw = strOf(h, "anthropic-ratelimit-unified-status")
+      ? intOf(h, "anthropic-ratelimit-unified-remaining")
+      : intOf(h, "anthropic-ratelimit-unified-remaining");
+    if (reqs !== null || toks !== null || unifiedRaw !== null) {
+      snap = {
+        provider,
+        requestsRemaining: reqs,
+        tokensRemaining: toks,
+        resets:
+          strOf(h, "anthropic-ratelimit-unified-reset") ??
+          strOf(h, "anthropic-ratelimit-tokens-reset") ??
+          strOf(h, "anthropic-ratelimit-requests-reset"),
+        unifiedRemaining: unifiedRaw === null ? null : Math.max(0, Math.min(1, unifiedRaw / 100)),
+        source: "anthropic",
+        capturedAtMs: nowMs,
+      };
+    }
+  } else if (family === "openai") {
+    const reqs = intOf(h, "x-ratelimit-remaining-requests");
+    const toks = intOf(h, "x-ratelimit-remaining-tokens");
+    if (reqs !== null || toks !== null) {
+      snap = {
+        provider,
+        requestsRemaining: reqs,
+        tokensRemaining: toks,
+        resets: strOf(h, "x-ratelimit-reset-tokens") ?? strOf(h, "x-ratelimit-reset-requests"),
+        unifiedRemaining: null,
+        source: "openai",
+        capturedAtMs: nowMs,
+      };
+    }
+  } else {
+    // openrouter: a single credit window on the completion response.
+    const remaining = intOf(h, "x-ratelimit-remaining");
+    if (remaining !== null) {
+      snap = {
+        provider,
+        requestsRemaining: remaining,
+        tokensRemaining: null,
+        resets: strOf(h, "x-ratelimit-reset"),
+        unifiedRemaining: null,
+        source: "openrouter",
+        capturedAtMs: nowMs,
+      };
+    }
+  }
+
+  return snap;
+}
+
+/** One human line for the /usage quota report; null when nothing was captured. */
+export function formatRateLimit(snap: RateLimitSnapshot | null): string | null {
+  if (!snap) return null;
+  const parts: string[] = [];
+  if (snap.unifiedRemaining !== null) parts.push(`${Math.round(snap.unifiedRemaining * 100)}% of subscription window left`);
+  if (snap.requestsRemaining !== null) parts.push(`${snap.requestsRemaining} requests left`);
+  if (snap.tokensRemaining !== null) parts.push(`${snap.tokensRemaining} tokens left`);
+  if (parts.length === 0) return null;
+  const when = snap.resets ? `, resets ${snap.resets}` : "";
+  return `${snap.provider}: ${parts.join(", ")}${when} (from response headers)`;
+}