@marcosgilf/pi-usage 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Gil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# 📊 pi-usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Show GitHub Copilot plan and usage percentage in Pi's default footer, with a modal for quota details.
+
+## Install
+
+```sh
+pi install npm:@marcosgilf/pi-usage
+```
+
+- When installed alone, the default footer shows Copilot plan and percentage.
+- `/copilot-usage` opens quota details.
+- `super+shift+u` opens the same modal.
+- In modal: `c` copies full summary; Ctrl/Cmd+C copies selected text; click outside closes.
+- Install `@marcosgilf/pi-footer` to place usage beside the model and coordinate it with session context. It loads this extension as a dependency; do not install both packages separately.
+
+Pi extensions run with Pi's operating-system permissions. Review package source before installing.
+
+The quota request uses GitHub's undocumented `copilot_internal/user` endpoint through `gh`. Install and sign in to GitHub CLI. The `user` OAuth scope may be required:
+
+```sh
+gh auth refresh -h github.com -s user
+```
+
+GitHub may change this endpoint.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@marcosgilf/pi-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Show GitHub Copilot plan and quota usage in Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "usage",
+    "quota",
+    "github-copilot",
+    "copilot"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./events": "./src/events.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@marcosgilf/pi-modal": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/copilot-usage.ts

@@ -0,0 +1,172 @@
+import { execFile } from "node:child_process";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ModalContent, type ModalRow, showModal } from "@marcosgilf/pi-modal";
+import { type CopilotUsage, formatPlanUsage, formatUsageSummary, getUsageProgress, parseCopilotUsage } from "./core.ts";
+import { COPILOT_USAGE_STATUS_KEY, OPEN_COPILOT_USAGE_EVENT } from "./events.ts";
+
+const CACHE_MS = 5 * 60 * 1000;
+
+type UsageSnapshot = CopilotUsage & { fetchedAt: number };
+
+let cachedUsage: UsageSnapshot | undefined;
+let lastError: string | undefined;
+let lastAttempt = 0;
+let pending: Promise<UsageSnapshot> | undefined;
+
+function runGh(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      "gh",
+      ["api", "--hostname", "github.com", ...args],
+      {
+        encoding: "utf8",
+        timeout: 15_000,
+        maxBuffer: 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          const message = String(stderr || error.message).trim();
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            reject(new Error("GitHub CLI (`gh`) not found. Install it and run `gh auth login -h github.com`."));
+          } else if (/needs the ["']user["'] scope/i.test(message)) {
+            reject(
+              new Error('Copilot usage needs the "user" OAuth scope. Run `gh auth refresh -h github.com -s user`.'),
+            );
+          } else if (/not logged in|authentication required/i.test(message)) {
+            reject(new Error("GitHub CLI is not logged in. Run `gh auth login -h github.com`."));
+          } else {
+            reject(new Error(`GitHub Copilot usage request failed: ${message}`));
+          }
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+  });
+}
+
+async function fetchCopilotUsage(): Promise<CopilotUsage> {
+  return parseCopilotUsage(JSON.parse(await runGh(["copilot_internal/user"])) as unknown);
+}
+
+async function refreshUsage(force = false): Promise<UsageSnapshot> {
+  if (pending) return pending;
+  if (!force && cachedUsage && Date.now() - cachedUsage.fetchedAt < CACHE_MS) return cachedUsage;
+  if (!force && lastError && Date.now() - lastAttempt < CACHE_MS) throw new Error(lastError);
+
+  lastAttempt = Date.now();
+  pending = fetchCopilotUsage()
+    .then((usage) => {
+      cachedUsage = { ...usage, fetchedAt: Date.now() };
+      lastError = undefined;
+      return cachedUsage;
+    })
+    .catch((error: unknown) => {
+      lastError = error instanceof Error ? error.message : String(error);
+      throw new Error(lastError);
+    })
+    .finally(() => {
+      pending = undefined;
+    });
+  return pending;
+}
+
+function buildCopilotUsageModal(usage: CopilotUsage): ModalContent {
+  const [title, planText, quotaText, resetText] = formatUsageSummary(usage);
+  const progress = getUsageProgress(usage);
+  const rows: ModalRow[] = [
+    { text: title, style: "accent" },
+    { text: "" },
+    { text: planText },
+    { text: "" },
+    { text: quotaText },
+  ];
+  if (progress === undefined) rows.push({ text: "" });
+  else rows.push({ text: "" }, { text: "", progress, style: progress >= 90 ? "warning" : "success" }, { text: "" });
+  rows.push({ text: resetText });
+  return { rows, clipboardText: [title, planText, quotaText, resetText].join("\n") };
+}
+
+async function showCopilotUsage(ctx: ExtensionContext, isCurrent: () => boolean): Promise<void> {
+  const unavailableMessage = "/copilot-usage requires Pi TUI mode.";
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify(unavailableMessage, "warning");
+    return;
+  }
+
+  try {
+    const usage = await refreshUsage(true);
+    if (!isCurrent()) return;
+    const content = buildCopilotUsageModal(usage);
+    ctx.ui.setStatus(COPILOT_USAGE_STATUS_KEY, formatPlanUsage(usage));
+    await showModal(
+      ctx,
+      content,
+      {
+        refresh: async () => {
+          const usage = await refreshUsage(true);
+          if (!isCurrent()) throw new Error("Session ended during usage refresh.");
+          ctx.ui.setStatus(COPILOT_USAGE_STATUS_KEY, formatPlanUsage(usage));
+          return buildCopilotUsageModal(usage);
+        },
+      },
+      unavailableMessage,
+    );
+  } catch (error) {
+    if (isCurrent()) ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  let currentContext: ExtensionContext | undefined;
+  let sessionGeneration = 0;
+  const isCurrent = (generation: number) => () => generation === sessionGeneration;
+
+  pi.events.on(OPEN_COPILOT_USAGE_EVENT, () => {
+    if (currentContext) void showCopilotUsage(currentContext, isCurrent(sessionGeneration));
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    const generation = ++sessionGeneration;
+    if (ctx.mode !== "tui") {
+      currentContext = undefined;
+      return;
+    }
+    currentContext = ctx;
+    ctx.ui.setStatus(COPILOT_USAGE_STATUS_KEY, formatPlanUsage(cachedUsage) || undefined);
+    void refreshUsage()
+      .then((usage) => {
+        if (generation === sessionGeneration)
+          currentContext?.ui.setStatus(COPILOT_USAGE_STATUS_KEY, formatPlanUsage(usage));
+      })
+      .catch(() => {});
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    currentContext = ctx;
+    const generation = sessionGeneration;
+    void refreshUsage()
+      .then((usage) => {
+        if (generation === sessionGeneration)
+          currentContext?.ui.setStatus(COPILOT_USAGE_STATUS_KEY, formatPlanUsage(usage));
+      })
+      .catch(() => {});
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    sessionGeneration++;
+    if (ctx.mode === "tui") ctx.ui.setStatus(COPILOT_USAGE_STATUS_KEY, undefined);
+    currentContext = undefined;
+  });
+
+  pi.registerCommand("copilot-usage", {
+    description: "Show GitHub Copilot plan and quota usage",
+    handler: (_args, ctx) => showCopilotUsage(ctx, isCurrent(sessionGeneration)),
+  });
+
+  pi.registerShortcut("super+shift+u", {
+    description: "Show GitHub Copilot AI-credit usage",
+    handler: (ctx) => showCopilotUsage(ctx, isCurrent(sessionGeneration)),
+  });
+}

