@llblab/pi-telegram 0.20.3 → 0.20.5

package/lib/bindings.ts

@@ -127,22 +127,29 @@ export function registerTelegramCommandsAndTools({
         });
         setupConfigStore.activateProfile(profileName);
         persistSetupConfig = async () => {
+          try {
+            configStore.activateProfile(undefined);
+            configStore.set({
+              ...storedConfig,
+              profiles: {
+                ...(storedConfig.profiles ?? {}),
+                [profileName]: storedConfig.profiles?.[profileName] ?? {
+                  botToken: "",
+                },
+              },
+            });
+            configStore.activateProfile(profileName);
+            configStore.set(setupConfigStore.get());
+            await persistConfig();
+          } catch (error) {
+            configStore.activateProfile(undefined);
+            configStore.set(storedConfig);
+            configStore.activateProfile(previousProfileName);
+            throw error;
+          }
           if (previousProfileName !== profileName) {
             await (stopPolling ?? lockedPollingRuntime.stop)();
           }
-          configStore.activateProfile(undefined);
-          configStore.set({
-            ...storedConfig,
-            profiles: {
-              ...(storedConfig.profiles ?? {}),
-              [profileName]: storedConfig.profiles?.[profileName] ?? {
-                botToken: "",
-              },
-            },
-          });
-          configStore.activateProfile(profileName);
-          configStore.set(setupConfigStore.get());
-          await persistConfig();
         };
       }
       const runSetup = Setup.createTelegramSetupPromptRuntime({
@@ -242,14 +249,8 @@ interface TelegramLifecycleBindingDeps {
   >["sendTextReply"] &
     NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendTextReply"]>;
   dispatchNextQueuedTelegramTurn: (ctx: Pi.ExtensionContext) => void;
-  answerGuestQuery: NonNullable<
-    Queue.TelegramAgentEndHookRuntimeDeps<
-      Queue.PendingTelegramTurn,
-      Pi.ExtensionContext,
-      Pi.AgentEndEvent["messages"][number],
-      Keyboard.TelegramInlineKeyboardMarkup
-    >["answerGuestQuery"]
-  >;
+  answerGuestQuery: TelegramApi.TelegramBridgeApiRuntime["answerGuestQuery"];
+  deleteMessage: TelegramApi.TelegramBridgeApiRuntime["deleteMessage"];
   sendGuestReply: NonNullable<
     Queue.TelegramAgentEndHookRuntimeDeps<
       Queue.PendingTelegramTurn,
@@ -295,6 +296,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   sendTextReply,
   dispatchNextQueuedTelegramTurn,
   answerGuestQuery,
+  deleteMessage,
   sendGuestReply,
   finalizeMarkdownPreview,
   proactivePushChatIdGetter,
@@ -319,18 +321,107 @@ export function registerTelegramLifecycleRuntimeHooks({
       sendTextReply,
       recordRuntimeEvent,
     });
-  const outboundReplyPlanner =
-    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
-  const outboundReplyArtifactSender =
-    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
-      execCommand: CommandTemplates.execCommandTemplate,
+  const sendGuestAttachment = async (
+    turn: Queue.PendingTelegramTurn,
+    attachment: Queue.QueuedAttachment,
+    caption?: string,
+  ): Promise<void> => {
+    const stagingTarget = proactivePushTargetGetter();
+    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    if (stagingChatId === undefined) {
+      throw new Error("Guest attachment staging requires a paired Telegram chat");
+    }
+    await OutboundAttachments.deliverTelegramGuestCachedAttachment({
+      guestQueryId: turn.guestQueryId!,
+      stagingChatId,
+      stagingTarget,
+      attachment,
+      caption,
       sendMultipart: callMultipart,
-      sendTextReply,
-      sendChatAction,
-      sendRecordVoiceAction,
-      getHandlers: configStore.getOutboundHandlers,
+      answerGuestQuery: (guestQueryId, result) =>
+        answerGuestQuery(guestQueryId, undefined, { result }),
+      answerGuestText: (guestQueryId, text) =>
+        answerGuestQuery(guestQueryId, text),
+      fallbackText:
+        caption || "Telegram bridge could not deliver the requested attachment.",
+      deleteMessage,
       recordRuntimeEvent,
     });
+  };
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const voiceReplySenderDeps = {
+    execCommand: CommandTemplates.execCommandTemplate,
+    sendMultipart: callMultipart,
+    sendTextReply,
+    sendChatAction,
+    sendRecordVoiceAction,
+    getHandlers: configStore.getOutboundHandlers,
+    recordRuntimeEvent,
+  };
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender(
+      voiceReplySenderDeps,
+    );
+  const sendGuestVoiceReply = async (
+    turn: Queue.PendingTelegramTurn,
+    plan: OutboundHandlers.TelegramOutboundReplyPlan,
+    caption?: string,
+  ): Promise<void> => {
+    const stagingTarget = proactivePushTargetGetter();
+    const stagingChatId = stagingTarget?.chatId ?? proactivePushChatIdGetter();
+    if (stagingChatId === undefined) {
+      throw new Error("Guest voice staging requires a paired Telegram chat");
+    }
+    const guestVoiceSender =
+      OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+        ...voiceReplySenderDeps,
+        sendChatAction: undefined,
+        sendRecordVoiceAction: undefined,
+        sendMultipart: async (
+          _method,
+          _fields,
+          _fileField,
+          filePath,
+          fileName,
+        ) => {
+          try {
+            await OutboundAttachments.deliverTelegramGuestCachedAttachment({
+              guestQueryId: turn.guestQueryId!,
+              stagingChatId,
+              stagingTarget,
+              attachment: { path: filePath, fileName },
+              caption,
+              sendMultipart: callMultipart,
+              answerGuestQuery: (guestQueryId, result) =>
+                answerGuestQuery(guestQueryId, undefined, { result }),
+              answerGuestText: (guestQueryId, text) =>
+                answerGuestQuery(guestQueryId, text),
+              fallbackText:
+                caption || "Telegram bridge could not deliver the voice reply.",
+              deleteMessage,
+              recordRuntimeEvent,
+            });
+          } catch (error) {
+            recordRuntimeEvent("delivery", error, {
+              phase: "guest-voice-answer",
+              guestQueryId: turn.guestQueryId,
+            });
+          }
+          return {};
+        },
+      });
+    await guestVoiceSender(
+      turn,
+      {
+        ...plan,
+        ...(plan.voiceReplies?.length
+          ? { voiceReplies: [plan.voiceReplies[0]!] }
+          : {}),
+      },
+      { replyToPrompt: false },
+    );
+  };
   const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
     Queue.PendingTelegramTurn,
     Pi.ExtensionContext,
@@ -383,6 +474,8 @@ export function registerTelegramLifecycleRuntimeHooks({
     sendQueuedAttachments: queuedAttachmentSender,
     answerGuestQuery,
     sendGuestReply,
+    sendGuestAttachment,
+    sendGuestVoiceReply,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     getDefaultChatId: proactivePushChatIdGetter,
@@ -398,8 +491,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
   );
-  const startAgentActivityTypingLoop = (ctx: Pi.ExtensionContext): void => {
-    if (!canSendAgentActivity(ctx)) return;
+  const startAgentActivityTypingLoop = (ctx: Pi.ExtensionContext): boolean => {
+    if (!canSendAgentActivity(ctx)) return false;
     const turn = activeTurnRuntime.get();
     const target = turn?.target ?? proactivePushTargetGetter();
     promptDispatchRuntime.startTypingLoop(
@@ -407,6 +500,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       turn?.chatId ?? target?.chatId ?? proactivePushChatIdGetter(),
       { target },
     );
+    return true;
   };
   const startActiveTurnTypingLoop = (ctx: Pi.ExtensionContext): void => {
     const turn = activeTurnRuntime.get();
@@ -417,9 +511,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
     setCompactionInProgress: lifecycle.setCompactionInProgress,
     updateStatus,
-    startTypingLoop: startActiveTurnTypingLoop,
+    startTypingLoop: startAgentActivityTypingLoop,
     stopTypingLoop: typing.stop,
-    shouldStartTypingLoop: activeTurnRuntime.has,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
     dispatchNextQueuedTelegramTurn,

package/lib/bus-api.ts

@@ -5,10 +5,10 @@
  */
 
 import type {
+  TelegramAnswerGuestQueryOptions,
   TelegramApiCallOptions,
   TelegramBridgeApiRuntime,
   TelegramEditMessageTextBody,
-  TelegramInputRichMessage,
   TelegramSendMessageBody,
   TelegramSendMessageDraftBody,
   TelegramSendRichMessageBody,
@@ -273,14 +273,16 @@ export function createTelegramBusAwareApiRuntime(
     async answerGuestQuery(
       guestQueryId: string,
       text?: string,
-      options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
+      options?: TelegramAnswerGuestQueryOptions,
     ): Promise<void> {
       if (deps.ownsDirect()) {
         await deps.directRuntime.answerGuestQuery(guestQueryId, text, options);
         return;
       }
       const body: Record<string, unknown> = { guest_query_id: guestQueryId };
-      if (text !== undefined || options?.richMessage) {
+      if (options?.result) {
+        body.result = options.result;
+      } else if (text !== undefined || options?.richMessage) {
         const inputContent: Record<string, unknown> = options?.richMessage
           ? { rich_message: options.richMessage }
           : { message_text: text };

package/lib/bus-follower.ts

@@ -777,6 +777,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
   let activeAuthSecret: string | undefined;
   let activeContext: TContext | undefined;
   let lastKnownTarget: TelegramTarget | undefined;
+  let lastKnownSlot: string | undefined;
+  let lastKnownThreadName: string | undefined;
   const stopHeartbeat = () => {
     if (!heartbeatInterval) return;
     clearInterval(heartbeatInterval);
@@ -788,6 +790,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
     deps.setActiveAuthSecret?.(undefined);
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
+    lastKnownSlot = undefined;
+    lastKnownThreadName = undefined;
     activeContext = undefined;
     void deps.stopReceiving?.();
   };
@@ -849,8 +853,13 @@ export function createTelegramBusFollowerRegistrationRuntime<
             deps.getProfileKey?.(ctx) ??
             (ctx.cwd ? `cwd:${ctx.cwd}` : undefined),
           threadName:
+            deps.registrationState?.getThreadName() ??
+            lastKnownThreadName ??
             deps.getThreadName?.(ctx) ??
             (ctx.cwd ? basename(ctx.cwd) : undefined),
+          ...(deps.registrationState?.getSlot() ?? lastKnownSlot
+            ? { slot: deps.registrationState?.getSlot() ?? lastKnownSlot }
+            : {}),
           cwd: ctx.cwd,
           pid: getPid(),
           target:
@@ -912,6 +921,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
           registrationResult,
         );
         lastKnownTarget = registrationResult.target;
+        lastKnownSlot = registrationResult.slot;
+        lastKnownThreadName = registrationResult.threadName;
         activeLeaderSocketPath = leaderSocketPath;
         activeContext = ctx;
         await sendHeartbeat();

package/lib/bus-leader.ts

@@ -477,6 +477,22 @@ export function createTelegramBusFollowerTargetProvisioner(
       : undefined;
     const followerOwner =
       Threads.getTelegramThreadOwnerFromProfileKey(followerProfileKey);
+    const recoverableTarget =
+      !reconnectRecord &&
+      registration.target?.chatId === chatId &&
+      registration.target.threadId !== undefined &&
+      !recordsBeforeProvision.some(
+        (record) =>
+          record.target.chatId === registration.target?.chatId &&
+          record.target.threadId === registration.target.threadId,
+      )
+        ? registration.target
+        : undefined;
+    const recoveryHint = recoverableTarget
+      ? deps.topicTargetStore.getFollowerRecoveryHintByTarget?.(
+          recoverableTarget,
+        )
+      : undefined;
     const registrationKey = followerProfileKey || registration.instanceId;
     const pendingRegistration = pendingRegistrations.get(registrationKey);
     if (pendingRegistration) return pendingRegistration;
@@ -499,12 +515,69 @@ export function createTelegramBusFollowerTargetProvisioner(
         deps.onProvisioningEnd?.();
       }
     };
+    const recoverRequestedTarget = async () => {
+      const nowMs = getNowMs();
+      const requestedThreadName =
+        registration.threadName &&
+        Threads.isTelegramTopicThreadNameValidForSlot(
+          registration.threadName,
+          registration.slot,
+        )
+          ? registration.threadName
+          : recoveryHint?.threadName &&
+              Threads.isTelegramTopicThreadNameValidForSlot(
+                recoveryHint.threadName,
+                recoveryHint.slot,
+              )
+            ? recoveryHint.threadName
+            : undefined;
+      let recoveredRecord = deps.topicTargetStore.upsert({
+        profileKey: followerProfileKey,
+        owner:
+          followerOwner.kind === "manual-follower"
+            ? followerOwner
+            : {
+                kind: "manual-follower",
+                instanceId: registration.instanceId,
+              },
+        target: {
+          chatId: recoverableTarget!.chatId,
+          threadId: recoverableTarget!.threadId!,
+        },
+        status: "active",
+        createdAtMs: registration.connectedAtMs || nowMs,
+        updatedAtMs: nowMs,
+        instanceId: registration.instanceId,
+        ...(requestedThreadName ? { threadName: requestedThreadName } : {}),
+        lastSyncObservedAtMs: nowMs,
+        lastReconcileAction: "follower-live-target-recovery",
+      });
+      const requestedSlot = registration.slot ?? recoveryHint?.slot;
+      const requestedSlotAvailable =
+        !!requestedSlot &&
+        /^[A-Z]$/.test(requestedSlot) &&
+        !recordsBeforeProvision.some((record) => record.slot === requestedSlot);
+      if (requestedSlotAvailable) {
+        recoveredRecord = deps.topicTargetStore.upsert({
+          ...recoveredRecord,
+          slot: requestedSlot,
+        });
+      }
+      await deps.topicTargetStore.persist();
+      return {
+        target: recoveredRecord.target,
+        reused: true,
+        record: recoveredRecord,
+      };
+    };
     const runRegistration = async (): Promise<
       (TelegramTarget & { slot?: string; threadName?: string }) | undefined
     > => {
     let result = reconnectRecord
       ? { target: reconnectRecord.target, reused: true, record: reconnectRecord }
-      : await provisionTarget();
+      : recoverableTarget
+        ? await recoverRequestedTarget()
+        : await provisionTarget();
     if (reconnectRecord) {
       const nowMs = getNowMs();
       const transferredRecord = deps.topicTargetStore.upsert({
@@ -1126,6 +1199,13 @@ export function createTelegramBusLeaderRuntime<TContext>(
     followerRealityTimer.unref?.();
   };
   const pruneFollowers = async () => {
+    try {
+      await localServer.ensureEndpoint();
+    } catch (error) {
+      deps.recordRuntimeEvent?.("bus", error, {
+        phase: "leader-endpoint-recovery",
+      });
+    }
     const removed = deps.followerRegistry.pruneStale(
       getNowMs(),
       followerStaleAfterMs,

package/lib/bus.ts

@@ -98,6 +98,7 @@ export interface TelegramBusInstanceRegistration {
   instanceId: string;
   profileKey?: string;
   threadName?: string;
+  slot?: string;
   cwd?: string;
   pid?: number;
   target?: TelegramTarget;
@@ -164,6 +165,7 @@ export function isTelegramFollowerApiCallAllowed(input: {
     "sendRichMessageDraft",
   ]);
   const allowedMultipartMethods = new Set([
+    "sendAudio",
     "sendDocument",
     "sendMediaGroup",
     "sendPhoto",
@@ -383,6 +385,7 @@ export function parseTelegramBusEnvelope(
 export interface TelegramBusLocalServer {
   start: () => Promise<void>;
   stop: () => Promise<void>;
+  ensureEndpoint: () => Promise<boolean>;
 }
 
 export type TelegramBusSocketPathSource = string | (() => string);
@@ -609,12 +612,14 @@ export function createTelegramBusLocalServer(
 ): TelegramBusLocalServer {
   let server: Server | undefined;
   let activeSocketPath: string | undefined;
+  let endpointRecovery: Promise<boolean> | undefined;
+  let stopGeneration = 0;
   const sockets = new Set<Socket>();
   const closeSocket = (socket: Socket) => {
     sockets.delete(socket);
     socket.destroy();
   };
-  return {
+  const runtime: TelegramBusLocalServer = {
     start: async () => {
       if (server) return;
       const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
@@ -678,6 +683,7 @@ export function createTelegramBusLocalServer(
       if (!usesWindowsPipe) chmodSync(socketPath, 0o600);
     },
     stop: async () => {
+      stopGeneration += 1;
       const activeServer = server;
       const socketPath = activeSocketPath;
       server = undefined;
@@ -702,7 +708,44 @@ export function createTelegramBusLocalServer(
         );
       }
     },
+    ensureEndpoint: async () => {
+      const socketPath = activeSocketPath;
+      if (
+        !server ||
+        !socketPath ||
+        isTelegramBusPipePath(socketPath) ||
+        existsSync(socketPath)
+      ) {
+        return false;
+      }
+      if (endpointRecovery) return endpointRecovery;
+      endpointRecovery = (async () => {
+        deps.recordTransportEvent?.(
+          "server-endpoint-missing",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
+        const recoveryStopGeneration = stopGeneration + 1;
+        await runtime.stop();
+        if (stopGeneration !== recoveryStopGeneration) return false;
+        await runtime.start();
+        if (stopGeneration !== recoveryStopGeneration) {
+          await runtime.stop();
+          return false;
+        }
+        deps.recordTransportEvent?.(
+          "server-endpoint-recovered",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
+        return true;
+      })();
+      try {
+        return await endpointRecovery;
+      } finally {
+        endpointRecovery = undefined;
+      }
+    },
   };
+  return runtime;
 }
 
 function getTelegramBusEnvelopeDiagnostics(
@@ -1068,6 +1111,9 @@ function parseRegistration(
     registration.profileKey = value.profileKey;
   if (typeof value.threadName === "string")
     registration.threadName = value.threadName;
+  if (typeof value.slot === "string" && /^[A-Z]$/.test(value.slot)) {
+    registration.slot = value.slot;
+  }
   if (typeof value.cwd === "string") registration.cwd = value.cwd;
   if (typeof value.pid === "number") registration.pid = value.pid;
   if (typeof value.busSocketPath === "string") {

package/lib/config.ts

@@ -85,8 +85,8 @@ export interface TelegramBotProfile {
   lastUpdateId?: number;
 }
 
-/** Profile names must be lowercase letters, digits, hyphens, underscores; max 32 chars. */
-const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** Profile names must contain only lowercase ASCII letters and digits; max 32 chars. */
+const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9]{1,32}$/;
 const TELEGRAM_RESERVED_PROFILE_NAMES: ReadonlySet<string> = new Set([
   "default",
   "main",

package/lib/lifecycle.ts

@@ -153,9 +153,8 @@ function unrefTelegramLifecycleTimer(timer: TelegramLifecycleTimer): void {
 export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   setCompactionInProgress: (inProgress: boolean) => void;
   updateStatus: (ctx: TContext) => void;
-  startTypingLoop?: (ctx: TContext) => void;
+  startTypingLoop?: (ctx: TContext) => boolean | void;
   stopTypingLoop?: () => void;
-  shouldStartTypingLoop?: () => boolean;
   requestDeferredDispatchNextQueuedTelegramTurn: (
     dispatch: (ctx: TContext) => void,
   ) => void;
@@ -196,8 +195,9 @@ export function createTelegramCompactionObserverRuntime<TContext>(
   return {
     onSessionBeforeCompact: (_event, ctx) => {
       deps.setCompactionInProgress(true);
-      typingStartedByObserver = deps.shouldStartTypingLoop?.() ?? true;
-      if (typingStartedByObserver) deps.startTypingLoop?.(ctx);
+      const typingStartResult = deps.startTypingLoop?.(ctx);
+      typingStartedByObserver =
+        !!deps.startTypingLoop && typingStartResult !== false;
       deps.updateStatus(ctx);
       clearFallbackTimer();
       fallbackTimer = setTimer(() => {

package/lib/locks.ts

@@ -203,6 +203,17 @@ export function formatTelegramLockEntry(lock: TelegramLockEntry): string {
   return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
 }
 
+function formatTelegramFollowerRegistrationFailure(message: string): string {
+  if (/\b(?:ENOENT|ECONNREFUSED|ETIMEDOUT)\b/u.test(message)) {
+    return (
+      `live owner / unreachable bus endpoint after bounded retries (${message}); ` +
+      "wait briefly for owner recovery, then retry /telegram-connect. " +
+      "Do not force takeover while the owner remains live"
+    );
+  }
+  return message;
+}
+
 function getLockState(
   lock: TelegramLockEntry | undefined,
   pid: number,
@@ -509,7 +520,7 @@ export function createTelegramLockedPollingRuntime<
               ok: false,
               canTakeover: false,
               owner,
-              message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${failureMessage}.`,
+              message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${formatTelegramFollowerRegistrationFailure(failureMessage)}.`,
             };
           }
         }

package/lib/logs.ts

@@ -65,7 +65,7 @@ export function getTelegramPreviousRuntimeLogPath(
 ): string {
   return resolveTelegramProfileTempFilePath(
     "logs",
-    "previous.jsonl",
+    "_prev.jsonl",
     agentDir,
     profileName,
   );
@@ -91,7 +91,7 @@ export function createTelegramRuntimeJsonlLog(
   const resolvePreviousPath = () => {
     if (typeof options.previousPath === "function") return options.previousPath();
     if (options.previousPath) return options.previousPath;
-    return resolvePath().replace(/\.jsonl$/u, ".previous.jsonl");
+    return resolvePath().replace(/\.jsonl$/u, "._prev.jsonl");
   };
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
   const getNowMs = options.getNowMs ?? Date.now;