@marcosgilf/pi-usage 0.0.0-stage → 0.1.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,63 @@
-# 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.
+[![npm](https://img.shields.io/npm/v/@marcosgilf/pi-usage)](https://www.npmjs.com/package/@marcosgilf/pi-usage) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+Show GitHub Copilot plan and quota usage in Pi.
+
+## ✨ Features
+
+- Show Copilot plan and usage beside Pi's model in the footer.
+- Open a quota modal by clicking the footer usage in fullscreen mode, running `/copilot-usage`, or pressing `super+shift+u`.
+- Refresh modal data with `r` and copy a plain-text summary with `c`.
+- Hide the progress bar for unlimited plans.
+
+## 📦 Install
+
+Install the published package:
+
+```sh
+pi install npm:@marcosgilf/pi-usage
+```
+
+For one-run testing, use `pi -e npm:@marcosgilf/pi-usage`. To load a local checkout, run `npm install` in the monorepo, then `pi -e ./packages/pi-usage`.
+
+Pi extensions run with Pi's operating-system permissions. Review package source before installing.
+
+## 🚀 Quick start
+
+Install `gh`, sign in to GitHub, and grant the `user` OAuth scope if needed:
+
+```sh
+gh auth refresh -h github.com -s user
+```
+
+Start Pi. The footer shows the plan and quota percentage. Run `/copilot-usage` for the modal.
+
+## 💬 Commands
+
+- `/copilot-usage` opens the modal and refreshes account quota.
+- `super+shift+u` opens the same modal.
+- In the modal, `r` refreshes data and `c` copies plain text. Esc or Enter closes it.
+
+The quota request uses GitHub's undocumented `copilot_internal/user` endpoint through `gh`. GitHub may change this endpoint.
+
+## 🚧 Limitations
+
+- Footer mouse clicks work in Pi fullscreen mode. Use the command or shortcut in regular mode.
+- Terminal mouse selection copies the rendered modal layout. Press `c` to copy plain text.
+- Clipboard copy uses macOS `pbcopy`.
+
+## 🗂️ Package layout
+
+- `src/index.ts` is the Pi extension entrypoint.
+- `src/copilot-usage.ts` registers commands, footer, and modal behavior.
+- `src/core.ts` parses and formats Copilot quota and session data.
+- `test/` contains Vitest tests.
+
+## 🔎 Keywords
+
+`pi-package`, `pi-extension`, `github-copilot`, `usage`, `quota`
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@marcosgilf/pi-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "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,332 @@
+import { execFile } from "node:child_process";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type TuiMouseEvent, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  type CopilotUsage,
+  formatPlanUsage,
+  formatProgressBar,
+  formatTokens,
+  formatUsageSummary,
+  getUsageProgress,
+  parseCopilotUsage,
+  summarizeSession,
+  writeClipboard,
+} from "./core.ts";
+
+const CACHE_MS = 5 * 60 * 1000;
+const FOOTER_STATUS_KEY = "copilot-usage";
+
+type UsageSnapshot = CopilotUsage & { fetchedAt: number };
+type FooterRow = { text: string; style?: "accent" | "success" | "warning"; progress?: number };
+
+let cachedUsage: UsageSnapshot | undefined;
+let lastError: string | undefined;
+let lastAttempt = 0;
+let pending: Promise<UsageSnapshot> | undefined;
+let requestFooterRender: (() => void) | 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;
+      requestFooterRender?.();
+      return cachedUsage;
+    })
+    .catch((error: unknown) => {
+      lastError = error instanceof Error ? error.message : String(error);
+      requestFooterRender?.();
+      throw new Error(lastError);
+    })
+    .finally(() => {
+      pending = undefined;
+    });
+  return pending;
+}
+
+function addCustomFooter(ctx: ExtensionContext): void {
+  ctx.ui.setFooter((tui, theme, footerData) => {
+    let disposed = false;
+    const requestRender = () => {
+      if (!disposed) tui.requestRender();
+    };
+    const unsubscribe = footerData.onBranchChange(requestRender);
+    requestFooterRender = requestRender;
+    let statsCache: { leafId: string | null; stats: ReturnType<typeof summarizeSession> } | undefined;
+    let usageClickBounds: { left: number; right: number } | undefined;
+    const getStats = () => {
+      const leafId = ctx.sessionManager.getLeafId();
+      if (statsCache?.leafId === leafId) return statsCache.stats;
+      const stats = summarizeSession(ctx.sessionManager.getEntries());
+      statsCache = { leafId, stats };
+      return stats;
+    };
+
+    return {
+      dispose() {
+        disposed = true;
+        unsubscribe();
+        if (requestFooterRender === requestRender) requestFooterRender = undefined;
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (
+          event.button !== "left" ||
+          event.y !== 1 ||
+          !usageClickBounds ||
+          event.x < usageClickBounds.left ||
+          event.x >= usageClickBounds.right
+        )
+          return;
+        if (event.type === "click") void showUsage(ctx);
+        if (event.type === "press" || event.type === "release" || event.type === "click") {
+          return { handled: true, render: event.type === "click" };
+        }
+      },
+      invalidate() {},
+      render(width: number) {
+        const stats = getStats();
+        const context = ctx.getContextUsage();
+        const leftParts: string[] = [];
+        const input = stats.input + stats.cacheRead + stats.cacheWrite;
+        if (input) leftParts.push(`↑${formatTokens(input)}`);
+        if (stats.output) leftParts.push(`↓${formatTokens(stats.output)}`);
+        if (stats.cacheRead) leftParts.push(`R${formatTokens(stats.cacheRead)}`);
+        if (stats.cacheWrite) leftParts.push(`W${formatTokens(stats.cacheWrite)}`);
+        if (stats.cost) leftParts.push(`$${stats.cost.toFixed(3)}`);
+        if (context) {
+          const percent = context.percent === null ? "?" : `${context.percent.toFixed(1)}%`;
+          leftParts.push(`${percent}/${formatTokens(context.contextWindow)}`);
+        }
+        let left = theme.fg("dim", leftParts.join(" "));
+
+        const model = ctx.model;
+        const modelName = model?.name || model?.id || "no-model";
+        const thinking = model?.reasoning ? ` • ${ctx.thinkingLevel || "off"}` : "";
+        let modelText = `${modelName}${thinking}`;
+        if (footerData.getAvailableProviderCount() > 1 && model) modelText = `(${model.provider}) ${modelText}`;
+        const usageText = formatPlanUsage(cachedUsage);
+        const usageStyle =
+          cachedUsage?.percentUsed !== undefined && cachedUsage.percentUsed >= 90 ? "warning" : "accent";
+        const usageLabel = usageText ? theme.fg(usageStyle, usageText) : "";
+        const right = usageLabel ? `${usageLabel} · ${modelText}` : modelText;
+
+        const clippedRight = truncateToWidth(right, width, "");
+        const clippedRightWidth = visibleWidth(clippedRight);
+        const usageLabelWidth = visibleWidth(usageLabel);
+        usageClickBounds =
+          usageLabelWidth > 0
+            ? {
+                left: width - clippedRightWidth,
+                right: width - clippedRightWidth + Math.min(usageLabelWidth, clippedRightWidth),
+              }
+            : undefined;
+        const leftWidth = Math.max(0, width - clippedRightWidth - 2);
+        left = leftWidth > 0 ? truncateToWidth(left, leftWidth, "...") : "";
+        const padding = " ".repeat(Math.max(0, width - visibleWidth(left) - clippedRightWidth));
+        const statsLine = `${left}${padding}${clippedRight}`;
+
+        const home = process.env.HOME || "";
+        let cwd = home && ctx.cwd.startsWith(`${home}/`) ? `~${ctx.cwd.slice(home.length)}` : ctx.cwd;
+        const branch = footerData.getGitBranch();
+        if (branch) cwd += ` (${branch})`;
+        const sessionName = ctx.sessionManager.getSessionName();
+        if (sessionName) cwd += ` • ${sessionName}`;
+        const lines = [truncateToWidth(theme.fg("dim", cwd), width, theme.fg("dim", "...")), statsLine];
+        const statuses = Array.from(footerData.getExtensionStatuses().entries())
+          .filter(([key]) => key !== FOOTER_STATUS_KEY)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([, text]) => text);
+        if (statuses.length) lines.push(truncateToWidth(statuses.join(" "), width, theme.fg("dim", "...")));
+        return lines;
+      },
+    };
+  });
+}
+
+function copyToClipboard(text: string): Promise<void> {
+  if (process.platform !== "darwin") return Promise.reject(new Error("Clipboard copy requires macOS."));
+  return writeClipboard(text);
+}
+
+function borderedRows(rows: FooterRow[], width: number, theme: Theme): string[] {
+  if (width < 6)
+    return rows.map(({ text, progress }) =>
+      truncateToWidth(progress === undefined ? text : formatProgressBar(progress, width), width, "…"),
+    );
+  const contentWidth = width - 4;
+  const edge = theme.fg("muted", "│");
+  const top = theme.fg("muted", `╭${"─".repeat(contentWidth + 2)}╮`);
+  const bottom = theme.fg("muted", `╰${"─".repeat(contentWidth + 2)}╯`);
+  const content = rows.map(({ text, style, progress }) => {
+    const value = progress === undefined ? text : formatProgressBar(progress, contentWidth);
+    const styled = style === "accent" ? theme.fg(style, theme.bold(value)) : style ? theme.fg(style, value) : value;
+    const clipped = truncateToWidth(styled, contentWidth, "…");
+    const padding = " ".repeat(Math.max(0, contentWidth - visibleWidth(clipped)));
+    return `${edge}${theme.bg("selectedBg", ` ${clipped}${padding} `)}${edge}`;
+  });
+  return [top, ...content, bottom];
+}
+
+function modalOverlayRows(rows: FooterRow[], width: number, height: number, theme: Theme): string[] {
+  const panelWidth = Math.min(width, 74);
+  const panel = borderedRows(rows, panelWidth, theme);
+  const left = Math.floor((width - panelWidth) / 2);
+  const top = Math.max(0, Math.floor((height - panel.length) / 2));
+  const screen = Array.from({ length: height }, () => " ".repeat(width));
+  panel.forEach((line, index) => {
+    const row = top + index;
+    if (row < height)
+      screen[row] = `${" ".repeat(left)}${line}${" ".repeat(Math.max(0, width - left - visibleWidth(line)))}`;
+  });
+  return screen;
+}
+
+function buildUsageModal(usage: CopilotUsage): { rows: FooterRow[]; clipboardText: string } {
+  const [title, planText, quotaText, resetText] = formatUsageSummary(usage);
+  const progress = getUsageProgress(usage);
+  const rows: FooterRow[] = [
+    { 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 }, { text: "" }, { text: "r refreshes · c copies plain text · Esc/Enter closes" });
+  return { rows, clipboardText: [title, planText, quotaText, resetText].join("\n") };
+}
+
+async function showUsage(ctx: ExtensionContext): Promise<void> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("/copilot-usage requires Pi TUI mode.", "warning");
+    return;
+  }
+
+  try {
+    let content = buildUsageModal(await refreshUsage(true));
+    await ctx.ui.custom(
+      (tui, theme, keybindings, done) => ({
+        render(width: number) {
+          // Mask transcript rows beneath overlay; TUI selection copies rendered screen cells.
+          return modalOverlayRows(content.rows, width, tui.terminal.rows, theme);
+        },
+        invalidate() {},
+        handleInput(data: string) {
+          if (keybindings.matches(data, "app.interrupt") || keybindings.matches(data, "tui.input.submit")) {
+            done(undefined);
+            return;
+          }
+          const key = data.toLowerCase();
+          if (key === "r") {
+            content.rows[content.rows.length - 1] = { text: "Refreshing usage…" };
+            tui.requestRender();
+            void refreshUsage(true)
+              .then((usage) => {
+                content = buildUsageModal(usage);
+                tui.requestRender();
+              })
+              .catch((error: unknown) => {
+                const message = error instanceof Error ? error.message : String(error);
+                content.rows[content.rows.length - 1] = { text: `Refresh failed: ${message}`, style: "warning" };
+                tui.requestRender();
+              });
+            return;
+          }
+          if (key === "c") {
+            void copyToClipboard(content.clipboardText)
+              .then(() => {
+                content.rows[content.rows.length - 1] = { text: "Copied plain text", style: "success" };
+                tui.requestRender();
+              })
+              .catch((error: unknown) => {
+                const message = error instanceof Error ? error.message : String(error);
+                content.rows[content.rows.length - 1] = { text: `Copy failed: ${message}`, style: "warning" };
+                tui.requestRender();
+              });
+            return;
+          }
+          tui.requestRender();
+        },
+      }),
+      {
+        overlay: true,
+        overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+      },
+    );
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+  }
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    ctx.ui.setStatus(FOOTER_STATUS_KEY, undefined);
+    addCustomFooter(ctx);
+    void refreshUsage().catch(() => {});
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    if (ctx.mode === "tui") void refreshUsage().catch(() => {});
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.mode === "tui") {
+      ctx.ui.setStatus(FOOTER_STATUS_KEY, undefined);
+      ctx.ui.setFooter(undefined);
+      requestFooterRender = undefined;
+    }
+  });
+
+  pi.registerCommand("copilot-usage", {
+    description: "Show GitHub Copilot plan and quota usage",
+    handler: (_args, ctx) => showUsage(ctx),
+  });
+
+  pi.registerShortcut("super+shift+u", {
+    description: "Show GitHub Copilot AI-credit usage",
+    handler: (ctx) => showUsage(ctx),
+  });
+}

