@llblab/pi-telegram 0.24.6 → 0.24.8

package/lib/outbound-buttons.ts

@@ -6,7 +6,10 @@
 
 import { randomUUID } from "node:crypto";
 
-import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import type {
+  TelegramInlineKeyboardButtonStyle,
+  TelegramInlineKeyboardMarkup,
+} from "./keyboard.ts";
 import {
   parseTelegramCommentAttributes,
   parseTopLevelTelegramComment,
@@ -24,6 +27,7 @@ const TELEGRAM_BUTTON_ACTION_TTL_MS = 24 * 60 * 60 * 1000;
 export interface TelegramOutboundButtonAction {
   text: string;
   prompt: string;
+  selectedStyle?: TelegramInlineKeyboardButtonStyle;
 }
 
 export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
@@ -51,6 +55,7 @@ export interface TelegramButtonCallbackQuery {
     message_id?: number;
     message_thread_id?: number;
     chat?: { id?: number };
+    reply_markup?: TelegramOutboundButtonMarkup;
   };
 }
 
@@ -66,7 +71,12 @@ export interface TelegramButtonCallbackHandlerDeps<TContext = unknown> {
     query: TelegramButtonCallbackQuery,
     action: TelegramOutboundButtonAction,
     ctx: TContext,
-  ) => void;
+  ) => boolean | void;
+  editMessageReplyMarkup?: (
+    chatId: number,
+    messageId: number,
+    replyMarkup: TelegramOutboundButtonMarkup,
+  ) => Promise<void>;
 }
 
 function nowMs(): number {
@@ -80,11 +90,18 @@ function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
 function parseButtonsCommentAttributes(input: string): {
   label?: string;
   prompt?: string;
+  selectedStyle?: TelegramInlineKeyboardButtonStyle;
 } {
   const attributes = parseTelegramCommentAttributes(input);
+  const selectedStyle = attributes.selected_style;
   return {
     ...(attributes.label ? { label: attributes.label } : {}),
     ...(attributes.prompt ? { prompt: attributes.prompt } : {}),
+    ...(selectedStyle === "success" ||
+    selectedStyle === "danger" ||
+    selectedStyle === "primary"
+      ? { selectedStyle }
+      : {}),
   };
 }
 
@@ -101,14 +118,34 @@ function parseButtonsCommentRows(
     }
     const attributes = parseButtonsCommentAttributes(head);
     return attributes.label && attributes.prompt
-      ? [[{ text: attributes.label, prompt: attributes.prompt }]]
+      ? [
+          [
+            {
+              text: attributes.label,
+              prompt: attributes.prompt,
+              ...(attributes.selectedStyle
+                ? { selectedStyle: attributes.selectedStyle }
+                : {}),
+            },
+          ],
+        ]
       : [];
   }
 
-  const label = parseButtonsCommentAttributes(head).label;
+  const attributes = parseButtonsCommentAttributes(head);
   const prompt = body.trim();
-  if (!label || !prompt) return [];
-  return [[{ text: label, prompt }]];
+  if (!attributes.label || !prompt) return [];
+  return [
+    [
+      {
+        text: attributes.label,
+        prompt,
+        ...(attributes.selectedStyle
+          ? { selectedStyle: attributes.selectedStyle }
+          : {}),
+      },
+    ],
+  ];
 }
 
 export function createTelegramButtonActionStore(
@@ -138,11 +175,19 @@ export function createTelegramButtonActionStore(
       const action = actions.get(callbackData);
       if (!action) return undefined;
       actions.delete(callbackData);
-      return { text: action.text, prompt: action.prompt };
+      return {
+        text: action.text,
+        prompt: action.prompt,
+        ...(action.selectedStyle
+          ? { selectedStyle: action.selectedStyle }
+          : {}),
+      };
     },
   };
 }
 
+const DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN = "Choose an option:";
+
 export function planTelegramButtonReply(
   markdown: string,
   deps: { registerAction: (action: TelegramOutboundButtonAction) => string },
@@ -162,8 +207,12 @@ export function planTelegramButtonReply(
     }
     return "";
   });
