@pify/usage 0.2.0 → 0.4.0

package/README.md

@@ -28,10 +28,36 @@ 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).
 
-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-abc...xyz)
+  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,20 +10,27 @@
  * 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 {
+  formatSkillsForPrompt,
   getAgentDir,
   type ExtensionAPI,
   type ExtensionContext,
 } 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 { buildBreakdown, formatBreakdown } from "../src/context.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 +93,81 @@ 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 ?? "";
+  }
+
+  /**
+   * 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 {
+      skillsText = formatSkillsForPrompt((options.skills ?? []) as never).trim();
+    } catch {
+      // A pi version that formats skills differently just reports 0 here.
+    }
+
+    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", {
-    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,7 +1,7 @@
 {
   "name": "@pify/usage",
-  "version": "0.2.0",
-  "description": "Token and cost reporting for pi sessions: live footer, /usage dashboard over local session history, zero network",
+  "version": "0.4.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/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");
+}