@llblab/pi-codex-usage 0.5.2 → 0.7.0

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Agent Notes
 
-- `Statusline-only scope`: Keep this extension zero-configuration and statusline-only.
+- `Statusline-first scope`: Keep this extension zero-configuration and focused on compact status surfaces.
   - Trigger: Considering commands, menus, persisted settings, or notification output.
-  - Action: Prefer deleting the surface unless it is required for the optimistic status widget.
+  - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget or the optional `pi-telegram` `/start` status-line mirror.
 
 - `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
   - Trigger: Updating quota polling or error handling.

package/BACKLOG.md

@@ -1,4 +1,3 @@
 # Backlog
 
-- [ ] `Runtime smoke test` Verify the extension inside a live Pi session against missing auth, missing subscription, and transient network failure. Usable subscription with weekly reset countdown has been checked against real Codex auth.
-- [ ] `Statusline polish` Tune the successful-refresh blink duration if the current 150ms redraw feels too visible or too subtle in the Pi footer.
+No open work.

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.7.0: Exhausted Quota Visibility
+
+- Added exhausted-quota warning background for the statusline quota bar. Impact: when either the 5-hour or weekly Codex window has 0% remaining, the bar keeps its shape but switches from the selected background to the error background for faster visual detection.
+- Added exhausted-primary countdown display for cases where the 5-hour Codex window has 0% remaining and exposes a reset time. Impact: the statusline keeps the normal ten-cell dual bar and appends `<5-hour-reset>/<weekly-reset>` countdowns, so operators can see both how long to wait for short-window recovery and how much weekly quota remains.
+- Fixed quota-bar rounding so a truly empty segment state is shown only when a quota window has 0% remaining, while any positive sub-5% remainder still renders as one visible step. Impact: the statusline now distinguishes exhausted Codex limits from tiny remaining quota without changing normal round-to-nearest behavior elsewhere.
+
+## 0.6.0: Telegram Status Integration
+
+- Added optional `pi-telegram` status-menu integration through the public Telegram status-line provider API. When `pi-telegram` is available and the active model is an OpenAI Codex subscription model, the `/start` menu status text now includes `codex: <value>` using the same compact quota bar and reset countdown value as the terminal statusline. Impact: Telegram operators can see Codex quota/reset state in the main control menu without any extra configuration, while non-Codex models and missing `pi-telegram` installs stay unchanged.
+
 ## 0.5.2: Sub-Day Reset Countdown And JPEG Banner
 
 - Refined the weekly reset countdown below 24 hours to use upward-rounded 6-minute hour-tenth steps (`24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, …, `1h`) instead of coarse whole-hour floors. Impact: the statusline gives more useful sub-day reset timing without growing wider than one decimal place.

package/README.md

@@ -16,6 +16,7 @@ This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-co
 
 - Shows an empty statusline bar immediately, then refreshes every 30 seconds while the active Pi model uses `openai-codex`
 - Statusline output stays compact, with the `codex` label accented and the quota bar plus weekly reset countdown drawn on a themed background
+- When `pi-telegram` is available, the same compact value appears as `codex: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
 - Additional returned buckets, including Spark-specific limits, are ignored
 - Pi OpenAI Codex provider auth is used first
 - Codex CLI app-server remains available as a fallback
@@ -46,10 +47,18 @@ Normal usage:
 codex ██████▀▀▀▀ 6d
 ```
 
