@firstpick/pi-package-webui 0.1.8 → 0.1.9

package/README.md

@@ -66,30 +66,18 @@ pi-webui --cwd /path/to/project
 
 ## Features
 
-- Browser chat with Pi over RPC
-- Isolated terminal tabs: each Web UI tab starts its own separate `pi --mode rpc` subprocess, event stream, session state, and prompt draft
-- Automatic tab naming from the first prompt on default-named tabs, plus `/name <title>` to manually sync the Pi session and browser tab name
-- Per-tab activity indicators for idle, working, blocked, and completed unseen work, with browser notifications when a tab needs an extension UI response and an optional side-panel toggle for agent-done notifications
-- Live assistant text streaming, including streamed thinking blocks when exposed by the provider
-- Prompt, steer, follow-up, abort, new session, and manual compact controls
-- Attachment button plus drag/drop and clipboard paste for images, documents, video, audio, and other files; uploaded files are saved to a server temp path and supported images are also sent through Pi RPC image attachments
-- Busy-session behavior selector for follow-up vs steer
-- Model and thinking-level controls
-- Browser-native selector dialogs for native slash commands such as `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, and `/tree`; `/login`/`/logout` currently show non-secret guidance rather than accepting credentials in the browser
-- Slash-command autocomplete while typing `/...`
-- `@` file/path references with live suggestions from the active tab cwd
-- Tool, process, compaction, queue, and extension event log
-- Collapsible side panel with independently collapsible sections for controls, optional features, session state, queue, available commands, events, local-network exposure status/control, and a theme picker
-- Pi-style footer with token, cache, estimated Pi-context tokens, speed, cost, context usage, clickable per-tab cwd picker with server-persisted fast picks, git branch, changes, runtime, model, and thinking level
-- Guided Git workflow: `git add .`, ask Pi to run `/git-staged-msg`, preview short/long messages, commit with the selected message, and `git push`
-- Hover-expand Publish workflow menu beside Git workflow, currently offering NPM Release and AUR Release
-- Basic rendering for user, assistant, tool result, bash execution, and thinking messages
-- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, with queued post-run submission that asks Pi to create/update a LEARNING
-- Basic extension UI bridge for `notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`, `select`, `confirm`, `input`, and `editor`
-- Specialized `/release-npm` and `/release-aur` widget rendering with scrollable live logs plus toggle/abort actions
-- Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded
-- PWA metadata, icons, and service worker for install-to-home-screen support when served from a secure context
-- Static frontend: no bundler, no frontend install step
+- Local browser chat over Pi RPC with isolated terminal tabs; each tab has its own `pi --mode rpc` subprocess, event stream, session state, prompt draft, cwd, and activity indicator.
+- Automatic tab naming from the first prompt on default-named tabs, plus `/name <title>` to manually sync the Pi session and browser tab name.
+- Live transcript with streamed assistant text/thinking, Markdown output, active-run status, tool/bash cards, queue/compaction events, jump-to-latest, sticky last-prompt navigation, and abort by button, Esc, or long press.
+- Prompt composer for prompts, steer/follow-up, busy-session behavior, model/thinking controls, manual compact/new session, uploads by button/drag/drop/paste, slash-command autocomplete, and `@` file/path references with live suggestions.
+- Browser-native selector dialogs for `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, `/tree`, and `/scoped-models`; `/login`/`/logout` show non-secret guidance instead of accepting credentials in the browser.
+- Session/workspace helpers for per-tab cwd changes, a clickable footer cwd picker with server-persisted fast picks, fork/clone/resume/tree navigation, and restart-safe restoration of currently open tabs.
+- Collapsible side-panel control deck for model/thinking/settings, optional features, Codex usage, session/queue/commands/events, local-network exposure, browser notifications, and Web UI themes/custom backgrounds.
+- Pi-style footer with token/cache/context/cost/speed telemetry, estimated Pi-context tokens, cwd/git/runtime/model/thinking metadata, and a scoped-model picker.
+- Optional companion management with capability-based enabled/disabled/install-needed status, localhost-only warned installs, Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded, guided Git commit/push workflow, NPM/AUR Publish menu, todo-progress rendering, and richer git/status/stats widgets.
+- Extension UI bridge for `notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`, `select`, `confirm`, `input`, and `editor`, with browser notifications when a tab needs an extension UI response and an optional side-panel toggle for agent-done notifications.
+- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, with queued post-run submission that asks Pi to create/update a LEARNING.
+- Mobile/PWA support: installable app shell, service worker/icons, backend-offline recovery panel, touch-friendly composer/tabs/footer, and a static frontend with no bundler or frontend install step.
 
 ## Mobile/PWA notes
 

package/bin/pi-webui.mjs

@@ -8,7 +8,7 @@ import { homedir, networkInterfaces, tmpdir } from "node:os";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, SessionManager } from "@earendil-works/pi-coding-agent";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -19,6 +19,10 @@ const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.js
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 31415;
 const REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
