pi-credits 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026—PRESENT Zilong Liang
+
+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

@@ -0,0 +1,30 @@
+# pi-credits
+
+A [pi](https://pi.dev/) extension that shows the active model provider's credit balance or rate-limit usage as a footer status.
+
+- The status appears only while a supported provider is active and uses that provider's stored credential or API key.
+- The status refreshes on session start, model switch, and after each turn that incurs usage.
+
+## Supported providers
+
+- **OpenAI Codex:** rate-limit usage of the 5-hour and weekly windows, as used percentages.
+- **OpenRouter:** remaining credit balance in dollars.
+- **Vercel AI Gateway:** remaining credit balance in dollars.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-credits
+```
+
+Install from git:
+
+```bash
+pi install git:github.com/zlliang/pi-credits
+```
+
+## Other pi packages
+
+- [pi-spark](https://github.com/zlliang/pi-spark): a small, opinionated collection of pi extensions.

package/index.ts

@@ -0,0 +1,47 @@
+import { CreditsManager } from "./src/manager";
+import { isUsage } from "./src/utils";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+function hasCost(message: AgentMessage): boolean {
+  const usage = (message as { usage?: unknown }).usage;
+  if (!isUsage(usage)) return false;
+
+  return usage.cost.total > 0 || usage.input > 0 || usage.output > 0;
+}
+
+export default function (pi: ExtensionAPI) {
+  let creditsManager: CreditsManager | undefined = undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    creditsManager = new CreditsManager();
+    creditsManager.refresh(ctx);
+  });
+
+  pi.on("model_select", (_event, ctx) => {
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    if (!hasCost(event.message)) return;
+
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_compact", (_event, ctx) => {
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_tree", (event, ctx) => {
+    if (!event.summaryEntry) return;
+
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_shutdown", () => {
+    creditsManager = undefined;
+  });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pi-credits",
+  "version": "0.1.0",
+  "description": "A pi extension that shows the active provider's credit balance or rate-limit usage",
+  "keywords": [
+    "pi-coding-agent",
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zlliang/pi-credits.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/zlliang/pi-credits/main/assets/cover.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "*",
+    "typebox": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/manager.ts

@@ -0,0 +1,56 @@
+import { findProvider } from "./providers";
+import { renderCredits, renderError } from "./status";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CreditsProvider } from "./types";
+
+const STATUS_KEY = "credits";
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export class CreditsManager {
+  private inflight: AbortController | undefined = undefined;
+
+  async refresh(ctx: ExtensionContext): Promise<void> {
+    this.inflight?.abort();
+
+    const provider = findProvider(ctx.model?.provider);
+    if (!provider) {
+      this.inflight = undefined;
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    const controller = new AbortController();
+    this.inflight = controller;
+
+    await this.fetch(ctx, provider, controller.signal).finally(() => {
+      if (this.inflight === controller) this.inflight = undefined;
+    });
+  }
+
+  private async fetch(ctx: ExtensionContext, provider: CreditsProvider, signal: AbortSignal): Promise<void> {
+    try {
+      const apiKey = await ctx.modelRegistry.getApiKeyForProvider(provider.provider);
+      if (!apiKey) {
+        ctx.ui.setStatus(STATUS_KEY, undefined);
+        return;
+      }
+
+      const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), signal];
+      if (ctx.signal) signals.push(ctx.signal);
+
+      const credits = await provider.fetch(ctx, apiKey, AbortSignal.any(signals));
+
+      // The active model may have changed while the request was in flight.
+      if (ctx.model?.provider !== provider.provider) return;
+
+      ctx.ui.setStatus(STATUS_KEY, renderCredits(ctx.ui.theme, provider.label, credits));
+    } catch (error) {
+      if (signal.aborted || ctx.signal?.aborted) return;
+      if (ctx.model?.provider !== provider.provider) return;
+
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.setStatus(STATUS_KEY, renderError(ctx.ui.theme, provider.label, message));
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,15 @@
+import { openaiCodexProvider } from "./openai-codex";
+import { openrouterProvider } from "./openrouter";
+import { vercelAiGatewayProvider } from "./vercel-ai-gateway";
+
+import type { CreditsProvider } from "../types";
+
+const PROVIDERS: CreditsProvider[] = [
+  openaiCodexProvider,
+  openrouterProvider,
+  vercelAiGatewayProvider,
+];
+
+export function findProvider(provider?: string): CreditsProvider | undefined {
+  return PROVIDERS.find((entry) => entry.provider === provider);
+}

package/src/providers/openai-codex.ts

@@ -0,0 +1,62 @@
+import { toNumber } from "../utils";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Credits, CreditsProvider } from "../types";
+
+const PROVIDER = "openai-codex";
+const URL = "https://chatgpt.com/backend-api/wham/usage";
+
+interface CodexUsageResponse {
+  rate_limit?: {
+    primary_window?: CodexRateWindow | null;
+    secondary_window?: CodexRateWindow | null;
+  } | null;
+  credits?: {
+    unlimited?: boolean;
+  } | null;
+}
+
+interface CodexRateWindow {
+  used_percent?: number | string;
+}
+
+export function getAccountId(ctx: ExtensionContext): string | undefined {
+  const credential = ctx.modelRegistry.authStorage.get(PROVIDER) as { accountId?: string } | undefined;
+  const accountId = credential?.accountId;
+
+  return typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
+}
+
+function parseUsedPercent(window?: CodexRateWindow | null): number | undefined {
+  const value = toNumber(window?.used_percent);
+  return typeof value === "number" ? Math.min(100, Math.max(0, value)) : undefined;
+}
+
+export const openaiCodexProvider: CreditsProvider = {
+  provider: PROVIDER,
+  label: "Codex",
+
+  async fetch(ctx, apiKey, signal): Promise<Credits> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    };
+
+    const accountId = getAccountId(ctx);
+    if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+
+    const response = await fetch(URL, { headers, signal });
+    if (!response.ok) throw new Error("request failed");
+
+    const payload = (await response.json()) as CodexUsageResponse;
+
+    return {
+      type: "windows",
+      unlimited: payload.credits?.unlimited === true,
+      lanes: [
+        { label: "5h", percent: parseUsedPercent(payload.rate_limit?.primary_window) },
+        { label: "7d", percent: parseUsedPercent(payload.rate_limit?.secondary_window) },
+      ],
+    };
+  },
+};

package/src/providers/openrouter.ts

@@ -0,0 +1,35 @@
+import { toNumber } from "../utils";
+
+import type { Credits, CreditsProvider } from "../types";
+
+const PROVIDER = "openrouter";
+const URL = "https://openrouter.ai/api/v1/credits";
+
+interface OpenRouterCreditsResponse {
+  data?: {
+    total_credits?: number | null;
+    total_usage?: number | null;
+  } | null;
+}
+
+export const openrouterProvider: CreditsProvider = {
+  provider: PROVIDER,
+  label: "OpenRouter",
+
+  async fetch(_ctx, apiKey, signal): Promise<Credits> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    };
+
+    const response = await fetch(URL, { headers, signal });
+    if (!response.ok) throw new Error("request failed");
+
+    const payload = (await response.json()) as OpenRouterCreditsResponse;
+    const totalCredits = toNumber(payload.data?.total_credits);
+    const totalUsage = toNumber(payload.data?.total_usage);
+    const remaining = typeof totalCredits === "number" && typeof totalUsage === "number" ? totalCredits - totalUsage : undefined;
+
+    return { type: "balance", remaining };
+  },
+};

package/src/providers/vercel-ai-gateway.ts

@@ -0,0 +1,30 @@
+import { toNumber } from "../utils";
+
+import type { Credits, CreditsProvider } from "../types";
+
+const PROVIDER = "vercel-ai-gateway";
+const URL = "https://ai-gateway.vercel.sh/v1/credits";
+
+interface VercelCreditsResponse {
+  balance?: string | number;
+}
+
+export const vercelAiGatewayProvider: CreditsProvider = {
+  provider: PROVIDER,
+  label: "Vercel",
+
+  async fetch(_ctx, apiKey, signal): Promise<Credits> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    };
+
+    const response = await fetch(URL, { headers, signal });
+    if (!response.ok) throw new Error("request failed");
+
+    const payload = (await response.json()) as VercelCreditsResponse;
+    const remaining = toNumber(payload.balance);
+
+    return { type: "balance", remaining };
+  },
+};

package/src/status.ts

@@ -0,0 +1,43 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Credits, CreditsLane } from "./types";
+
+const WINDOWS_WARNING = 70;
+const WINDOWS_ERROR = 90;
+const BALANCE_WARNING = 10;
+const BALANCE_ERROR = 5;
+
+export function renderCredits(theme: Theme, label: string, credits: Credits): string {
+  const styledLabel = theme.fg("dim", label);
+
+  if (credits.type === "windows") return `${styledLabel} ${renderWindows(theme, credits)}`;
+  return `${styledLabel} ${renderBalance(theme, credits)}`;
+}
+
+export function renderError(theme: Theme, label: string, message: string): string {
+  return theme.fg("error", `${label} credits unavailable: ${message}`);
+}
+
+function renderWindows(theme: Theme, credits: Extract<Credits, { type: "windows" }>): string {
+  const unlimited = credits.unlimited || credits.lanes.every((lane) => lane.percent === undefined);
+  if (unlimited) return theme.fg("success", "unlimited");
+
+  return credits.lanes.map((lane) => renderLane(theme, lane)).join(" ");
+}
+
+function renderLane(theme: Theme, lane: CreditsLane): string {
+  const text = `${lane.label} ${lane.percent === undefined ? "?" : lane.percent.toFixed(0)}%`;
+
+  if (lane.percent && lane.percent > WINDOWS_ERROR) return theme.fg("error", text);
+  if (lane.percent && lane.percent > WINDOWS_WARNING) return theme.fg("warning", text);
+  return theme.fg("success", text);
+}
+
+function renderBalance(theme: Theme, credits: Extract<Credits, { type: "balance" }>): string {
+  if (credits.remaining === undefined) return theme.fg("dim", "$?");
+
+  const text = `$${credits.remaining.toFixed(2)}`;
+
+  if (credits.remaining < BALANCE_ERROR) return theme.fg("error", text);
+  if (credits.remaining < BALANCE_WARNING) return theme.fg("warning", text);
+  return theme.fg("success", text);
+}

package/src/types.ts

@@ -0,0 +1,24 @@
+import type { Provider } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Normalized credits/usage for a provider.
+ *
+ * - `balance` providers (e.g., OpenRouter, Vercel AI Gateway) report a remaining dollar balance.
+ * - `windows` providers (e.g., OpenAI Codex) report rate-limit windows as used percentages.
+ */
+export type Credits =
+  | { type: "balance"; remaining?: number | undefined }
+  | { type: "windows"; lanes: CreditsLane[]; unlimited?: boolean | undefined };
+
+export interface CreditsLane {
+  label: string;
+  percent: number | undefined;
+}
+
+/** A credits source for a pi provider, shown in the status line while that provider is active. */
+export interface CreditsProvider {
+  readonly provider: Provider;
+  readonly label: string;
+  fetch(ctx: ExtensionContext, apiKey: string, signal: AbortSignal): Promise<Credits>;
+}

package/src/utils.ts

@@ -0,0 +1,31 @@
+import type { Usage } from "@earendil-works/pi-ai";
+
+/** Structural type guard for the pi `Usage` shape. */
+export function isUsage(value: unknown): value is Usage {
+  if (typeof value !== "object" || value === null) return false;
+
+  const usage = value as Record<string, unknown>;
+  const hasTokenFields =
+    typeof usage.input === "number" &&
+    typeof usage.output === "number" &&
+    typeof usage.cacheRead === "number" &&
+    typeof usage.cacheWrite === "number" &&
+    typeof usage.totalTokens === "number";
+  if (!hasTokenFields) return false;
+
+  if (typeof usage.cost !== "object" || usage.cost === null) return false;
+  const cost = usage.cost as Record<string, unknown>;
+  return (
+    typeof cost.input === "number" &&
+    typeof cost.output === "number" &&
+    typeof cost.cacheRead === "number" &&
+    typeof cost.cacheWrite === "number" &&
+    typeof cost.total === "number"
+  );
+}
+
+export function toNumber(value?: string | number | null): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}