@pify/usage 0.2.0 → 0.3.0

package/README.md

@@ -31,7 +31,19 @@ By project (all time)
 - **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).
 
-Provider quota APIs (Codex windows, Copilot allowances, OpenRouter credits…) are deliberately out of v0.1 — they cost ~18k lines of per-provider contract maintenance (see `@narumitw/pi-usage` if you need them today).
+## `/usage quota` (v0.3)
+
+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
+```
+
+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.
+
+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).
 
 ## License
 

package/extensions/usage.ts

@@ -10,9 +10,12 @@
  * tmustier's lesson) with a per-file mtime cache. The usage_status tool
  * lets the agent itself check consumption mid-session.
  *
- * Provider quota APIs (Codex windows, Copilot, OpenRouter…) are deliberately
- * v0.2 — @narumitw/pi-usage shows they cost ~18k lines of per-provider
- * contract maintenance.
+ * 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.
  */
 import {
   getAgentDir,
@@ -21,9 +24,11 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { join } from "node:path";
+import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
+import { fetchOpenRouterQuota, quotaBlock } from "../src/quota.ts";
 import { scanSessions } from "../src/sessions.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
@@ -86,10 +91,33 @@ export default function usage(pi: ExtensionAPI) {
 
   // ── 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.
+   */
+  function providerKey(provider: string): string {
+    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;
+    } catch {
+      // no auth.json, or unreadable — fall through to the environment
+    }
+    return process.env.OPENROUTER_API_KEY ?? "";
+  }
+
   pi.registerCommand("usage", {
-    description: "Token and cost dashboard: current session + local history",
-    handler: async (_args, ctx) => {
-      if (ctx.hasUI) ctx.ui.notify(dashboard(ctx), "info");
+    description: "Token and cost dashboard: /usage [quota]",
+    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");
+        return;
+      }
+      ctx.ui.notify(dashboard(ctx), "info");
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Token and cost reporting for pi sessions: live footer, /usage dashboard over local session history, zero network",
   "keywords": [
     "pi-package",

package/src/quota.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import { finite, isRecord } from "./types.ts";
+
+export interface QuotaInfo {
+  provider: string;
+  /** Spend on this key, in USD, as the provider reports it. */
+  used: number | null;
+  /** Hard credit limit, when the key has one. */
+  limit: number | null;
+  remaining: number | null;
+  /** Rolling-window spend, when reported. */
+  daily: number | null;
+  weekly: number | null;
+  monthly: number | null;
+  label: string | null;
+  freeTier: boolean | null;
+}
+
+export type QuotaResult =
+  | { ok: true; quota: QuotaInfo }
+  | { ok: false; provider: string; reason: string };
+
+export const QUOTA_TIMEOUT_MS = 8000;
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * 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.
+ */
+export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload)) return null;
+  // The endpoint wraps its fields in `data`; a flat body is accepted too, but
+  // a `data` that is present and not an object means the shape changed.
+  if ("data" in payload && !isRecord(payload.data)) return null;
+  const data = isRecord(payload.data) ? payload.data : payload;
+
+  const used = num(data.usage);
+  const limit = num(data.limit);
+  const remaining = num(data.limit_remaining) ?? (limit !== null && used !== null ? limit - used : null);
+
+  return {
+    provider: "openrouter",
+    used: used === null ? null : finite(used),
+    limit,
+    remaining,
+    daily: num(data.usage_daily),
+    weekly: num(data.usage_weekly),
+    monthly: num(data.usage_monthly),
+    label: typeof data.label === "string" ? data.label : null,
+    freeTier: typeof data.is_free_tier === "boolean" ? data.is_free_tier : null,
+  };
+}
+
+export type Fetcher = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}>;
+
+/** Fetch the OpenRouter key status. Never throws — failure is a result. */
+export async function fetchOpenRouterQuota(
+  apiKey: string,
+  fetcher: Fetcher = globalThis.fetch as unknown as Fetcher,
+  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),
+    };
+  }
+}
+
+function money(value: number | null): string {
+  if (value === null) return "—";
+  if (value === 0) return "$0";
+  if (Math.abs(value) < 0.01) return "<$0.01";
+  return `$${value.toFixed(2)}`;
+}
+
+export function quotaBlock(result: QuotaResult): string {
+  if (!result.ok) {
+    return `Quota (${result.provider})\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`,
+  );
+  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)}`);
+  }
+  if (q.freeTier) lines.push("  tier     free");
+  return lines.join("\n");
+}