@openlines/opl-pi-sht 0.2.9 → 0.2.10

package/README.md

@@ -15,6 +15,8 @@
 A portable collection of various Pi coding agent extensions. Repository directories and config files use `opl-`; established Pi-facing commands and tool names stay compatible.
 
 >
+> ### v0.2.10 - Codex subscription usage in opl-footer
+> - `opl-footer` added ChatGPT Codex subs 5-hour/weekly quota segment with reset countdowns and stale-snapshot fallback.
 > ### v0.2.9 - pi dependencies patch, updated test scripts
 > - `devDependencies` updated to `>=0.87.0`, conforming to latest pi release `v0.99.x`; TUI and tests updates
 > ### v0.2.8 - SSRF and tool-safety hardening
@@ -92,7 +94,7 @@ Copy mode overwrites matching destinations. Link mode skips existing destination
 | [`opl-questionnaire`](extensions/opl-questionnaire/README.md) | Interactive structured-choice tool.                                                                                                                                                                                          | `questionnaire`; no config.                                                                                    |
 | [`opl-input`](extensions/opl-input/README.md)                 | Configurable replacement editor - enhanced [pikit chat-input](https://github.com/adrianapan/pikit) (because pet is life, and configurable). ![pet](images/ss-input-pet.png)                                                                                   | No commands/tools;`opl-input.json`.                                                                            |
 | [`opl-modes`](extensions/opl-modes/README.md)                 | Mode, plan, tool-safety, lazy-tool-loading, and active-appearance manager - highly-modified, configrable and enhanced mode-switcher.                                                                                         | `/mode`, `/chat`, `/plan`, `/execute`, `plan_complete`, `load_tools`; `opl-modes.json`.                        |
-| [`opl-footer`](extensions/opl-footer/README.md)               | Configurable multi-row status footer - highly-specialized, and enhanced [pikit footer](https://github.com/adrianapan/pikit).                                                                                                  | `/configure-opl`; `opl-footer.json`.                                                                           |
+| [`opl-footer`](extensions/opl-footer/README.md)               | Configurable multi-row status footer - highly-specialized, and enhanced [pikit footer](https://github.com/adrianapan/pikit).                                      | `/configure-opl`; `opl-footer.json`.                                                                           |
 
 ## What you'll gain
 
@@ -137,7 +139,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 
 ### See what the agent is doing
 
-- **`opl-footer`** surfaces model, cost, token and cache activity, git state, agent status, and per-turn timing in a configurable multi-row footer; `/configure-opl` edits and reorders its layout interactively.
+- **`opl-footer`** surfaces model, cost, token and cache activity, git state, agent status, per-turn timing, and an optional exact remaining ChatGPT Codex 5-hour/weekly subscription-quota segment with reset countdowns and stale-snapshot fallback; `/configure-opl` edits and reorders its layout interactively.
 - **`opl-input`** is a configurable editor that reflects the active mode's identity, so you always know which mode you are typing into.
 ![input-footer](images/ss-input-footer.png)
 

package/configs/opl-footer.json.sample

@@ -1,5 +1,5 @@
 {
-  "_comment": "Available segment IDs: pi, model, path, git, thinking, caveman, plan_mode, chat_mode, mode_switcher, separator, token_in, token_out, token_total, cache_read, cache_write, cost, context_pct, context_total, session_stats, perf_stats, status, text:<literal>",
+  "_comment": "Available segment IDs: pi, model, path, git, thinking, caveman, plan_mode, chat_mode, mode_switcher, separator, token_in, token_out, token_total, cache_read, cache_write, cost, context_pct, context_total, session_stats, perf_stats, status, codex_usage, text:<literal>. codex_usage is hidden by default; add it to any row to show ChatGPT Codex subscription windows.",
   "row1LeftSegments": [
     "pi",
     "separator",

package/extensions/opl-footer/README.md

@@ -31,6 +31,7 @@ The third row is populated after the first completed turn. Its session and perfo
 - **Context bar**: configurable gradient bar with percentage and context-window size
 - **Git integration**: branch plus staged, unstaged, and untracked counts, with invalidation after relevant file and Git commands
 - **Token and cost tracking**: total, cache, input/output, and accumulated cost segments
+- **Codex subscription quota**: optional exact 5-hour and weekly ChatGPT Codex usage percentages with reset countdowns and stale-snapshot fallback
 - **Session statistics**: prompt, API-call, and model tool-call counts
 - **Performance statistics**: cumulative LLM/tool duration, most recent user-prompt-to-completion turnaround time, average time to first token, output rate, and cache-hit percentage
 - **Thinking, mode, and status indicators**: thinking-level colors plus caveman, plan, chat, unified mode, and `Working`/`Waiting`/`Ready` status segments
@@ -91,9 +92,16 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 | `session_stats` | Prompt, API-call, and tool-call counts | Hidden until the first prompt |
 | `perf_stats` | LLM/tool timing, TTFT, output rate, and cache-hit percentage | Hidden until the first prompt |
 | `status` | `Working`, `Waiting`, or `Ready` | `accent`, `warning`, and `success` theme colors respectively; optional and hidden by default |
+| `codex_usage` | `5h 76% ↻2h18m · W 37% ↻3d7h` | Exact remaining ChatGPT Codex subscription quota; OAuth-only, optional and hidden by default; a retained snapshot is marked `(stale)` after refresh failure |
 | `separator` | `\|` divider | Coloured via `separator` in `colors` |
 | `text:...` | Literal text, e.g. `text:⚡` | — |
 
+## Codex Subscription Usage
+
+Add `codex_usage` to any row through `/configure-opl` or `opl-footer.json`. While the active model is the OAuth-authenticated `openai-codex` provider, the footer asks Pi's model registry to resolve the same short-lived OAuth access token that Pi uses for the selected model, then sends `GET https://chatgpt.com/backend-api/wham/usage` directly from the local Pi process. The request carries `Authorization: Bearer <Pi OAuth token>`, `Accept: application/json`, a fixed `User-Agent: opl-footer-codex-usage`, and the token's `chatgpt_account_id` JWT claim as `chatgpt-account-id` when present. It runs after session start, model selection, and settled agent turns, with a 30-second refresh floor and a 15-second request timeout. It classifies the returned windows by duration rather than response order. This is ChatGPT subscription quota, not OpenAI Platform API-key usage or billing.
+
+No OAuth token, account ID, or response body is written to disk, logged, added to the Pi session, or sent anywhere other than `chatgpt.com` for that request. **The footer retains only the parsed 5-hour/weekly percentage and reset time in process memory for the active session.** The endpoint is an internal ChatGPT backend API and can change without notice. A failed refresh keeps the most recent exact snapshot and marks it `(stale)`; if no request has ever succeeded, the segment stays hidden. Disabling the segment prevents future requests and discards any result from a request already in flight.
+
 ## Context Bar
 
 The `context_pct` segment's bar is fully configurable via `segmentOptions.contextBar`:

package/extensions/opl-footer/codex-usage.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const FIVE_HOURS_SECONDS = 5 * 60 * 60;
+const WEEK_SECONDS = 7 * 24 * 60 * 60;
+const WINDOW_TOLERANCE_SECONDS = 120;
+const REQUEST_TIMEOUT_MS = 15_000;
+const OPENAI_AUTH_CLAIM = "https://api.openai.com/auth";
+
+export interface CodexUsageWindow {
+  usedPercent: number;
+  windowSeconds: number;
+  resetAt?: number;
+}
+
+export interface CodexUsageSnapshot {
+  fiveHour?: CodexUsageWindow;
+  weekly?: CodexUsageWindow;
+  fetchedAt: number;
+  stale: boolean;
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+type UsageRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UsageRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as UsageRecord
+    : null;
+}
+
+function normalizeWindow(value: unknown): CodexUsageWindow | null {
+  const record = asRecord(value);
+  if (!record) return null;
+
+  const usedPercent = record.used_percent;
+  const windowSeconds = record.limit_window_seconds;
+  const resetAt = record.reset_at;
+  if (
+    typeof usedPercent !== "number" || !Number.isFinite(usedPercent) ||
+    typeof windowSeconds !== "number" || !Number.isFinite(windowSeconds) || windowSeconds <= 0
+  ) return null;
+
+  return {
+    usedPercent,
+    windowSeconds,
+    ...(typeof resetAt === "number" && Number.isFinite(resetAt) ? { resetAt } : {}),
+  };
+}
+
+function matchesWindow(window: CodexUsageWindow, seconds: number): boolean {
+  return Math.abs(window.windowSeconds - seconds) <= WINDOW_TOLERANCE_SECONDS;
+}
+
+export function parseCodexUsage(data: unknown, fetchedAt = Date.now()): CodexUsageSnapshot | null {
+  const root = asRecord(data);
+  const rateLimit = asRecord(root?.rate_limit);
+  const windows = [
+    normalizeWindow(rateLimit?.primary_window),
+    normalizeWindow(rateLimit?.secondary_window),
+  ].filter((window): window is CodexUsageWindow => window !== null);
+
+  const fiveHour = windows.find((window) => matchesWindow(window, FIVE_HOURS_SECONDS));
+  const weekly = windows.find((window) => matchesWindow(window, WEEK_SECONDS));
+  if (!fiveHour && !weekly) return null;
+
+  return { fiveHour, weekly, fetchedAt, stale: false };
+}
+
+function accountIdFromToken(token: string): string | undefined {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return undefined;
+    const claims = asRecord(JSON.parse(Buffer.from(payload, "base64url").toString("utf8")));
+    const auth = asRecord(claims?.[OPENAI_AUTH_CLAIM]);
+    return typeof auth?.chatgpt_account_id === "string" ? auth.chatgpt_account_id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function fetchCodexUsage(
+  ctx: ExtensionContext,
+  fetchFn: FetchLike = globalThis.fetch,
+  fetchedAt = Date.now(),
+): Promise<CodexUsageSnapshot> {
+  const model = ctx.model;
+  if (!model || model.provider !== "openai-codex" || !ctx.modelRegistry.isUsingOAuth(model)) {
+    throw new Error("Codex usage requires an openai-codex OAuth subscription model");
+  }
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) throw new Error("OpenAI Codex OAuth authentication is unavailable");
+
+  const accountId = accountIdFromToken(auth.apiKey);
+  const response = await fetchFn(USAGE_URL, {
+    headers: {
+      Authorization: `Bearer ${auth.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": "opl-footer-codex-usage",
+      ...(accountId ? { "chatgpt-account-id": accountId } : {}),
+    },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`Codex usage request failed (${response.status})`);
+
+  const snapshot = parseCodexUsage(await response.json(), fetchedAt);
+  if (!snapshot) throw new Error("Codex usage response contained no supported windows");
+  return snapshot;
+}
+
+export async function refreshCodexUsageSnapshot(
+  previous: CodexUsageSnapshot | null,
+  load: () => Promise<CodexUsageSnapshot>,
+): Promise<CodexUsageSnapshot | null> {
+  try {
+    return await load();
+  } catch {
+    return previous ? { ...previous, stale: true } : null;
+  }
+}

package/extensions/opl-footer/config.ts

@@ -27,7 +27,7 @@ export const CONFIGURABLE_SEGMENTS: StatusLineSegmentId[] = [
   "pi", "model", "path", "git", "thinking", "caveman", "plan_mode",
   "chat_mode", "mode_switcher", "token_in", "token_out", "token_total",
   "cache_read", "cache_write", "cost", "context_pct", "context_total",
-  "session_stats", "perf_stats", "status",
+  "session_stats", "perf_stats", "status", "codex_usage",
 ];
 
 const DEFAULT_LAYOUTS: Record<FooterLayoutKey, StatusLineSegmentId[]> = {

package/extensions/opl-footer/index.ts

@@ -12,6 +12,7 @@ import { getEffectiveConfig } from "./config.js";
 import { getIcons } from "./icons.js";
 import { getDefaultColors, fg } from "./theme.js";
 import { showFooterConfigurator } from "./configure.js";
+import { fetchCodexUsage, refreshCodexUsageSnapshot, type CodexUsageSnapshot } from "./codex-usage.js";
 
 const GIT_BRANCH_PATTERNS: RegExp[] = [
   // init/clone included: creating a repo mid-session must clear the not-a-repo back-off.
@@ -19,8 +20,10 @@ const GIT_BRANCH_PATTERNS: RegExp[] = [
   /\bgit\s+stash\s+(pop|apply)/,
 ];
 
-/** Row keys whose configured segments decide whether git must be probed at all. */
-const GIT_LAYOUT_ROWS = [
+/** Row keys used to detect whether an optional segment is enabled. */
+const CODEX_USAGE_REFRESH_MS = 30_000;
+
+const LAYOUT_ROWS = [
   "row1LeftSegments",
   "row1RightSegments",
   "row2LeftSegments",
@@ -116,6 +119,52 @@ export default function footer(pi: ExtensionAPI) {
   let lastBranchLength = 0;
   let cachedUsageStats: UsageStats | null = null;
   let tuiRef: TUI | null = null;
+  let codexUsage: CodexUsageSnapshot | null = null;
+  let codexUsageLastAttempt = 0;
+  let codexUsageGeneration = 0;
+  let codexUsageInFlight: Promise<void> | null = null;
+
+  const refreshCodexUsage = (ctx: ExtensionContext, force = false): Promise<void> => {
+    const model = ctx.model;
+    const isCodexSubscription = model?.provider === "openai-codex" && ctx.modelRegistry.isUsingOAuth(model);
+    if (!isCodexSubscription) {
+      codexUsageGeneration++;
+      codexUsageInFlight = null;
+      codexUsage = null;
+      tuiRef?.requestRender();
+      return Promise.resolve();
+    }
+
+    const config = getEffectiveConfig();
+    const enabled = LAYOUT_ROWS.some((row) => config[row]?.includes("codex_usage"));
+    if (!enabled) {
+      codexUsageGeneration++;
+      codexUsageInFlight = null;
+      codexUsage = null;
+      codexUsageLastAttempt = 0;
+      tuiRef?.requestRender();
+      return Promise.resolve();
+    }
+    if (codexUsageInFlight) return codexUsageInFlight;
+
+    const now = Date.now();
+    if (!force && now - codexUsageLastAttempt < CODEX_USAGE_REFRESH_MS) return Promise.resolve();
+    codexUsageLastAttempt = now;
+    const generation = ++codexUsageGeneration;
+
+    let request: Promise<void>;
+    request = refreshCodexUsageSnapshot(codexUsage, () => fetchCodexUsage(ctx))
+      .then((snapshot) => {
+        if (generation !== codexUsageGeneration) return;
+        codexUsage = snapshot;
+        tuiRef?.requestRender();
+      })
+      .finally(() => {
+        if (codexUsageInFlight === request) codexUsageInFlight = null;
+      });
+    codexUsageInFlight = request;
+    return request;
+  };
 
   // Session stats accumulators (timing only; counts are reconstructed from the branch)
   let llmMs = 0;
@@ -132,7 +181,10 @@ export default function footer(pi: ExtensionAPI) {
   pi.registerCommand("configure-opl", {
     description: "Interactively configure the OPL footer layout",
     handler: async (_args, ctx) => {
-      await showFooterConfigurator(ctx, () => tuiRef?.requestRender());
+      await showFooterConfigurator(ctx, () => {
+        tuiRef?.requestRender();
+        void refreshCodexUsage(ctx, true);
+      });
     },
   });
 
@@ -142,6 +194,10 @@ export default function footer(pi: ExtensionAPI) {
     currentCtx = ctx;
     lastBranchLength = 0;
     cachedUsageStats = null;
+    codexUsage = null;
+    codexUsageLastAttempt = 0;
+    codexUsageGeneration++;
+    codexUsageInFlight = null;
     llmMs = 0;
     toolMs = 0;
     ttftSamples = [];
@@ -155,9 +211,14 @@ export default function footer(pi: ExtensionAPI) {
 
     if (ctx.hasUI) {
       setupFooter(ctx);
+      void refreshCodexUsage(ctx, true);
     }
   });
 
+  pi.on("model_select", async (_event: unknown, ctx: ExtensionContext) => {
+    void refreshCodexUsage(ctx, true);
+  });
+
   // Track user-prompt-to-completion turnaround. agent_start may fire multiple
   // times per user turn (retries/compaction); only the first since the last
   // settle marks when the user's prompt began processing. agent_settled is the
@@ -175,6 +236,7 @@ export default function footer(pi: ExtensionAPI) {
     }
     statusTracker.agentSettled();
     tuiRef?.requestRender();
+    void refreshCodexUsage(_ctx);
   });
 
   pi.on("turn_start", async (_event: unknown, _ctx: ExtensionContext) => {
@@ -292,7 +354,7 @@ export default function footer(pi: ExtensionAPI) {
 
     // Get git status (cached). Skip the probes entirely when no visible row renders the
     // git segment — otherwise an unused cell keeps spawning git once per second.
-    const usesGit = GIT_LAYOUT_ROWS.some((row) => effectiveConfig[row]?.includes("git"));
+    const usesGit = LAYOUT_ROWS.some((row) => effectiveConfig[row]?.includes("git"));
     const gitBranch = usesGit ? footerDataRef?.getGitBranch() ?? null : null;
     const gitStatus = usesGit
       ? getGitStatus(gitBranch)
@@ -339,6 +401,7 @@ export default function footer(pi: ExtensionAPI) {
       icons: getIcons(effectiveConfig.icons),
       sessionStats: { prompts: branchPrompts, apiCalls: branchApiCalls, toolCalls: branchToolCalls, llmMs, toolMs, ttftSamples, lastTurnaroundMs },
       agentStatus: statusTracker.status(),
+      codexUsage,
     };
   }
 

package/extensions/opl-footer/segments/codex-usage.ts

@@ -0,0 +1,45 @@
+import type { RenderedSegment, SegmentContext } from "../types.js";
+import { applyColor } from "../theme.js";
+
+function formatPercent(value: number): string {
+  const clamped = Math.max(0, Math.min(100, value));
+  return Number.isInteger(clamped) ? String(clamped) : clamped.toFixed(1);
+}
+
+function formatReset(resetAt: number | undefined, nowMs: number): string {
+  if (resetAt === undefined) return "";
+  const resetMs = resetAt > 10_000_000_000 ? resetAt : resetAt * 1000;
+  const remainingMinutes = Math.max(0, Math.floor((resetMs - nowMs) / 60_000));
+  if (remainingMinutes === 0) return "now";
+
+  const days = Math.floor(remainingMinutes / (24 * 60));
+  const hours = Math.floor((remainingMinutes % (24 * 60)) / 60);
+  if (days > 0) return `${days}d${hours}h`;
+
+  const minutes = remainingMinutes % 60;
+  if (hours > 0) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+
+export const codexUsageSegment = {
+  id: "codex_usage" as const,
+  render(ctx: SegmentContext): RenderedSegment {
+    const snapshot = ctx.codexUsage;
+    if (!snapshot) return { content: "", visible: false };
+
+    const nowMs = ctx.now ?? Date.now();
+    const parts: string[] = [];
+    if (snapshot.fiveHour) {
+      const reset = formatReset(snapshot.fiveHour.resetAt, nowMs);
+      parts.push(`5h ${formatPercent(100 - snapshot.fiveHour.usedPercent)}% ${reset ? `↻${reset}` : ""}`);
+    }
+    if (snapshot.weekly) {
+      const reset = formatReset(snapshot.weekly.resetAt, nowMs);
+      parts.push(`W ${formatPercent(100 - snapshot.weekly.usedPercent)}% ${reset ? `↻${reset}` : ""}`);
+    }
+    if (parts.length === 0) return { content: "", visible: false };
+
+    const stale = snapshot.stale ? applyColor(ctx.theme, "dim", " (stale)") : "";
+    return { content: parts.join(applyColor(ctx.theme, "dim", " · ")) + stale, visible: true };
+  },
+};

package/extensions/opl-footer/segments/index.ts

@@ -14,6 +14,7 @@ import { chatModeSegment } from "./chat-mode.js";
 import { modeSwitcherSegment } from "./mode-switcher.js";
 import { sessionStatsSegment, perfStatsSegment } from "./session-stats.js";
 import { statusSegment } from "./status.js";
+import { codexUsageSegment } from "./codex-usage.js";
 
 const SEGMENTS = {
   pi: piSegment,
@@ -37,6 +38,7 @@ const SEGMENTS = {
   session_stats: sessionStatsSegment,
   perf_stats: perfStatsSegment,
   status: statusSegment,
+  codex_usage: codexUsageSegment,
 };
 
 export function renderSegment(id: StatusLineSegmentId, ctx: SegmentContext): RenderedSegment {

package/extensions/opl-footer/types.ts

@@ -1,5 +1,6 @@
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { IconSet } from "./icons.js";
+import type { CodexUsageSnapshot } from "./codex-usage.js";
 
 // Theme color - either a pi theme color name or a custom hex color
 export type ColorValue = ThemeColor | `#${string}`;
@@ -54,6 +55,7 @@ export type StatusLineSegmentId =
   | "session_stats"
   | "perf_stats"
   | "status"
+  | "codex_usage"
   | "separator"
   | `text:${string}`;
 
@@ -131,6 +133,8 @@ export interface SegmentContext {
   icons: IconSet;
   sessionStats: SessionStats;
   agentStatus: AgentStatus;
+  codexUsage: CodexUsageSnapshot | null;
+  now?: number;
 }
 
 // Minimal event shapes used by the opl-footer handlers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, tool and session safety, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
   "scripts": {
     "test": "node tests/test-summary.mjs",
     "test:opl-browser": "bun test tests/opl-browser-helpers.test.mjs && OPL_EXTENSION=opl-browser bun test tests/extension-smoke.test.mjs",
-    "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
+    "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs tests/opl-footer-lifecycle.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
     "test:opl-guardian": "bun test tests/opl-guardian.test.mjs && OPL_EXTENSION=opl-guardian bun test tests/extension-smoke.test.mjs",
     "test:opl-init": "bun test tests/opl-init-crawl.test.mjs tests/opl-init-fingerprint.test.mjs tests/opl-init-packet.test.mjs && OPL_EXTENSION=opl-init bun test tests/extension-smoke.test.mjs",
     "test:opl-input": "bun test tests/opl-input-style.test.mjs && OPL_EXTENSION=opl-input bun test tests/extension-smoke.test.mjs",