@llblab/pi-telegram 0.45.8 → 0.45.10

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.45.10: Rich headings and state-scope markers
+
+- `Rich section headings`: Public Rich Message block types now include native headings, allowing companion sections to place a fixed title above sibling disclosures instead of wrapping the entire view in another collapsible block.
+- `State-scope markers`: Registers 🌐 Global, 📂 CWD, 💬 Session, and 🧬 Effective as canonical state-scope semantics for chooser buttons and selected-scope headings, with composition flowing Global → CWD → Session → Effective.
+
+## 0.45.9: Rich sections and exact queue continuation
+
+- `Extension Sections`: Public section contexts now expose `openRich(message)` for one standalone Telegram Native Rich Message routed to the exact callback chat/thread with normal message-ownership recording and scoped callback diagnostics. Companion extensions can reuse native `details`/`pre` disclosure without raw bot access; `👁` is the canonical read-only inspection marker.
+- `/next` ordering: Active interruption settles before continuation is announced. The notice is bound to the exact selected queued item and revalidates queue identity, readiness, admission, pending mutations, and transport authority before dispatch; removal, clear, reordering, concurrent append, or transport loss cannot transfer stale intent to unrelated work.
+
 ## 0.45.8: Follower Forwarding Hotfix
 
 - `Follower Forwarding`: Message-ownership lookups now project the matching live registration's protocol identity before forwarding. Voice/message and edit retries, message-only callbacks, and reactions no longer stall on an incomplete cached owner after a rejection or re-registration. Exact generation, binding, protocol, and durable-receipt checks remain enforced.

package/api/sections.ts

@@ -4,6 +4,8 @@
  * Exposes the stable managed Telegram menu-section surface while keeping registry internals package-private
  */
 
