@llblab/pi-telegram 0.24.3 → 0.24.5

package/lib/bindings.ts

@@ -99,6 +99,7 @@ interface TelegramCommandsAndToolsBindingDeps {
   activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
   lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
   stopPolling?: () => Promise<void | string>;
+  recoverPollingStart?: Commands.TelegramBridgeCommandRegistrationDeps["recoverPollingStart"];
   getDisconnectThreadName?: () => string | undefined;
   onTransportChanged?: () => Promise<void> | void;
   getStatusLines: (
@@ -127,6 +128,7 @@ export function registerTelegramCommandsAndTools({
   activeTurnRuntime,
   lockedPollingRuntime,
   stopPolling,
+  recoverPollingStart,
   getDisconnectThreadName,
   onTransportChanged,
   getStatusLines,
@@ -234,8 +236,16 @@ export function registerTelegramCommandsAndTools({
     getStatusLines,
     reloadConfig: configStore.load,
     hasBotToken: configStore.hasBotToken,
-    startPolling: lockedPollingRuntime.start,
+    startPolling: async (ctx, options) => {
+      try {
+        return await lockedPollingRuntime.start(ctx, options);
+      } catch (error) {
+        recordRuntimeEvent("recovery", error, { phase: "polling-start" });
+        throw error;
+      }
+    },
     stopPolling: stopPolling ?? lockedPollingRuntime.stop,
+    recoverPollingStart,
     getDisconnectThreadName,
     updateStatus,
     getProfileNames: () =>
@@ -295,10 +305,9 @@ interface TelegramLifecycleBindingDeps {
   >;
   promptDispatchRuntime: Runtime.TelegramPromptDispatchRuntime<Pi.ExtensionContext>;
   deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
-  lockOwnershipGuard: Pick<
-    Locks.TelegramLockOwnershipGuard<Pi.ExtensionContext>,
-    "ownsContext"
-  >;
+  modelContextAvailabilityRuntime: Prompts.TelegramModelContextAvailabilityRuntime;
+  disconnectOnQuit?: () => Promise<unknown>;
+  resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
   buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
   sendChatAction: NonNullable<
@@ -338,7 +347,6 @@ interface TelegramLifecycleBindingDeps {
     Keyboard.TelegramInlineKeyboardMarkup
   >["finalizeMarkdownPreview"];
   proactivePushTargetGetter: () => Queue.TelegramQueueTarget | undefined;
-  isProactivePushEnabled: () => boolean;
   getAssistantRenderingMode: () => "rich" | "html";
   recordMessageOwnership?: (input: {
     chatId: number;
@@ -367,7 +375,9 @@ export function registerTelegramLifecycleRuntimeHooks({
   previewRuntime,
   promptDispatchRuntime,
   deferredQueueDispatchRuntime,
-  lockOwnershipGuard,
+  modelContextAvailabilityRuntime,
+  disconnectOnQuit,
+  resolveAutomaticThreadCleanupEnabled,
   buttonActionStore,
   callMultipart,
   sendChatAction,
@@ -380,7 +390,6 @@ export function registerTelegramLifecycleRuntimeHooks({
   sendGuestReply,
   finalizeMarkdownPreview,
   proactivePushTargetGetter,
-  isProactivePushEnabled,
   getAssistantRenderingMode,
   recordMessageOwnership,
   canSendAgentActivity,
@@ -629,6 +638,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       previewRuntime.invalidate();
       assistantOutputRuntime.start();
       activityRuntime.onSessionStart?.();
+      modelContextAvailabilityRuntime.reconcile();
       await sessionLifecycleRuntime.onSessionStart(event, ctx);
     },
     async onSessionShutdown(event, ctx) {
@@ -637,6 +647,17 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onSessionShutdown();
       assistantOutputRuntime.stop();
       compactionObserver.onSessionShutdown();
+      if (event.reason === "quit" && disconnectOnQuit) {
+        try {
+          const automaticCleanupEnabled =
+            (await resolveAutomaticThreadCleanupEnabled?.()) ?? true;
+          if (automaticCleanupEnabled) await disconnectOnQuit();
+        } catch (error) {
+          recordRuntimeEvent("session", error, {
+            phase: "automatic-disconnect-on-quit",
+          });
+        }
+      }
       await sessionLifecycleRuntime.onSessionShutdown(event, ctx);
     },
     onSessionBeforeCompact(event, ctx) {
@@ -704,11 +725,11 @@ export function registerTelegramLifecycleRuntimeHooks({
       if (!isSessionContextActive(ctx)) return;
       await agentLifecycleHooks.onAgentSettled(event, ctx);
       activityRuntime.onAgentSettled();
+      modelContextAvailabilityRuntime.reconcile();
     },
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
-      isConfigured: configStore.hasBotToken,
-      isProactivePushEnabled,
-      isCurrentOwner: lockOwnershipGuard.ownsContext,
+      reconcileAvailability: modelContextAvailabilityRuntime.reconcile,
+      isAvailable: canSendAgentActivity,
     }),
   });
 }

package/lib/bus-follower.ts

@@ -138,6 +138,17 @@ export interface TelegramBusFollowerSessionRefreshHookDeps<TContext> {
   ) => void;
 }
 
+export type TelegramBusFollowerControlLifecyclePhase = "electing";
+
+export interface TelegramBusFollowerControlState {
+  getActiveAuthSecret: () => string | undefined;
+  setActiveAuthSecret: (secret: string | undefined) => void;
+  getLifecyclePhase: () => TelegramBusFollowerControlLifecyclePhase | undefined;
+  setLifecyclePhase: (
+    phase: TelegramBusFollowerControlLifecyclePhase | undefined,
+  ) => void;
+}
+
 export interface TelegramBusFollowerRegistrationState {
   isRegistered: () => boolean;
   getTarget: () => TelegramTarget | undefined;
@@ -841,7 +852,24 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
   };
 }
 
-export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowerRegistrationState {
+export function createTelegramBusFollowerControlState(): TelegramBusFollowerControlState {
+  let activeAuthSecret: string | undefined;
+  let lifecyclePhase: TelegramBusFollowerControlLifecyclePhase | undefined;
+  return {
+    getActiveAuthSecret: () => activeAuthSecret,
+    setActiveAuthSecret(secret) {
+      activeAuthSecret = secret;
+    },
+    getLifecyclePhase: () => lifecyclePhase,
+    setLifecyclePhase(phase) {
+      lifecyclePhase = phase;
+    },
+  };
+}
+
+export function createTelegramBusFollowerRegistrationState(
+  options: { onAvailabilityChanged?: () => void } = {},
+): TelegramBusFollowerRegistrationState {
   let registered = false;
   let target: TelegramTarget | undefined;
   let slot: string | undefined;
@@ -861,11 +889,13 @@ export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowe
       ).sort();
     },
     setRegistered: (next, nextTarget, metadata) => {
+      const availabilityChanged = registered !== next;
       registered = next;
       target = next ? (nextTarget ? { ...nextTarget } : undefined) : undefined;
       slot = next ? metadata?.slot : undefined;
       threadName = next ? metadata?.threadName : undefined;
       generation = next ? metadata?.generation : undefined;
+      if (availabilityChanged) options.onAvailabilityChanged?.();
     },
   };
 }

package/lib/commands.ts

@@ -297,6 +297,11 @@ export interface TelegramBridgeCommandStartPollingResult {
   owner?: string;
 }
 
+export type TelegramPollingStartRecoveryResult =
+  | { kind: "unhandled" }
+  | { kind: "retry"; message: string }
+  | { kind: "blocked"; message: string };
+
 export interface TelegramBridgeCommandRegistrationDeps {
   promptForConfig: (ctx: ExtensionCommandContext, profileName?: string) => Promise<void>;
   getStatusLines: (options?: TelegramBridgeStatusLineOptions) => string[];
@@ -310,6 +315,9 @@ export interface TelegramBridgeCommandRegistrationDeps {
     | Promise<void | TelegramBridgeCommandStartPollingResult>
     | TelegramBridgeCommandStartPollingResult;
   stopPolling: () => Promise<void | string>;
+  recoverPollingStart?: (
+    error: unknown,
+  ) => Promise<TelegramPollingStartRecoveryResult>;
   getDisconnectThreadName?: () => string | undefined;
   updateStatus: (ctx: ExtensionCommandContext) => void;
   getProfileNames?: () => string[];
@@ -390,7 +398,41 @@ export function registerTelegramBridgeCommands(
         await deps.promptForConfig(ctx, profileName);
         return;
       }
-      let result = await deps.startPolling(ctx, {
+      let recoveryUsed = false;
+      const startWithRecovery = async (
+        options: TelegramBridgeCommandStartPollingOptions,
+      ): Promise<void | TelegramBridgeCommandStartPollingResult> => {
+        try {
+          return await deps.startPolling(ctx, options);
+        } catch (error) {
+          if (!deps.recoverPollingStart || recoveryUsed) throw error;
+          const recovery = await deps.recoverPollingStart(error);
+          if (recovery.kind === "unhandled") throw error;
+          if (recovery.kind === "blocked") {
+            return { ok: false, message: recovery.message };
+          }
+          recoveryUsed = true;
+          try {
+            const retry = await deps.startPolling(ctx, options);
+            if (!retry) {
+              return { ok: true, message: recovery.message };
+            }
+            return {
+              ...retry,
+              message: retry.ok
+                ? `${recovery.message} ${retry.message ?? "Telegram bridge connected."}`
+                : retry.message,
+            };
+          } catch {
+            return {
+              ok: false,
+              message:
+                "Telegram temporary state was recovered, but the bridge could not restart. Restart this Pi instance and run /telegram-connect again.",
+            };
+          }
+        }
+      };
+      let result = await startWithRecovery({
         forceFreshLeaderThread: true,
       });
       if (result && !result.ok && result.canTakeover) {
@@ -403,7 +445,7 @@ export function registerTelegramBridgeCommands(
           deps.updateStatus(ctx);
           return;
         }
-        result = await deps.startPolling(ctx, {
+        result = await startWithRecovery({
           force: true,
           forceFreshLeaderThread: true,
         });

package/lib/config.ts

@@ -87,6 +87,10 @@ export interface TelegramConfig {
     sendTranscript?: boolean;
   };
   time?: TelegramTimeConfig;
+  threads?: {
+    /** Delete this instance's bound Telegram thread on graceful Pi quit. */
+    automaticCleanup?: boolean;
+  };
   /** Canonical bot/session profiles, including profiles.default. */
   profiles?: Record<string, TelegramBotProfile>;
 }
@@ -140,6 +144,7 @@ export interface TelegramConfigStore {
   getOutboundHandlers: () => TelegramOutboundHandlerConfig[] | undefined;
   setAllowedUserId: (userId: number) => void;
   load: () => Promise<void>;
+  didLastLoadRecoverInvalidConfig: () => boolean;
   persist: (config?: TelegramConfig) => Promise<void>;
 }
 
@@ -188,6 +193,7 @@ type TelegramMutableConfigStore = Pick<
   "get" | "set" | "persist"
 > & {
   load?: () => Promise<void>;
+  didLastLoadRecoverInvalidConfig?: () => boolean;
 };
 
 function isEmptyTelegramConfig(config: TelegramConfig): boolean {
@@ -498,6 +504,7 @@ export function createTelegramConfigStore(
   let mutationVersion = 0;
   let persistQueue: Promise<void> = Promise.resolve();
   let activeProfileName: string | undefined;
+  let lastLoadRecoveredInvalidConfig = false;
   const agentDir = options.agentDir ?? resolveAgentDir();
   const configPath = options.configPath ?? getConfigPath();
   const getEffectiveConfig = () =>
@@ -556,8 +563,10 @@ export function createTelegramConfigStore(
       setEffectiveConfig(nextConfig);
     },
     load: async () => {
+      lastLoadRecoveredInvalidConfig = false;
       const loadedConfig = await readTelegramConfig(configPath, {
         onInvalidConfig: (recovery) => {
+          lastLoadRecoveredInvalidConfig = true;
           options.recordRuntimeEvent?.("config", recovery.error, {
             phase: "load",
             configPath: recovery.configPath,
@@ -593,6 +602,7 @@ export function createTelegramConfigStore(
       persistedConfig = cloneTelegramConfig(config);
       mutationVersion += 1;
     },
+    didLastLoadRecoverInvalidConfig: () => lastLoadRecoveredInvalidConfig,
     persist: (nextConfig = getEffectiveConfig()) => {
       const profileName = activeProfileName;
       const desiredConfig = storeTelegramEffectiveConfig(
@@ -862,6 +872,41 @@ export function createTelegramProactivePushTargetGetter(deps: {
   };
 }
 
+export function createTelegramAutomaticThreadCleanupChecker(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => boolean {
+  return () => configStore.get().threads?.automaticCleanup ?? true;
+}
+
+export function createTelegramAutomaticThreadCleanupResolver(
+  configStore: TelegramMutableConfigStore,
+): () => Promise<boolean> {
+  return async () => {
+    await loadLatestTelegramConfig(configStore);
+    if (configStore.didLastLoadRecoverInvalidConfig?.()) {
+      throw new Error(
+        "Automatic thread cleanup setting is unavailable after invalid Telegram config recovery.",
+      );
+    }
+    return createTelegramAutomaticThreadCleanupChecker(configStore)();
+  };
+}
+
+export function createTelegramAutomaticThreadCleanupSetter(
+  configStore: TelegramMutableConfigStore,
+): (enabled: boolean) => Promise<void> {
+  return async (enabled) => {
+    await loadLatestTelegramConfig(configStore);
+    const current = configStore.get();
+    const config = {
+      ...current,
+      threads: { ...current.threads, automaticCleanup: enabled },
+    };
+    configStore.set(config);
+    await configStore.persist(config);
+  };
+}
+
 export function createTelegramConfigControls(
   configStore: TelegramMutableConfigStore,
 ) {
@@ -880,6 +925,12 @@ export function createTelegramConfigControls(
     setVoiceReplyMode: createTelegramVoiceReplyModeSetter(configStore),
     getTimeInjectionMode: createTelegramTimeInjectionModeGetter(configStore),
     setTimeInjectionMode: createTelegramTimeInjectionModeSetter(configStore),
+    isAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupChecker(configStore),
+    resolveAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupResolver(configStore),
+    setAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupSetter(configStore),
   };
 }
 

package/lib/locks.ts

@@ -176,6 +176,42 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(buffer), 0, 0, ms);
 }
 
+export interface TelegramRenameRetryOptions {
+  rename?: typeof renameSync;
+  attempts?: number;
+  retryDelayMs?: number;
+}
+
+/** Rename one Telegram runtime artifact with bounded Windows sharing retries. */
+export function renameTelegramPathWithRetry(
+  sourcePath: string,
+  destinationPath: string,
+  options: TelegramRenameRetryOptions = {},
+): boolean {
+  const rename = options.rename ?? renameSync;
+  const attempts = Math.max(
+    1,
+    options.attempts ?? TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS,
+  );
+  const retryDelayMs = Math.max(
+    0,
+    options.retryDelayMs ?? TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS,
+  );
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      rename(sourcePath, destinationPath);
+      return true;
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "ENOENT") return false;
+      if (!isRetryableLockWriteError(error) || attempt === attempts - 1) {
+        throw error;
+      }
+      sleepSync(retryDelayMs * (attempt + 1));
+    }
+  }
+  return false;
+}
+
 interface TelegramLockTransactionOwner {
   pid: number;
   acquiredAtMs: number;
@@ -307,29 +343,11 @@ function releaseLockTransactionGuard(
     );
   }
   const releasedPath = `${path}.released.${randomUUID()}`;
-  for (
-    let attempt = 0;
-    attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
-    attempt += 1
-  ) {
-    try {
-      renameSync(path, releasedPath);
-      try {
-        removeLockTransactionGuard(releasedPath);
-      } catch {
-        /* released debris cannot retain transaction authority */
-      }
-      return;
-    } catch (error) {
-      if ((error as { code?: unknown })?.code === "ENOENT") return;
-      if (
-        !isRetryableLockWriteError(error) ||
-        attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
-      ) {
-        throw error;
-      }
-      sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
-    }
+  if (!renameTelegramPathWithRetry(path, releasedPath)) return;
+  try {
+    removeLockTransactionGuard(releasedPath);
+  } catch {
+    /* released debris cannot retain transaction authority */
   }
 }
 
@@ -411,28 +429,8 @@ function reclaimAbandonedDirectoryGuard(
     throw error;
   }
 
-  const renameWithRetry = (fromPath: string, toPath: string): boolean => {
-    for (
-      let attempt = 0;
-      attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
-      attempt += 1
-    ) {
-      try {
-        renameRecovery(fromPath, toPath);
-        return true;
-      } catch (error) {
-        if ((error as { code?: unknown })?.code === "ENOENT") return false;
-        if (
-          !isRetryableLockWriteError(error) ||
-          attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
-        ) {
-          throw error;
-        }
-        sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
-      }
-    }
-    return false;
-  };
+  const renameWithRetry = (fromPath: string, toPath: string): boolean =>
+    renameTelegramPathWithRetry(fromPath, toPath, { rename: renameRecovery });
 
   activeReclaims.add(reclaimGeneration);
   const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;
@@ -1139,6 +1137,7 @@ export interface TelegramLockedPollingRuntimeDeps<
     owner: TelegramLockEntry,
   ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
+  onTransportAvailabilityChanged?: () => void;
   updateStatus: (ctx: TContext) => void;
   recordRuntimeEvent?: (
     category: string,
@@ -1189,6 +1188,7 @@ export function createTelegramLockedPollingRuntime<
   const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
     stopOwnershipWatcher();
+    deps.onTransportAvailabilityChanged?.();
     ownershipStop = deps
       .stopPolling()
       .catch((error) =>
@@ -1242,12 +1242,14 @@ export function createTelegramLockedPollingRuntime<
         });
       }
       deps.lock.release();
+      deps.onTransportAvailabilityChanged?.();
       throw error;
     }
     if (deps.lock.owns(ctx)) return true;
     stopOwnershipWatcher();
     if (ownershipStop) await ownershipStop;
     await deps.stopPolling();
+    deps.onTransportAvailabilityChanged?.();
     return false;
   };
   const canStartPolling = (ctx: TContext): boolean =>
@@ -1337,6 +1339,7 @@ export function createTelegramLockedPollingRuntime<
           message: "Telegram leadership changed during polling startup.",
         };
       }
+      deps.onTransportAvailabilityChanged?.();
       deps.updateStatus(ctx);
       const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
       return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
@@ -1344,6 +1347,7 @@ export function createTelegramLockedPollingRuntime<
     stop: async () => {
       await suspendPolling();
       const state = deps.lock.release();
+      deps.onTransportAvailabilityChanged?.();
       if (state.kind === "active-elsewhere") {
         return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
       }
@@ -1391,6 +1395,7 @@ export function createTelegramLockedPollingRuntime<
         if (generation !== sessionAutoStartGeneration) return;
         if (!(await runOwnedPollingStart(ctx, {}))) return;
         if (generation !== sessionAutoStartGeneration) return;
+        deps.onTransportAvailabilityChanged?.();
         deps.updateStatus(ctx);
         deps.recordRuntimeEvent?.("lock", "Telegram auto-start completed", {
           phase: "auto-start-complete",