Merge pull request #61 from llblab/dev

0.15.0: Companion Status Lines

Author: llblab

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 No open changes.
 
+## 0.15.0: Companion Status Lines
+
+- `[API]` Added `registerTelegramStatusLineProvider()` on the public `/status` subpath so companion extensions can append compact rows to the `/start` menu status text. Providers are synchronous, model-aware, isolated on failure, and rendered with Telegram-style capitalized labels. Impact: quota/status widgets can progressively enhance the Telegram operator menu without owning polling, transport, or core menu rendering.
+- `[Docs]` Documented the status-line provider with an abstract companion-extension example and listed `pi-codex-usage` as a companion extension. Impact: the public API docs stay implementation-neutral while the README still points operators to the concrete Codex quota widget.
+
 ## 0.14.0: Direct Telegram Delivery, Queue Semantics, And Section Diagnostics
 
 - `[Prompt Guidance]` Tightened agent context for Telegram buttons: use normal Markdown plus top-level hidden `telegram_button` comments, never JSON button specs or standalone button actions, and keep comments out of code/quotes/lists/indented examples. Impact: agents immediately know how to author visible Telegram text, inline buttons, and direct `telegram_message` payloads without transport hacks.

README.md

@@ -209,7 +209,7 @@ Unknown inline-button callbacks are forwarded to π as `[callback] <data>` when
 
 ### Extension Sections
 
