@llblab/pi-kit 0.5.2 → 0.7.0

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

@@ -5,7 +5,8 @@
  */
 
 import { normalizeTelegramNativeMarkdown } from "./replies.ts";
-import { stripTelegramCommentMarkupForPreview } from "./outbound.ts";
+import type { TelegramAssistantOutputPreparation } from "./activity.ts";
+import { stripTelegramCommentMarkupForPreview } from "./outbound-markup.ts";
 import {
   getTelegramTargetThreadParams,
   type TelegramTarget,
@@ -14,6 +15,7 @@ import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
 const TELEGRAM_DRAFT_ID_MAX = 2_147_483_647;
 const TELEGRAM_DRAFT_PREVIEW_MAX_CHARS = 4096;
+const TELEGRAM_DRAFT_INTERVAL_MS = 2_000;
 
 export type TelegramDraftSupport = "unknown" | "supported";
 
@@ -27,6 +29,11 @@ export interface TelegramPreviewState {
 export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
   flushPromise?: Promise<void>;
   flushRequested?: boolean;
+  precedingFlush?: Promise<void>;
+  publicationPromise?: Promise<void>;
+  sealed?: boolean;
+  nextDraftAt?: number;
+  flushTimer?: ReturnType<typeof setTimeout>;
 }
 
 export type TelegramPreviewReplyMarkup = unknown;
@@ -35,6 +42,7 @@ export interface TelegramPreviewRuntimeDeps {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   maxMessageLength: number;
+  minDraftIntervalMs?: number;
   getDraftSupport: () => TelegramDraftSupport;
   setDraftSupport: (support: TelegramDraftSupport) => void;
   allocateDraftId: () => number;
@@ -64,23 +72,13 @@ export interface TelegramPreviewActiveTurn {
   voiceReplyRequired?: boolean;
 }
 
-export interface TelegramAssistantMessagePreviewStartDeps<
-  TMessage,
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> {
+export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
   getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
   isAssistantMessage: (message: TMessage) => boolean;
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   createPreviewState: () => TelegramPreviewRuntimeState;
   canSend?: () => boolean;
-  finalizePreview: (chatId: number) => Promise<boolean>;
-  finalizeMarkdownPreview: (
-    chatId: number,
-    markdown: string,
-    replyToMessageId?: number,
-    options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
-  ) => Promise<boolean>;
 }
 
 export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
@@ -97,10 +95,7 @@ export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
   ) => void;
 }
 