+  const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
   return {
-    markdown: normalizeMarkdownAfterButtonExtraction(stripped),
+    markdown:
+      keyboard.length > 0 && !visibleMarkdown
+        ? DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN
+        : visibleMarkdown,
     ...(keyboard.length > 0
       ? { replyMarkup: { inline_keyboard: keyboard } }
       : {}),
@@ -203,6 +252,22 @@ export function createTelegramButtonPromptTurn(options: {
   };
 }
 
+export function markTelegramButtonSelected(
+  replyMarkup: TelegramOutboundButtonMarkup,
+  callbackData: string,
+  selectedStyle: TelegramInlineKeyboardButtonStyle = "primary",
+): TelegramOutboundButtonMarkup | undefined {
+  let matched = false;
+  const inlineKeyboard = replyMarkup.inline_keyboard.map((row) =>
+    row.map((button) => {
+      if (button.callback_data !== callbackData) return { ...button };
+      matched = true;
+      return { ...button, style: selectedStyle };
+    }),
+  );
+  return matched ? { inline_keyboard: inlineKeyboard } : undefined;
+}
+
 export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
   query: TelegramButtonCallbackQuery,
   ctx: TContext,
@@ -225,7 +290,22 @@ export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
     return true;
   }
 
-  deps.enqueueButtonPrompt(query, action, ctx);
+  const enqueued = deps.enqueueButtonPrompt(query, action, ctx);
+  if (enqueued === false) {
+    await deps.answerCallbackQuery(query.id, "Already queued.");
+    return true;
+  }
+  const selectedMarkup =
+    query.data && query.message?.reply_markup
+      ? markTelegramButtonSelected(
+          query.message.reply_markup,
+          query.data,
+          action.selectedStyle,
+        )
+      : undefined;
+  if (selectedMarkup && deps.editMessageReplyMarkup) {
+    await deps.editMessageReplyMarkup(chatId, messageId, selectedMarkup);
+  }
   await deps.answerCallbackQuery(query.id, "Queued.");
   return true;
 }

package/lib/outbound.ts

