@llblab/pi-telegram 0.52.2 → 0.53.0

package/lib/status.ts

@@ -9,25 +9,53 @@ import { isDeepStrictEqual } from "node:util";
 
 /** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
 export function formatTelegramConnectionFailure(error: unknown): string {
-  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
-  const status = error && typeof error === "object" && "status" in error ? error.status : undefined;
-  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "";
+  const status =
+    error && typeof error === "object" && "status" in error
+      ? error.status
+      : undefined;
+  const code =
+    error && typeof error === "object" && "code" in error
+      ? error.code
+      : undefined;
   if (status === 401) return "Telegram token rejected. Run /telegram-setup.";
-  if (status === 403) return "Telegram access denied. Check /telegram-status --debug.";
-  if ((typeof code === "string" && ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET"].includes(code)) ||
-      /network unavailable|fetch failed/i.test(message)) {
+  if (status === 403)
+    return "Telegram access denied. Check /telegram-status --debug.";
+  if (
+    (typeof code === "string" &&
+      ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET"].includes(
+        code,
+      )) ||
+    /network unavailable|fetch failed/i.test(message)
+  ) {
     return "Telegram network unavailable. Retry /telegram-connect.";
   }
-  if (/Workspace slots?.*(?:unavailable|exhausted)|no free.*slot/i.test(message)) {
+  if (
+    /Workspace slots?.*(?:unavailable|exhausted)|no free.*slot/i.test(message)
+  ) {
     return "No Telegram slot available. Check /telegram-status --debug.";
   }
-  if (code === "incompatible-protocol" || /protocol.*(?:incompatible|mismatch)|incompatible.*protocol/i.test(message)) {
+  if (
+    code === "incompatible-protocol" ||
+    /protocol.*(?:incompatible|mismatch)|incompatible.*protocol/i.test(message)
+  ) {
     return "Telegram instances are incompatible. Update them together.";
   }
-  if (/unsupported.*(?:journal|version)|(?:journal|version).*unsupported/i.test(message)) {
+  if (
+    /unsupported.*(?:journal|version)|(?:journal|version).*unsupported/i.test(
+      message,
+    )
+  ) {
     return "Telegram state version unsupported. Use a compatible runtime.";
   }
-  if (/follower registration failed|active in another Pi instance/i.test(message)) {
+  if (
+    /follower registration failed|active in another Pi instance/i.test(message)
+  ) {
     return "Telegram leader is active but unavailable. Check /telegram-status --debug.";
   }
   if (/unfinished Thread creation does not match/i.test(message)) {
@@ -466,30 +494,15 @@ function truncateTelegramRuntimeEventText(
   return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
 }
 
-function redactTelegramRuntimeMessage(
-  message: string,
-  botToken: string | undefined,
-): string {
-  const redacted = botToken
-    ? message.split(botToken).join("<redacted-token>")
-    : message;
-  return truncateTelegramRuntimeEventText(
-    redacted,
-    MAX_TELEGRAM_RUNTIME_EVENT_MESSAGE_LENGTH,
-  );
-}
-
-function redactTelegramRuntimeDetail(
-  message: string,
+function redactTelegramRuntimeText(
+  text: string,
   botToken: string | undefined,
+  maxLength: number,
 ): string {
   const redacted = botToken
-    ? message.split(botToken).join("<redacted-token>")
-    : message;
-  return truncateTelegramRuntimeEventText(
-    redacted,
-    MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH,
-  );
+    ? text.split(botToken).join("<redacted-token>")
+    : text;
+  return truncateTelegramRuntimeEventText(redacted, maxLength);
 }
 
 function normalizeTelegramRuntimeEventDetails(
@@ -501,7 +514,11 @@ function normalizeTelegramRuntimeEventDetails(
   for (const [key, value] of Object.entries(details)) {
     if (value === undefined) continue;
     if (typeof value === "string") {
-      normalized[key] = redactTelegramRuntimeDetail(value, botToken);
+      normalized[key] = redactTelegramRuntimeText(
+        value,
+        botToken,
+        MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH,
+      );
       continue;
     }
     if (typeof value === "number" || typeof value === "boolean") {
@@ -512,7 +529,11 @@ function normalizeTelegramRuntimeEventDetails(
       normalized[key] = null;
       continue;
     }
-    normalized[key] = redactTelegramRuntimeDetail(String(value), botToken);
+    normalized[key] = redactTelegramRuntimeText(
+      String(value),
+      botToken,
+      MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH,
+    );
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
@@ -537,9 +558,10 @@ export function recordStructuredTelegramRuntimeEvent(
   events.push({
     at: options.now ?? Date.now(),
     category: input.category,
-    message: redactTelegramRuntimeMessage(
+    message: redactTelegramRuntimeText(
       getTelegramRuntimeEventMessage(input),
       options.botToken,
+      MAX_TELEGRAM_RUNTIME_EVENT_MESSAGE_LENGTH,
     ),
     ...(details ? { details } : {}),
   });
@@ -738,7 +760,9 @@ export function createTelegramBridgeStatusRuntime<
       const config = deps.getConfig();
       const queuedItems = deps.getQueuedItems();
       const hasPendingDispatch = deps.hasDispatchPending();
-      const waitingItems = hasPendingDispatch ? queuedItems.slice(1) : queuedItems;
+      const waitingItems = hasPendingDispatch
+        ? queuedItems.slice(1)
+        : queuedItems;
       const queuedItemCount =
         deps.getQueuedItemCount?.(waitingItems) ?? waitingItems.length;
       const hasActiveTurn = deps.hasActiveTurn();
@@ -797,9 +821,7 @@ export function createTelegramBridgeStatusRuntime<
         instanceThreadName: deps.getInstanceThreadName?.(),
         lockState: deps.getRuntimeLockState?.(),
         pollingActive: deps.isPollingActive(),
-        ...(deps.getPollingState
-          ? { polling: deps.getPollingState() }
-          : {}),
+        ...(deps.getPollingState ? { polling: deps.getPollingState() } : {}),
         ...(deps.getInboundWorkerState
           ? { inboundWorker: deps.getInboundWorkerState() }
           : {}),
@@ -891,12 +913,33 @@ export function createTelegramStatusSnapshot(
   };
 }
 
-function isRuntimeProjection(value: unknown): value is TelegramStoredRuntimeProjection {
+function isRuntimeProjection(
+  value: unknown,
+): value is TelegramStoredRuntimeProjection {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value as Record<string, unknown>;
-  return record.version === 1 && record.source === "snapshot" && Number.isSafeInteger(record.writtenAtMs) && (record.writtenAtMs as number) >= 0 &&
-    Object.keys(record).every(key => ["version", "source", "writtenAtMs", "runtime", "liveRoster", "diagnostics"].includes(key)) &&
-    ["runtime", "liveRoster", "diagnostics"].every(key => record[key] !== null && typeof record[key] === "object" && !Array.isArray(record[key]));
+  return (
+    record.version === 1 &&
+    record.source === "snapshot" &&
+    Number.isSafeInteger(record.writtenAtMs) &&
+    (record.writtenAtMs as number) >= 0 &&
+    Object.keys(record).every((key) =>
+      [
+        "version",
+        "source",
+        "writtenAtMs",
+        "runtime",
+        "liveRoster",
+        "diagnostics",
+      ].includes(key),
+    ) &&
+    ["runtime", "liveRoster", "diagnostics"].every(
+      (key) =>
+        record[key] !== null &&
+        typeof record[key] === "object" &&
+        !Array.isArray(record[key]),
+    )
+  );
 }
 export interface TelegramRuntimeProjectionScope {
   path: string;
@@ -920,7 +963,9 @@ export interface TelegramRuntimeProjectionStoreOptions {
   getNowMs?: () => number;
 }
 /** Observational runtime storage only; Workspace, admission, transport, logs and recovery remain with their owners. */
