@llblab/pi-kit 0.6.0 → 0.7.1

package/node_modules/@llblab/pi-telegram/lib/polling.ts

@@ -280,11 +280,12 @@ export type TelegramDurablePollingRuntimeAssemblyDeps<
   "appendUpdateBatch" | "getJournalEntryCount" | "signalUpdateWorker"
 > & {
   canStart?: (ctx: TContext) => boolean;
+  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   journal: {
     appendBatch: (
       updates: readonly TUpdate[],
       acceptedThroughUpdateId?: number,
-    ) => MaybePromise<unknown>;
+    ) => { nonExcludedUpdateIds: readonly number[] };
     getAcceptedThroughUpdateId: () => number | undefined;
     prepareCursorCutover?: () => MaybePromise<void>;
     getEntryCount: () => number;
@@ -303,7 +304,30 @@ export function createTelegramDurablePollingRuntimeAssembly<
 ): TelegramDurablePollingRuntimeAssembly<TContext> {
   const controller = createTelegramPollingControllerRuntime({
     ...deps,
-    appendUpdateBatch: deps.journal.appendBatch,
+    appendUpdateBatch(updates, cursor) {
+      const result = deps.journal.appendBatch(updates, cursor);
+      if (!deps.prepareUpdateBatch) return result;
+      // No await: an already-draining worker must not observe the new batch before preparation.
+      try {
+        const included = new Set(result.nonExcludedUpdateIds);
+        let batch: TUpdate[] = [];
+        for (const update of updates) {
+          if (included.has(update.update_id)) batch.push(update);
+          else if (batch.length > 0) {
+            deps.prepareUpdateBatch(batch);
+            batch = [];
+          }
+        }
+        if (batch.length > 0) deps.prepareUpdateBatch(batch);
+      } catch (error) {
+        try {
+          deps.recordRuntimeEvent?.("polling", error, { phase: "batch-preparation", updateCount: updates.length });
+        } catch {
+          // Already-published input must still reach the worker if diagnostics fail.
+        }
+      }
+      return result;
+    },
     getAcceptedThroughUpdateId: deps.journal.getAcceptedThroughUpdateId,
     getJournalEntryCount: deps.journal.getEntryCount,
     signalUpdateWorker: deps.journal.signalWorker,
@@ -393,7 +417,6 @@ export function createTelegramPollingControllerRuntime<
       getAcceptedThroughUpdateId: deps.getAcceptedThroughUpdateId,
       getJournalEntryCount: deps.getJournalEntryCount,
       signalUpdateWorker: deps.signalUpdateWorker,
-      prepareUpdateBatch: deps.prepareUpdateBatch,
       updateStatus: deps.updateStatus,
       sleep: deps.sleep,
       onPhaseChange(phase, currentUpdateId) {
@@ -651,6 +674,7 @@ export interface TelegramThreadCapabilityRuntimeDeps<
   getPollingStartedWithTelegramBus: () => boolean;
   setPollingStartedWithTelegramBus: (started: boolean) => void;
   setTopicModeUnavailable: (unavailable: boolean) => void;
+  suspendLiveThreadTarget?: () => void;
   stopFollowerRegistration: () => void;
   startClassicPolling: (ctx: TContext) => MaybePromise<void>;
   stopClassicPolling: () => MaybePromise<void>;
@@ -682,6 +706,8 @@ export interface TelegramThreadCapabilityStateRuntime {
   isBusRuntimeEnabled(): boolean;
   shouldForceFreshLeaderThread(): boolean;
   setForceFreshLeaderThread(forceFresh: boolean): void;
+  getRequestedThreadName(): string | undefined;
+  setRequestedThreadName(threadName: string | undefined): void;
 }
 
 export type TelegramThreadTargetObservationHandler<TContext> = (
@@ -715,6 +741,10 @@ export interface TelegramThreadAwarePollingPorts<TContext, TOwner> {
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithOwner: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
   stopFollowerRegistration: () => void;
 }
 
@@ -738,6 +768,11 @@ export interface TelegramThreadAwarePollingDeps<
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithLeader?: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
+  hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
   stopFollowerRegistration: () => void;
 }
 
@@ -760,6 +795,12 @@ export interface TelegramThreadCapabilityOrchestrationDeps<
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithLeader?: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
+  hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
+  suspendLiveThreadTarget?: () => void;
   stopFollowerRegistration: () => void;
   isTopicModeUnavailableError: (error: unknown) => boolean;
   updateStatus: (ctx: TContext) => void;
@@ -780,6 +821,7 @@ export function createTelegramThreadCapabilityStateRuntime(): TelegramThreadCapa
   let busPollingStarted = false;
   let topicModeUnavailable = false;
   let forceFreshLeaderThread = false;
+  let requestedThreadName: string | undefined;
   return {
     isBusPollingStarted: () => busPollingStarted,
     setBusPollingStarted(started) {
@@ -794,6 +836,10 @@ export function createTelegramThreadCapabilityStateRuntime(): TelegramThreadCapa
     setForceFreshLeaderThread(forceFresh) {
       forceFreshLeaderThread = forceFresh;
     },
+    getRequestedThreadName: () => requestedThreadName,
+    setRequestedThreadName(threadName) {
+      requestedThreadName = threadName;
+    },
   };
 }
 
@@ -818,6 +864,7 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
     getPollingStartedWithTelegramBus: deps.state.isBusPollingStarted,
     setPollingStartedWithTelegramBus: deps.state.setBusPollingStarted,
     setTopicModeUnavailable: deps.state.setTopicModeUnavailable,
+    suspendLiveThreadTarget: deps.suspendLiveThreadTarget,
     stopFollowerRegistration: deps.stopFollowerRegistration,
     startClassicPolling: deps.startClassicPolling,
     stopClassicPolling: deps.stopClassicPolling,
@@ -850,6 +897,8 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
       startLeaderHealth: deps.startLeaderHealth,
       stopLeaderHealth: deps.stopLeaderHealth,
       registerFollowerWithLeader: deps.registerFollowerWithLeader,
+      restoreFollowerWithLeader: deps.restoreFollowerWithLeader,
+      hasRememberedWorkspaceBinding: deps.hasRememberedWorkspaceBinding,
       stopFollowerRegistration: deps.stopFollowerRegistration,
       recordEvent: deps.recordEvent,
       setTopicModeUnavailable: deps.state.setTopicModeUnavailable,
@@ -958,14 +1007,16 @@ export async function applyTelegramThreadCapability<TContext>(
     if (!isCurrent()) return;
     deps.setTopicModeUnavailable(true);
     deps.stopFollowerRegistration();
+    const hadLiveThreadTransport = deps.getPollingStartedWithTelegramBus();
     if (
-      deps.getPollingStartedWithTelegramBus() ||
+      hadLiveThreadTransport ||
       hasTelegramClassicRestoreFailure(previousBotState)
     ) {
       deps.stopLeaderHealth();
       await deps.stopBusPolling();
       if (!isCurrent()) return;
       deps.setPollingStartedWithTelegramBus(false);
+      if (hadLiveThreadTransport) deps.suspendLiveThreadTarget?.();
       try {
         await deps.startClassicPolling(ctx);
         if (!isCurrent()) return;
@@ -1110,24 +1161,34 @@ export function createTelegramThreadAwarePollingPorts<TContext, TOwner>(
     }
     await deps.stopClassicPolling();
   };
-  const registerFollowerWithOwner = async (
-    ctx: TContext,
-    owner: TOwner,
-  ): Promise<boolean | undefined> => {
+  const refreshFollowerState = async (): Promise<boolean> => {
     if (deps.topicTargetStore.refresh) {
       await deps.topicTargetStore.refresh();
     } else {
       await deps.topicTargetStore.load();
     }
-    if (deps.topicTargetStore.getBotState().threadMode !== "enabled") {
-      return undefined;
-    }
+    return deps.topicTargetStore.getBotState().threadMode === "enabled";
+  };
+  const registerFollowerWithOwner = async (
+    ctx: TContext,
+    owner: TOwner,
+  ): Promise<boolean | undefined> => {
+    if (!(await refreshFollowerState())) return undefined;
     return deps.registerFollowerWithLeader(ctx, owner);
   };
+  const restoreFollowerWithOwner = async (
+    ctx: TContext,
+    owner: TOwner,
+  ): Promise<boolean | undefined> => {
+    if (!(await refreshFollowerState())) return undefined;
+    if (!deps.hasRememberedWorkspaceBinding?.(ctx)) return undefined;
+    return deps.restoreFollowerWithLeader?.(ctx, owner);
+  };
   return {
     startPolling,
     stopPolling,
     registerFollowerWithOwner,
+    restoreFollowerWithOwner,
     stopFollowerRegistration: deps.stopFollowerRegistration,
   };
 }
@@ -1179,9 +1240,9 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   let consecutiveDisabledProbes = 0;
   const stop = (): void => {
     generation += 1;
-    deps.lifecycle?.invalidate();
     if (interval) clearInterval(interval);
     interval = undefined;
+    deps.lifecycle?.invalidate();
   };
   const check = (ctx: TContext): void => {
     if (transitionPromise || !canProbeTelegramThreadCapability(ctx, deps)) {
@@ -1276,8 +1337,19 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   return {
     start(ctx) {
       stop();
+      const expectedGeneration = generation;
       interval = setInterval(() => {
-        check(ctx);
+        if (generation !== expectedGeneration) return;
+        try {
+          check(ctx);
+        } catch (error) {
+          try { stop(); } catch { /* Timer shutdown must not escape the callback. */ }
+          try {
+            deps.recordEvent("bus", error, { phase: "capability-monitor" });
+          } catch {
+            // Monitor diagnostics cannot create an uncaught interval exception.
+          }
+        }
       }, intervalMs);
       interval.unref?.();
     },
@@ -1416,7 +1488,6 @@ export interface TelegramPollLoopDeps<
   getAcceptedThroughUpdateId?: () => number | undefined;
   getJournalEntryCount: () => number;
   signalUpdateWorker: () => void;
-  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   onErrorStatus: (message: string) => void;
   onStatusReset: () => void;
   sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -1446,7 +1517,6 @@ export interface TelegramPollLoopRunnerDeps<
   getAcceptedThroughUpdateId?: () => number | undefined;
   getJournalEntryCount: () => number;
   signalUpdateWorker: () => void;
-  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   updateStatus: (ctx: TContext, message?: string) => void;
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
   onPhaseChange?: (
@@ -1501,7 +1571,6 @@ export function createTelegramPollLoopRunner<
       getAcceptedThroughUpdateId: deps.getAcceptedThroughUpdateId,
       getJournalEntryCount: deps.getJournalEntryCount,
       signalUpdateWorker: deps.signalUpdateWorker,
-      prepareUpdateBatch: deps.prepareUpdateBatch,
       onErrorStatus: (message) => {
         updateTelegramPollingStatusSafely(deps.updateStatus, ctx, {
           message,
@@ -1702,7 +1771,6 @@ export async function runTelegramPollLoop<
       reportTelegramPollingPhase(deps, "long-poll");
       const updates = await requestTelegramUpdatesWithinBudget(deps, request);
       reportTelegramPollingResponse(deps, updates.length);
-      deps.prepareUpdateBatch?.(updates);
       consecutiveGetUpdatesConflicts = 0;
       currentUpdateId = updates[0]?.update_id;
       await admitTelegramPollingUpdateBatch({

package/node_modules/@llblab/pi-telegram/lib/preview.ts

@@ -70,6 +70,7 @@ export interface TelegramPreviewActiveTurn {
   target?: TelegramTarget;
   voiceReplyPreferred?: boolean;
   voiceReplyRequired?: boolean;
+  guestQueryId?: string;
 }
 
 export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
@@ -408,6 +409,17 @@ export function createTelegramAssistantMessagePreviewHooks<TMessage>(
   };
 }
 
+/**
+ * Returns true when the active turn is a Telegram Guest Mode query. A guest
+ * query allows exactly one answer within a limited Telegram response window,
+ * so it must never emit streaming draft previews.
+ */
+export function shouldSuppressPreviewForGuestTurn(
+  turn: { guestQueryId?: string } | null | undefined,
+): boolean {
+  return !!turn?.guestQueryId;
+}
+
 export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
   message: TMessage,
   deps: TelegramAssistantMessagePreviewStartDeps<TMessage>,
@@ -422,6 +434,10 @@ export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
     deps.setState(undefined);
     return;
   }
+  if (shouldSuppressPreviewForGuestTurn(turn)) {
+    deps.setState(undefined);
+    return;
+  }
   const state = deps.getState();
   sealTelegramPreviewState(state);
   const next = deps.createPreviewState();
@@ -443,6 +459,7 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
     return;
   }
   if (shouldSuppressPreviewForVoice(turn)) return;
+  if (shouldSuppressPreviewForGuestTurn(turn)) return;
   let state = deps.getState();
   if (!state) {
     state = deps.createPreviewState();

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -14,7 +14,7 @@ export const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE =
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} For Telegram work, consult bundled Skills in routing order: \`telegram-bridge\` for the transport and turn protocol, \`generated-control-surface\` when contextual controls materially shorten feedback, then \`generative-apps\` when the interaction warrants a reusable deterministic app. Load a Skill only if its instructions are not already present in the current context. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
+${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} For Telegram work, consult bundled Skills in routing order: \`telegram-bridge\` for the transport and turn protocol, \`show-me\` when a user needs a truthful visual explanation of work or behavior, \`generated-control-surface\` when contextual controls materially shorten feedback, then \`generative-apps\` when the interaction warrants a reusable deterministic app. Load a Skill only if its instructions are not already present in the current context. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
@@ -28,9 +28,11 @@ export const TELEGRAM_ATTACH_PROMPT_GUIDELINES = [
   "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
 ] as const;
 export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
-  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
+  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery to a concrete chat, channel, or live Pi Thread outside the normal reply flow.";
 export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
+  "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.",
+  "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.",
   "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
@@ -48,6 +50,8 @@ const TELEGRAM_TOOL_METADATA_LINES = Object.fromEntries(
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_bind",
+  "telegram_channel_post",
+  "telegram_channel_posts",
   "telegram_message",
 ]);
 const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(

package/node_modules/@llblab/pi-telegram/lib/queue.ts

@@ -110,6 +110,7 @@ export interface TelegramQueueItemBase {
   transportStamp?: TelegramTransportStamp;
   replyToMessageId: number;
   guestQueryId?: string;
+  guestInlineMessageId?: string;
   queueOrder: number;
   queueLane: TelegramQueueLane;
   laneOrder: number;
@@ -152,6 +153,7 @@ export interface TelegramQueueHandoffBase {
   transportStamp?: TelegramTransportStamp;
   replyToMessageId: number;
   guestQueryId?: string;
+  guestInlineMessageId?: string;
   queueOrder: number;
   queueLane: TelegramQueueLane;
   laneOrder: number;
@@ -612,6 +614,9 @@ export function createTelegramQueueHandoffPayload<TContext>(
       ...(item.transportStamp ? { transportStamp: item.transportStamp } : {}),
       replyToMessageId: item.replyToMessageId,
       ...(item.guestQueryId ? { guestQueryId: item.guestQueryId } : {}),
+      ...(item.guestInlineMessageId
+        ? { guestInlineMessageId: item.guestInlineMessageId }
+        : {}),
       queueOrder: item.queueOrder,
       queueLane: item.queueLane,
       laneOrder: item.laneOrder,
@@ -626,6 +631,9 @@ export function createTelegramQueueHandoffPayload<TContext>(
     ...(item.transportStamp ? { transportStamp: item.transportStamp } : {}),
     replyToMessageId: item.replyToMessageId,
     ...(item.guestQueryId ? { guestQueryId: item.guestQueryId } : {}),
+    ...(item.guestInlineMessageId
+      ? { guestInlineMessageId: item.guestInlineMessageId }
+      : {}),
     queueOrder: item.queueOrder,
     queueLane: item.queueLane,
     laneOrder: item.laneOrder,
@@ -1527,7 +1535,7 @@ export interface TelegramAgentEndRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: TelegramQueueTarget },
+    options?: { target?: TelegramQueueTarget; parseMode?: "HTML" },
   ) => Promise<unknown>;
   sendQueuedAttachments: (
     turn: TTurn,
@@ -1544,6 +1552,8 @@ export interface TelegramAgentEndRuntimeDeps<
     options?: { parseMode?: string },
   ) => Promise<void>;
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
+  /** Replaces the early guest ACK with the final text. */
+  editGuestReply?: (inlineMessageId: string, markdown: string) => Promise<void>;
   sendGuestAttachment?: (
     turn: TTurn,
     attachment: QueuedAttachment,
@@ -1622,6 +1632,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   >["sendRichAttachmentReply"];
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
+  editGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["editGuestReply"];
   sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
   sendGuestVoiceReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestVoiceReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
@@ -1762,6 +1773,7 @@ export function createTelegramAgentEndHook<
         sendRichAttachmentReply: deps.sendRichAttachmentReply,
         answerGuestQuery: deps.answerGuestQuery,
         sendGuestReply: deps.sendGuestReply,
+        editGuestReply: deps.editGuestReply,
         sendGuestAttachment: deps.sendGuestAttachment,
         sendGuestVoiceReply: deps.sendGuestVoiceReply,
         planOutboundReply: deps.planOutboundReply,
@@ -1854,11 +1866,47 @@ export async function handleTelegramAgentEndRuntime<
     return;
   }
   if (turn.guestQueryId) {
+    if (turn.guestInlineMessageId && deps.editGuestReply) {
+      const experimentText = assistant.errorMessage
+        ? "Telegram bridge: Pi failed while processing the request."
+        : finalText;
+      if (experimentText) {
+        try {
+          await deps.editGuestReply(turn.guestInlineMessageId, experimentText);
+          deps.recordRuntimeEvent?.(
+            "guest",
+            new Error("Guest ACK experiment edited the guest answer"),
+            { phase: "guest-ack-edited", guestQueryId: turn.guestQueryId },
+          );
+        } catch (error) {
+          deps.recordRuntimeEvent?.("delivery", error, {
+            phase: "guest-ack-edit",
+            guestQueryId: turn.guestQueryId,
+          });
+        }
+      } else {
+        deps.recordRuntimeEvent?.(
+          "delivery",
+          new Error("Guest ACK experiment turn produced no editable text"),
+          { phase: "guest-ack-edit-empty", guestQueryId: turn.guestQueryId },
+        );
+      }
+      if (!isDeliveryActive()) return;
+      if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+      return;
+    }
     if (assistant.errorMessage) {
-      await deps.answerGuestQuery?.(
-        turn.guestQueryId,
-        "Telegram bridge: Pi failed while processing the request.",
-      );
+      try {
+        await deps.answerGuestQuery?.(
+          turn.guestQueryId,
+          "Telegram bridge: Pi failed while processing the request.",
+        );
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-error-reply",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
       if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
       return;
     }
@@ -1894,10 +1942,20 @@ export async function handleTelegramAgentEndRuntime<
         });
       }
     } else if (finalText) {
-      if (deps.sendGuestReply) {
-        await deps.sendGuestReply(turn.guestQueryId, finalText);
-      } else {
-        await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+      try {
+        if (deps.sendGuestReply) {
+          await deps.sendGuestReply(turn.guestQueryId, finalText);
+        } else {
+          await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+        }
+      } catch (error) {
+        // Guest queries expire after Telegram's response timeout, so a slow
+        // turn can fail the only delivery attempt. Record and continue the
+        // agent-end lifecycle instead of rejecting the extension hook.
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-reply",
+          guestQueryId: turn.guestQueryId,
+        });
       }
     }
     if (!isDeliveryActive()) return;
@@ -1908,23 +1966,37 @@ export async function handleTelegramAgentEndRuntime<
   const deliverActiveTurn = async () => {
     await deps.waitForActivityIdle?.();
     if (!isDeliveryActive()) return;
-    if (endPlan.shouldClearPreview || (!finalText && hasOutboundArtifacts)) {
+    let previewCleared = false;
+    const clearTurnPreview = async () => {
+      if (previewCleared) return;
       await clearPreview?.();
+      previewCleared = true;
+    };
+    if (endPlan.shouldClearPreview || (!finalText && hasOutboundArtifacts)) {
+      await clearTurnPreview();
       if (!isDeliveryActive()) return;
     }
     if (endPlan.shouldSendErrorMessage) {
+      const errorMessage = assistant.errorMessage ||
+        "Telegram bridge: Pi failed while processing the request.";
+      const isOperationAborted = errorMessage.trim().replace(/\.$/, "") ===
+        "This operation was aborted";
       await deps.sendTextReply(
         turn.chatId,
         turn.replyToMessageId,
-        assistant.errorMessage ||
-          "Telegram bridge: Pi failed while processing the request.",
-        { target: turn.target },
+        isOperationAborted
+          ? "<b>⏹️ This operation was aborted.</b>"
+          : errorMessage,
+        {
+          target: turn.target,
+          ...(isOperationAborted ? { parseMode: "HTML" as const } : {}),
+        },
       );
       if (!isDeliveryActive()) return;
       if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
       return;
     }
-    if (finalText) setPreviewPendingText(finalText);
+    if (finalText && turn.queuedAttachments.length === 0) setPreviewPendingText(finalText);
 
     if (!isDeliveryActive()) return;
     let richAttachmentDelivered = false;
@@ -1942,7 +2014,7 @@ export async function handleTelegramAgentEndRuntime<
         );
         if (!isDeliveryActive()) return;
         if (richAttachmentDelivered) {
-          await clearPreview?.();
+          await clearTurnPreview();
           if (!isDeliveryActive()) return;
           setPreviewPendingText("");
         }
@@ -1957,24 +2029,42 @@ export async function handleTelegramAgentEndRuntime<
       }
     }
     if (!isDeliveryActive()) return;
+    let queuedAttachmentsDelivered = false;
+    if (!richAttachmentDelivered && turn.queuedAttachments.length > 0) {
+      await clearTurnPreview();
+      if (!isDeliveryActive()) return;
+      setPreviewPendingText("");
+      await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+      if (!isDeliveryActive()) return;
+      queuedAttachmentsDelivered = true;
+    }
     if (!richAttachmentDelivered && endPlan.kind === "text" && finalText) {
       try {
-        const finalized = await finalizeMarkdownPreview(
-          turn.chatId,
-          finalText,
-          turn.replyToMessageId,
-          { replyMarkup, target: turn.target },
-        );
-        if (!isDeliveryActive()) return;
-        if (!finalized) {
-          await clearPreview?.();
-          if (!isDeliveryActive()) return;
+        if (queuedAttachmentsDelivered) {
           await deps.sendMarkdownReply(
             turn.chatId,
             turn.replyToMessageId,
             finalText,
             { replyMarkup, target: turn.target },
           );
+        } else {
+          const finalized = await finalizeMarkdownPreview(
+            turn.chatId,
+            finalText,
+            turn.replyToMessageId,
+            { replyMarkup, target: turn.target },
+          );
+          if (!isDeliveryActive()) return;
+          if (!finalized) {
+            await clearTurnPreview();
+            if (!isDeliveryActive()) return;
+            await deps.sendMarkdownReply(
+              turn.chatId,
+              turn.replyToMessageId,
+              finalText,
+              { replyMarkup, target: turn.target },
+            );
+          }
         }
         if (!isDeliveryActive()) return;
         setPreviewPendingText("");
@@ -2041,7 +2131,9 @@ export async function handleTelegramAgentEndRuntime<
       );
     }
     if (!isDeliveryActive()) return;
-    if (!richAttachmentDelivered) await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+    if (!richAttachmentDelivered && !queuedAttachmentsDelivered) {
+      await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+    }
     if (!isDeliveryActive()) return;
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
   };

package/node_modules/@llblab/pi-telegram/lib/rendering.ts

@@ -551,9 +551,12 @@ function applyInlineMarkdownStyles(text: string): string {
   result = renderDelimitedInlineStyle(result, "*", (content) => {
     return `<i>${content}</i>`;
   });
-  return renderDelimitedInlineStyle(result, "_", (content) => {
+  result = renderDelimitedInlineStyle(result, "_", (content) => {
     return `<i>${content}</i>`;
   });
+  return renderDelimitedInlineStyle(result, "||", (content) => {
+    return `<tg-spoiler>${content}</tg-spoiler>`;
+  });
 }
 
 function restoreInlineMarkdownTokens(

package/node_modules/@llblab/pi-telegram/lib/replies.ts

@@ -672,7 +672,7 @@ export async function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
       chatId, index === 0 ? replyToMessageId : undefined, options?.target,
       (replyParameters) => deps.sendRichMessage({
         chat_id: chatId,
-        rich_message: { markdown: chunk, skip_entity_detection: true },
+        rich_message: { markdown: chunk },
         reply_markup:
           index === chunks.length - 1 ? options?.replyMarkup : undefined,
         ...(replyParameters ? { reply_parameters: replyParameters } : {}),
@@ -894,7 +894,26 @@ export function createGuestMarkdownReplySender(deps: {
   return async (guestQueryId: string, markdown: string) => {
     const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
     await deps.answerGuestQuery(guestQueryId, undefined, {
-      richMessage: { markdown: richMarkdown, skip_entity_detection: true },
+      richMessage: { markdown: richMarkdown },
+    });
+  };
+}
+
+/**
+ * Guest reply editor: replaces an early Guest Mode answer (the temporary ACK
+ * experiment) with native Rich Markdown content addressed by
+ * `inline_message_id` instead of a chat/message pair.
+ */
+export function createGuestMarkdownReplyEditor(deps: {
+  editGuestInlineMessage: (
+    inlineMessageId: string,
+    content: { richMessage?: TelegramInputRichMessage; text?: string },
+  ) => Promise<void>;
+}) {
+  return async (inlineMessageId: string, markdown: string) => {
+    const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
+    await deps.editGuestInlineMessage(inlineMessageId, {
+      richMessage: { markdown: richMarkdown },
     });
   };
 }