pi-openai-usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,196 @@
+# pi-openai-usage
+
+Shows your remaining OpenAI Codex subscription usage in Pi.
+
+```text
+Usage: 5h ████████░░ 88% | 7d ███████░░░ 73% | 5h ↺ 42m | 7d ↺ 2d4h
+```
+
+## Prerequisites
+
+- [Pi](https://github.com/earendil-works/pi) CLI.
+- An OpenAI subscription.
+
+## Install
+
+```bash
+pi install git:github.com/studioarray/pi-openai-usage
+```
+
+## Login
+
+This extension uses Pi's existing OpenAI Codex login. If you have not logged in yet, run:
+
+```text
+/login openai-codex
+```
+
+## Command
+
+`/openai-usage-settings` is the command for OpenAI usage and settings.
+
+Run it with no arguments in Pi's interactive UI to open the settings menu. In non-UI runs, it shows a read-only fallback with the available utility subcommands.
+
+```text
+/openai-usage-settings
+/openai-usage-settings usage
+/openai-usage-settings refresh
+/openai-usage-settings diagnostics
+/openai-usage-settings help
+```
+
+### Utility subcommands
+
+Use utility subcommands when you want a direct status check, refresh, diagnostics, or help:
+
+| Subcommand | What it does |
+| --- | --- |
+| `usage` | Show cached usage, refreshing first if the cache is missing or stale. |
+| `refresh` | Force a usage refresh and show the updated usage status. |
+| `diagnostics` | Show setup, auth, config-path, timestamp, and last-error diagnostics without printing tokens. |
+| `help` | Show command help for the one-command workflow. |
+
+Example form: `/openai-usage-settings usage`.
+
+### Interactive settings menu
+
+Running `/openai-usage-settings` with no arguments opens a ten-row menu for common settings:
+
+| Row | Visible values |
+| --- | --- |
+| Display | `On`, `Off`, `Always` |
+| Color scheme | `traffic`, `cyan`, `green`, `mono`, `none` |
+| Bar style | `blocks`, `thin`, `ascii`, `dots`, `squares`, `braille` |
+| Bar width | `4`, `6`, `8`, `10`, `12`, `16`, `20` |
+| 5h display | `hidden`, `percent`, `bar`, `bar + percent` |
+| 7d display | `hidden`, `percent`, `bar`, `bar + percent` |
+| 5h reset display | `hidden`, `countdown`, `clock`, `both` |
+| 7d reset display | `hidden`, `countdown`, `clock`, `both` |
+| Refresh interval | `15s`, `30s`, `1m`, `2m`, `5m`, `10m` |
+| Hide label | `No`, `Yes` |
+
+`Display` controls whether the status line is shown normally, hidden, or always shown. Normal display appears for OAuth-backed `openai` and `openai-codex` models; `Always` shows usage regardless of the selected model. `Hide label` controls the `Usage:` prefix. If a JSON config uses a custom color scheme or custom bar style, the menu may show `custom (JSON)` as the current value; selecting a preset replaces it with that preset.
+
+## Configuration files
+
+Configuration is read from:
+
+1. Project config: `.pi/extensions/pi-openai-usage.json`
+2. Global config: `~/.pi/agent/extensions/pi-openai-usage.json`
+
+Project config overrides global config.
+
+The interactive menu writes to the project config only when `.pi/extensions/pi-openai-usage.json` already exists. Otherwise, menu changes are written to the global config. Create the project config file first if you want menu changes to stay project-local.
+
+Use the interactive menu for common display settings. Advanced visual customization is JSON-file-only: edit the project or global config file for custom label text, widget labels, separators, partial bars, custom bar glyphs, custom color stops or targets, and bar-gradient controls. Slash-command setting writes are not supported.
+
+## JSON configuration reference
+
+### Top-level settings
+
+| Key | Type | Default | Accepted values / notes |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | Enables or hides the status-line entry. |
+| `refreshIntervalMs` | number | `60000` | `15000`, `30000`, `60000`, `120000`, `300000`, `600000`. |
+| `display` | object | see below | Status-line label and visibility presentation. |
+| `widgets` | object | see below | Usage and reset widgets. |
+| `bar` | object | see below | Progress-bar style and width. |
+| `colors` | object | see below | Color scheme, target, gradients, and custom stops. |
+
+### `display`
+
+| Key | Type | Default | Accepted values / notes |
+| --- | --- | --- | --- |
+| `display.showAlways` | boolean | `false` | `true` shows usage even when the selected model is not an OAuth-backed OpenAI/Codex model. |
+| `display.showLabel` | boolean | `true` | Controls the label prefix. |
+| `display.label` | string | `"Usage"` | Non-empty string. |
+| `display.separator` | string | `" | "` | Separator between visible widgets. |
+
+### `widgets`
+
+| Key | Type | Default | Accepted values / notes |
+| --- | --- | --- | --- |
+| `widgets.fiveHour.enabled` | boolean | `true` | Shows or hides the 5h usage widget. |
+| `widgets.fiveHour.label` | string | `"5h"` | Non-empty string. |
+| `widgets.fiveHour.mode` | string | `"bar-percent"` | `percent`, `bar`, `bar-percent`, `hidden`. |
+| `widgets.sevenDay.enabled` | boolean | `true` | Shows or hides the 7d usage widget. |
+| `widgets.sevenDay.label` | string | `"7d"` | Non-empty string. |
+| `widgets.sevenDay.mode` | string | `"bar-percent"` | `percent`, `bar`, `bar-percent`, `hidden`. |
+| `widgets.fiveHourReset.enabled` | boolean | `true` | Shows or hides the 5h reset widget. |
+| `widgets.fiveHourReset.label` | string | `"5h ↺"` | Non-empty string. |
+| `widgets.fiveHourReset.mode` | string | `"countdown"` | `countdown`, `clock`, `both`, `hidden`. |
+| `widgets.sevenDayReset.enabled` | boolean | `true` | Shows or hides the 7d reset widget. |
+| `widgets.sevenDayReset.label` | string | `"7d ↺"` | Non-empty string. |
+| `widgets.sevenDayReset.mode` | string | `"countdown"` | `countdown`, `clock`, `both`, `hidden`. |
+
+### `bar`
+
+| Key | Type | Default | Accepted values / notes |
+| --- | --- | --- | --- |
+| `bar.style` | string | `"blocks"` | `blocks`, `thin`, `ascii`, `dots`, `squares`, `braille`, `custom`. |
+| `bar.width` | number | `10` | `4`, `6`, `8`, `10`, `12`, `16`, `20`. |
+| `bar.partials` | boolean | `true` | Uses partial glyphs when the selected style supports them. |
+| `bar.custom.filled` | string | `"▰"` | Filled glyph used when `bar.style` is `custom`. |
+| `bar.custom.empty` | string | `"▱"` | Empty glyph used when `bar.style` is `custom`. |
+| `bar.custom.partials` | string[] | `[]` | Optional partial glyphs used when `bar.style` is `custom` and `bar.partials` is `true`. |
+
+### `colors`
+
+| Key | Type | Default | Accepted values / notes |
+| --- | --- | --- | --- |
+| `colors.scheme` | string | `"traffic"` | `traffic`, `cyan`, `green`, `mono`, `none`, `custom`. |
+| `colors.target` | string | `"value"` | `value`, `widget`, `bar`, `percent`, `none`. |
+| `colors.barGradient.enabled` | boolean | `false` | Colors filled bar cells across the selected color scale. |
+| `colors.barGradient.direction` | string | `"low-to-high"` | `low-to-high`, `high-to-low`. |
+| `colors.custom.mode` | string | `"step"` | `step`, `gradient`. |
+| `colors.custom.stops` | array | see below | Array of color stops sorted by `percent`. |
+
+Default `colors.custom.stops`:
+
+| percent | color | label |
+| --- | --- | --- |
+| `80` | `success` | `success` |
+| `60` | `#65a30d` | `lime/olive` |
+| `40` | `warning` | `warning` |
+| `20` | `#c2410c` | `orange` |
+| `0` | `error` | `error` |
+
+Each custom color stop has this shape:
+
+| Key | Type | Accepted values / notes |
+| --- | --- | --- |
+| `percent` | number | Clamped to `0` through `100`. |
+| `color` | string or number | Pi theme token (`success`, `warning`, `error`, `muted`, `dim`, `text`, `accent`) for `step` mode, `#RRGGBB`, or xterm color number `0` through `255`. Gradient mode supports interpolating `#RRGGBB` and xterm colors. |
+| `label` | string | Optional label for your own reference. |
+
+## Display customization
+
+The default display uses progress bars and percentages:
+
+```text
+Usage: 5h ████████░░ 88% | 7d ███████░░░ 73% | 5h ↺ 42m | 7d ↺ 2d4h
+```
+
+To simplify it in the interactive menu, set:
+
+- Hide label: `Yes`
+- 5h display: `percent`
+- 7d display: `percent`
+- 5h reset display: `hidden`
+- 7d reset display: `hidden`
+
+Result:
+
+```text
+5h: 88% | 7d: 73%
+```
+
+To use the neutral footer text colour instead of usage-coloured values, set Color scheme to `none`.
+
+## Privacy and auth
+
+The extension uses Pi's existing `openai-codex` OAuth credentials to request Codex usage from ChatGPT's usage endpoint. Diagnostics are designed for troubleshooting and do not print access tokens.
+
+## Reference attribution
+
+Inspired by [pi-better-openai](https://github.com/mattleong/pi-better-openai/).

package/index.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerOpenAIUsageSettingsCommand } from "./src/usage-settings";
+import {
+  createUsageRefreshCoordinator,
+  type UsageRefreshCoordinator,
+} from "./src/usage-refresh-coordinator";
+import { createUsageStateStore } from "./src/usage-state";
+import { fetchCodexUsage, type UsageClientPort } from "./src/usage-client";
+import { registerUsageStatusController } from "./src/status-controller";
+
+export default function piOpenAIUsage(pi: ExtensionAPI): void {
+  const usageClient: UsageClientPort = { fetchUsage: fetchCodexUsage };
+  const usageState = createUsageStateStore();
+  const usageRefreshCoordinator: UsageRefreshCoordinator = createUsageRefreshCoordinator({
+    usageClient,
+    usageState,
+  });
+
+  const statusController = registerUsageStatusController(pi, {
+    usageClient,
+    usageState,
+    usageRefreshCoordinator,
+  });
+  if (typeof (pi as { registerCommand?: unknown }).registerCommand === "function") {
+    registerOpenAIUsageSettingsCommand(pi, {
+      usageState,
+      usageRefreshCoordinator,
+      reapplyStatusLine: (ctx) => statusController.reapply(ctx),
+    });
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-openai-usage",
+  "version": "0.1.0",
+  "description": "Focused Pi extension package for showing OpenAI Codex subscription usage in the status line.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "codex",
+    "usage"
+  ],
+  "main": "index.ts",
+  "types": "index.ts",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "index.ts",
+    "src"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,303 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CODEX_PROVIDER_ID = "openai-codex";
+
+export type CodexCredentialSource = "registry" | "auth_file";
+export type CodexCredentialErrorCode = "missing_credentials" | "missing_account_id";
+
+export type CodexOAuthCredentials = {
+  accessToken: string;
+  accountId: string;
+  source: CodexCredentialSource;
+  toJSON(): RedactedCodexCredentials;
+};
+
+export type RedactedCodexCredentials = {
+  accessToken: "<redacted>";
+  accountId: string;
+  source: CodexCredentialSource;
+};
+
+export type CodexCredentialDiagnostics = {
+  source: CodexCredentialSource | "none";
+  checkedSources: CodexCredentialSource[];
+  hasAccessToken: boolean;
+  hasAccountId: boolean;
+  accountId?: string;
+};
+
+export type CodexCredentialError = {
+  code: CodexCredentialErrorCode;
+  message: string;
+};
+
+export type CodexCredentialResolution =
+  | {
+      ok: true;
+      credentials: CodexOAuthCredentials;
+      diagnostics: CodexCredentialDiagnostics;
+      toJSON(): {
+        ok: true;
+        credentials: RedactedCodexCredentials;
+        diagnostics: CodexCredentialDiagnostics;
+      };
+    }
+  | {
+      ok: false;
+      error: CodexCredentialError;
+      diagnostics: CodexCredentialDiagnostics;
+    };
+
+export type CodexModelRegistry = {
+  getApiKeyForProvider?: (
+    provider: string,
+  ) => string | undefined | Promise<string | undefined>;
+};
+
+export type ResolveCodexOAuthCredentialsOptions = {
+  modelRegistry?: CodexModelRegistry;
+  authFilePath?: string;
+  home?: string;
+  env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;
+};
+
+export async function resolveCodexOAuthCredentials(
+  options: ResolveCodexOAuthCredentialsOptions = {},
+): Promise<CodexCredentialResolution> {
+  const checkedSources: CodexCredentialSource[] = [];
+  let bestAttempt: CredentialAttempt | undefined;
+
+  const registryAttempt = await readRegistryCredentials(options.modelRegistry);
+  checkedSources.push("registry");
+  if (registryAttempt?.credentials !== undefined) {
+    return credentialSuccess(registryAttempt.credentials, checkedSources);
+  }
+  bestAttempt = bestCredentialAttempt(bestAttempt, registryAttempt);
+
+  const authFileAttempt = readAuthFileCredentials(authFilePath(options));
+  checkedSources.push("auth_file");
+  if (authFileAttempt?.credentials !== undefined) {
+    return credentialSuccess(authFileAttempt.credentials, checkedSources);
+  }
+  bestAttempt = bestCredentialAttempt(bestAttempt, authFileAttempt);
+
+  return credentialFailure(bestAttempt, checkedSources);
+}
+
+export function authFilePath(options: ResolveCodexOAuthCredentialsOptions = {}): string {
+  if (options.authFilePath !== undefined) return options.authFilePath;
+
+  const env = options.env ?? process.env;
+  const configuredAgentDir = env.PI_CODING_AGENT_DIR?.trim();
+  const agentDir =
+    configuredAgentDir !== undefined && configuredAgentDir.length > 0
+      ? configuredAgentDir
+      : join(options.home ?? homedir(), ".pi", "agent");
+  return join(agentDir, "auth.json");
+}
+
+type CredentialMaterial = {
+  accessToken?: string;
+  accountId?: string;
+  source: CodexCredentialSource;
+};
+
+type CredentialAttempt = CredentialMaterial & {
+  credentials?: CodexOAuthCredentials;
+};
+
+async function readRegistryCredentials(
+  modelRegistry: CodexModelRegistry | undefined,
+): Promise<CredentialAttempt | undefined> {
+  if (modelRegistry?.getApiKeyForProvider === undefined) return undefined;
+
+  try {
+    const rawCredential = await modelRegistry.getApiKeyForProvider(CODEX_PROVIDER_ID);
+    if (rawCredential === undefined) return undefined;
+
+    return credentialAttempt(parseRegistryCredential(rawCredential));
+  } catch {
+    return undefined;
+  }
+}
+
+function readAuthFileCredentials(path: string): CredentialAttempt | undefined {
+  if (!existsSync(path)) return undefined;
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    const root = asRecord(parsed);
+    const entry = root === undefined ? undefined : asRecord(root[CODEX_PROVIDER_ID]);
+    if (entry?.type !== "oauth") return undefined;
+
+    return credentialAttempt({
+      accessToken: trimmedString(entry.access),
+      accountId: trimmedString(entry.accountId) ?? trimmedString(entry.account_id),
+      source: "auth_file",
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+function parseRegistryCredential(rawCredential: string): CredentialMaterial | undefined {
+  const trimmed = rawCredential.trim();
+  if (trimmed.length === 0) return undefined;
+
+  const jsonCredentials = parseRegistryJsonCredential(trimmed);
+  if (jsonCredentials !== undefined) return jsonCredentials;
+
+  return {
+    accessToken: trimmed,
+    accountId: accountIdFromJwt(trimmed),
+    source: "registry",
+  };
+}
+
+function parseRegistryJsonCredential(rawCredential: string): CredentialMaterial | undefined {
+  try {
+    const parsed = JSON.parse(rawCredential) as unknown;
+    const record = asRecord(parsed);
+    if (record === undefined) return undefined;
+
+    return {
+      accessToken: trimmedString(record.access) ?? trimmedString(record.token),
+      accountId: trimmedString(record.accountId) ?? trimmedString(record.account_id),
+      source: "registry",
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function accountIdFromJwt(token: string): string | undefined {
+  const payloadSegment = token.split(".")[1];
+  if (payloadSegment === undefined) return undefined;
+
+  try {
+    const payload = JSON.parse(
+      Buffer.from(toBase64(payloadSegment), "base64").toString("utf8"),
+    ) as unknown;
+    const payloadRecord = asRecord(payload);
+    const authRecord = asRecord(payloadRecord?.["https://api.openai.com/auth"]);
+    return trimmedString(authRecord?.chatgpt_account_id);
+  } catch {
+    return undefined;
+  }
+}
+
+function toBase64(base64Url: string): string {
+  const base64 = base64Url.replaceAll("-", "+").replaceAll("_", "/");
+  const paddingLength = (4 - (base64.length % 4)) % 4;
+  return `${base64}${"=".repeat(paddingLength)}`;
+}
+
+function credentialAttempt(material: CredentialMaterial | undefined): CredentialAttempt | undefined {
+  if (material === undefined) return undefined;
+
+  const attempt: CredentialAttempt = { ...material };
+  const credentials = credentialsFromParts(material);
+  if (credentials !== undefined) attempt.credentials = credentials;
+  return attempt;
+}
+
+function credentialsFromParts(parts: CredentialMaterial): CodexOAuthCredentials | undefined {
+  if (parts.accessToken === undefined || parts.accountId === undefined) return undefined;
+
+  const accessToken = parts.accessToken;
+  const accountId = parts.accountId;
+  const source = parts.source;
+
+  return {
+    accessToken,
+    accountId,
+    source,
+    toJSON() {
+      return {
+        accessToken: "<redacted>",
+        accountId: redactAccountId(accountId),
+        source,
+      };
+    },
+  };
+}
+
+function bestCredentialAttempt(
+  current: CredentialAttempt | undefined,
+  next: CredentialAttempt | undefined,
+): CredentialAttempt | undefined {
+  if (next === undefined) return current;
+  if (current === undefined) return next;
+  if (next.accessToken !== undefined && current.accessToken === undefined) return next;
+  return current;
+}
+
+function credentialFailure(
+  bestAttempt: CredentialAttempt | undefined,
+  checkedSources: CodexCredentialSource[],
+): CodexCredentialResolution {
+  const hasAccessToken = bestAttempt?.accessToken !== undefined;
+  const hasAccountId = bestAttempt?.accountId !== undefined;
+  const code: CodexCredentialErrorCode =
+    hasAccessToken && !hasAccountId ? "missing_account_id" : "missing_credentials";
+
+  return {
+    ok: false,
+    error: {
+      code,
+      message:
+        code === "missing_account_id"
+          ? "Missing openai-codex Account ID. Run /login openai-codex."
+          : "Missing openai-codex OAuth credentials. Run /login openai-codex.",
+    },
+    diagnostics: {
+      source: bestAttempt?.source ?? "none",
+      checkedSources,
+      hasAccessToken,
+      hasAccountId,
+      ...(bestAttempt?.accountId === undefined
+        ? {}
+        : { accountId: redactAccountId(bestAttempt.accountId) }),
+    },
+  };
+}
+
+function credentialSuccess(
+  credentials: CodexOAuthCredentials,
+  checkedSources: CodexCredentialSource[],
+): CodexCredentialResolution {
+  const diagnostics: CodexCredentialDiagnostics = {
+    source: credentials.source,
+    checkedSources,
+    hasAccessToken: true,
+    hasAccountId: true,
+    accountId: redactAccountId(credentials.accountId),
+  };
+
+  return {
+    ok: true,
+    credentials,
+    diagnostics,
+    toJSON() {
+      return { ok: true, credentials: credentials.toJSON(), diagnostics };
+    },
+  };
+}
+
+function redactAccountId(accountId: string): string {
+  if (accountId.length <= 4) return "<redacted>";
+  return `…${accountId.slice(-4)}`;
+}
+
+function trimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}