+export type { TelegramInputRichBlock, TelegramInputRichMessage, TelegramRichText } from "../lib/telegram-api.ts";
+
 export {
   getTelegramSectionDiagnostics,
   registerTelegramSection,

package/docs/architecture.md

@@ -507,7 +507,7 @@ Immediate controls:
 - `/start` opens the main inline application menu.
 - `/model`, `/thinking`, `/queue`, and `/settings` are hidden shortcuts to menu sections.
 - `/compact` opens an inline confirmation dialog and then runs compaction when the bridge is idle.
-- `/next` dispatches the next queued turn, aborting Pi first when needed. When an active Telegram turn is aborted, its single Pi-aligned informational notice replies to a pre-abort snapshot of that turn; otherwise the command message is the fallback target. Aborted pending assistant text is not projected as a second reply, while already completed intermediate output remains visible.
+- `/next` dispatches the next queued turn, aborting Pi first when needed. Active-turn settlement delivers its abort notice to the interrupted prompt before queue dispatch continues. The queue owner then emits `Dispatching next queued turn.` against the exact selected prompt's chat/thread/reply id before its one model dispatch; skipped, inactive, pending-mutation, and admission-blocked candidates never receive it. The `/next` command itself is never a lifecycle-notice reply target. Aborted pending assistant text is not projected as a second reply, while already completed intermediate output remains visible.
 - `/abort` aborts active work while preserving queued items. Abort-history preservation is enabled only for Telegram-owned active turns; later local/non-Telegram agent starts clear stale abort-history mode so the next Telegram prompt appends instead of absorbing old queued turns as history.
 - `/stop` aborts and clears waiting Telegram queue items.
 

package/docs/public-api.md

@@ -52,7 +52,7 @@ Stable commands inside the paired Telegram DM:
 
 - `/start` — pair when needed and open the main application menu.
 - `/compact` — open confirmation and compact when idle.
-- `/next` — dispatch the next queued turn, aborting active work first when needed; one Pi-aligned informational reply anchors to a pre-abort snapshot of the Telegram turn or falls back to the command, and aborted pending assistant text is suppressed.
+- `/next` — abort active work first when needed, let the interrupted prompt receive its abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. The command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.
 - `/abort` — abort active work and keep the queue; abort-history is scoped to Telegram-owned active turns.
 - `/stop` — abort active Telegram-owned work and clear waiting Telegram queue items.

package/docs/sections.md

@@ -262,6 +262,8 @@ interface TelegramSectionContext {
   edit(view: TelegramSectionView): Promise<void>;
   /** Send a standalone chat message without auto-navigation */
   open(view: TelegramSectionView): Promise<void>;
+  /** Send one standalone Telegram Native Rich Message without exposing transport */
+  openRich(message: TelegramInputRichMessage): Promise<void>;
   /** Enqueue a plain-text prompt turn */
   enqueuePrompt(prompt: string): Promise<void>;
   /** Build a section-namespaced callback_data string */
@@ -285,6 +287,7 @@ interface TelegramSectionCallbackContext {
   answerCallback(text?: string): Promise<void>;
   edit(view: TelegramSectionView): Promise<void>;
   open(view: TelegramSectionView): Promise<void>;
+  openRich(message: TelegramInputRichMessage): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
   /** Delete the message that triggered this callback */
@@ -292,6 +295,12 @@ interface TelegramSectionCallbackContext {
 }
 ```
 
+### `openRich` semantics
+
+`ctx.openRich(message)` sends exactly one standalone Telegram Native Rich Message to the callback's exact chat/thread target. It accepts the public `TelegramInputRichMessage` tree (`details` and `pre` blocks) used by native tool evidence, records message ownership, and routes through the active direct/follower transport. It adds no menu navigation and exposes no raw bot client or arbitrary API method.
+
+Use it when disclosure behavior is part of the document, such as one selected read-only state or evidence tree. Do not imitate nested disclosure with HTML or Markdown when the native tree is required.
+
 ### `enqueuePrompt` semantics
 
 Queues a `[telegram] <prompt>` turn in the default lane with the paired user's `chatId`. Uses `queueMutationRuntime.append()` and triggers `dispatchNextQueuedTelegramTurn()`. The prompt arrives as a normal Telegram-owned turn — the agent sees it as if the user typed it.

package/docs/ui-style.md

@@ -36,6 +36,11 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `🔬` | Activity / technical detail | Activity settings row and detail card | Chooses quiet, thinking, tools, or verbose bridge activity; not a generic diagnostics marker. |
 | `🧠` | Model thinking controls | Thinking menus and status rows | Thinking activity quotes omit this icon and their header entirely to minimize chat height. |
 | `📎` | Attachment | Attachment summaries, queue rows for attachment-only turns | Not for thread binding. |
+| `👁` | Read-only inspection | State/detail viewers and inspection entrypoints | Opens evidence without mutating the inspected object; do not use for edit or refresh actions. |
+| `🌐` | Global state scope | State-scope chooser and selected-scope heading | Cross-project memory composed first. |
+| `📂` | Current-working-directory state scope | State-scope chooser and selected-scope heading | Project-local memory composed after Global. |
+| `💬` | Session state scope | State-scope chooser and selected-scope heading | Conversation-branch memory composed after CWD. |
+| `🧬` | Effective composed state | State-scope chooser and selected-scope heading | The resulting Global → CWD → Session projection. |
 
 ### Command And Control Actions
 

package/lib/bindings.ts

@@ -50,6 +50,7 @@ type TelegramAgentMessageRouter = NonNullable<
 export interface TelegramQueueBindingRuntime<TContext> {
   mutation: Queue.TelegramQueueMutationController<TContext>;
   dispatchNext: (ctx: TContext) => void;
+  requestNextDispatchAnnouncement: () => void;
   watchdog: Queue.TelegramQueueDispatchWatchdogRuntime<TContext>;
 }
 
@@ -122,7 +123,7 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
     updateStatus: deps.updateStatus,
     recordRuntimeEvent: deps.recordRuntimeEvent,
   });
-  const dispatchNext = Queue.createTelegramQueueDispatchRuntime({
+  const dispatch = Queue.createTelegramQueueDispatchRuntime({
     ...deps.store,
     isCompactionInProgress: deps.lifecycle.isCompactionInProgress,
     hasActiveTurn: deps.activeTurn.has,
@@ -162,13 +163,14 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
     recordRuntimeEvent: deps.recordRuntimeEvent,
     ...deps.promptDispatch,
     sendUserMessage: deps.sendUserMessage,
-  }).dispatchNext;
+  });
   return {
     mutation,
-    dispatchNext,
+    dispatchNext: dispatch.dispatchNext,
+    requestNextDispatchAnnouncement: dispatch.requestNextDispatchAnnouncement,
     watchdog: Queue.createTelegramQueueDispatchWatchdogRuntime({
       hasQueuedItems: deps.store.hasQueuedItems,
-      dispatchNextQueuedTelegramTurn: dispatchNext,
+      dispatchNextQueuedTelegramTurn: dispatch.dispatchNext,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     }),
   };

package/lib/commands.ts

@@ -1147,6 +1147,7 @@ export interface TelegramCommandRuntimeDeps<
   updateStatus: (ctx: TContext) => void;
   isContextActive?: (ctx: TContext) => boolean;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  requestNextDispatchAnnouncement?: () => void;
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: (ctx: TContext) => void,
   ) => void;
@@ -1416,6 +1417,7 @@ export async function handleTelegramNextCommand(deps: {
   clearPendingModelSwitch: () => void;
   abortCurrentTurn: () => void;
   dispatchNextQueuedTurn: () => void;
+  requestNextDispatchAnnouncement?: () => void;
   clearFoldForDispatch: () => void;
   updateStatus: () => void;
   sendTextReply: (
@@ -1435,19 +1437,10 @@ export async function handleTelegramNextCommand(deps: {
     return;
   }
   if (!deps.isIdle() && deps.hasAbortHandler()) {
-    const activeTurnReply = deps.getActiveTurnReply?.();
     deps.clearFoldForDispatch();
+    deps.requestNextDispatchAnnouncement?.();
     deps.abortCurrentTurn();
     deps.updateStatus();
-    const notice = formatTelegramInformationHeading(
-      "⏩",
-      "Dispatching next queued turn.",
-    );
-    if (activeTurnReply) {
-      await activeTurnReply(notice, { parseMode: "HTML" });
-    } else {
-      await deps.sendTextReply(notice, { parseMode: "HTML" });
-    }
     return;
   }
   if (!deps.isIdle()) {
@@ -1460,12 +1453,9 @@ export async function handleTelegramNextCommand(deps: {
     );
     return;
   }
+  deps.requestNextDispatchAnnouncement?.();
   deps.dispatchNextQueuedTurn();
   deps.updateStatus();
-  await deps.sendTextReply(
-    formatTelegramInformationHeading("▶️", "Dispatching next queued turn."),
-    { parseMode: "HTML" },
-  );
 }
 
 export async function handleTelegramContinueCommand<TMessage, TContext>(
@@ -2029,6 +2019,7 @@ async function handleTelegramCommandRuntime<
           abortCurrentTurn: deps.abortCurrentTurn,
           dispatchNextQueuedTurn: () =>
             deps.dispatchNextQueuedTelegramTurn(commandCtx),
+          requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
           clearFoldForDispatch: () =>
             deps.setFoldQueuedPromptsIntoHistory(false),
           updateStatus: updateStatusFor(commandCtx),

package/lib/extension.ts

@@ -629,8 +629,12 @@ export default function (pi: Pi.ExtensionAPI) {
     getAssistantRenderingMode: configControls.getAssistantRenderingMode,
     editMessage: editTelegramMessageText,
   });
-  const { replyTransport, editInteractiveMessage, sendInteractiveMessage } =
-    replyRuntime;
+  const {
+    replyTransport,
+    editInteractiveMessage,
+    sendInteractiveMessage,
+    sendSectionRichMessage,
+  } = replyRuntime;
   const deliveryTargetPolicyRuntime =
     Delivery.createTelegramDeliveryTargetPolicyRuntime({
       ownsDirect: lockRuntime.owns,
@@ -744,6 +748,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const {
     mutation: queueMutationRuntime,
     dispatchNext: dispatchNextQueuedTelegramTurn,
+    requestNextDispatchAnnouncement,
     watchdog: queueDispatchWatchdogRuntime,
   } = Bindings.createTelegramQueueBindingRuntime({
     store: telegramQueueStore,
@@ -964,6 +969,7 @@ export default function (pi: Pi.ExtensionAPI) {
     openSettingsMenu: settingsMenuRuntime.openSettingsMenu,
     settingsMenuCallbackHandler: settingsMenuRuntime.handleCallbackQuery,
     sectionRegistry,
+    sendSectionRichMessage,
     buttonActionStore,
     invokeBoundButtonAction: invokeGenerativeAppBoundButtonAction,
     inboundHandlerRuntime,
@@ -972,6 +978,7 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatus,
     isContextActive: telegramSessionContextStore.isCurrent,
     dispatchNextQueuedTelegramTurn,
+    requestNextDispatchAnnouncement,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
     hasDeferredDispatchContext: deferredQueueDispatchRuntime.isBound,

package/lib/menu.ts

@@ -32,6 +32,7 @@ import {
   type ScopedTelegramModel,
   type ThinkingLevel,
 } from "./model.ts";
+import type { TelegramInputRichMessage } from "./telegram-api.ts";
 import {
   handleTelegramSectionCallback,
   handleTelegramSectionOpen,
@@ -225,6 +226,11 @@ export interface TelegramMenuCallbackRuntimeDeps<
     replyMarkup: TelegramReplyMarkup,
     options?: { target?: { chatId: number; threadId?: number } },
   ) => Promise<number | undefined>;
+  sendSectionRichMessage?: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: { target?: { chatId: number; threadId?: number } },
+  ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (
     prompt: string,
     ctx: TContext,
@@ -478,6 +484,11 @@ export interface TelegramMenuCallbackRuntimeAdapterDeps<
     replyMarkup: TelegramReplyMarkup,
     options?: { target?: { chatId: number; threadId?: number } },
   ) => Promise<number | undefined>;
+  sendSectionRichMessage?: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: { target?: { chatId: number; threadId?: number } },
+  ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (
     prompt: string,
     ctx: TContext,
@@ -527,6 +538,7 @@ export function createTelegramMenuCallbackHandlerForContext<
     sectionRegistry: deps.sectionRegistry,
     editInteractiveMessage: deps.editInteractiveMessage,
     sendInteractiveMessage: deps.sendInteractiveMessage,
+    sendSectionRichMessage: deps.sendSectionRichMessage,
     enqueueSectionPrompt: deps.enqueueSectionPrompt,
     deleteMessage: deps.deleteMessage,
   });
@@ -591,6 +603,9 @@ export async function handleTelegramMenuCallbackRuntime<
                 deps.editInteractiveMessage ?? (async () => {}),
               sendInteractiveMessage:
                 deps.sendInteractiveMessage ?? (async () => undefined),
+              sendRichMessage: deps.sendSectionRichMessage ?? (async () => {
+                throw new Error("Rich Message delivery is unavailable");
+              }),
               enqueuePrompt: deps.enqueueSectionPrompt
                 ? (prompt: string) =>
                     deps.enqueueSectionPrompt!(prompt, ctx, target, query)
@@ -614,6 +629,9 @@ export async function handleTelegramMenuCallbackRuntime<
                   deps.editInteractiveMessage ?? (async () => {}),
                 sendInteractiveMessage:
                   deps.sendInteractiveMessage ?? (async () => undefined),
+                sendRichMessage: deps.sendSectionRichMessage ?? (async () => {
+                  throw new Error("Rich Message delivery is unavailable");
+                }),
                 enqueuePrompt: deps.enqueueSectionPrompt
                   ? (prompt: string) =>
                       deps.enqueueSectionPrompt!(prompt, ctx, target, query)
@@ -639,6 +657,9 @@ export async function handleTelegramMenuCallbackRuntime<
                 deps.editInteractiveMessage ?? (async () => {}),
               sendInteractiveMessage:
                 deps.sendInteractiveMessage ?? (async () => undefined),
+              sendRichMessage: deps.sendSectionRichMessage ?? (async () => {
+                throw new Error("Rich Message delivery is unavailable");
+              }),
               enqueuePrompt: deps.enqueueSectionPrompt
                 ? (prompt: string) =>
                     deps.enqueueSectionPrompt!(prompt, ctx, target, query)

package/lib/queue.ts

@@ -3055,6 +3055,7 @@ export interface TelegramQueueDispatchControllerDeps<
 
 export interface TelegramQueueDispatchController<TContext = unknown> {
   dispatchNext: (ctx: TContext) => void;
+  requestNextDispatchAnnouncement: () => void;
 }
 
 export function executeTelegramQueueDispatchPlan<TContext = unknown>(
@@ -3123,7 +3124,13 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
   deps: TelegramQueueDispatchControllerDeps<TContext>,
 ): TelegramQueueDispatchController<TContext> {
   let controlDispatchPending = false;
+  let nextDispatchAnnouncementRequested = false;
+  let nextDispatchAnnouncementAnchor: TelegramQueueItem<TContext> | undefined;
   const controller: TelegramQueueDispatchController<TContext> = {
+    requestNextDispatchAnnouncement: () => {
+      nextDispatchAnnouncementRequested = true;
+      nextDispatchAnnouncementAnchor = undefined;
+    },
     dispatchNext: (ctx) => {
       if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
       if (controlDispatchPending) {
@@ -3151,6 +3158,10 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
       }
       if (droppedInactiveItemCount > 0) {
         deps.setQueuedItems(retainedItems);
+        if (retainedItems.length === 0) {
+          nextDispatchAnnouncementRequested = false;
+          nextDispatchAnnouncementAnchor = undefined;
+        }
         deps.recordRuntimeEvent?.(
           "dispatch",
           new Error(
@@ -3209,6 +3220,21 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
       }
       const dispatchableItems = activeItems.slice(nextActiveIndex);
       const nextItem = dispatchableItems[0];
+      if (nextDispatchAnnouncementRequested) {
+        if (nextDispatchAnnouncementAnchor) {
+          const anchorRetained = retainedItems.includes(nextDispatchAnnouncementAnchor);
+          const anchorTransportActive =
+            deps.isQueueItemTransportActive?.(nextDispatchAnnouncementAnchor) !== false;
+          if (!anchorRetained || !anchorTransportActive) {
+            nextDispatchAnnouncementRequested = false;
+            nextDispatchAnnouncementAnchor = undefined;
+          }
+        } else if (nextItem) {
+          nextDispatchAnnouncementAnchor = nextItem;
+        } else if (retainedItems.length === 0) {
+          nextDispatchAnnouncementRequested = false;
+        }
+      }
       if (
         nextItem &&
         deps.hasPendingInboundQueueMutationForItem?.(nextItem)
@@ -3224,17 +3250,49 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
         deps.updateStatus(ctx);
         return;
       }
+      const dispatchBasisItems = deps.getQueuedItems();
       const dispatchPlan = planNextTelegramQueueAction(
         dispatchableItems,
         canDispatch,
       );
-      if (dispatchPlan.kind !== "none") {
+      const commitDispatchPlan = (): boolean => {
+        if (dispatchPlan.kind === "none") return true;
+        const currentItems = deps.getQueuedItems();
+        if (dispatchPlan.kind === "prompt") {
+          const queueDrifted =
+            currentItems.length !== dispatchBasisItems.length ||
+            currentItems.some((item, index) => item !== dispatchBasisItems[index]);
+          const dispatchEligibilityDrifted =
+            !deps.canDispatch(ctx) ||
+            deps.hasPendingInboundQueueMutationForItem?.(dispatchPlan.item) === true ||
+            (deps.isQueueItemAdmissionReady?.(dispatchPlan.item) === false) ||
+            (deps.isQueueItemTransportActive?.(dispatchPlan.item) === false);
+          if (queueDrifted || dispatchEligibilityDrifted) {
+            const selectedItemRetained = currentItems.includes(dispatchPlan.item);
+            const selectedTransportActive =
+              deps.isQueueItemTransportActive?.(dispatchPlan.item) !== false;
+            nextDispatchAnnouncementRequested =
+              selectedItemRetained && selectedTransportActive;
+            nextDispatchAnnouncementAnchor = nextDispatchAnnouncementRequested
+              ? dispatchPlan.item
+              : undefined;
+            deps.updateStatus(ctx);
+            if (nextDispatchAnnouncementRequested && queueDrifted && !dispatchEligibilityDrifted) {
+              controller.dispatchNext(ctx);
+            }
+            return false;
+          }
+        }
         deps.setQueuedItems([
           ...dispatchPlan.remainingItems,
           ...protectedInactiveItems,
         ]);
-      }
-      executeTelegramQueueDispatchPlan(dispatchPlan, {
+        nextDispatchAnnouncementAnchor = undefined;
+        return true;
+      };
+      const executePlan = (): void => {
+        if (!commitDispatchPlan()) return;
+        executeTelegramQueueDispatchPlan(dispatchPlan, {
         executeControlItem: (item) => {
           controlDispatchPending = true;
           const dispatchGeneration = deps.getDispatchGeneration?.();
@@ -3280,6 +3338,32 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
           deps.updateStatus(ctx);
         },
       });
+      };
+      if (dispatchPlan.kind === "prompt" && nextDispatchAnnouncementRequested) {
+        nextDispatchAnnouncementRequested = false;
+        controlDispatchPending = true;
+        const dispatchGeneration = deps.getDispatchGeneration?.();
+        deps.updateStatus(ctx);
+        void deps.sendTextReply(
+          dispatchPlan.item.chatId,
+          dispatchPlan.item.replyToMessageId,
+          "<b>⏩ Dispatching next queued turn.</b>",
+          { target: dispatchPlan.item.target },
+        ).catch((error) => {
+          deps.recordRuntimeEvent?.("dispatch", error, { phase: "next-announcement" });
+        }).finally(() => {
+          controlDispatchPending = false;
+          if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
+          if (
+            dispatchGeneration !== undefined &&
+            deps.isDispatchGenerationActive &&
+            !deps.isDispatchGenerationActive(dispatchGeneration)
+          ) return;
+          executePlan();
+        });
+        return;
+      }
+      executePlan();
     },
   };
   return controller;

package/lib/replies.ts

@@ -730,6 +730,24 @@ export async function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
   return lastMessageId;
 }
 
+export async function sendTelegramNativeRichMessage(
+  chatId: number,
+  richMessage: TelegramInputRichMessage,
+  deps: {
+    recordOwnership?: TelegramReplyOwnershipRecorder["record"];
+    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
+  },
+  options?: TelegramReplyTargetOptions,
+): Promise<number> {
+  const sent = await deps.sendRichMessage({
+    chat_id: chatId,
+    rich_message: richMessage,
+    ...(options?.target ? getTelegramTargetThreadParams(options.target) : {}),
+  });
+  deps.recordOwnership?.({ chatId, messageId: sent.message_id, target: options?.target });
+  return sent.message_id;
+}
+
 // UI/compat regular-message runtime for bridge-owned text and interactive
 // surfaces. Assistant and guest Markdown delivery bypass this path and use
 // native Rich Message helpers above.
@@ -775,6 +793,11 @@ export interface TelegramRenderedMessageRuntime<TReplyMarkup> {
     replyMarkup: TReplyMarkup,
     options?: TelegramReplyTargetOptions,
   ) => Promise<number | undefined>;
+  sendSectionRichMessage: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: TelegramReplyTargetOptions,
+  ) => Promise<number>;
 }
 
 export interface TelegramRenderedMessageDeliveryRuntime<
@@ -891,6 +914,11 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
         },
       );
     },
+    sendSectionRichMessage: (chatId, message, options) =>
+      sendTelegramNativeRichMessage(chatId, message, {
+        recordOwnership: deps.recordOwnership,
+        sendRichMessage: deps.sendRichMessage,
+      }, options),
   };
 }
 

package/lib/routing.ts

@@ -19,6 +19,7 @@ import * as Queue from "./queue.ts";
 import * as Replies from "./replies.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import type { TelegramSectionRegistry } from "./sections.ts";
+import type { TelegramInputRichMessage } from "./telegram-api.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as ThreadNaming from "./thread-naming.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
@@ -625,6 +626,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  requestNextDispatchAnnouncement?: () => void;
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: (ctx: TContext) => void,
   ) => void;
@@ -706,6 +708,11 @@ export interface TelegramInboundRouteRuntimeDeps<
     details?: Record<string, unknown>,
   ) => void;
   sectionRegistry?: TelegramSectionRegistry;
+  sendSectionRichMessage?: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: { target?: { chatId: number; threadId?: number } },
+  ) => Promise<number | undefined>;
 }
 
 const TELEGRAM_OWNED_CALLBACK_PREFIXES = [
@@ -1013,6 +1020,7 @@ export function createTelegramInboundRouteRuntime<
     sectionRegistry: deps.sectionRegistry,
     editInteractiveMessage: deps.editInteractiveMessage,
     sendInteractiveMessage: deps.sendInteractiveMessage,
+    sendSectionRichMessage: deps.sendSectionRichMessage,
     deleteMessage: deps.deleteMessage,
     enqueueSectionPrompt: async (
       prompt: string,
@@ -2171,6 +2179,7 @@ export function createTelegramInboundRouteRuntime<
     updateStatus: deps.updateStatus,
     isContextActive: deps.isContextActive,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deps.requestDeferredDispatchNextQueuedTelegramTurn,
     startTypingLoop: deps.startTypingLoop,

package/lib/sections.ts

@@ -8,6 +8,7 @@ import {
   assertTelegramCallbackData,
   type TelegramInlineKeyboardMarkup,
 } from "./keyboard.ts";
+import type { TelegramInputRichMessage } from "./telegram-api.ts";
 
 const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
 
@@ -66,6 +67,7 @@ export interface TelegramSectionContext {
   answerCallback(text?: string): Promise<void>;
   edit(view: TelegramSectionView): Promise<void>;
   open(view: TelegramSectionView): Promise<void>;
+  openRich(message: TelegramInputRichMessage): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
   /** Delete the message that triggered this callback (dialog cleanup) */
@@ -81,6 +83,7 @@ export interface TelegramSectionCallbackContext {
   answerCallback(text?: string): Promise<void>;
   edit(view: TelegramSectionView): Promise<void>;
   open(view: TelegramSectionView): Promise<void>;
+  openRich(message: TelegramInputRichMessage): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
   /** Delete the message that triggered this callback (dialog cleanup) */
@@ -160,6 +163,11 @@ export interface TelegramSectionRuntimeDeps {
     replyMarkup: TelegramInlineKeyboardMarkup,
     options?: { target?: TelegramSectionTarget },
   ) => Promise<number | undefined>;
+  sendRichMessage: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: { target?: TelegramSectionTarget },
+  ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
 }
@@ -202,6 +210,12 @@ function buildTelegramSectionContext(
           deps.target ? { target: deps.target } : undefined,
         )
         .then(() => {}),
+    openRich: (message) =>
+      deps.sendRichMessage(
+        chatId,
+        message,
+        deps.target ? { target: deps.target } : undefined,
+      ).then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
     callbackData: (action, payload) =>
       buildTelegramSectionCallbackData(token, action, payload),
@@ -251,6 +265,12 @@ function buildTelegramSectionCallbackContext(
           deps.target ? { target: deps.target } : undefined,
         )
         .then(() => {}),
+    openRich: (message) =>
+      deps.sendRichMessage(
+        chatId,
+        message,
+        deps.target ? { target: deps.target } : undefined,
+      ).then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
     callbackData: (action, payload) =>
       buildTelegramSectionCallbackData(token, action, payload),
@@ -526,6 +546,11 @@ export interface TelegramSectionCallbackHandlerDeps {
     replyMarkup: TelegramInlineKeyboardMarkup,
     options?: { target?: TelegramSectionTarget },
   ) => Promise<number | undefined>;
+  sendRichMessage: (
+    chatId: number,
+    message: TelegramInputRichMessage,
+    options?: { target?: TelegramSectionTarget },
+  ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
 }

package/lib/telegram-api.ts

@@ -292,6 +292,7 @@ export type TelegramRichText =
   | { type: "bold" | "code"; text: TelegramRichText };
 
 export type TelegramInputRichBlock =
+  | { type: "heading"; text: TelegramRichText; size?: 1 | 2 | 3 }
   | { type: "pre"; text: TelegramRichText; language?: string }
   | {
       type: "details";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.45.8",
+  "version": "0.45.10",
   "private": false,
   "publishConfig": {
     "access": "public"