@llblab/pi-telegram 0.13.2 → 0.15.0

package/lib/runtime.ts

@@ -4,7 +4,8 @@
  * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
  */
 
-const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 2500;
+const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 3000;
+const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 300;
 
 export interface TelegramRuntimeQueueCounters {
   nextQueuedTelegramItemOrder: number;
@@ -16,7 +17,7 @@ export interface TelegramRuntimeLifecycleFlags {
   activeTelegramToolExecutions: number;
   telegramTurnDispatchPending: boolean;
   compactionInProgress: boolean;
-  preserveQueuedTurnsAsHistory: boolean;
+  foldQueuedPromptsIntoHistory: boolean;
   setupInProgress: boolean;
 }
 
@@ -24,6 +25,7 @@ export interface TelegramBridgeRuntimeState
   extends TelegramRuntimeQueueCounters, TelegramRuntimeLifecycleFlags {
   abortHandler?: () => void;
   typingInterval?: ReturnType<typeof setInterval>;
+  typingInFlight?: Promise<void>;
 }
 
 export interface TelegramRuntimeQueuePort {
@@ -44,8 +46,8 @@ export interface TelegramRuntimeLifecyclePort {
   clearDispatchPending: () => void;
   isCompactionInProgress: () => boolean;
   setCompactionInProgress: (inProgress: boolean) => void;
-  shouldPreserveQueuedTurnsAsHistory: () => boolean;
-  setPreserveQueuedTurnsAsHistory: (preserve: boolean) => void;
+  shouldFoldQueuedPromptsIntoHistory: () => boolean;
+  setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
 }
 
 export interface TelegramRuntimeSetupPort {
@@ -65,6 +67,7 @@ export interface TelegramRuntimeAbortPort {
 export interface TelegramRuntimeTypingPort {
   start: (deps: TelegramTypingLoopDeps) => boolean;
   stop: () => boolean;
+  waitForIdle: () => Promise<void>;
 }
 
 export interface TelegramBridgeRuntime {
@@ -84,7 +87,7 @@ export function createTelegramBridgeRuntimeState(): TelegramBridgeRuntimeState {
     activeTelegramToolExecutions: 0,
     telegramTurnDispatchPending: false,
     compactionInProgress: false,
-    preserveQueuedTurnsAsHistory: false,
+    foldQueuedPromptsIntoHistory: false,
     setupInProgress: false,
   };
 }
@@ -117,10 +120,10 @@ export function createTelegramBridgeRuntime(
       isCompactionInProgress: () => isTelegramCompactionInProgress(state),
       setCompactionInProgress: (inProgress) =>
         setTelegramCompactionInProgress(state, inProgress),
-      shouldPreserveQueuedTurnsAsHistory: () =>
-        shouldPreserveQueuedTurnsAsHistory(state),
-      setPreserveQueuedTurnsAsHistory: (preserve) =>
-        setPreserveQueuedTurnsAsHistory(state, preserve),
+      shouldFoldQueuedPromptsIntoHistory: () =>
+        shouldFoldQueuedPromptsIntoHistory(state),
+      setFoldQueuedPromptsIntoHistory: (fold) =>
+        setFoldQueuedPromptsIntoHistory(state, fold),
     },
     setup: {
       isInProgress: () => isTelegramSetupInProgress(state),
@@ -138,6 +141,7 @@ export function createTelegramBridgeRuntime(
     typing: {
       start: (deps) => startTelegramTypingLoop(state, deps),
       stop: () => stopTelegramTypingLoop(state),
+      waitForIdle: () => waitForTelegramTypingLoopIdle(state),
     },
   };
 }
@@ -195,8 +199,8 @@ export function syncTelegramLifecycleRuntimeFlags(
   if (flags.compactionInProgress !== undefined) {
     state.compactionInProgress = flags.compactionInProgress;
   }
-  if (flags.preserveQueuedTurnsAsHistory !== undefined) {
-    state.preserveQueuedTurnsAsHistory = flags.preserveQueuedTurnsAsHistory;
+  if (flags.foldQueuedPromptsIntoHistory !== undefined) {
+    state.foldQueuedPromptsIntoHistory = flags.foldQueuedPromptsIntoHistory;
   }
   if (flags.setupInProgress !== undefined) {
     state.setupInProgress = flags.setupInProgress;
@@ -254,17 +258,17 @@ export function setTelegramCompactionInProgress(
   state.compactionInProgress = inProgress;
 }
 
-export function shouldPreserveQueuedTurnsAsHistory(
+export function shouldFoldQueuedPromptsIntoHistory(
   state: TelegramBridgeRuntimeState,
 ): boolean {
-  return state.preserveQueuedTurnsAsHistory;
+  return state.foldQueuedPromptsIntoHistory;
 }
 
-export function setPreserveQueuedTurnsAsHistory(
+export function setFoldQueuedPromptsIntoHistory(
   state: TelegramBridgeRuntimeState,
-  preserve: boolean,
+  fold: boolean,
 ): void {
-  state.preserveQueuedTurnsAsHistory = preserve;
+  state.foldQueuedPromptsIntoHistory = fold;
 }
 
 export function isTelegramSetupInProgress(
@@ -392,7 +396,13 @@ export function startTelegramTypingLoop(
   if (state.typingInterval || deps.chatId === undefined || deps.chatId === 0)
     return false;
   const sendTyping = (): void => {
-    void deps.sendTypingAction(deps.chatId as number);
+    const typing = Promise.resolve(deps.sendTypingAction(deps.chatId as number))
+      .then(() => undefined)
+      .catch(() => undefined);
+    state.typingInFlight = typing;
+    void typing.finally(() => {
+      if (state.typingInFlight === typing) state.typingInFlight = undefined;
+    });
   };
   sendTyping();
   state.typingInterval = setInterval(sendTyping, deps.intervalMs);
@@ -408,6 +418,24 @@ export function stopTelegramTypingLoop(
   return true;
 }
 
+export async function waitForTelegramTypingLoopIdle(
+  state: TelegramBridgeRuntimeState,
+  timeoutMs = TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS,
+): Promise<void> {
+  const inFlight = state.typingInFlight;
+  if (!inFlight) return;
+  if (timeoutMs <= 0) {
+    await Promise.race([inFlight, Promise.resolve()]);
+    return;
+  }
+  await Promise.race([
+    inFlight,
+    new Promise<void>((resolve) => {
+      setTimeout(resolve, timeoutMs);
+    }),
+  ]);
+}
+
 export function createTelegramContextAbortHandlerSetter<
   TContext extends { abort: () => void },
 >(

package/lib/sections.ts

@@ -94,7 +94,7 @@ export interface TelegramSectionDiagnostic {
   id: TelegramSectionId;
   token: TelegramSectionToken;
   label: string;
-  status: "active" | "stale" | "error";
+  status: "active" | "error";
   lastError?: string;
 }
 
@@ -106,6 +106,12 @@ export interface TelegramSectionRegistry {
     token: TelegramSectionToken,
   ): RegisteredTelegramSection | undefined;
   getDiagnostics(): TelegramSectionDiagnostic[];
+  recordError(
+    token: TelegramSectionToken,
+    message: string,
+    source?: string,
+  ): void;
+  clearError(token: TelegramSectionToken, source?: string): void;
   clear(): void;
 }
 
@@ -299,6 +305,10 @@ function getUtf8ByteLength(value: string): number {
   return new TextEncoder().encode(value).byteLength;
 }
 
+function sectionErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function buildTelegramSectionCallbackData(
   token: TelegramSectionToken,
   action: string,
@@ -340,7 +350,10 @@ function prependBackRow(
 /** @internal */
 export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistry {
   const sections = new Map<TelegramSectionToken, RegisteredTelegramSection>();
-  const errors = new Map<TelegramSectionToken, string>();
+  const errors = new Map<
+    TelegramSectionToken,
+    { message: string; source: string }
+  >();
   let nextToken = 0;
 
   function register(section: TelegramSectionRegistration): () => void {
@@ -382,24 +395,46 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
       token: s.token,
       label: s.label,
       status: errors.has(s.token) ? "error" : "active",
-      lastError: errors.get(s.token),
+      lastError: errors.get(s.token)?.message,
     }));
   }
 
+  function recordError(
+    token: TelegramSectionToken,
+    message: string,
+    source = "runtime",
+  ): void {
+    if (sections.has(token)) errors.set(token, { message, source });
+  }
+
+  function clearError(token: TelegramSectionToken, source?: string): void {
+    const current = errors.get(token);
+    if (!source || !current || current.source === source) errors.delete(token);
+  }
+
   function clear(): void {
     sections.clear();
     errors.clear();
     nextToken = 0;
   }
 
-  return { register, getSections, getByToken, getDiagnostics, clear };
+  return {
+    register,
+    getSections,
+    getByToken,
+    getDiagnostics,
+    recordError,
+    clearError,
+    clear,
+  };
 }
 
 /** @internal */
 export function getTelegramExtensionSettingsRows(
   registry: TelegramSectionRegistry,
 ): TelegramSectionSettingsRow[] {
-  return registry
+  const rows: TelegramSectionSettingsRow[] = [];
+  for (const section of registry
     .getSections()
     .filter((s) => s.registration.settings)
     .sort((a, b) => {
@@ -407,22 +442,47 @@ export function getTelegramExtensionSettingsRows(
       const orderB = b.registration.settings!.order ?? 0;
       if (orderA !== orderB) return orderA - orderB;
       return a.id.localeCompare(b.id);
-    })
-    .map((s) => ({
-      label:
-        s.registration.settings!.getLabel?.() ?? s.registration.settings!.label,
-      callback_data: `section:${s.token}:settings:open`,
-    }));
+    })) {
+    try {
+      rows.push({
+        label:
+          section.registration.settings!.getLabel?.() ??
+          section.registration.settings!.label,
+        callback_data: `section:${section.token}:settings:open`,
+      });
+      registry.clearError(section.token, "settings_label");
+    } catch (error) {
+      registry.recordError(
+        section.token,
+        sectionErrorMessage(error),
+        "settings_label",
+      );
+    }
+  }
+  return rows;
 }
 
 /** @internal */
 export function getTelegramSectionMainMenuRows(
   registry: TelegramSectionRegistry,
 ): TelegramSectionMainMenuRow[] {
-  return registry.getSections().map((s) => ({
-    text: s.registration.getLabel?.() ?? s.label,
-    callback_data: `section:${s.token}:open`,
-  }));
+  const rows: TelegramSectionMainMenuRow[] = [];
+  for (const section of registry.getSections()) {
+    try {
+      rows.push({
+        text: section.registration.getLabel?.() ?? section.label,
+        callback_data: `section:${section.token}:open`,
+      });
+      registry.clearError(section.token, "main_label");
+    } catch (error) {
+      registry.recordError(
+        section.token,
+        sectionErrorMessage(error),
+        "main_label",
+      );
+    }
+  }
+  return rows;
 }
 
 /** @internal */
@@ -508,9 +568,11 @@ export async function handleTelegramSectionOpen(
       viewWithBack.replyMarkup,
     );
     await deps.answerCallbackQuery(callbackQueryId);
+    registry.clearError(token, "render");
     return true;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = sectionErrorMessage(error);
+    registry.recordError(token, message, "render");
     await deps.answerCallbackQuery(
       callbackQueryId,
       `Section error: ${message}`,
@@ -537,10 +599,10 @@ export async function handleTelegramSectionCallback(
     );
     return true;
   }
-  // Try main handleCallback first, then settings handleCallback as fallback
-  const handler =
-    section.registration.handleCallback ??
-    section.registration.settings?.handleCallback;
+  // Try main handleCallback first, then settings handleCallback as fallback.
+  const mainHandler = section.registration.handleCallback;
+  const settingsHandler = section.registration.settings?.handleCallback;
+  const handler = mainHandler ?? settingsHandler;
   if (!handler) {
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
@@ -555,16 +617,12 @@ export async function handleTelegramSectionCallback(
       payload,
       callbackQueryId,
       deps,
-      `section:${token}:open`,
+      mainHandler ? `section:${token}:open` : "settings:list",
     );
     let result = await handler(ctx);
     // Fallback: if main handler passed and settings handler exists, try settings
-    // with the correct navigation context (back → settings list)
-    if (
-      result === "pass" &&
-      handler !== section.registration.settings?.handleCallback &&
-      section.registration.settings?.handleCallback
-    ) {
+    // with the correct navigation context (back → settings list).
+    if (result === "pass" && mainHandler && settingsHandler) {
       const settingsCtx = buildTelegramSectionCallbackContext(
         section.id,
         token,
@@ -576,14 +634,16 @@ export async function handleTelegramSectionCallback(
         deps,
         "settings:list",
       );
-      result = await section.registration.settings.handleCallback(settingsCtx);
+      result = await settingsHandler(settingsCtx);
     }
     if (result === "pass") {
       await deps.answerCallbackQuery(callbackQueryId);
     }
+    registry.clearError(token, "callback");
     return true;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = sectionErrorMessage(error);
+    registry.recordError(token, message, "callback");
     await deps.answerCallbackQuery(
       callbackQueryId,
       `Section error: ${message}`,
@@ -632,9 +692,11 @@ export async function handleTelegramSectionSettingsOpen(
       viewWithBack.replyMarkup,
     );
     await deps.answerCallbackQuery(callbackQueryId);
+    registry.clearError(token, "settings_open");
     return true;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = sectionErrorMessage(error);
+    registry.recordError(token, message, "settings_open");
     await deps.answerCallbackQuery(
       callbackQueryId,
       `Section error: ${message}`,
@@ -677,9 +739,11 @@ export async function handleTelegramSectionSettingsCallback(
     if (result === "pass") {
       await deps.answerCallbackQuery(callbackQueryId);
     }
+    registry.clearError(token, "settings_callback");
     return true;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = sectionErrorMessage(error);
+    registry.recordError(token, message, "settings_callback");
     await deps.answerCallbackQuery(
       callbackQueryId,
       `Section error: ${message}`,

package/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);
@@ -462,7 +539,7 @@ export function buildTelegramStatusBarText(
     ? theme.fg("success", state.queuedStatus)
     : "";
   if (state.compactionInProgress) {
-    return `${label} ${theme.fg("accent", "compacting")}${queued}`;
+    return `${label} ${theme.fg("warning", "compacting")}${queued}`;
   }
   if (state.processing) {
     const processingStatus = state.queuedStatus
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.13.2",
+  "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"
   },