package/src/core.ts

@@ -0,0 +1,182 @@
+import { execFile } from "node:child_process";
+
+type Usage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+};
+
+type UsageEntry = {
+  type?: string;
+  provider?: string;
+  usage?: Usage;
+  message?: { role?: string; provider?: string; usage?: Usage };
+};
+
+export type CopilotUsage = {
+  plan: string;
+  unit: "AI credits" | "premium requests";
+  used?: number;
+  limit?: number;
+  remaining?: number;
+  percentUsed?: number;
+  resetAt?: string;
+  unlimited: boolean;
+};
+
+export type SessionUsage = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+};
+
+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 formatTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 1_000) return `${(tokens / 1_000).toFixed(1)}K`;
+  return Math.round(tokens).toLocaleString("en-US");
+}
+
+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);
+}
+
+export function writeClipboard(text: string, command = "pbcopy"): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, (error) => (error ? reject(error) : resolve()));
+    child.stdin?.on("error", reject);
+    child.stdin?.end(text);
+  });
+}
+
+export function formatProgressBar(percent: number, width: number): string {
+  const cells = Math.max(0, Math.floor(width));
+  const value = Number.isFinite(percent) ? Math.min(100, Math.max(0, percent)) : 0;
+  const filled = Math.round((value / 100) * cells);
+  return `${"█".repeat(filled)}${"░".repeat(cells - filled)}`;
+}
+
+export function summarizeSession(entries: readonly unknown[], provider?: string): SessionUsage {
+  const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  const add = (usage?: Usage) => {
+    if (!usage) return;
+    for (const key of ["input", "output", "cacheRead", "cacheWrite"] as const) {
+      const value = usage[key];
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) total[key] += value;
+    }
+    const cost = usage.cost?.total;
+    if (typeof cost === "number" && Number.isFinite(cost) && cost > 0) total.cost += cost;
+  };
+
+  for (const rawEntry of entries) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as UsageEntry;
+    if (
+      entry.type === "message" &&
+      entry.message?.role === "assistant" &&
+      (!provider || entry.message.provider === provider)
+    ) {
+      add(entry.message.usage);
+    } else if (entry.type === "usage" && (!provider || entry.provider === provider)) {
+      add(entry.usage);
+    }
+  }
+  return total;
+}

package/src/index.ts

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