@llblab/pi-codex-usage 0.5.1 → 0.6.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.
@@ -14,4 +14,4 @@
 
 - `Weekly reset countdown`: Append the weekly reset countdown only when the secondary window exposes a reset time.
   - Trigger: Changing reset-time normalization or statusline refresh cadence.
-  - Action: Keep `d` labels rounded upward in 144-minute day-tenth steps, `h`/`m`/`s` labels floored, and hold `0s` until a successful quota refresh reports the next window.
+  - Action: Keep `d` labels rounded upward in 144-minute day-tenth steps above 24h, show 24h..1h labels in upward-rounded 6-minute hour-tenth steps, keep `m`/`s` labels floored, and hold `0s` until a successful quota refresh reports the next window.

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 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.
+- Replaced the package/banner artwork from PNG to JPEG and updated package metadata plus README image references. Impact: the package ships the new compressed banner asset consistently across npm and Pi extension listings.
+
 ## 0.5.1: Non-Codex Bucket Hotfix
 
 - Fixed non-Codex app-server quota buckets so Spark-only or unrelated limits are ignored instead of being displayed as Codex quota.

package/README.md

@@ -2,7 +2,7 @@
 
 > Minimal zero-configuration Pi extension for showing primary ChatGPT Codex usage limits in the statusline
 
-![Codex Usage](./banner.png)
+![Codex Usage](./banner.jpg)
 
 This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-codex-usage`](https://github.com/narumiruna/pi-extensions/tree/main/extensions/pi-codex-usage). It keeps the auth and quota-fetching path, but intentionally narrows the interface to the primary Codex 5-hour and weekly limits.
 
@@ -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
@@ -48,7 +49,7 @@ 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.
 
-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`, `1.1d`, and `1d`, rounded upward to the next tenth. Under a day it switches to floored hours, under an hour 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 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.
 
 Unavailable because Codex auth or subscription quota is not available:
 
@@ -62,6 +63,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,11 +7,13 @@ 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;
 const MINUTE_MS = 60 * SECOND_MS;
 const HOUR_MS = 60 * MINUTE_MS;
+const HOUR_TENTH_MS = 6 * MINUTE_MS;
 const DAY_MS = 24 * HOUR_MS;
 const DAY_TENTH_MS = 144 * MINUTE_MS;
 const REFRESH_INTERVAL_MS = 30 * SECOND_MS;
@@ -20,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 = [
   "⠀",
   "▘",
@@ -43,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;
@@ -139,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);
@@ -298,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);
@@ -318,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(
@@ -327,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">,
@@ -790,10 +861,10 @@ 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 ?? "");
   return countdown
     ? `${barText} ${ctx.ui.theme.fg("dim", countdown)}`
     : barText;
@@ -805,6 +876,16 @@ export function formatCodexUsageBar(
   return formatReportBar(report);
 }
 
+export function formatCodexUsageStatusValue(
+  report: CodexUsageReport,
+  now = Date.now(),
+): string | undefined {
+  const bar = formatReportBar(report);
+  if (!bar) return undefined;
+  const countdown = formatWeeklyResetCountdown(report, now);
+  return countdown ? `${bar} ${countdown}` : bar;
+}
+
 export function formatWeeklyResetCountdown(
   report: CodexUsageReport,
   now = Date.now(),
@@ -819,11 +900,14 @@ export function formatResetCountdown(
   now = Date.now(),
 ): string {
   const remainingMs = Math.max(0, resetAt - now);
-  if (remainingMs >= DAY_MS) {
+  if (remainingMs > DAY_MS) {
     const dayTenths = Math.max(10, Math.ceil(remainingMs / DAY_TENTH_MS));
     return `${formatTenths(dayTenths)}d`;
   }
-  if (remainingMs >= HOUR_MS) return `${Math.floor(remainingMs / HOUR_MS)}h`;
+  if (remainingMs >= HOUR_MS) {
+    const hourTenths = Math.max(10, Math.ceil(remainingMs / HOUR_TENTH_MS));
+    return `${formatTenths(hourTenths)}h`;
+  }
   if (remainingMs >= MINUTE_MS)
     return `${Math.floor(remainingMs / MINUTE_MS)}m`;
   return `${Math.floor(remainingMs / SECOND_MS)}s`;
@@ -842,15 +926,14 @@ export function nextResetCountdownDelayForRemainingMs(
   remainingMs: number,
 ): number | undefined {
   if (remainingMs <= 0) return undefined;
-  if (remainingMs >= DAY_MS) {
+  if (remainingMs > DAY_MS) {
     const dayTenths = Math.max(10, Math.ceil(remainingMs / DAY_TENTH_MS));
     return Math.max(1, remainingMs - (dayTenths - 1) * DAY_TENTH_MS);
   }
   if (remainingMs >= HOUR_MS) {
-    return Math.max(
-      1,
-      remainingMs - Math.floor(remainingMs / HOUR_MS) * HOUR_MS + 1,
-    );
+    const hourTenths = Math.max(10, Math.ceil(remainingMs / HOUR_TENTH_MS));
+    if (hourTenths === 10) return Math.max(1, remainingMs - HOUR_MS + 1);
+    return Math.max(1, remainingMs - (hourTenths - 1) * HOUR_TENTH_MS);
   }
   if (remainingMs >= MINUTE_MS) {
     return Math.max(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits.",
   "keywords": [
@@ -38,13 +38,13 @@
     "BACKLOG.md",
     "CHANGELOG.md",
     "LICENSE",
-    "banner.png"
+    "banner.jpg"
   ],
   "pi": {
     "extensions": [
       "./index.ts"
     ],
-    "image": "https://github.com/llblab/pi-codex-usage/raw/main/banner.png"
+    "image": "https://github.com/llblab/pi-codex-usage/raw/main/banner.jpg"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",