package/src/core.ts

@@ -0,0 +1,108 @@
+export type CopilotUsage = {
+  plan: string;
+  unit: "AI credits" | "premium requests";
+  used?: number;
+  limit?: number;
+  remaining?: number;
+  percentUsed?: number;
+  resetAt?: string;
+  unlimited: boolean;
+};
+
+const planNames: Record<string, string> = {
+  business: "Copilot Business",
+  enterprise: "Copilot Enterprise",
+  free: "Copilot Free",
+  individual: "Copilot Individual",
+  pro: "Copilot Pro",
+  pro_plus: "Copilot Pro+",
+  max: "Copilot Max",
+};
+
+function numberOrUndefined(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+export function parseCopilotUsage(data: unknown): CopilotUsage {
+  if (!data || typeof data !== "object") throw new Error("GitHub returned invalid Copilot usage data.");
+  const account = data as {
+    copilot_plan?: unknown;
+    token_based_billing?: unknown;
+    quota_reset_date_utc?: unknown;
+    quota_snapshots?: { premium_interactions?: unknown };
+  };
+  const quota = account.quota_snapshots?.premium_interactions;
+  if (!quota || typeof quota !== "object") throw new Error("GitHub returned no Copilot usage quota.");
+
+  const snapshot = quota as {
+    percent_remaining?: unknown;
+    credits_used?: unknown;
+    entitlement?: unknown;
+    quota_remaining?: unknown;
+    remaining?: unknown;
+    token_based_billing?: unknown;
+    unlimited?: unknown;
+    has_quota?: unknown;
+  };
+  const limit = numberOrUndefined(snapshot.entitlement);
+  const remaining = numberOrUndefined(snapshot.quota_remaining) ?? numberOrUndefined(snapshot.remaining);
+  const used =
+    numberOrUndefined(snapshot.credits_used) ??
+    (limit !== undefined && remaining !== undefined ? Math.max(0, limit - remaining) : undefined);
+  const percentRemaining = numberOrUndefined(snapshot.percent_remaining);
+  if (percentRemaining !== undefined && percentRemaining > 100)
+    throw new Error("GitHub returned an invalid Copilot quota percentage.");
+  const ratioPercent = used !== undefined && limit && limit > 0 ? Math.round((used / limit) * 100) : undefined;
+  const percentUsed =
+    snapshot.unlimited === true || snapshot.has_quota === false
+      ? undefined
+      : ratioPercent !== undefined && ratioPercent > 100
+        ? ratioPercent
+        : percentRemaining !== undefined
+          ? Math.round(100 - percentRemaining)
+          : ratioPercent;
+  if (percentUsed === undefined && snapshot.unlimited !== true && snapshot.has_quota !== false) {
+    throw new Error("GitHub returned no Copilot usage percentage.");
+  }
+
+  const rawPlan = typeof account.copilot_plan === "string" ? account.copilot_plan : "unknown";
+  const planKey = rawPlan
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+  const tokenBased = snapshot.token_based_billing === true || account.token_based_billing === true;
+  return {
+    plan: planNames[planKey] ?? `Copilot ${rawPlan}`,
+    unit: tokenBased ? "AI credits" : "premium requests",
+    used,
+    limit,
+    remaining,
+    percentUsed,
+    resetAt: typeof account.quota_reset_date_utc === "string" ? account.quota_reset_date_utc : undefined,
+    unlimited: snapshot.unlimited === true || snapshot.has_quota === false,
+  };
+}
+
+export function formatPlanUsage(usage?: CopilotUsage): string {
+  if (!usage) return "";
+  return usage.unlimited ? `${usage.plan} ∞` : `${usage.plan} ${usage.percentUsed ?? 0}%`;
+}
+
+export function formatCredits(value: number | undefined): string {
+  return value === undefined ? "—" : value.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+
+export function formatUsageSummary(usage: CopilotUsage): [string, string, string, string] {
+  const percent = usage.percentUsed ?? 0;
+  const quota = usage.unlimited
+    ? `${usage.unit}: unlimited`
+    : `${usage.unit} (resets monthly): ${formatCredits(usage.used)} / ${formatCredits(usage.limit)} (${percent}% used)`;
+  const reset = usage.resetAt
+    ? `Resets: ${new Date(usage.resetAt).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" })} UTC`
+    : "Resets monthly";
+  return ["Copilot usage and plan", `Plan: ${usage.plan}`, quota, reset];
+}
+
+export function getUsageProgress(usage: CopilotUsage): number | undefined {
+  return usage.unlimited ? undefined : (usage.percentUsed ?? 0);
+}

package/src/events.ts

@@ -0,0 +1,2 @@
+export const COPILOT_USAGE_STATUS_KEY = "pi-usage";
+export const OPEN_COPILOT_USAGE_EVENT = "pi-footer:open-copilot-usage";

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./copilot-usage.ts";