-The ten-character bar encodes two twenty-step limits at once: 40 total bits of quota state in 10 terminal cells. Each step is 5%: the top quadrants are the 5-hour limit, and the bottom quadrants are the weekly limit.
+The ten-character bar encodes two twenty-step limits at once: 40 total bits of quota state in 10 terminal cells. Each step is 5%: the top quadrants are the 5-hour limit, and the bottom quadrants are the weekly limit. If either quota window is exhausted, the bar keeps the same shape but switches to the error background color.
 
 When the weekly reset time is available, the bar is followed by a countdown. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `6.6d`, `5.1d`, `5d`, `3.7d`, `3d`, `2d`, `1.9d`, `1.5d`, and `1.1d`, rounded upward to the next tenth. At 24 hours and below it switches to upward-rounded 6-minute hour-tenth steps such as `24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, `1.4h`, `1.3h`, `1.2h`, `1.1h`, and `1h`. Under an hour it switches to floored minutes, and under a minute to seconds. After the reset timestamp passes, `0s` is held until the next successful quota refresh reports the new weekly window.
 
+When the 5-hour window is exhausted and exposes its own reset time, the statusline adds the 5-hour reset before the weekly reset:
+
+```text
+codex ▄▄▄▄▄⠀⠀⠀⠀⠀ 5h/7d
+```
+
+The ten-character dual bar stays unchanged. The first countdown is the 5-hour reset, and the second countdown after `/` is the weekly reset.
+
 Unavailable because Codex auth or subscription quota is not available:
 
 ```text