@@ -817,6 +817,7 @@ export {
   createTelegramButtonPromptTurn,
   createTelegramButtonReplyPlanner,
   handleTelegramButtonCallbackQuery,
+  markTelegramButtonSelected,
   planTelegramButtonReply,
   type TelegramButtonActionStore,
   type TelegramButtonCallbackHandlerDeps,

package/lib/prompts.ts

@@ -143,8 +143,9 @@ Assistant-authored Telegram actions:
 - Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
 - Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
 - Voice reply modes are compact: \`hidden\` emits no automatic context, \`mirror\` emits it for voice/audio input, and \`always\` emits it for every Telegram turn. Explicit \`telegram_voice\` remains available for an intentionally distinct spoken payload.
-- Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.
-- If hidden comments would be the whole reply, add visible text such as \`Choose one:\`.
+- Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks" selected_style="danger"\nList the main risks first.\n-->\`.
+- Optional \`selected_style\` controls the button after queue admission: \`primary\` (default, blue), \`success\` (green), or \`danger\` (red). It never suppresses the prompt.
+- If hidden button comments form the whole reply, the bridge supplies visible fallback text automatically.
 
 Local/TUI direct delivery:
 - Do not send Telegram actions from local/TUI prompts unless explicitly asked.

package/lib/routing.ts

@@ -608,6 +608,11 @@ export interface TelegramInboundRouteRuntimeDeps<
     mode: "markdown" | "html" | "plain",
     replyMarkup: Menu.TelegramReplyMarkup,
   ) => Promise<void>;
+  editMessageReplyMarkup?: (
+    chatId: number,
+    messageId: number,
+    replyMarkup: OutboundHandlers.TelegramOutboundButtonMarkup,
+  ) => Promise<void>;
   sendInteractiveMessage?: (
     chatId: number,
     text: string,
@@ -1448,11 +1453,28 @@ export function createTelegramInboundRouteRuntime<
         {
           resolveAction: deps.buttonActionStore.resolve,
           answerCallbackQuery: deps.answerCallbackQuery,
+          editMessageReplyMarkup: deps.editMessageReplyMarkup
+            ? async (chatId, messageId, replyMarkup) => {
+                try {
+                  await deps.editMessageReplyMarkup?.(
+                    chatId,
+                    messageId,
+                    replyMarkup,
+                  );
+                } catch (error) {
+                  deps.recordRuntimeEvent?.("telegram", error, {
+                    phase: "button-selection-mark",
+                    chatId,
+                    messageId,
+                  });
+                }
+              }
+            : undefined,
           enqueueButtonPrompt: (buttonQuery, action, context) => {
             const chatId = buttonQuery.message?.chat?.id;
             const messageId = buttonQuery.message?.message_id;
             if (typeof chatId !== "number" || typeof messageId !== "number")
-              return;
+              return false;
             const queueOrder = deps.bridgeRuntime.queue.allocateItemOrder();
             const turn = OutboundHandlers.createTelegramButtonPromptTurn({
               chatId,
@@ -1471,10 +1493,11 @@ export function createTelegramInboundRouteRuntime<
               deps.telegramQueueStore.getQueuedItems(),
               turn,
             );
-            if (!result.appended) return;
+            if (!result.appended) return false;
             deps.telegramQueueStore.setQueuedItems(result.items);
             deps.updateStatus(context);
             requestDispatchNextQueuedTelegramTurn(context);
+            return true;
           },
         },
       );

package/lib/status.ts

@@ -1272,11 +1272,13 @@ function buildStatusSummary(ctx: TelegramStatusContext): string {
   return "unknown";
 }
 
-function buildTelegramStatusRoleSuffix(
+function buildTelegramStatusThreadSummary(
   state: TelegramBridgeStatusLineState | undefined,
-): string {
-  if (state?.botThreadMode !== "enabled" || !state.busRole) return "";
-  return ` @${state.busRole}`;
+): string | undefined {
+  if (state?.botThreadMode !== "enabled" || !state.busRole) return undefined;
+  const threadName = state.instanceThreadName?.trim();
+  const identity = threadName || (state.instanceSlot ? `[${state.instanceSlot}]` : "");
+  return identity ? `${identity} @${state.busRole}` : undefined;
 }
 
 export function buildStatusHtml(
@@ -1288,12 +1290,11 @@ export function buildStatusHtml(
   const usesSubscription = activeModel
     ? ctx.modelRegistry.isUsingOAuth(activeModel)
     : false;
-  const lines: string[] = [
-    buildStatusRow(
-      "Status",
-      `${buildStatusSummary(ctx)}${buildTelegramStatusRoleSuffix(bridgeStatus)}`,
-    ),
-  ];
+  const lines: string[] = [buildStatusRow("Status", buildStatusSummary(ctx))];
+  const threadSummary = buildTelegramStatusThreadSummary(bridgeStatus);
+  if (threadSummary) {
+    lines.push(buildStatusRow("Thread", threadSummary));
+  }
   const usageSummary = buildUsageSummary(stats);
   const costSummary = buildCostSummary(stats, usesSubscription);
   if (usageSummary) {

package/lib/sync.ts

@@ -110,11 +110,19 @@ export interface TelegramLeaderHealthRuntime {
 export interface TelegramManualThreadDisconnectDeps<TSyncState> {
   instanceId: string;
   getCurrentThreadRecord: () =>
-    | { target: TelegramTarget; instanceId?: string; owner?: { kind?: string } }
+    | {
+        target: TelegramTarget;
+        instanceId?: string;
+        profileKey?: string;
+        owner?: { kind?: string };
+      }
     | undefined;
   topicTargetStore: Pick<
     TelegramTopicTargetStore,
-    "markOfflineByInstanceId" | "persist"
+    | "markStaleByTarget"
+    | "persist"
+    | "upsertPendingCleanup"
+    | "removePendingCleanup"
   >;
   callApi: <TResponse>(
     method: string,
@@ -175,22 +183,44 @@ export function createTelegramManualThreadDisconnectHandler<
           }
         }
       } else {
-        const stillOwnsLeaderEpoch = () =>
-          !deps.getCurrentLeaderEpoch ||
-          (leaderEpoch !== undefined &&
-            deps.getCurrentLeaderEpoch() === leaderEpoch);
+        const target = currentRecord.target as TelegramTarget & {
+          threadId: number;
+        };
+        const runtimeGeneration = currentRecord.instanceId ?? deps.instanceId;
+        const intent: ThreadReconciler.TelegramThreadCleanupIntent = {
+          id: `cleanup:${deps.instanceId}:${runtimeGeneration}:${target.chatId}:${target.threadId}`,
+          owner: isManualFollower ? "manual-follower" : "leader",
+          instanceId: deps.instanceId,
+          runtimeGeneration,
+          ...(currentRecord.profileKey
+            ? { profileKey: currentRecord.profileKey }
+            : {}),
+          target,
+          requestedAtMs: (deps.getNowMs ?? Date.now)(),
+        };
+        deps.topicTargetStore.upsertPendingCleanup(intent);
+        await deps.topicTargetStore.persist();
         const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
-          ThreadReconciler.planDisconnectedInstanceThreadCleanup({
-            target: currentRecord.target as TelegramTarget & {
-              threadId: number;
-            },
-            instanceId: deps.instanceId,
-            leaderEpoch,
+          ThreadReconciler.planThreadReconciliation({
+            nowMs: (deps.getNowMs ?? Date.now)(),
+            currentLeaderEpoch: leaderEpoch,
+            records: [],
+            pendingCleanups: [intent],
           }),
           {
             callApi(method, body) {
               return deps.callApi(method, body);
             },
+            markStaleByTarget(targetToMark, syncStatus, lastSyncError) {
+              return deps.topicTargetStore.markStaleByTarget(
+                targetToMark,
+                syncStatus,
+                lastSyncError,
+              );
+            },
+            removeCleanupIntentById(id) {
+              return deps.topicTargetStore.removePendingCleanup(id);
+            },
             persist() {
               return deps.topicTargetStore.persist();
             },
@@ -203,14 +233,6 @@ export function createTelegramManualThreadDisconnectHandler<
             "Telegram thread deletion was not confirmed; inspect /telegram-status --debug and retry /telegram-disconnect.",
           );
         }
-        if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
-        const offlineChanged =
-          deps.topicTargetStore.markOfflineByInstanceId(deps.instanceId) > 0;
-        if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
-        if (offlineChanged) {
-          await deps.topicTargetStore.persist();
-          if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
-        }
       }
       const leaderTarget = deps.getLeaderTarget();
       if (

package/lib/thread-reconciler.ts

@@ -48,6 +48,16 @@ export interface TelegramThreadPendingProvision {
   leaderEpoch?: number | string;
 }
 
+export interface TelegramThreadCleanupIntent {
+  id: string;
+  owner: "leader" | "manual-follower";
+  instanceId: string;
+  runtimeGeneration: string;
+  profileKey?: string;
+  target: ThreadTarget;
+  requestedAtMs: number;
+}
+
 export interface TelegramUnboundThreadMessageObservation {
   target: TelegramTarget & { threadId: number };
   observedAtMs: number;
@@ -130,6 +140,24 @@ export type ThreadReconciliationAction =
       messageId?: number;
       leaderEpoch?: number | string;
     }
+  | {
+      kind: "close-delete-graceful-shutdown-topic";
+      target: TelegramTarget & { threadId: number };
+      reason: "graceful-shutdown";
+      cleanupIntentId: string;
+      instanceId: string;
+      runtimeGeneration: string;
+      leaderEpoch?: number | string;
+    }
+  | {
+      kind: "cancel-superseded-graceful-shutdown-cleanup";
+      target: TelegramTarget & { threadId: number };
+      reason: "replacement-registration";
+      cleanupIntentId: string;
+      instanceId: string;
+      runtimeGeneration: string;
+      leaderEpoch?: number | string;
+    }
   | {
       kind: "close-delete-expired-pending-provision-topic";
       target: TelegramTarget & { threadId: number };
@@ -186,6 +214,7 @@ export interface ThreadReconciliationApplyPorts {
   ) => boolean;
   persist?: () => Promise<void>;
   removePendingProvisionById?: (id: string) => boolean;
+  removeCleanupIntentById?: (id: string) => boolean;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   recordRuntimeEvent?: (
     category: string,
@@ -201,6 +230,7 @@ export interface ThreadReconciliationInput {
   reservations?: readonly ThreadReconciliationReservation[];
   observations?: readonly ThreadReconciliationObservation[];
   pendingProvisions?: readonly TelegramThreadPendingProvision[];
+  pendingCleanups?: readonly TelegramThreadCleanupIntent[];
   unboundMessages?: readonly TelegramUnboundThreadMessageObservation[];
   reservedMessages?: readonly TelegramReservedThreadMessageObservation[];
   proactiveReservationCleanup?: boolean;
@@ -291,6 +321,8 @@ function isCleanupAction(action: ThreadReconciliationAction): boolean {
     action.kind === "close-delete-replaced-follower-topic" ||
     action.kind === "close-delete-previous-leader-topic" ||
     action.kind === "close-delete-disconnected-instance-topic" ||
+    action.kind === "close-delete-graceful-shutdown-topic" ||
+    action.kind === "cancel-superseded-graceful-shutdown-cleanup" ||
     action.kind === "close-delete-expired-pending-provision-topic"
   );
 }
@@ -505,6 +537,26 @@ export async function applyThreadReconciliationPlan(
         shouldPersist;
       continue;
     }
+    if (action.kind === "cancel-superseded-graceful-shutdown-cleanup") {
+      if (shouldSkipForStaleLeaderEpoch(action, ports)) {
+        incompleteActions.push(action);
+        continue;
+      }
+      const changed =
+        ports.removeCleanupIntentById?.(action.cleanupIntentId) ?? false;
+      shouldPersist = changed || shouldPersist;
+      ports.recordRuntimeEvent?.(
+        "telegram",
+        "Cancelled superseded Telegram topic cleanup",
+        {
+          phase: "thread-reconciler-cleanup-superseded",
+          instanceId: action.instanceId,
+          chatId: action.target.chatId,
+          threadId: action.target.threadId,
+        },
+      );
+      continue;
+    }
     if (action.kind === "close-stale-replaced-topic") {
       if (shouldSkipForStaleLeaderEpoch(action, ports)) {
         incompleteActions.push(action);
@@ -558,6 +610,7 @@ export async function applyThreadReconciliationPlan(
       action.kind === "close-delete-replaced-follower-topic" ||
       action.kind === "close-delete-previous-leader-topic" ||
       action.kind === "close-delete-disconnected-instance-topic" ||
+      action.kind === "close-delete-graceful-shutdown-topic" ||
       action.kind === "close-delete-expired-pending-provision-topic"
     ) {
       if (shouldSkipForStaleLeaderEpoch(action, ports)) {
@@ -647,7 +700,9 @@ export async function applyThreadReconciliationPlan(
                   ? "Previous leader Telegram topic deleted"
                   : action.kind === "close-delete-disconnected-instance-topic"
                     ? "Disconnected instance Telegram topic deleted"
-                    : "Expired pending provision Telegram topic deleted",
+                    : action.kind === "close-delete-graceful-shutdown-topic"
+                      ? "Graceful shutdown Telegram topic deleted"
+                      : "Expired pending provision Telegram topic deleted",
         {
           phase:
             action.kind === "close-delete-unbound-topic"
@@ -661,7 +716,10 @@ export async function applyThreadReconciliationPlan(
                       : action.kind ===
                           "close-delete-disconnected-instance-topic"
                         ? "thread-reconciler-disconnected-instance-topic-delete"
-                        : "thread-reconciler-expired-pending-provision-topic-delete",
+                        : action.kind ===
+                            "close-delete-graceful-shutdown-topic"
+                          ? "thread-reconciler-graceful-shutdown-topic-delete"
+                          : "thread-reconciler-expired-pending-provision-topic-delete",
           chatId: action.target.chatId,
           threadId: action.target.threadId,
           ...("messageId" in action ? { messageId: action.messageId } : {}),
@@ -678,6 +736,16 @@ export async function applyThreadReconciliationPlan(
         if (changed) persistFences.push(action);
         shouldPersist = changed || shouldPersist;
       }
+      if (
+        action.kind === "close-delete-graceful-shutdown-topic" &&
+        deleteConfirmed
+      ) {
+        if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
+        const changed =
+          ports.removeCleanupIntentById?.(action.cleanupIntentId) ?? false;
+        if (changed) persistFences.push(action);
+        shouldPersist = changed || shouldPersist;
+      }
     }
   }
   if (shouldPersist) {
@@ -736,6 +804,36 @@ export function planThreadReconciliation(
   );
 
   const actions: ThreadReconciliationAction[] = [];
+  for (const cleanup of input.pendingCleanups ?? []) {
+    const superseded = input.records.some(
+      (record) =>
+        isCurrentRecord(record) &&
+        targetKey(record.target) === targetKey(cleanup.target) &&
+        record.instanceId !== cleanup.instanceId,
+    );
+    const common = {
+      target: cleanup.target,
+      cleanupIntentId: cleanup.id,
+      instanceId: cleanup.instanceId,
+      runtimeGeneration: cleanup.runtimeGeneration,
+      ...(input.currentLeaderEpoch !== undefined
+        ? { leaderEpoch: input.currentLeaderEpoch }
+        : {}),
+    };
+    if (superseded) {
+      actions.push({
+        ...common,
+        kind: "cancel-superseded-graceful-shutdown-cleanup",
+        reason: "replacement-registration",
+      });
+    } else {
+      actions.push({
+        ...common,
+        kind: "close-delete-graceful-shutdown-topic",
+        reason: "graceful-shutdown",
+      });
+    }
+  }
   for (const provision of input.pendingProvisions ?? []) {
     if (!provision.target) continue;
     if (!isPendingProvisionExpired(provision, input.nowMs)) continue;