-export type TelegramAssistantMessagePreviewHookDeps<
-  TMessage,
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> = TelegramAssistantMessagePreviewStartDeps<TMessage, TReplyMarkup> &
+export type TelegramAssistantMessagePreviewHookDeps<TMessage> = TelegramAssistantMessagePreviewStartDeps<TMessage> &
   TelegramAssistantMessagePreviewUpdateDeps<TMessage>;
 
 export interface TelegramAssistantMessagePreviewHookEvent<TMessage> {
@@ -140,6 +135,8 @@ export interface TelegramPreviewControllerDeps {
 }
 
 export interface TelegramPreviewController {
+  seal: () => void;
+  preparePublication: () => TelegramAssistantOutputPreparation | undefined;
   prepareClear: (
     chatId: number,
     options?: { target?: TelegramTarget; isDeliveryActive?: () => boolean },
@@ -201,11 +198,18 @@ export interface TelegramAssistantPreviewRuntimeDeps<
   ) => Promise<number | undefined>;
 }
 
+export interface TelegramPreparedPreviewDelivery<TReplyMarkup = unknown> {
+  clearPreview: TelegramPreviewController["clear"];
+  setPreviewPendingText: TelegramPreviewController["setPendingText"];
+  finalizeMarkdownPreview: ReturnType<typeof createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>>;
+}
+
 export type TelegramAssistantPreviewRuntime<
   TMessage,
   TReplyMarkup = TelegramPreviewReplyMarkup,
 > = TelegramPreviewController &
   TelegramAssistantMessagePreviewHooks<TMessage> & {
+    prepareDelivery: (isDeliveryActive: () => boolean) => TelegramPreparedPreviewDelivery<TReplyMarkup>;
     finalizeMarkdown: (
       chatId: number,
       markdown: string,
@@ -214,6 +218,14 @@ export type TelegramAssistantPreviewRuntime<
     ) => Promise<boolean>;
   };
 
+function sealTelegramPreviewState(state: TelegramPreviewRuntimeState | undefined): void {
+  if (!state) return;
+  state.sealed = true;
+  state.flushRequested = false;
+  if (state.flushTimer) clearTimeout(state.flushTimer);
+  state.flushTimer = undefined;
+}
+
 export function createTelegramNativeMarkdownPreviewFinalizer<
   TReplyMarkup,
 >(deps: {
@@ -223,6 +235,7 @@ export function createTelegramNativeMarkdownPreviewFinalizer<
     options?: { awaitFlush?: boolean; target?: TelegramTarget },
   ) => Promise<void>;
   discard?: () => void;
+  isDeliveryActive?: () => boolean;
   sendMarkdownReply: (
     chatId: number,
     replyToMessageId: number | undefined,
@@ -235,14 +248,21 @@ export function createTelegramNativeMarkdownPreviewFinalizer<
   replyToMessageId?: number,
   options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
 ) => Promise<boolean> {
+  return (...args) => prepareTelegramNativeMarkdownPreviewFinalizer(deps)(...args);
+}
+
+function prepareTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>(
+  deps: Parameters<typeof createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>>[0],
+): ReturnType<typeof createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>> {
+  const state = deps.getState();
+  sealTelegramPreviewState(state);
+  const inFlight = state?.flushPromise ?? state?.precedingFlush;
   return async (chatId, markdown, replyToMessageId, options) => {
-    const state = deps.getState();
-    if (state?.flushPromise) {
-      await state.flushPromise.catch(() => {});
-      if (deps.getState() !== state) return false;
-    }
+    if (deps.isDeliveryActive?.() === false) return false;
+    await inFlight?.catch(() => {});
+    if (deps.getState() !== state || deps.isDeliveryActive?.() === false) return false;
     await deps.sendMarkdownReply(chatId, replyToMessageId, markdown, options);
-    if (deps.getState() === state) deps.discard?.();
+    if (deps.getState() === state && deps.isDeliveryActive?.() !== false) deps.discard?.();
     return true;
   };
 }
@@ -254,15 +274,28 @@ export function createTelegramAssistantPreviewRuntime<
   deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>,
 ): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup> {
   const controller = createTelegramPreviewControllerRuntime(deps);
-  const finalizeMarkdownPreview = createTelegramNativeMarkdownPreviewFinalizer({
+  const finalizerDeps = {
     getState: controller.getState,
     clear: controller.clear,
     discard: () => controller.setState(undefined),
     sendMarkdownReply: deps.sendMarkdownReply,
-  });
+  };
   return {
     ...controller,
-    finalizeMarkdown: finalizeMarkdownPreview,
+    finalizeMarkdown: createTelegramNativeMarkdownPreviewFinalizer(finalizerDeps),
+    prepareDelivery(isDeliveryActive) {
+      const state = controller.getState();
+      return {
+        setPreviewPendingText(text) {
+          if (controller.getState() === state && isDeliveryActive()) controller.setPendingText(text);
+        },
+        clearPreview: async (chatId, options) => {
+          if (controller.getState() !== state || !isDeliveryActive()) return;
+          await controller.prepareClear(chatId, { ...options, isDeliveryActive })();
+        },
+        finalizeMarkdownPreview: prepareTelegramNativeMarkdownPreviewFinalizer({ ...finalizerDeps, isDeliveryActive }),
+      };
+    },
     ...createTelegramAssistantMessagePreviewHooks({
       getActiveTurn: deps.getActiveTurn,
       isAssistantMessage: deps.isAssistantMessage,
@@ -270,8 +303,6 @@ export function createTelegramAssistantPreviewRuntime<
       setState: controller.setState,
       createPreviewState: controller.createState,
       canSend: deps.canSend,
-      finalizePreview: controller.finalize,
-      finalizeMarkdownPreview,
       getMessageText: deps.getMessageText,
       schedulePreviewFlush: controller.scheduleFlush,
     }),
@@ -288,14 +319,17 @@ export function createTelegramPreviewController(
     deps.maxMessageLength ?? TELEGRAM_DRAFT_PREVIEW_MAX_CHARS;
   let draftSupport = deps.initialDraftSupport ?? "unknown";
   let nextDraftId = 0;
+  const setState = (nextState: TelegramPreviewRuntimeState | undefined): void => {
+    if (state !== nextState) sealTelegramPreviewState(state);
+    state = nextState;
+  };
   const getRuntimeDeps = (
     operationGeneration = generation,
   ): TelegramPreviewRuntimeDeps => ({
     getState: () => state,
-    setState: (nextState) => {
-      state = nextState;
-    },
+    setState,
     maxMessageLength,
+    minDraftIntervalMs: TELEGRAM_DRAFT_INTERVAL_MS,
     getDraftSupport: () => draftSupport,
     setDraftSupport: (support) => {
       draftSupport = support;
@@ -311,20 +345,27 @@ export function createTelegramPreviewController(
   });
   return {
     getState: () => state,
-    setState: (nextState) => {
-      state = nextState;
-    },
+    setState,
     setPendingText: (text) => {
       if (state) state.pendingText = text;
     },
     createState: () => createTelegramPreviewRuntimeState(),
     resetState: () => {
       generation += 1;
-      state = createTelegramPreviewRuntimeState();
+      setState({ ...createTelegramPreviewRuntimeState(), nextDraftAt: state?.nextDraftAt });
     },
     invalidate: () => {
       generation += 1;
-      state = undefined;
+      setState(undefined);
+    },
+    seal: () => sealTelegramPreviewState(state),
+    preparePublication: () => {
+      if (!state) return undefined;
+      sealTelegramPreviewState(state);
+      const prior = state.publicationPromise ?? state.flushPromise ?? state.precedingFlush;
+      let settle!: () => void;
+      state.publicationPromise = new Promise<void>((resolve) => { settle = resolve; });
+      return { wait: async () => { await prior?.catch(() => {}); }, settle };
     },
     prepareClear: (chatId, options) => {
       const admittedState = state;
@@ -350,11 +391,8 @@ export function createTelegramPreviewController(
   };
 }
 
-export function createTelegramAssistantMessagePreviewHooks<
-  TMessage,
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
-  deps: TelegramAssistantMessagePreviewHookDeps<TMessage, TReplyMarkup>,
+export function createTelegramAssistantMessagePreviewHooks<TMessage>(
+  deps: TelegramAssistantMessagePreviewHookDeps<TMessage>,
 ): TelegramAssistantMessagePreviewHooks<TMessage> {
   return {
     onMessageStart: async (
@@ -370,12 +408,9 @@ export function createTelegramAssistantMessagePreviewHooks<
   };
 }
 
-export async function handleTelegramAssistantMessagePreviewStart<
-  TMessage,
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
+export async function handleTelegramAssistantMessagePreviewStart<TMessage>(
   message: TMessage,
-  deps: TelegramAssistantMessagePreviewStartDeps<TMessage, TReplyMarkup>,
+  deps: TelegramAssistantMessagePreviewStartDeps<TMessage>,
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
@@ -388,26 +423,13 @@ export async function handleTelegramAssistantMessagePreviewStart<
     return;
   }
   const state = deps.getState();
-  if (
-    state &&
-    (state.pendingText.trim().length > 0 ||
-      state.lastSentText.trim().length > 0)
-  ) {
-    const previousText = state.pendingText.trim();
-    if (previousText.length > 0) {
-      await deps.finalizeMarkdownPreview(
-        turn.chatId,
-        previousText,
-        turn.replyToMessageId,
-        {
-          target: turn.target,
-        },
-      );
-    } else {
-      await deps.finalizePreview(turn.chatId);
-    }
-  }
-  deps.setState(deps.createPreviewState());
+  sealTelegramPreviewState(state);
+  const next = deps.createPreviewState();
+  // Carry the previous delivery boundary; permanent text remains with its publication owner.
+  next.draftId = state?.draftId;
+  next.nextDraftAt = state?.nextDraftAt;
+  next.precedingFlush = state?.publicationPromise ?? state?.flushPromise ?? state?.precedingFlush;
+  deps.setState(next);
 }
 
 export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
@@ -426,6 +448,7 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
     state = deps.createPreviewState();
     deps.setState(state);
   }
+  if (state.sealed) return;
   state.pendingText = stripTelegramCommentMarkupForPreview(
     deps.getMessageText(message),
   );
@@ -473,9 +496,11 @@ export async function clearTelegramPreview(
 ): Promise<void> {
   const state = deps.getState();
   if (!state || options.isDeliveryActive?.() === false) return;
-  if (state.flushPromise && options.awaitFlush !== false) {
+  sealTelegramPreviewState(state);
+  const inFlight = state.flushPromise ?? state.precedingFlush;
+  if (inFlight && options.awaitFlush !== false) {
     state.flushRequested = false;
-    await state.flushPromise.catch(() => {});
+    await inFlight.catch(() => {});
     if (deps.getState() !== state) return;
   }
   if (options.isDeliveryActive?.() === false) return;
@@ -782,13 +807,15 @@ async function performTelegramPreviewFlush(
   ) {
     const draftId = state.draftId ?? deps.allocateDraftId();
     state.draftId = draftId;
+    state.nextDraftAt = Date.now() + (deps.minDraftIntervalMs ?? 0);
     try {
-      await deps.sendDraft(
+      const delivered = await deps.sendDraft(
         chatId,
         draftId,
         normalizeTelegramNativeMarkdown(snapshot.text),
         { ...getTelegramTargetThreadParams(options.target ?? { chatId }) },
       );
+      if (delivered === false || deps.getState() !== state || deps.canSend?.() === false) return;
       deps.setDraftSupport("supported");
       state.mode = "draft";
       state.lastSentText = snapshot.text;
@@ -810,15 +837,33 @@ export async function flushTelegramPreview(
   options: { target?: TelegramTarget } = {},
 ): Promise<void> {
   const state = deps.getState();
-  if (!state) return;
+  if (!state || state.sealed) return;
   if (state.flushPromise) {
     state.flushRequested = true;
     await state.flushPromise;
     return;
   }
   state.flushPromise = (async () => {
+    if (state.precedingFlush) {
+      await state.precedingFlush.catch(() => {});
+      state.precedingFlush = undefined;
+      if (deps.getState() !== state || state.sealed) return;
+    }
     do {
       state.flushRequested = false;
+      const delay = (state.nextDraftAt ?? 0) - Date.now();
+      if (delay > 0) {
+        if (!state.flushTimer) {
+          state.flushTimer = setTimeout(() => {
+            state.flushTimer = undefined;
+            if (deps.getState() === state && !state.sealed) void flushTelegramPreview(chatId, deps, options);
+          }, delay);
+          state.flushTimer.unref?.();
+        }
+        break;
+      }
+      if (state.flushTimer) clearTimeout(state.flushTimer);
+      state.flushTimer = undefined;
       try {
         await performTelegramPreviewFlush(chatId, state, deps, options);
       } catch (error) {
@@ -829,7 +874,7 @@ export async function flushTelegramPreview(
         });
         break;
       }
-    } while (deps.getState() === state && state.flushRequested);
+    } while (deps.getState() === state && !state.sealed && state.flushRequested);
   })();
   try {
     await state.flushPromise;

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,10 @@ 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 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 +49,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

@@ -1498,6 +1498,10 @@ export interface TelegramAgentEndRuntimeDeps<
   updateStatus: () => void;
   dispatchNextQueuedTelegramTurn: () => void;
   scheduleActiveTurnDelivery?: (task: () => Promise<void>) => void;
+  preparePreviewDelivery?: (isDeliveryActive: () => boolean) => Pick<
+    TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>,
+    "clearPreview" | "setPreviewPendingText" | "finalizeMarkdownPreview"
+  > | undefined;
   preparePreviewClear?: (
     chatId: number,
     options?: { target?: TelegramQueueTarget; isDeliveryActive?: () => boolean },
@@ -1523,7 +1527,7 @@ export interface TelegramAgentEndRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: TelegramQueueTarget },
+    options?: { target?: TelegramQueueTarget; parseMode?: "HTML" },
   ) => Promise<unknown>;
   sendQueuedAttachments: (
     turn: TTurn,
@@ -1595,6 +1599,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
     schedule: (task: () => Promise<void>) => void;
     cancel: () => void;
   };
+  preparePreviewDelivery?: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["preparePreviewDelivery"];
   preparePreviewClear?: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>["preparePreviewClear"];
   clearPreview: TelegramAgentEndRuntimeDeps<
     TTurn,
@@ -1746,6 +1751,7 @@ export function createTelegramAgentEndHook<
                 await task();
               })
           : undefined,
+        preparePreviewDelivery: deps.preparePreviewDelivery,
         preparePreviewClear: deps.preparePreviewClear,
         clearPreview: deps.clearPreview,
         setPreviewPendingText: deps.setPreviewPendingText,
@@ -1807,9 +1813,13 @@ export async function handleTelegramAgentEndRuntime<
   const isDeliveryActive = (): boolean =>
     deps.isSessionActive?.() !== false &&
     (!turn || deps.isTurnTransportActive?.(turn) !== false);
+  const preview = turn && !turn.guestQueryId ? deps.preparePreviewDelivery?.(isDeliveryActive) : undefined;
+  const setPreviewPendingText = preview?.setPreviewPendingText ?? deps.setPreviewPendingText;
+  const finalizeMarkdownPreview = preview?.finalizeMarkdownPreview ?? deps.finalizeMarkdownPreview;
   const clearPreview = turn
-    ? deps.preparePreviewClear?.(turn.chatId, { target: turn.target, isDeliveryActive })
-      ?? (() => deps.clearPreview(turn.chatId, { target: turn.target }))
+    ? preview ? () => preview.clearPreview(turn.chatId, { target: turn.target })
+      : deps.preparePreviewClear?.(turn.chatId, { target: turn.target, isDeliveryActive })
+        ?? (() => deps.clearPreview(turn.chatId, { target: turn.target }))
     : undefined;
   const updateStatusIgnoringStaleContext = (): void => {
     try {
@@ -1898,23 +1908,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) deps.setPreviewPendingText(finalText);
+    if (finalText && turn.queuedAttachments.length === 0) setPreviewPendingText(finalText);
 
     if (!isDeliveryActive()) return;
     let richAttachmentDelivered = false;
@@ -1932,9 +1956,9 @@ export async function handleTelegramAgentEndRuntime<
         );
         if (!isDeliveryActive()) return;
         if (richAttachmentDelivered) {
-          await deps.clearPreview(turn.chatId, { target: turn.target });
+          await clearTurnPreview();
           if (!isDeliveryActive()) return;
-          deps.setPreviewPendingText("");
+          setPreviewPendingText("");
         }
       } catch (error) {
         if (!isDeliveryActive()) return;
@@ -1947,27 +1971,45 @@ 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 deps.finalizeMarkdownPreview(
-          turn.chatId,
-          finalText,
-          turn.replyToMessageId,
-          { replyMarkup, target: turn.target },
-        );
-        if (!isDeliveryActive()) return;
-        if (!finalized) {
-          await deps.clearPreview(turn.chatId, { target: turn.target });
-          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;
-        deps.setPreviewPendingText("");
+        setPreviewPendingText("");
       } catch (error) {
         deps.recordRuntimeEvent?.("delivery", error, {
           phase: "final-text",
@@ -2031,7 +2073,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();
   };