-export function createTelegramRuntimeProjectionStore(options: TelegramRuntimeProjectionStoreOptions): {
+export function createTelegramRuntimeProjectionStore(
+  options: TelegramRuntimeProjectionStoreOptions,
+): {
   read: () => TelegramStoredRuntimeProjection | undefined;
   persist: (snapshot: TelegramStatusSnapshot) => Promise<boolean>;
 } {
@@ -928,36 +973,69 @@ export function createTelegramRuntimeProjectionStore(options: TelegramRuntimePro
   const { getPath, getProfile: readProfile, captureAuthority } = options;
   const { read, publish } = options.storage;
   const getNowMs = options.getNowMs ?? Date.now;
-  const getProfile = (): string => readProfile() || TELEGRAM_STATUS_DEFAULT_PROFILE_NAME;
+  const getProfile = (): string =>
+    readProfile() || TELEGRAM_STATUS_DEFAULT_PROFILE_NAME;
   return {
     read() {
       try {
-        const path = getPath(), profile = getProfile(), value = read({ path, profile });
-        return getPath() === path && getProfile() === profile && isRuntimeProjection(value) ? value : undefined;
-      } catch { return undefined; }
+        const path = getPath(),
+          profile = getProfile(),
+          value = read({ path, profile });
+        return getPath() === path &&
+          getProfile() === profile &&
+          isRuntimeProjection(value)
+          ? value
+          : undefined;
+      } catch {
+        return undefined;
+      }
     },
     async persist(snapshot) {
-      const path = getPath(), profile = getProfile(), authority = captureAuthority();
+      const path = getPath(),
+        profile = getProfile(),
+        authority = captureAuthority();
       if (!authority) return false;
       // Freeze wire content at submission, but do not duplicate the event log in persistent runtime state.
-      const semantic = JSON.parse(JSON.stringify({ version: 1, source: "snapshot", runtime: snapshot.runtime,
-        liveRoster: snapshot.liveRoster, diagnostics: snapshot.diagnostics })) as Omit<TelegramStoredRuntimeProjection, "writtenAtMs">;
-      if (!isRuntimeProjection({ ...semantic, writtenAtMs: 0 })) throw new Error("Telegram runtime projection is malformed.");
+      const semantic = JSON.parse(
+        JSON.stringify({
+          version: 1,
+          source: "snapshot",
+          runtime: snapshot.runtime,
+          liveRoster: snapshot.liveRoster,
+          diagnostics: snapshot.diagnostics,
+        }),
+      ) as Omit<TelegramStoredRuntimeProjection, "writtenAtMs">;
+      if (!isRuntimeProjection({ ...semantic, writtenAtMs: 0 }))
+        throw new Error("Telegram runtime projection is malformed.");
       delete semantic.diagnostics.recentRuntimeEvents;
-      const isCurrent = (): boolean => getPath() === path && getProfile() === profile && authority() === true;
+      const isCurrent = (): boolean =>
+        getPath() === path && getProfile() === profile && authority() === true;
       const publication = publicationQueue.then(() => {
         if (!isCurrent()) return false;
-        return publish({ path, profile }, current => {
-          if (isRuntimeProjection(current)) {
-            const { writtenAtMs: _writtenAtMs, ...existing } = current;
-            if (isDeepStrictEqual(existing, semantic)) return { value: current, changed: false };
-          }
-          const writtenAtMs = getNowMs();
-          if (!Number.isSafeInteger(writtenAtMs) || writtenAtMs < 0) throw new Error("Telegram runtime projection timestamp is invalid.");
-          return { value: { ...semantic, writtenAtMs }, changed: true };
-        }, isCurrent) === true;
+        return (
+          publish(
+            { path, profile },
+            (current) => {
+              if (isRuntimeProjection(current)) {
+                const { writtenAtMs: _writtenAtMs, ...existing } = current;
+                if (isDeepStrictEqual(existing, semantic))
+                  return { value: current, changed: false };
+              }
+              const writtenAtMs = getNowMs();
+              if (!Number.isSafeInteger(writtenAtMs) || writtenAtMs < 0)
+                throw new Error(
+                  "Telegram runtime projection timestamp is invalid.",
+                );
+              return { value: { ...semantic, writtenAtMs }, changed: true };
+            },
+            isCurrent,
+          ) === true
+        );
       });
-      publicationQueue = publication.then(() => undefined, () => undefined);
+      publicationQueue = publication.then(
+        () => undefined,
+        () => undefined,
+      );
       return publication;
     },
   };
@@ -969,14 +1047,20 @@ export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
   persistSnapshot: (isCurrent: () => boolean) => Promise<void>;
   recordError: (error: unknown) => void;
   captureScope?: () => (() => boolean) | undefined;
-  setTimer?: (callback: () => void, ms: number) => { unref?: () => void } | number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => { unref?: () => void } | number;
   clearTimer?: (timer: { unref?: () => void } | number) => void;
 }): (() => void) & { resume(): void; suspend(): Promise<void> } {
   const setTimer = deps.setTimer ?? setTimeout;
-  const clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+  const clearTimer =
+    deps.clearTimer ??
+    ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
   let generation = 0;
   let enabled = true;
-  let timer: { token: object; handle: { unref?: () => void } | number } | undefined;
+  let timer:
+    { token: object; handle: { unref?: () => void } | number } | undefined;
   let persistPromise: Promise<void> | undefined;
   let pending: (() => boolean) | undefined;
   const recordError = (error: unknown): void => {
@@ -990,25 +1074,41 @@ export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
     const previous = timer;
     timer = undefined;
     if (previous) {
-      try { clearTimer(previous.handle); } catch (error) { recordError(error); }
+      try {
+        clearTimer(previous.handle);
+      } catch (error) {
+        recordError(error);
+      }
     }
   };
   const capture = (): (() => boolean) | undefined => {
     if (!enabled) return undefined;
     const expectedGeneration = generation;
     let scope: (() => boolean) | undefined;
-    try { scope = deps.captureScope ? deps.captureScope() : () => true; }
-    catch (error) { recordError(error); return undefined; }
+    try {
+      scope = deps.captureScope ? deps.captureScope() : () => true;
+    } catch (error) {
+      recordError(error);
+      return undefined;
+    }
     if (!scope) return undefined;
     return () => {
       if (!enabled || generation !== expectedGeneration) return false;
-      try { return scope!(); } catch (error) { recordError(error); return false; }
+      try {
+        return scope!();
+      } catch (error) {
+        recordError(error);
+        return false;
+      }
     };
   };
   const arm = (): void => {
     if (timer || persistPromise || !pending) return;
     const authority = pending;
-    if (!authority()) { pending = undefined; return; }
+    if (!authority()) {
+      pending = undefined;
+      return;
+    }
     const token = {};
     const handle = setTimer(() => {
       if (timer?.token !== token) return;
@@ -1018,7 +1118,11 @@ export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
       if (!authority() || !publicationAuthority?.()) return;
       let tracked: Promise<void>;
       tracked = Promise.resolve()
-        .then(() => publicationAuthority() ? deps.persistSnapshot(publicationAuthority) : undefined)
+        .then(() =>
+          publicationAuthority()
+            ? deps.persistSnapshot(publicationAuthority)
+            : undefined,
+        )
         .catch(recordError)
         .finally(() => {
           if (persistPromise !== tracked) return;
@@ -1069,11 +1173,7 @@ export function getTelegramStatusBarProcessingStatus(state: {
 }
 
 function getTelegramStatusBarLabel(state: TelegramStatusBarState): string {
-  const threadName = state.instanceThreadName?.trim();
-  if (!threadName) return "telegram";
-  const genericLabels = new Set(["telegram", "leader", "follower"]);
-  if (genericLabels.has(threadName.toLowerCase())) return "telegram";
-  return threadName;
+  return state.instanceThreadName?.trim() || "telegram";
 }
 
 export function buildTelegramStatusBarText(
@@ -1086,14 +1186,17 @@ export function buildTelegramStatusBarText(
     : "";
   if (!state.hasBotToken)
     return `${label} ${theme.fg("muted", "not configured")}${queued}`;
-  if (state.pollingStopReason === "persistent-conflict" && state.busRole !== "follower")
+  if (
+    state.pollingStopReason === "persistent-conflict" &&
+    state.busRole !== "follower"
+  )
     return `${label} ${theme.fg("error", "error")}`;
   if (!state.paired)
     return `${label} ${theme.fg("warning", "awaiting pairing")}${queued}`;
   if (state.busLifecyclePhase === "electing")
     return `${label} ${theme.fg("warning", "electing")}${queued}`;
   if (!state.pollingActive && state.busRole !== "follower")
-    return `${theme.fg("accent", "telegram")} ${theme.fg("dim", "disconnected")}${queued}`;
+    return `${label} ${theme.fg("dim", "disconnected")}${queued}`;
   if (state.error) {
     return `${label} ${theme.fg("error", "error")}${queued}`;
   }
@@ -1190,9 +1293,7 @@ function buildTelegramLocalBusLines(
     slot: localBus.followerSlot,
     threadName: localBus.followerThreadName,
   });
-  const protocol = formatTelegramBusProtocolIdentity(
-    localBus.leaderProtocol,
-  );
+  const protocol = formatTelegramBusProtocolIdentity(localBus.leaderProtocol);
   const followerLine = `- follower registered: ${localBus.followerRegistered ? "yes" : "no"}${label ? ` ${label}` : ""}${target}${protocol}`;
   const lines = ["", "local bus:", followerLine];
   if (options.verbose) {
@@ -1399,9 +1500,7 @@ function buildTelegramPollingDiagnosticLines(
   return [
     `- phase: ${polling.phase}`,
     ...(polling.phaseStartedAtMs !== undefined
-      ? [
-          `- phase started: ${new Date(polling.phaseStartedAtMs).toISOString()}`,
-        ]
+      ? [`- phase started: ${new Date(polling.phaseStartedAtMs).toISOString()}`]
       : []),
     ...(polling.currentUpdateId !== undefined
       ? [`- current update id: ${polling.currentUpdateId}`]
@@ -1472,7 +1571,9 @@ function buildTelegramInboundWorkerDiagnosticLines(
       ? [`- blocked reason: ${worker.blockedReason}`]
       : []),
     ...(worker.blockedInputCustody
-      ? [`- blocked input custody: update=${worker.blockedInputCustody.updateId}, kind=${worker.blockedInputCustody.kind}`]
+      ? [
+          `- blocked input custody: update=${worker.blockedInputCustody.updateId}, kind=${worker.blockedInputCustody.kind}`,
+        ]
       : []),
     ...(worker.lastCompletedUpdateId !== undefined
       ? [
@@ -1487,18 +1588,26 @@ function buildTelegramInboundWorkerDiagnosticLines(
   ];
 }
 
+function countTelegramQueueLanes(
+  items: TelegramBridgeStatusLineState["queuedItems"],
+): Record<TelegramStatusQueueLane, number> {
+  const counts: Record<TelegramStatusQueueLane, number> = {
+    control: 0,
+    priority: 0,
+    default: 0,
+  };
+  for (const item of items) counts[item.queueLane]++;
+  return counts;
+}
+
 function buildTelegramBridgeCompactStatusLines(
   state: TelegramBridgeStatusLineState,
 ): string[] {
-  const controlQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "control",
-  ).length;
-  const priorityQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "priority",
-  ).length;
-  const defaultQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "default",
-  ).length;
+  const {
+    control: controlQueueCount,
+    priority: priorityQueueCount,
+    default: defaultQueueCount,
+  } = countTelegramQueueLanes(state.queuedItems);
   const queueLine = `- queued turns: ${state.queuedItems.length}${
     state.queuedItems.length > 0
       ? ` (control=${controlQueueCount}, priority=${priorityQueueCount}, default=${defaultQueueCount})`
@@ -1566,15 +1675,11 @@ export function buildTelegramBridgeStatusLines(
 function buildTelegramBridgeDiagnosticStatusLines(
   state: TelegramBridgeStatusLineState,
 ): string[] {
-  const controlQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "control",
-  ).length;
-  const priorityQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "priority",
-  ).length;
-  const defaultQueueCount = state.queuedItems.filter(
-    (item) => item.queueLane === "default",
-  ).length;
+  const {
+    control: controlQueueCount,
+    priority: priorityQueueCount,
+    default: defaultQueueCount,
+  } = countTelegramQueueLanes(state.queuedItems);
   return [
     "connection:",
     `- bot: ${formatTelegramBridgeBotStatus(state)}`,
@@ -1631,13 +1736,6 @@ function buildTelegramBridgeDiagnosticStatusLines(
   ];
 }
 
-function escapeHtml(text: string): string {
-  return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
-
 function formatTokens(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -1773,3 +1871,10 @@ function buildStatusHtml(
   }
   return lines.join("\n");
 }
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}