@saifymatteo/pi-extensions 0.0.0-stage → 0.1.1

package/packages/pi-claude-usage/README.md

@@ -0,0 +1,27 @@
+# Claude subscription usage
+
+Displays Claude subscription rate-limit windows from provider message diagnostics.
+
+## Try locally
+
+From the repository root:
+
+```sh
+pi -e ./packages/pi-claude-usage
+```
+
+This uses your normal personal resources unless you isolate the agent home. Follow the [root README](../../README.md#isolated-sessions) to avoid loading an existing copy of the extension. Nothing is installed globally. 
+
+## Configuration and requirements
+
+Uses rate-limit diagnostics from the external pi-claude-code provider; it does not poll Anthropic. Caches the most recent windows in <agent-dir>/state/claude-usage.json. No additional configuration.
+
+## Compatibility and safety
+
+Status/footer presentation depends on the host and other footer extensions.
+
+Imported host APIs are declared as peer dependencies and supplied by the Pi host. A `*` peer range describes host resolution, not a guarantee of compatibility with every release. See root verification notes for what was actually exercised.
+
+## Status
+
+Part of the [pi-extensions](../../README.md) collection. No personal settings or credentials are included; see [NOTICE.md](NOTICE.md) for licensing and provenance.

package/packages/pi-claude-usage/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@saifymatteo/pi-claude-usage",
+  "version": "0.1.1",
+  "description": "Displays Claude subscription rate-limit windows from provider message diagnostics.",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-claude-usage"
+  }
+}

package/packages/pi-claude-usage/src/index.ts

@@ -0,0 +1,130 @@
+// Claude subscription usage (5h + 7d windows) in the footer.
+//
+// Data is free: pi-claude-code attaches Claude Code's rate_limit_event to
+// every assistant message as a "claude-code.rate-limit" diagnostic, whose
+// unifiedWindows carry utilization (0..1) and resetsAt (epoch seconds). The
+// last value is cached on disk so a fresh session shows it before any turn.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const STATUS_KEY = "claude-usage";
+const DIAGNOSTIC_TYPE = "claude-code.rate-limit";
+const TICK_MS = 60_000; // countdown refresh only, no network
+
+export interface Window {
+	pct: number; // 0..100
+	resetsAt: number; // epoch ms
+}
+
+export interface Usage {
+	fiveHour?: Window;
+	sevenDay?: Window;
+	rejected?: boolean;
+	overage?: boolean;
+}
+
+function cachePath(): string {
+	return join(process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "state", "claude-usage.json");
+}
+
+// rate_limit_info from Claude Code stream-json.
+export function fromRateLimit(info: any): Usage | undefined {
+	const w = info?.unifiedWindows;
+	if (!w || typeof w !== "object") return undefined;
+	const win = (x: any): Window | undefined =>
+		typeof x?.utilization === "number" && typeof x?.resetsAt === "number"
+			? { pct: x.utilization * 100, resetsAt: x.resetsAt * 1000 }
+			: undefined;
+	return {
+		fiveHour: win(w.five_hour),
+		sevenDay: win(w.seven_day),
+		rejected: info.status === "rejected",
+		overage: info.isUsingOverage === true,
+	};
+}
+
+export function formatLeft(ms: number): string {
+	const mins = Math.max(0, Math.ceil(ms / 60_000));
+	const d = Math.floor(mins / 1440);
+	const h = Math.floor((mins % 1440) / 60);
+	const m = mins % 60;
+	if (d > 0) return `${d}d${h}h`;
+	if (h > 0) return `${h}h${String(m).padStart(2, "0")}m`;
+	return `${m}m`;
+}
+
+function part(label: string, w: Window | undefined, now: number): string {
+	if (!w) return `${label} ?`;
+	// A passed reset means the window rolled over since we last saw it.
+	if (w.resetsAt <= now) return `${label} 0%`;
+	return `${label} ${Math.round(w.pct)}% ↻${formatLeft(w.resetsAt - now)}`;
+}
+
+export function formatFooter(u: Usage, now = Date.now()): string {
+	return `Claude ${part("5h", u.fiveHour, now)} · ${part("7d", u.sevenDay, now)}${u.overage ? " · overage" : ""}`;
+}
+
+function peak(u: Usage, now: number): number {
+	const live = (w?: Window) => (w && w.resetsAt > now ? w.pct : 0);
+	return Math.max(live(u.fiveHour), live(u.sevenDay));
+}
+
+export default function (pi: ExtensionAPI) {
+	let usage: Usage | undefined;
+	let ctx: ExtensionContext | undefined;
+	let tick: ReturnType<typeof setInterval> | undefined;
+
+	function render() {
+		if (!ctx || !usage) return;
+		const now = Date.now();
+		const text = formatFooter(usage, now);
+		const p = peak(usage, now);
+		const color = usage.rejected || usage.overage || p >= 90 ? "error" : p >= 75 ? "warning" : "dim";
+		try {
+			ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg(color, text));
+		} catch {
+			/* replaced session */
+		}
+	}
+
+	function update(next: Usage | undefined) {
+		if (!next) return;
+		usage = next;
+		render();
+		try {
+			mkdirSync(dirname(cachePath()), { recursive: true });
+			writeFileSync(cachePath(), JSON.stringify(next));
+		} catch {
+			/* cache is best-effort */
+		}
+	}
+
+	pi.on("session_start", async (_event, sessionCtx) => {
+		ctx = sessionCtx;
+		try {
+			usage ??= JSON.parse(readFileSync(cachePath(), "utf8"));
+		} catch {
+			/* no cache yet */
+		}
+		render();
+		if (!tick) {
+			tick = setInterval(render, TICK_MS);
+			tick.unref?.();
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		if (tick) clearInterval(tick);
+		tick = undefined;
+		ctx = undefined;
+	});
+
+	pi.on("message_end", async (event) => {
+		const msg: any = event.message;
+		if (msg?.role !== "assistant" || !Array.isArray(msg.diagnostics)) return;
+		const diag = msg.diagnostics.findLast((d: any) => d?.type === DIAGNOSTIC_TYPE);
+		if (diag) update(fromRateLimit(diag.details));
+	});
+}