@pify/usage 0.5.1 → 0.6.0

package/README.md

@@ -73,6 +73,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

@@ -33,6 +33,7 @@ import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from
 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,6 +42,23 @@ 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;
@@ -182,7 +200,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,7 +214,11 @@ 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");
@@ -200,6 +228,7 @@ export default function usage(pi: ExtensionAPI) {
   pi.registerTool({
     name: "usage_status",
     label: "Usage status",
+    promptSnippet: "Tokens, cost, and context used so far this session",
     description:
       "Current session token/cost totals plus today's local aggregate. Use when deciding whether " +
       "an expensive approach (large reads, many subagents) is proportionate.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.5.1",
+  "version": "0.6.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/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)`;
+}