@@ -62,6 +71,16 @@ Runtime failure, such as a network or provider error:
 codex error
 ```
 
+## Telegram Status Menu
+
+If `@llblab/pi-telegram` is loaded with the public status-line provider API, this extension registers an optional `/start` menu status row. The row is shown only while the active model uses the OpenAI Codex subscription provider:
+
+```text
+codex: ██████▀▀▀▀ 6d
+```
+
+The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
+
 ## Auth
 
 The extension tries usage sources in this order:

package/index.ts

@@ -7,6 +7,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 const CODEX_PROVIDER_ID = "openai-codex";
+const CODEX_USAGE_EXTENSION_ID = "@llblab/pi-codex-usage";
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 const DEFAULT_TIMEOUT_MS = 15_000;
 const SECOND_MS = 1000;
@@ -21,6 +22,10 @@ const STATUS_KEY = "aa-codex-usage";
 const MAX_ERROR_BODY_CHARS = 600;
 const STATUS_LABEL_TEXT = "codex";
 const DUAL_BAR_WIDTH = 10;
+const TELEGRAM_STATUS_IMPORT_SPECIFIERS = [
+  "@llblab/pi-telegram/status",
+  new URL("../pi-telegram/api/status.ts", import.meta.url).href,
+];
 const DUAL_BAR_CHARS = [
   "⠀",
   "▘",
@@ -44,6 +49,19 @@ type UsageSource = "pi-auth" | "codex-app-server";
 type TimeoutHandle = ReturnType<typeof setTimeout> & { unref?: () => void };
 type PiModel = NonNullable<ExtensionContext["model"]>;
 export type CodexUsageModel = Pick<PiModel, "id" | "name" | "provider">;
+type CodexUsageTelegramStatusModel = Pick<PiModel, "provider">;
+type TelegramStatusLineProviderResult =
+  | { label: string; value: string }
+  | undefined;
+type TelegramStatusLineProvider = (ctx: {
+  activeModel?: CodexUsageTelegramStatusModel;
+}) => TelegramStatusLineProviderResult;
+type TelegramStatusLineModule = {
+  registerTelegramStatusLineProvider?: (
+    provider: TelegramStatusLineProvider,
+    options: { id: string },
+  ) => () => void;
+};
 
 type QueryUsageOptions = {
   timeoutMs: number;
@@ -140,6 +158,26 @@ export default function codexUsage(pi: ExtensionAPI) {
   let statuslineCountdownTimer: TimeoutHandle | undefined;
   let statuslineRefreshTimer: TimeoutHandle | undefined;
   let statuslineRequestId = 0;
+  let unregisterTelegramStatusLine: (() => void) | undefined;
+  let telegramStatusLineRegistration: Promise<void> | undefined;
+
+  const ensureTelegramStatusLineRegistered = () => {
+    if (unregisterTelegramStatusLine || telegramStatusLineRegistration) return;
+    telegramStatusLineRegistration = registerCodexUsageTelegramStatusLine(
+      ({ activeModel }) => {
+        if (!isOpenAICodexModel(activeModel)) return undefined;
+        if (!cache) return undefined;
+        const value = formatCodexUsageStatusValue(cache.report);
+        return value ? { label: "codex", value } : undefined;
+      },
+    )
+      .then((unregister) => {
+        unregisterTelegramStatusLine = unregister;
+      })
+      .finally(() => {
+        telegramStatusLineRegistration = undefined;
+      });
+  };
 
   const clearStatuslineTimers = () => {
     if (statuslineBlinkTimer) clearTimeout(statuslineBlinkTimer);
@@ -299,7 +337,10 @@ export default function codexUsage(pi: ExtensionAPI) {
     });
   };
 
+  ensureTelegramStatusLineRegistered();
+
   pi.on("session_start", (_event, ctx) => {
+    ensureTelegramStatusLineRegistered();
     if (isOpenAICodexModel(ctx.model))
       void refreshCurrentCodexUsageStatusline(ctx, false);
     else clearUsageStatusline(ctx);
@@ -319,7 +360,11 @@ export default function codexUsage(pi: ExtensionAPI) {
     }
   });
 
-  pi.on("session_shutdown", (_event, ctx) => clearUsageStatusline(ctx));
+  pi.on("session_shutdown", (_event, ctx) => {
+    clearUsageStatusline(ctx);
+    unregisterTelegramStatusLine?.();
+    unregisterTelegramStatusLine = undefined;
+  });
 }
 
 function isOpenAICodexModel(
@@ -328,6 +373,31 @@ function isOpenAICodexModel(
   return model?.provider === CODEX_PROVIDER_ID;
 }
 
+async function importTelegramStatusLineModule(): Promise<
+  TelegramStatusLineModule | undefined
+> {
+  for (const specifier of TELEGRAM_STATUS_IMPORT_SPECIFIERS) {
+    try {
+      const imported = (await import(specifier)) as TelegramStatusLineModule;
+      if (typeof imported.registerTelegramStatusLineProvider === "function") {
+        return imported;
+      }
+    } catch {
+      // pi-telegram is optional; absence just disables the Telegram status line.
+    }
+  }
+  return undefined;
+}
+
+async function registerCodexUsageTelegramStatusLine(
+  provider: TelegramStatusLineProvider,
+): Promise<(() => void) | undefined> {
+  const telegramStatus = await importTelegramStatusLineModule();
+  return telegramStatus?.registerTelegramStatusLineProvider?.(provider, {
+    id: CODEX_USAGE_EXTENSION_ID,
+  });
+}
+
 async function queryUsage(
   ctx: ExtensionContext,
   options: Pick<QueryUsageOptions, "timeoutMs">,
@@ -791,10 +861,14 @@ export function formatCodexUsageStatusline(
   ctx: ExtensionContext,
   _model?: CodexUsageModel,
 ): string {
-  const bar = formatReportBar(report);
-  if (!bar) return formatStatuslineText(ctx, "n/a");
-  const countdown = formatWeeklyResetCountdown(report);
-  const barText = formatStatuslineBarText(ctx, bar);
+  const value = formatCodexUsageStatusValue(report);
+  if (!value) return formatStatuslineText(ctx, "n/a");
+  const [bar, countdown] = value.split(" ", 2);
+  const barText = formatStatuslineBarText(
+    ctx,
+    bar ?? "",
+    hasExhaustedQuotaWindow(report) ? "toolErrorBg" : "selectedBg",
+  );
   return countdown
     ? `${barText} ${ctx.ui.theme.fg("dim", countdown)}`
     : barText;
@@ -806,6 +880,26 @@ export function formatCodexUsageBar(
   return formatReportBar(report);
 }
 
+export function formatCodexUsageStatusValue(
+  report: CodexUsageReport,
+  now = Date.now(),
+): string | undefined {
+  const snapshot = selectPrimaryCodexSnapshot(report);
+  if (!snapshot || (!snapshot.primary && !snapshot.secondary)) return undefined;
+  const bar = formatDualLimitBar(snapshot.primary, snapshot.secondary);
+  if (isQuotaWindowExhausted(snapshot.primary) && snapshot.primary?.resetAt) {
+    const primaryCountdown = formatResetCountdown(snapshot.primary.resetAt, now);
+    const weeklyCountdown = snapshot.secondary?.resetAt
+      ? formatResetCountdown(snapshot.secondary.resetAt, now)
+      : undefined;
+    return weeklyCountdown
+      ? `${bar} ${primaryCountdown}/${weeklyCountdown}`
+      : `${bar} ${primaryCountdown}`;
+  }
+  const countdown = formatWeeklyResetCountdown(report, now);
+  return countdown ? `${bar} ${countdown}` : bar;
+}
+
 export function formatWeeklyResetCountdown(
   report: CodexUsageReport,
   now = Date.now(),
@@ -837,9 +931,16 @@ export function nextResetCountdownDelayMs(
   report: CodexUsageReport,
   now = Date.now(),
 ): number | undefined {
-  const resetAt = selectPrimaryCodexSnapshot(report)?.secondary?.resetAt;
-  if (resetAt === undefined) return undefined;
-  return nextResetCountdownDelayForRemainingMs(resetAt - now);
+  const snapshot = selectPrimaryCodexSnapshot(report);
+  const resetTimes = [snapshot?.secondary?.resetAt];
+  if (isQuotaWindowExhausted(snapshot?.primary)) {
+    resetTimes.push(snapshot?.primary?.resetAt);
+  }
+  const delays = resetTimes
+    .filter((resetAt): resetAt is number => resetAt !== undefined)
+    .map((resetAt) => nextResetCountdownDelayForRemainingMs(resetAt - now))
+    .filter((delay): delay is number => delay !== undefined);
+  return delays.length > 0 ? Math.min(...delays) : undefined;
 }
 
 export function nextResetCountdownDelayForRemainingMs(
@@ -882,9 +983,13 @@ function formatStatuslineText(ctx: ExtensionContext, value: string): string {
   return `${label} ${ctx.ui.theme.fg("dim", value)}`;
 }
 
-function formatStatuslineBarText(ctx: ExtensionContext, bar: string): string {
+function formatStatuslineBarText(
+  ctx: ExtensionContext,
+  bar: string,
+  background: "selectedBg" | "toolErrorBg" = "selectedBg",
+): string {
   const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
-  const value = ctx.ui.theme.bg("selectedBg", ctx.ui.theme.fg("dim", bar));
+  const value = ctx.ui.theme.bg(background, ctx.ui.theme.fg("dim", bar));
   return `${label} ${value}`;
 }
 
@@ -961,15 +1066,38 @@ function formatDualLimitBar(
 
 function filledTwentieths(
   window: NormalizedRateLimitWindow | undefined,
+): number {
+  return filledParts(window, 20);
+}
+
+function filledParts(
+  window: NormalizedRateLimitWindow | undefined,
+  totalParts: number,
 ): number {
   if (!window) return 0;
-  return Math.round(remainingPercent(window) / 5);
+  const remaining = remainingPercent(window);
+  if (remaining <= 0) return 0;
+  return Math.max(1, Math.round(remaining / (100 / totalParts)));
 }
 
 function remainingPercent(window: NormalizedRateLimitWindow): number {
   return 100 - clampPercent(window.usedPercent);
 }
 
+function isQuotaWindowExhausted(
+  window: NormalizedRateLimitWindow | undefined,
+): boolean {
+  return window !== undefined && remainingPercent(window) <= 0;
+}
+
+function hasExhaustedQuotaWindow(report: CodexUsageReport): boolean {
+  const snapshot = selectPrimaryCodexSnapshot(report);
+  return (
+    isQuotaWindowExhausted(snapshot?.primary) ||
+    isQuotaWindowExhausted(snapshot?.secondary)
+  );
+}
+
 function isPrimaryCodexSnapshot(
   snapshot: NormalizedRateLimitSnapshot,
 ): boolean {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits.",
   "keywords": [