-Ordinary pi extensions can register structured UI sections that appear in the main Telegram menu and Settings submenu without owning a second polling loop. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
+Ordinary pi extensions can register structured UI sections that appear in the main Telegram menu and Settings submenu without owning a second polling loop. Companion extensions can also register compact status lines for the `/start` menu status text, allowing widgets such as quota indicators to appear beside Status, Usage, Cost, and Context only when relevant to the active model. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
 
 Import `registerTelegramSection()` from `@llblab/pi-telegram/sections` and return a disposer on shutdown. Sections can send interactive messages directly into the chat via `ctx.open()` — confirmation dialogs, approve/deny gates, and multi-step forms live outside the menu hierarchy while callbacks route through the same typed handler. See [`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) for a working reference and the [Extension Sections Standard](./docs/sections.md) for the full contract.
 
@@ -260,6 +260,12 @@ Modes are `hidden`, `always`, and `interval`. `hidden` means no time line is add
 
 Third-party extensions that integrate with `pi-telegram`:
 
+- [`pi-codex-usage`](https://github.com/llblab/pi-codex-usage) — Compact Codex subscription quota/status widget for the Pi statusline and the inline menu status text opened by `/start`.
+
+```bash
+pi install npm:@llblab/pi-codex-usage
+```
+
 - [`pi-telegram-tool-status`](https://github.com/Timur00Kh/pi-telegram-tool-status) — Live-updating service messages that list tools used by the agent. It keeps one message per Telegram prompt and edits it in place as tools execute.
 
 ```bash

api/status.ts

@@ -0,0 +1,12 @@
+/**
+ * Public Telegram status API
+ * Zones: package boundary, companion extension interop
+ * Exposes compact status-menu line registration for companion extensions while keeping status rendering internals package-private
+ */
+
+export {
+  registerTelegramStatusLineProvider,
+  type TelegramStatusLineProvider,
+  type TelegramStatusLineProviderContext,
+  type TelegramStatusLineProviderResult,
+} from "../lib/status.ts";

docs/public-api.md

@@ -16,6 +16,7 @@ Preferred public imports:
 ```ts
 import telegram from "@llblab/pi-telegram";
 import { registerTelegramSection } from "@llblab/pi-telegram/sections";
+import { registerTelegramStatusLineProvider } from "@llblab/pi-telegram/status";
 import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
 import { registerTelegramInboundHandler } from "@llblab/pi-telegram/inbound";
 import { registerTelegramOutboundHandler } from "@llblab/pi-telegram/outbound";
@@ -102,6 +103,9 @@ High-level stable APIs:
 - `registerTelegramSection()`
   - Identity: required `id`.
   - Purpose: managed menu/settings UI surfaces.
+- `registerTelegramStatusLineProvider()`
+  - Identity: required `id`.
+  - Purpose: compact companion status rows in the `/start` menu status text.
 - `registerTelegramVoiceTranscriptionProvider()`
   - Identity: required stable `id` for new code.
   - Purpose: STT fallback for voice/audio input.
@@ -165,6 +169,27 @@ Contract:
 
 Full behavior: [Extension Sections](./sections.md).
 
+## Status Lines
+
+Import from `@llblab/pi-telegram/status`.
+
+```ts
+const off = registerTelegramStatusLineProvider(
+  ({ activeModel }) => {
+    if (activeModel?.provider !== "example-provider") return undefined;
+    return { label: "service", value: "ready" };
+  },
+  { id: "@scope/example-status" },
+);
+```
+
+Contract:
+
+- Providers are synchronous because `/start` status text is rendered inline with the menu.
+- Return `undefined` when the line is not relevant for the active model.
+- Provider failures are isolated and skipped so optional companion status cannot break the core Telegram menu.
+- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Usage, Cost, and Context, capitalizing the first label character for Telegram UI consistency.
+
 ## Updates
 
 Import from `@llblab/pi-telegram/updates`.

lib/status.ts

@@ -36,9 +36,24 @@ interface TelegramContextUsage {
 }
 
 export interface TelegramStatusActiveModel {
+  provider?: string;
+  id?: string;
   contextWindow?: number;
 }
 
+export interface TelegramStatusLineProviderContext {
+  activeModel: TelegramStatusActiveModel | undefined;
+}
+
+export interface TelegramStatusLineProviderResult {
+  label: string;
+  value: string;
+}
+
+export type TelegramStatusLineProvider = (
+  ctx: TelegramStatusLineProviderContext,
+) => TelegramStatusLineProviderResult | undefined;
+
 export interface TelegramStatusContext {
   sessionManager: { getEntries(): TelegramStatusSessionEntry[] };
   getContextUsage(): TelegramContextUsage | undefined;
@@ -52,6 +67,8 @@ export interface TelegramStatusContext {
 
 export type TelegramRuntimeEventDetailValue = string | number | boolean | null;
 
+const TELEGRAM_STATUS_LINE_PROVIDER_REGISTRY_KEY =
+  "__piTelegramStatusLineProviders__";
 const MAX_RECENT_TELEGRAM_RUNTIME_EVENTS = 10;
 const MAX_TELEGRAM_RUNTIME_EVENT_MESSAGE_LENGTH = 1000;
 const MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH = 1000;
@@ -166,7 +183,10 @@ export interface TelegramStatusRuntime<
   getStatusLines: () => string[];
 }
 
-function truncateTelegramRuntimeEventText(text: string, maxLength: number): string {
+function truncateTelegramRuntimeEventText(
+  text: string,
+  maxLength: number,
+): string {
   if (text.length <= maxLength) return text;
   return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
 }
@@ -262,6 +282,61 @@ export function recordTelegramRuntimeEvent(
   recordStructuredTelegramRuntimeEvent(events, { category, error }, options);
 }
 
+function getOrCreateTelegramStatusLineProviderRegistry(): Map<
+  string,
+  TelegramStatusLineProvider
+> {
+  const existing = (globalThis as Record<string, unknown>)[
+    TELEGRAM_STATUS_LINE_PROVIDER_REGISTRY_KEY
+  ];
+  if (existing instanceof Map)
+    return existing as Map<string, TelegramStatusLineProvider>;
+  const registry = new Map<string, TelegramStatusLineProvider>();
+  (globalThis as Record<string, unknown>)[
+    TELEGRAM_STATUS_LINE_PROVIDER_REGISTRY_KEY
+  ] = registry;
+  return registry;
+}
+
+/**
+ * Register a compact companion-extension line for the Telegram status menu.
+ *
+ * Providers are synchronous and should return undefined when their line is not
+ * relevant for the active model. Errors are isolated so optional companion
+ * status cannot break the core Telegram menu.
+ */
+export function registerTelegramStatusLineProvider(
+  provider: TelegramStatusLineProvider,
+  options: { id: string },
+): () => void {
+  const registry = getOrCreateTelegramStatusLineProviderRegistry();
+  registry.set(options.id, provider);
+  return () => {
+    if (registry.get(options.id) === provider) registry.delete(options.id);
+  };
+}
+
+export function getTelegramStatusLineProviderResults(
+  ctx: TelegramStatusLineProviderContext,
+): TelegramStatusLineProviderResult[] {
+  const results: TelegramStatusLineProviderResult[] = [];
+  const registry = getOrCreateTelegramStatusLineProviderRegistry();
+  for (const provider of registry.values()) {
+    try {
+      const result = provider(ctx);
+      if (!result?.label || !result.value) continue;
+      results.push(result);
+    } catch {
+      continue;
+    }
+  }
+  return results;
+}
+
+export function clearTelegramStatusLineProviders(): void {
+  getOrCreateTelegramStatusLineProviderRegistry().clear();
+}
+
 export function createTelegramRuntimeEventRecorder(
   options: TelegramRuntimeEventRecorderOptions,
 ): TelegramRuntimeEventRecorder {
@@ -314,7 +389,9 @@ function formatTelegramRuntimeEvent(event: TelegramRuntimeEvent): string {
   return `${new Date(event.at).toISOString()} ${formatTelegramRuntimeEventSummary(event)}`;
 }
 
-function buildTelegramRuntimeEventSummary(events: TelegramRuntimeEvent[]): string {
+function buildTelegramRuntimeEventSummary(
+  events: TelegramRuntimeEvent[],
+): string {
   const counts = new Map<string, number>();
   for (const event of events) {
     const category = formatTelegramRuntimeEventCategory(event);
@@ -553,8 +630,13 @@ function collectUsageStats(ctx: TelegramStatusContext): TelegramUsageStats {
   return stats;
 }
 
+function formatStatusRowLabel(label: string): string {
+  if (!label) return label;
+  return `${label[0]?.toUpperCase() ?? ""}${label.slice(1)}`;
+}
+
 function buildStatusRow(label: string, value: string): string {
-  return `<b>${escapeHtml(label)}:</b> <code>${escapeHtml(value)}</code>`;
+  return `<b>${escapeHtml(formatStatusRowLabel(label))}:</b> <code>${escapeHtml(value)}</code>`;
 }
 
 function buildUsageSummary(stats: TelegramUsageStats): string | undefined {
@@ -613,5 +695,8 @@ export function buildStatusHtml(
     lines.push(buildStatusRow("Cost", costSummary));
   }
   lines.push(buildStatusRow("Context", buildContextSummary(ctx, activeModel)));
+  for (const row of getTelegramStatusLineProviderResults({ activeModel })) {
+    lines.push(buildStatusRow(row.label, row.value));
+  }
   return lines.join("\n");
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -50,6 +50,7 @@
     "./outbound": "./api/outbound.ts",
     "./updates": "./api/updates.ts",
     "./sections": "./api/sections.ts",
+    "./status": "./api/status.ts",
     "./voice": "./api/voice.ts",
     "./keyboard": "./api/keyboard.ts"
   },

package.json

@@ -166,6 +166,7 @@ test("Package exports expose only stable public domains", () => {
     "./outbound": "./api/outbound.ts",
     "./updates": "./api/updates.ts",
     "./sections": "./api/sections.ts",
+    "./status": "./api/status.ts",
     "./voice": "./api/voice.ts",
     "./keyboard": "./api/keyboard.ts",
   });

tests/invariants.test.ts

@@ -18,13 +18,14 @@ async function assertPackagePathNotExported(specifier: string): Promise<void> {
 }
 
 test("Public package subpaths expose the stable companion-extension API", async () => {
-  const [root, inbound, outbound, updates, sections, voice, keyboard] =
+  const [root, inbound, outbound, updates, sections, status, voice, keyboard] =
     await Promise.all([
       import("@llblab/pi-telegram"),
       import("@llblab/pi-telegram/inbound"),
       import("@llblab/pi-telegram/outbound"),
       import("@llblab/pi-telegram/updates"),
       import("@llblab/pi-telegram/sections"),
+      import("@llblab/pi-telegram/status"),
       import("@llblab/pi-telegram/voice"),
       import("@llblab/pi-telegram/keyboard"),
     ]);
@@ -44,6 +45,9 @@ test("Public package subpaths expose the stable companion-extension API", async
     "getTelegramSectionDiagnostics",
     "registerTelegramSection",
   ]);
+  assert.deepEqual(Object.keys(status).sort(), [
+    "registerTelegramStatusLineProvider",
+  ]);
   assert.deepEqual(Object.keys(voice).sort(), [
     "TELEGRAM_VOICE_REPLY_MODES",
     "computeVoicePromptContribution",

tests/public-api.test.ts

@@ -10,13 +10,15 @@ import {
   buildTelegramBridgeStatusLines,
   buildTelegramRuntimeEventLines,
   buildTelegramStatusBarText,
+  clearTelegramStatusLineProviders,
   createTelegramBridgeStatusRuntime,
   createTelegramRuntimeEventRecorder,
   createTelegramStatusHtmlBuilder,
   createTelegramStatusRuntime,
   getTelegramStatusBarProcessingStatus,
   recordStructuredTelegramRuntimeEvent,
   recordTelegramRuntimeEvent,
+  registerTelegramStatusLineProvider,
   type TelegramRuntimeEvent,
 } from "../lib/status.ts";
 
@@ -384,6 +386,40 @@ test("Status HTML builder binds active model lookup", () => {
   assert.match(html, /Context.*0\.0%\/1\.0k/s);
 });
 
+test("Status HTML builder includes companion status lines", () => {
+  clearTelegramStatusLineProviders();
+  const unregisterCodex = registerTelegramStatusLineProvider(
+    ({ activeModel }) =>
+      activeModel?.contextWindow === 1000
+        ? { label: "codex", value: "████ 23.7h" }
+        : undefined,
+    { id: "@scope/codex" },
+  );
+  const unregisterBroken = registerTelegramStatusLineProvider(
+    () => {
+      throw new Error("optional provider failed");
+    },
+    { id: "@scope/broken" },
+  );
+  try {
+    const buildStatusHtml = createTelegramStatusHtmlBuilder({
+      getActiveModel: () => ({ contextWindow: 1000 }),
+    });
+    const html = buildStatusHtml({
+      sessionManager: { getEntries: () => [] },
+      getContextUsage: () => ({ percent: 0, contextWindow: undefined }),
+      isIdle: () => true,
+      modelRegistry: { isUsingOAuth: () => false },
+    });
+    assert.match(html, /Context.*0\.0%\/1\.0k/s);
+    assert.match(html, /Codex.*████ 23\.7h/s);
+  } finally {
+    unregisterCodex();
+    unregisterBroken();
+    clearTelegramStatusLineProviders();
+  }
+});
+
 test("Status HTML builder shows compacting while compact is running", () => {
   const buildStatusHtml = createTelegramStatusHtmlBuilder({
     getActiveModel: () => undefined,