+const CODEX_USAGE_TIMEOUT_MS = 15 * 1000;
+const CODEX_TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1000;
+const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+const OPENAI_CODEX_USAGE_ENDPOINT = process.env.PI_WEBUI_CODEX_USAGE_URL || "https://chatgpt.com/backend-api/wham/usage";
 const BODY_LIMIT_BYTES = 1024 * 1024;
 const PROMPT_BODY_LIMIT_BYTES = 24 * 1024 * 1024;
 const UPLOAD_BODY_LIMIT_BYTES = 96 * 1024 * 1024;
@@ -839,6 +843,302 @@ async function readJsonFileIfExists(filePath) {
   }
 }
 
+function firstDefined(...values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function numericValue(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function booleanValue(value) {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function isoTimestamp(value) {
+  const number = numericValue(value);
+  if (number !== undefined) {
+    const milliseconds = number > 1e12 ? number : number * 1000;
+    const date = new Date(milliseconds);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+  }
+  return undefined;
+}
+
+function decodeJwtPayload(token) {
+  try {
+    const payload = String(token || "").split(".")[1];
+    if (!payload) return null;
+    const padded = `${payload}${"=".repeat((4 - (payload.length % 4)) % 4)}`;
+    return JSON.parse(Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function codexAccountIdFromAccessToken(accessToken) {
+  const payload = decodeJwtPayload(accessToken);
+  const auth = payload?.["https://api.openai.com/auth"];
+  const accountId = auth?.chatgpt_account_id;
+  return typeof accountId === "string" && accountId ? accountId : null;
+}
+
+function normalizeCodexRateLimitWindow(rawWindow) {
+  if (!rawWindow || typeof rawWindow !== "object") return null;
+  const windowDurationSeconds = firstDefined(
+    numericValue(rawWindow.windowDurationSeconds),
+    numericValue(rawWindow.limitWindowSeconds),
+    numericValue(rawWindow.limit_window_seconds),
+    numericValue(rawWindow.windowDurationMins) !== undefined ? numericValue(rawWindow.windowDurationMins) * 60 : undefined,
+  );
+  const windowDurationMins = firstDefined(
+    numericValue(rawWindow.windowDurationMins),
+    windowDurationSeconds !== undefined ? windowDurationSeconds / 60 : undefined,
+  );
+  const normalized = {
+    usedPercent: numericValue(firstDefined(rawWindow.usedPercent, rawWindow.used_percent)),
+    windowDurationSeconds,
+    windowDurationMins,
+    resetAfterSeconds: numericValue(firstDefined(rawWindow.resetAfterSeconds, rawWindow.reset_after_seconds)),
+    resetsAt: isoTimestamp(firstDefined(rawWindow.resetsAt, rawWindow.resetAt, rawWindow.reset_at)),
+  };
+  return Object.values(normalized).some((value) => value !== undefined) ? normalized : null;
+}
+
+function normalizeCodexCredits(rawCredits) {
+  if (!rawCredits || typeof rawCredits !== "object") return null;
+  return {
+    hasCredits: booleanValue(firstDefined(rawCredits.hasCredits, rawCredits.has_credits)),
+    unlimited: booleanValue(rawCredits.unlimited),
+    balance: firstDefined(rawCredits.balance),
+    approxLocalMessages: firstDefined(rawCredits.approxLocalMessages, rawCredits.approx_local_messages),
+    approxCloudMessages: firstDefined(rawCredits.approxCloudMessages, rawCredits.approx_cloud_messages),
+  };
+}
+
+function normalizeCodexRateLimitDetails(rawDetails) {
+  if (!rawDetails || typeof rawDetails !== "object") return { primary: null, secondary: null };
+  return {
+    allowed: booleanValue(rawDetails.allowed),
+    limitReached: booleanValue(firstDefined(rawDetails.limitReached, rawDetails.limit_reached)),
+    primary: normalizeCodexRateLimitWindow(firstDefined(rawDetails.primary, rawDetails.primaryWindow, rawDetails.primary_window)),
+    secondary: normalizeCodexRateLimitWindow(firstDefined(rawDetails.secondary, rawDetails.secondaryWindow, rawDetails.secondary_window)),
+  };
+}
+
+function normalizeCodexRateLimitReachedType(rawType) {
+  if (typeof rawType === "string" && rawType) return rawType;
+  if (rawType && typeof rawType === "object") {
+    const value = firstDefined(rawType.type, rawType.kind);
+    return typeof value === "string" && value ? value : null;
+  }
+  return null;
+}
+
+function makeCodexUsageSnapshot({ limitId, limitName, rateLimit, credits, planType, rateLimitReachedType }) {
+  const details = normalizeCodexRateLimitDetails(rateLimit);
+  return {
+    limitId: limitId || null,
+    limitName: limitName || null,
+    primary: details.primary,
+    secondary: details.secondary,
+    allowed: details.allowed,
+    limitReached: details.limitReached,
+    credits: normalizeCodexCredits(credits),
+    planType: planType || null,
+    rateLimitReachedType: rateLimitReachedType || null,
+  };
+}
+
+function normalizeCodexUsagePayload(rawPayload) {
+  const payload = rawPayload && typeof rawPayload === "object" ? rawPayload : {};
+  const planType = firstDefined(payload.planType, payload.plan_type, null);
+  const rateLimitReachedType = normalizeCodexRateLimitReachedType(firstDefined(payload.rateLimitReachedType, payload.rate_limit_reached_type));
+  const snapshotsByKey = new Map();
+  const addSnapshot = (snapshot) => {
+    if (!snapshot) return;
+    const key = snapshot.limitId || snapshot.limitName || `snapshot-${snapshotsByKey.size + 1}`;
+    if (!snapshotsByKey.has(key)) snapshotsByKey.set(key, snapshot);
+  };
+
+  const directRateLimits = firstDefined(payload.rateLimits, payload.rate_limits);
+  if (directRateLimits && typeof directRateLimits === "object" && (directRateLimits.primary || directRateLimits.primary_window || directRateLimits.primaryWindow)) {
+    addSnapshot(makeCodexUsageSnapshot({
+      limitId: firstDefined(directRateLimits.limitId, directRateLimits.limit_id, "codex"),
+      limitName: firstDefined(directRateLimits.limitName, directRateLimits.limit_name),
+      rateLimit: directRateLimits,
+      credits: firstDefined(directRateLimits.credits, payload.credits),
+      planType: firstDefined(directRateLimits.planType, directRateLimits.plan_type, planType),
+      rateLimitReachedType: firstDefined(directRateLimits.rateLimitReachedType, directRateLimits.rate_limit_reached_type, rateLimitReachedType),
+    }));
+  } else {
+    addSnapshot(makeCodexUsageSnapshot({
+      limitId: "codex",
+      rateLimit: firstDefined(payload.rateLimit, payload.rate_limit),
+      credits: payload.credits,
+      planType,
+      rateLimitReachedType,
+    }));
+  }
+
+  const byLimitId = firstDefined(payload.rateLimitsByLimitId, payload.rate_limits_by_limit_id);
+  if (byLimitId && typeof byLimitId === "object" && !Array.isArray(byLimitId)) {
+    for (const [limitId, rawSnapshot] of Object.entries(byLimitId)) {
+      if (!rawSnapshot || typeof rawSnapshot !== "object") continue;
+      addSnapshot(makeCodexUsageSnapshot({
+        limitId: firstDefined(rawSnapshot.limitId, rawSnapshot.limit_id, limitId),
+        limitName: firstDefined(rawSnapshot.limitName, rawSnapshot.limit_name),
+        rateLimit: rawSnapshot,
+        credits: rawSnapshot.credits,
+        planType: firstDefined(rawSnapshot.planType, rawSnapshot.plan_type, planType),
+        rateLimitReachedType: firstDefined(rawSnapshot.rateLimitReachedType, rawSnapshot.rate_limit_reached_type),
+      }));
+    }
+  }
+
+  const additionalRateLimits = firstDefined(payload.additionalRateLimits, payload.additional_rate_limits);
+  if (Array.isArray(additionalRateLimits)) {
+    for (const item of additionalRateLimits) {
+      if (!item || typeof item !== "object") continue;
+      addSnapshot(makeCodexUsageSnapshot({
+        limitId: firstDefined(item.limitId, item.limit_id, item.meteredFeature, item.metered_feature, item.limitName, item.limit_name),
+        limitName: firstDefined(item.limitName, item.limit_name),
+        rateLimit: firstDefined(item.rateLimit, item.rate_limit),
+        credits: item.credits,
+        planType,
+      }));
+    }
+  }
+
+  const snapshots = [...snapshotsByKey.values()];
+  const selected = snapshots.find((snapshot) => snapshot.limitId === "codex") || snapshots[0] || null;
+  const rateLimitsByLimitId = Object.fromEntries(snapshots.filter((snapshot) => snapshot.limitId).map((snapshot) => [snapshot.limitId, snapshot]));
+  return {
+    planType: planType || selected?.planType || null,
+    rateLimitReachedType: rateLimitReachedType || selected?.rateLimitReachedType || null,
+    credits: normalizeCodexCredits(payload.credits) || selected?.credits || null,
+    selected,
+    snapshots,
+    rateLimits: selected,
+    rateLimitsByLimitId,
+  };
+}
+
+async function getOpenAICodexUsageCredentials({ forceRefresh = false } = {}) {
+  const authStorage = AuthStorage.create();
+  const stored = authStorage.get(OPENAI_CODEX_PROVIDER_ID);
+  const storedExpires = numericValue(stored?.expires);
+  const shouldRefresh = stored?.type === "oauth" && (forceRefresh || storedExpires === undefined || Date.now() + CODEX_TOKEN_REFRESH_SKEW_MS >= storedExpires);
+  let accessToken;
+  let refreshed = false;
+
+  if (shouldRefresh) {
+    try {
+      const refreshResult = await authStorage.refreshOAuthTokenWithLock(OPENAI_CODEX_PROVIDER_ID);
+      if (refreshResult?.apiKey) {
+        accessToken = refreshResult.apiKey;
+        refreshed = forceRefresh || refreshResult.newCredentials?.access !== stored?.access;
+      }
+    } catch (error) {
+      if (forceRefresh || !storedExpires || Date.now() >= storedExpires) {
+        throw makeHttpError(401, "OpenAI Codex OAuth token refresh failed. Run /login and choose ChatGPT Plus/Pro (Codex Subscription) to re-authenticate.");
+      }
+      console.warn(`OpenAI Codex token refresh warning: ${sanitizeError(error)}`);
+    }
+  }
+
+  if (!accessToken) {
+    accessToken = await authStorage.getApiKey(OPENAI_CODEX_PROVIDER_ID, { includeFallback: false });
+  }
+  if (!accessToken) {
+    const status = authStorage.getAuthStatus(OPENAI_CODEX_PROVIDER_ID);
+    if (status.configured) throw makeHttpError(401, "OpenAI Codex OAuth token is expired or unavailable. Run /login to refresh credentials.");
+    throw makeHttpError(401, "OpenAI Codex OAuth is not configured. Run /login and choose ChatGPT Plus/Pro (Codex Subscription).");
+  }
+
+  const latest = authStorage.get(OPENAI_CODEX_PROVIDER_ID) || stored || {};
+  const accountId = latest.accountId || codexAccountIdFromAccessToken(accessToken);
+  if (!accountId) {
+    throw makeHttpError(401, "OpenAI Codex account id is unavailable. Run /login and choose ChatGPT Plus/Pro (Codex Subscription) again.");
+  }
+
+  return {
+    accessToken,
+    accountId,
+    refreshed,
+    source: latest.type === "oauth" ? "stored-oauth" : "api-key",
+    expiresAt: numericValue(latest.expires) ? new Date(numericValue(latest.expires)).toISOString() : undefined,
+  };
+}
+
+async function fetchOpenAICodexUsagePayload(credentials) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CODEX_USAGE_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    const response = await fetch(OPENAI_CODEX_USAGE_ENDPOINT, {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${credentials.accessToken}`,
+        "chatgpt-account-id": credentials.accountId,
+        originator: "pi-webui",
+      },
+      signal: controller.signal,
+    });
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+      const error = makeHttpError(response.status === 401 ? 401 : 502, `OpenAI Codex usage request failed (${response.status}${response.statusText ? ` ${response.statusText}` : ""})`);
+      error.openaiStatus = response.status;
+      throw error;
+    }
+    try {
+      return JSON.parse(text || "{}");
+    } catch {
+      throw makeHttpError(502, "OpenAI Codex usage response was not valid JSON");
+    }
+  } catch (error) {
+    if (error?.name === "AbortError") throw makeHttpError(504, "OpenAI Codex usage request timed out");
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function getOpenAICodexUsageStatus({ forceRefresh = false } = {}) {
+  let credentials = await getOpenAICodexUsageCredentials({ forceRefresh });
+  let rawPayload;
+  try {
+    rawPayload = await fetchOpenAICodexUsagePayload(credentials);
+  } catch (error) {
+    if (error?.openaiStatus === 401 && !credentials.refreshed) {
+      credentials = await getOpenAICodexUsageCredentials({ forceRefresh: true });
+      rawPayload = await fetchOpenAICodexUsagePayload(credentials);
+    } else {
+      throw error;
+    }
+  }
+
+  return {
+    available: true,
+    providerId: OPENAI_CODEX_PROVIDER_ID,
+    source: "chatgpt.com",
+    fetchedAt: new Date().toISOString(),
+    auth: {
+      source: credentials.source,
+      expiresAt: credentials.expiresAt,
+      refreshed: credentials.refreshed,
+    },
+    ...normalizeCodexUsagePayload(rawPayload),
+  };
+}
+
 async function configuredScopedModelPatterns(cwd = options.cwd) {
   const cliPatterns = parseCliScopedModelPatterns();
   if (cliPatterns !== undefined) return { patterns: cliPatterns, source: "cli" };
@@ -2954,6 +3254,16 @@ const server = createServer(async (req, res) => {
       return;
     }
 
+    if (url.pathname === "/api/codex-usage" && req.method === "GET") {
+      try {
+        const forceRefresh = ["1", "true", "yes"].includes(String(url.searchParams.get("refresh") || "").toLowerCase());
+        sendJson(res, 200, { ok: true, data: await getOpenAICodexUsageStatus({ forceRefresh }) });
+      } catch (error) {
+        sendJson(res, error?.statusCode || 500, { ok: false, error: error?.message || "Failed to read OpenAI Codex usage" });
+      }
+      return;
+    }
+
     if (url.pathname === "/api/network" && req.method === "GET") {
       sendJson(res, 200, { ok: true, data: networkStatus() });
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-webui",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Pi Web UI companion package with a local browser UI CLI plus /webui-start and /webui-status commands.",
   "license": "MIT",
   "type": "module",

package/public/app.js

@@ -63,6 +63,8 @@ const elements = {
   agentDoneNotificationsToggle: $("#agentDoneNotificationsToggle"),
   agentDoneNotificationsStatus: $("#agentDoneNotificationsStatus"),
   optionalFeaturesBox: $("#optionalFeaturesBox"),
+  codexUsageBox: $("#codexUsageBox"),
+  refreshCodexUsageButton: $("#refreshCodexUsageButton"),
   toggleSidePanelButton: $("#toggleSidePanelButton"),
   sidePanelExpandButton: $("#sidePanelExpandButton"),
   sidePanelBackdrop: $("#sidePanelBackdrop"),
@@ -146,6 +148,11 @@ let pathSuggestAbortController = null;
 let latestStats = null;
 let latestWorkspace = null;
 let latestNetwork = null;
+let latestCodexUsage = null;
+let codexUsageError = null;
+let codexUsageLoading = false;
+let refreshCodexUsageTimer = null;
+let codexUsageRenderTimer = null;
 let backendOffline = false;
 let backendOfflineNoticeShown = false;
 let latestMessages = [];
@@ -220,6 +227,8 @@ const STICKY_USER_PROMPT_TOP_GAP_PX = 12;
 const CHAT_FOLLOW_SETTLE_DELAY_MS = 80;
 const CHAT_PROGRAMMATIC_SCROLL_GRACE_MS = 500;
 const CHAT_USER_SCROLL_INTENT_MS = 700;
+const CODEX_USAGE_REFRESH_MS = 5 * 60 * 1000;
+const CODEX_USAGE_RENDER_TICK_MS = 30 * 1000;
 const RUN_INDICATOR_TICK_MS = 1000;
 const RUN_INDICATOR_START_GRACE_MS = 2500;
 const RUN_INDICATOR_STATE_RECHECK_MS = 5000;
@@ -3584,6 +3593,197 @@ function scheduleRefreshFooter(delay = 300, tabContext = activeTabContext()) {
   }, delay);
 }
 
+function formatCodexPlanType(value) {
+  const text = String(value || "").trim();
+  if (!text) return "unknown plan";
+  return text.replace(/[_-]+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+function formatCodexPercent(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? `${Math.max(0, Math.min(100, Math.round(number)))}%` : "—";
+}
+
+function codexWindowDurationMinutes(window) {
+  const minutes = Number(window?.windowDurationMins);
+  if (Number.isFinite(minutes) && minutes > 0) return minutes;
+  const seconds = Number(window?.windowDurationSeconds);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds / 60 : null;
+}
+
+function formatCodexWindowDuration(window) {
+  const minutes = codexWindowDurationMinutes(window);
+  if (!minutes) return "window";
+  if (minutes >= 280 && minutes <= 320) return "5h window";
+  if (minutes >= 9500 && minutes <= 10550) return "weekly window";
+  if (minutes >= 60 * 24) {
+    const days = minutes / (60 * 24);
+    return `${days >= 10 ? Math.round(days) : Number(days.toFixed(1))}d window`;
+  }
+  if (minutes >= 60) {
+    const hours = minutes / 60;
+    return `${Number.isInteger(hours) ? hours : Number(hours.toFixed(1))}h window`;
+  }
+  return `${Math.round(minutes)}m window`;
+}
+
+function formatDurationParts(milliseconds) {
+  if (!Number.isFinite(Number(milliseconds))) return "now";
+  const totalMinutes = Math.max(0, Math.ceil(Number(milliseconds) / 60000));
+  if (totalMinutes <= 1) return "<1m";
+  if (totalMinutes < 60) return `${totalMinutes}m`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours < 48) return minutes ? `${hours}h ${minutes}m` : `${hours}h`;
+  const days = Math.floor(hours / 24);
+  const remHours = hours % 24;
+  return remHours ? `${days}d ${remHours}h` : `${days}d`;
+}
+
+function codexWindowResetDate(window) {
+  const resetAt = window?.resetsAt ? new Date(window.resetsAt) : null;
+  if (resetAt && Number.isFinite(resetAt.getTime())) return resetAt;
+  const resetAfterSeconds = Number(window?.resetAfterSeconds);
+  if (Number.isFinite(resetAfterSeconds) && resetAfterSeconds >= 0) return new Date(Date.now() + resetAfterSeconds * 1000);
+  return null;
+}
+
+function formatCodexReset(window) {
+  const resetDate = codexWindowResetDate(window);
+  if (!resetDate) return "reset unknown";
+  const diff = resetDate.getTime() - Date.now();
+  if (diff <= 0) return "resetting now";
+  return `resets in ${formatDurationParts(diff)}`;
+}
+
+function codexSnapshotName(snapshot) {
+  return snapshot?.limitName || snapshot?.limitId || "codex";
+}
+
+function codexUsageBuckets(data) {
+  const buckets = [];
+  const selected = data?.selected || data?.rateLimits || null;
+  const snapshots = Array.isArray(data?.snapshots) ? data.snapshots : selected ? [selected] : [];
+  const selectedKey = selected?.limitId || selected?.limitName || "codex";
+  const pushWindow = (snapshot, kind, window, { prefix } = {}) => {
+    if (!window) return;
+    const durationLabel = formatCodexWindowDuration(window);
+    const baseLabel = kind === "secondary" && durationLabel === "window" ? "secondary window" : durationLabel;
+    buckets.push({
+      key: `${snapshot?.limitId || snapshot?.limitName || buckets.length}-${kind}`,
+      label: prefix ? `${prefix} · ${baseLabel}` : baseLabel,
+      window,
+    });
+  };
+
+  if (selected) {
+    pushWindow(selected, "primary", selected.primary);
+    pushWindow(selected, "secondary", selected.secondary);
+  }
+  for (const snapshot of snapshots) {
+    const key = snapshot?.limitId || snapshot?.limitName;
+    if (!snapshot || snapshot === selected || key === selectedKey) continue;
+    const name = codexSnapshotName(snapshot);
+    pushWindow(snapshot, "primary", snapshot.primary, { prefix: name });
+    pushWindow(snapshot, "secondary", snapshot.secondary, { prefix: name });
+  }
+  return buckets.slice(0, 6);
+}
+
+function renderCodexUsage() {
+  const box = elements.codexUsageBox;
+  if (!box) return;
+  if (elements.refreshCodexUsageButton) {
+    elements.refreshCodexUsageButton.disabled = codexUsageLoading;
+    elements.refreshCodexUsageButton.textContent = codexUsageLoading ? "Refreshing…" : "Refresh usage";
+  }
+
+  box.replaceChildren();
+  box.classList.toggle("muted", !latestCodexUsage);
+
+  if (!latestCodexUsage && codexUsageLoading) {
+    box.textContent = "Checking Codex usage…";
+    return;
+  }
+  if (!latestCodexUsage && codexUsageError) {
+    const title = make("div", "codex-usage-unavailable", "Usage unavailable");
+    const detail = make("div", "codex-usage-detail", codexUsageError.message || String(codexUsageError));
+    box.append(title, detail);
+    return;
+  }
+  if (!latestCodexUsage) {
+    box.textContent = "Codex usage has not loaded yet.";
+    return;
+  }
+
+  const header = make("div", "codex-usage-summary");
+  header.append(
+    make("span", "codex-usage-plan", formatCodexPlanType(latestCodexUsage.planType)),
+    make("span", "codex-usage-fetched", latestCodexUsage.fetchedAt ? `updated ${formatDurationParts(Date.now() - new Date(latestCodexUsage.fetchedAt).getTime())} ago` : "updated now"),
+  );
+  box.append(header);
+
+  const buckets = codexUsageBuckets(latestCodexUsage);
+  if (buckets.length === 0) {
+    box.append(make("div", "codex-usage-detail", "No Codex rate-limit windows were returned."));
+  } else {
+    for (const bucket of buckets) {
+      const usedPercent = Number(bucket.window?.usedPercent);
+      const fillPercent = Number.isFinite(usedPercent) ? Math.max(0, Math.min(100, usedPercent)) : 0;
+      const item = make("div", "codex-usage-bucket");
+      const row = make("div", "codex-usage-row");
+      row.append(
+        make("span", "codex-usage-label", bucket.label),
+        make("strong", "codex-usage-percent", formatCodexPercent(bucket.window?.usedPercent)),
+      );
+      const meter = make("div", "codex-usage-meter");
+      const fill = make("span", "codex-usage-meter-fill");
+      fill.style.width = `${fillPercent}%`;
+      meter.append(fill);
+      item.append(row, meter, make("div", "codex-usage-reset", formatCodexReset(bucket.window)));
+      box.append(item);
+    }
+  }
+
+  if (latestCodexUsage.rateLimitReachedType) {
+    box.append(make("div", "codex-usage-warning", `Limit status: ${latestCodexUsage.rateLimitReachedType}`));
+  }
+  if (codexUsageError) {
+    box.append(make("div", "codex-usage-detail", `Latest refresh failed: ${codexUsageError.message || codexUsageError}`));
+  }
+}
+
+async function refreshCodexUsage({ forceAuthRefresh = false } = {}) {
+  if (codexUsageLoading) return;
+  codexUsageLoading = true;
+  renderCodexUsage();
+  try {
+    const suffix = forceAuthRefresh ? "?refresh=1" : "";
+    const response = await api(`/api/codex-usage${suffix}`, { scoped: false });
+    latestCodexUsage = response.data || null;
+    codexUsageError = null;
+  } catch (error) {
+    codexUsageError = error;
+  } finally {
+    codexUsageLoading = false;
+    renderCodexUsage();
+  }
+}
+
+function scheduleRefreshCodexUsage(delay = CODEX_USAGE_REFRESH_MS) {
+  clearTimeout(refreshCodexUsageTimer);
+  refreshCodexUsageTimer = setTimeout(() => {
+    refreshCodexUsage().finally(() => scheduleRefreshCodexUsage());
+  }, delay);
+}
+
+function initializeCodexUsage() {
+  renderCodexUsage();
+  refreshCodexUsage().finally(() => scheduleRefreshCodexUsage());
+  clearInterval(codexUsageRenderTimer);
+  codexUsageRenderTimer = setInterval(renderCodexUsage, CODEX_USAGE_RENDER_TICK_MS);
+}
+
 function renderStatus() {
   const state = currentState;
   updateComposerModeButtons();
@@ -8166,6 +8366,7 @@ function handleEvent(event) {
       scheduleRefreshState();
       scheduleRefreshMessages();
       scheduleRefreshFooter();
+      scheduleRefreshCodexUsage(2200);
       renderFeedbackTray();
       {
         const workflowTabId = event.tabId || activeTabId;
@@ -8561,6 +8762,9 @@ window.addEventListener("keydown", (event) => {
   }
 });
 
+elements.refreshCodexUsageButton?.addEventListener("click", () => {
+  refreshCodexUsage({ forceAuthRefresh: true }).finally(() => scheduleRefreshCodexUsage());
+});
 elements.pathPickerAddFastPickButton.addEventListener("click", () => addCurrentFastPick().catch((error) => addEvent(error.message, "error")));
 elements.pathPickerCancelButton.addEventListener("click", () => closePathPicker(null));
 elements.pathPickerChooseButton.addEventListener("click", () => closePathPicker(pathPickerState?.cwd || null));
@@ -8657,6 +8861,7 @@ restoreThinkingVisibilitySetting();
 restoreSidePanelSectionState();
 bindSidePanelSectionToggles();
 restoreSidePanelState();
+initializeCodexUsage();
 bindMobileViewChanges();
 registerPwaServiceWorker();
 renderServerOfflinePanel();

package/public/index.html

@@ -240,6 +240,20 @@
               <div id="optionalFeaturesBox" class="optional-features-box muted">Checking optional features…</div>
             </div>
           </section>
+          <section class="side-panel-section" data-side-panel-section="codex-usage">
+            <h2>
+              <button id="sidePanelSectionToggleCodexUsage" class="side-panel-section-toggle" type="button" aria-expanded="true" aria-controls="sidePanelSectionCodexUsage" aria-label="Collapse Codex Usage section" title="Collapse Codex Usage section" data-side-panel-section-toggle="codex-usage">
+                <span class="side-panel-section-label">Codex Usage</span>
+                <span class="side-panel-section-chevron" aria-hidden="true">›</span>
+              </button>
+            </h2>
+            <div id="sidePanelSectionCodexUsage" class="side-panel-section-content">
+              <div class="codex-usage-actions">
+                <button id="refreshCodexUsageButton" type="button">Refresh usage</button>
+              </div>
+              <div id="codexUsageBox" class="codex-usage-box muted">Checking Codex usage…</div>
+            </div>
+          </section>
           <section class="side-panel-section" data-side-panel-section="session">
             <h2>
               <button id="sidePanelSectionToggleSession" class="side-panel-section-toggle" type="button" aria-expanded="true" aria-controls="sidePanelSectionSession" aria-label="Collapse Session section" title="Collapse Session section" data-side-panel-section-toggle="session">

package/public/styles.css

@@ -808,6 +808,83 @@ body.side-panel-collapsed .terminal-tabs-shell {
   background: rgba(var(--ctp-crust-rgb), 0.46);
   box-shadow: inset 0 1px 0 rgba(255,255,255,0.035), 0 0 1rem rgba(148, 226, 213, 0.05);
 }
+.codex-usage-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-bottom: 0.48rem;
+}
+.codex-usage-actions button {
+  min-height: 34px;
+  padding: 0.32rem 0.58rem;
+  font-size: 0.72rem;
+}
+.codex-usage-box {
+  display: grid;
+  gap: 0.58rem;
+  padding: 0.72rem;
+  border: 1px solid rgba(180, 190, 254, 0.16);
+  border-radius: 0.85rem;
+  background: rgba(var(--ctp-crust-rgb), 0.50);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.035), 0 0 1rem rgba(203, 166, 247, 0.05);
+}
+.codex-usage-summary {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 0.35rem 0.55rem;
+  align-items: baseline;
+}
+.codex-usage-plan {
+  color: rgba(var(--ctp-text-rgb), 0.94);
+  font-weight: 900;
+}
+.codex-usage-fetched,
+.codex-usage-detail,
+.codex-usage-reset {
+  color: rgba(var(--ctp-subtext-rgb), 0.70);
+  font-size: 0.72rem;
+  line-height: 1.35;
+}
+.codex-usage-unavailable,
+.codex-usage-warning {
+  color: var(--ctp-yellow);
+  font-weight: 800;
+}
+.codex-usage-bucket {
+  display: grid;
+  gap: 0.32rem;
+}
+.codex-usage-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 0.6rem;
+  align-items: center;
+}
+.codex-usage-label {
+  min-width: 0;
+  color: rgba(var(--ctp-text-rgb), 0.86);
+  font-size: 0.78rem;
+  font-weight: 800;
+  overflow-wrap: anywhere;
+}
+.codex-usage-percent {
+  color: var(--ctp-teal);
+  font-size: 0.82rem;
+}
+.codex-usage-meter {
+  overflow: hidden;
+  height: 0.5rem;
+  border: 1px solid rgba(180, 190, 254, 0.14);
+  border-radius: 999px;
+  background: rgba(var(--ctp-surface-rgb), 0.26);
+}
+.codex-usage-meter-fill {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: linear-gradient(90deg, var(--ctp-green), var(--ctp-yellow), var(--ctp-peach));
+  box-shadow: 0 0 0.85rem rgba(148, 226, 213, 0.20);
+}
 .optional-feature-row {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto;

package/tests/mobile-static.test.mjs

@@ -51,6 +51,8 @@ assert.match(html, /id="thinkingVisibilityStatus"/, "thinking-output visibility
 assert.match(html, /id="nativeCommandDialog"/, "native slash selector UI should have a dedicated dialog");
 assert.match(html, /id="nativeCommandSearch"[^>]*type="search"/, "native slash selector dialog should expose a filter box");
 assert.match(html, /id="optionalFeaturesBox"/, "side panel should expose optional feature status and controls");
+assert.match(html, /id="codexUsageBox"/, "side panel should expose Codex subscription usage status");
+assert.match(html, /data-side-panel-section="codex-usage"/, "Codex usage should live in a collapsible side-panel section");
 assert.match(html, /id="serverOfflinePanel"/, "PWA/offline shell should expose a backend-offline recovery panel");
 assert.match(html, /id="copyServerCommandButton"/, "backend-offline recovery panel should expose a start-command copy button");
 assert.match(html, /id="retryServerConnectionButton"/, "backend-offline recovery panel should expose a retry button");
@@ -258,6 +260,8 @@ assert.match(app, /Optional feature detection intentionally checks loaded Pi cap
 assert.match(app, /function resetOptionalFeatureAvailability\(\)/, "optional feature state should reset across active-tab and reload boundaries");
 assert.match(app, /function renderOptionalFeaturePanel\(\)/, "side panel should render optional feature installed/enabled state");
 assert.match(app, /function setSidePanelSectionCollapsed\(record, collapsed/, "side panel sections should have explicit collapse/expand behavior");
+assert.match(app, /function renderCodexUsage\(\)/, "frontend should render Codex usage buckets in the side panel");
+assert.match(app, /api\(`\/api\/codex-usage\$\{suffix\}`, \{ scoped: false \}\)/, "Codex usage should load through a server endpoint without browser credentials");
 assert.match(app, /restoreSidePanelSectionState\(\);\nbindSidePanelSectionToggles\(\);/, "side panel section state should restore before toggles are bound");
 assert.match(app, /OPTIONAL_FEATURES_STORAGE_KEY/, "optional feature disable toggles should persist in browser storage");
 assert.match(app, /function renderOptionalFeatureDependentDisplays\(\)[\s\S]*renderOptionalFeatureControls\(\);[\s\S]*renderThemeSelect\(\);[\s\S]*renderWidgets\(\);[\s\S]*renderStatus\(\);[\s\S]*renderCommands\(\);[\s\S]*renderAllMessages\(\{ preserveScroll: true \}\);[\s\S]*if \(streamRawText\) renderStreamingAssistantText\(\);/, "optional feature toggles should immediately refresh visible controls, commands, transcript, and live stream displays");
@@ -490,6 +494,10 @@ assert.ok(icon512.length > icon192.length, "PWA 512px icon should be present and
 assert.ok(matrixBackground.length > 100000, "Matrix background image should be present as an optimized WebP asset");
 assert.ok(mochaBackground.length > 8000, "Catppuccin Mocha background image should be present as a compact PNG asset");
 
+assert.match(server, /AuthStorage, SessionManager/, "server should import AuthStorage for safe OAuth token refresh");
+assert.match(server, /const CODEX_TOKEN_REFRESH_SKEW_MS = 5 \* 60 \* 1000/, "server should refresh Codex OAuth tokens before they expire");
+assert.match(server, /url\.pathname === "\/api\/codex-usage" && req\.method === "GET"/, "server should expose a sanitized Codex usage endpoint");
+assert.match(server, /OPENAI_CODEX_USAGE_ENDPOINT/, "server should query Codex usage from the backend, not the browser");
 assert.match(server, /const NATIVE_SLASH_COMMANDS = \[/, "server should define Pi native slash commands for autocomplete");
 assert.match(server, /\{ name: "reload", description: "Reload keybindings, extensions, skills, prompts, and themes" \}/, "native /reload should be advertised for autocomplete");
 assert.match(server, /function parseSlashCommand\(message\)/, "server should parse native slash commands before prompt forwarding");