@llblab/pi-codex-usage 0.5.2 → 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.

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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.

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
@@ -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,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,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;
@@ -806,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(),

package/package.json

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