@llblab/pi-telegram 0.16.5 → 0.17.0

package/lib/replies.ts

@@ -1,11 +1,14 @@
 /**
  * Telegram reply delivery helpers
- * Zones: telegram outbound, rendering transport
- * Owns rendered-message delivery, reply transport wiring, and plain or markdown final replies
+ * Zones: telegram outbound, native rich markdown, UI/compat rendering transport
+ * Owns native assistant replies, rendered UI delivery, reply transport wiring, and plain text replies
  */
 
+import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
 import type {
+  TelegramInputRichMessage,
   TelegramReplyParameters,
+  TelegramSendRichMessageBody,
   TelegramSentMessage,
 } from "./telegram-api.ts";
 import {
@@ -20,6 +23,9 @@ export {
   type TelegramRenderMode,
 };
 
+export const TELEGRAM_RICH_MESSAGE_MAX_CHARS = 32768;
+export const TELEGRAM_RICH_MESSAGE_MAX_BLOCKS = 500;
+
 // --- Reply Dedup ---
 
 /** Non-persistent reply deduplication for a single agent turn.
@@ -50,25 +56,29 @@ export function createReplyDedupRuntime(): ReplyDedupRuntime {
 
 // --- Transport-level dedup ---
 
-let lastRepliedToMessageId: number | undefined;
+const lastRepliedToMessageIdByChat = new Map<number, number>();
 
 export function resetTransportReplyDedup(): void {
-  lastRepliedToMessageId = undefined;
+  lastRepliedToMessageIdByChat.clear();
 }
 
 export function buildTelegramReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): TelegramReplyParameters | undefined {
   if (messageId === undefined) return undefined;
-  if (messageId === lastRepliedToMessageId) return undefined;
-  lastRepliedToMessageId = messageId;
+  if (lastRepliedToMessageIdByChat.get(chatId) === messageId) {
+    return undefined;
+  }
+  lastRepliedToMessageIdByChat.set(chatId, messageId);
   return { message_id: messageId, allow_sending_without_reply: true };
 }
 
 export function buildTelegramMultipartReplyParameters(
+  chatId: number,
   messageId: number | undefined,
 ): string | undefined {
-  const parameters = buildTelegramReplyParameters(messageId);
+  const parameters = buildTelegramReplyParameters(chatId, messageId);
   return parameters ? JSON.stringify(parameters) : undefined;
 }
 
@@ -133,7 +143,8 @@ export interface TelegramReplyDeliveryDeps<TReplyMarkup> {
   editMessage: (body: {
     chat_id: number;
     message_id: number;
-    text: string;
+    text?: string;
+    rich_message?: TelegramInputRichMessage;
     parse_mode?: "HTML";
     reply_markup?: TReplyMarkup;
   }) => Promise<unknown>;
@@ -178,11 +189,12 @@ export async function sendTelegramRenderedChunks<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup; replyToMessageId?: number },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   let lastMessageId: number | undefined;
   for (const [index, chunk] of chunks.entries()) {
     const replyParameters =
       index === 0
-        ? buildTelegramReplyParameters(options?.replyToMessageId)
+        ? buildTelegramReplyParameters(chatId, options?.replyToMessageId)
         : undefined;
     const sent = await deps.sendMessage({
       chat_id: chatId,
@@ -204,6 +216,7 @@ export async function editTelegramRenderedMessage<TReplyMarkup>(
   deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
   options?: { replyMarkup?: TReplyMarkup },
 ): Promise<number | undefined> {
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
   if (chunks.length === 0) return messageId;
   const [firstChunk, ...remainingChunks] = chunks;
   await deps.editMessage({
@@ -244,24 +257,180 @@ export async function sendTelegramPlainReply(
   return deps.sendRenderedChunks(chunks);
 }
 
-export async function sendTelegramMarkdownReply<TReplyMarkup = unknown>(
+export function splitTelegramNativeMarkdown(markdown: string): string[] {
+  if (
+    markdown.length <= TELEGRAM_RICH_MESSAGE_MAX_CHARS &&
+    countTelegramNativeMarkdownBlocks(markdown) <= TELEGRAM_RICH_MESSAGE_MAX_BLOCKS
+  ) {
+    return [markdown];
+  }
+  const chunks: string[] = [];
+  let current = "";
+  let currentBlockCount = 0;
+  for (const rawBlock of splitTelegramNativeMarkdownBlocks(markdown)) {
+    for (const block of splitTelegramNativeMarkdownCountedBlocks(rawBlock)) {
+      const blockCount = countTelegramNativeMarkdownBlocks(block);
+      const candidate = current ? `${current}\n\n${block}` : block;
+      const exceedsChars = candidate.length > TELEGRAM_RICH_MESSAGE_MAX_CHARS;
+      const exceedsBlocks = currentBlockCount + blockCount > TELEGRAM_RICH_MESSAGE_MAX_BLOCKS;
+      if (!exceedsChars && !exceedsBlocks) {
+        current = candidate;
+        currentBlockCount += blockCount;
+        continue;
+      }
+      if (current) chunks.push(current.trimEnd());
+      if (
+        block.length <= TELEGRAM_RICH_MESSAGE_MAX_CHARS &&
+        blockCount <= TELEGRAM_RICH_MESSAGE_MAX_BLOCKS
+      ) {
+        current = block;
+        currentBlockCount = blockCount;
+        continue;
+      }
+      chunks.push(...splitTelegramNativeMarkdownLongBlock(block));
+      current = "";
+      currentBlockCount = 0;
+    }
+  }
+  if (current) chunks.push(current.trimEnd());
+  return chunks;
+}
+
+function splitTelegramNativeMarkdownBlocks(markdown: string): string[] {
+  const blocks: string[] = [];
+  const current: string[] = [];
+  let fence: { marker: "`" | "~"; length: number } | undefined;
+  const flush = (): void => {
+    if (current.length === 0) return;
+    blocks.push(current.join("\n"));
+    current.length = 0;
+  };
+  for (const line of markdown.split("\n")) {
+    const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (!fence && line.trim().length === 0) {
+      flush();
+      continue;
+    }
+    current.push(line);
+    if (!fence && fenceMatch) {
+      const markerText = fenceMatch[1] ?? "```";
+      fence = { marker: markerText[0] as "`" | "~", length: markerText.length };
+      continue;
+    }
+    if (
+      fence &&
+      new RegExp(`^ {0,3}${fence.marker}{${fence.length},}\\s*$`).test(line)
+    ) {
+      fence = undefined;
+    }
+  }
+  flush();
+  return blocks;
+}
+
+function splitTelegramNativeMarkdownCountedBlocks(block: string): string[] {
+  if (countTelegramNativeMarkdownBlocks(block) <= TELEGRAM_RICH_MESSAGE_MAX_BLOCKS) {
+    return [block];
+  }
+  const chunks: string[] = [];
+  let current: string[] = [];
+  let fence: { marker: "`" | "~"; length: number } | undefined;
+  for (const line of block.split("\n")) {
+    const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (!fence && current.length >= TELEGRAM_RICH_MESSAGE_MAX_BLOCKS) {
+      chunks.push(current.join("\n"));
+      current = [];
+    }
+    current.push(line);
+    if (!fence && fenceMatch) {
+      const markerText = fenceMatch[1] ?? "```";
+      fence = { marker: markerText[0] as "`" | "~", length: markerText.length };
+      continue;
+    }
+    if (
+      fence &&
+      new RegExp(`^ {0,3}${fence.marker}{${fence.length},}\\s*$`).test(line)
+    ) {
+      fence = undefined;
+    }
+  }
+  if (current.length > 0) chunks.push(current.join("\n"));
+  return chunks;
+}
+
+function countTelegramNativeMarkdownBlocks(block: string): number {
+  if (/^ {0,3}(`{3,}|~{3,})/.test(block)) return 1;
+  const lines = block.split("\n").filter((line) => line.trim().length > 0);
+  if (lines.some((line) => /^\s*([-*+] |\d+\. |>|\|)/.test(line))) {
+    return Math.max(1, lines.length);
+  }
+  return 1;
+}
+
+function splitTelegramNativeMarkdownLongBlock(block: string): string[] {
+  const chunks: string[] = [];
+  let remaining = block;
+  while (remaining.length > TELEGRAM_RICH_MESSAGE_MAX_CHARS) {
+    const window = remaining.slice(0, TELEGRAM_RICH_MESSAGE_MAX_CHARS + 1);
+    const splitIndex = findTelegramNativeMarkdownSplitIndex(window);
+    chunks.push(remaining.slice(0, splitIndex).trimEnd());
+    remaining = remaining.slice(splitIndex).trimStart();
+  }
+  if (remaining.length > 0) chunks.push(remaining);
+  return chunks;
+}
+
+function findTelegramNativeMarkdownSplitIndex(text: string): number {
+  const hardLimit = TELEGRAM_RICH_MESSAGE_MAX_CHARS;
+  const paragraphIndex = text.lastIndexOf("\n\n", hardLimit);
+  if (paragraphIndex > 0) return paragraphIndex + 2;
+  const lineIndex = text.lastIndexOf("\n", hardLimit);
+  if (lineIndex > 0) return lineIndex + 1;
+  const spaceIndex = text.lastIndexOf(" ", hardLimit);
+  if (spaceIndex > 0) return spaceIndex + 1;
+  return hardLimit;
+}
+
+export async function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
+  chatId: number,
+  replyToMessageId: number | undefined,
   markdown: string,
-  deps: TelegramReplyRuntimeDeps,
+  deps: {
+    sendRichMessage: (
+      body: TelegramSendRichMessageBody,
+    ) => Promise<TelegramSentMessage>;
+  },
   options?: { replyMarkup?: TReplyMarkup },
 ): Promise<number | undefined> {
-  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
-  if (chunks.length === 0) {
-    return sendTelegramPlainReply(markdown, deps);
+  assertTelegramInlineKeyboardCallbackData(options?.replyMarkup);
+  let lastMessageId: number | undefined;
+  const chunks = splitTelegramNativeMarkdown(markdown);
+  for (const [index, chunk] of chunks.entries()) {
+    const replyParameters =
+      index === 0
+        ? buildTelegramReplyParameters(chatId, replyToMessageId)
+        : undefined;
+    const sent = await deps.sendRichMessage({
+      chat_id: chatId,
+      rich_message: { markdown: chunk, skip_entity_detection: true },
+      reply_markup: index === chunks.length - 1 ? options?.replyMarkup : undefined,
+      ...(replyParameters ? { reply_parameters: replyParameters } : {}),
+    });
+    lastMessageId = sent.message_id;
   }
-  return deps.sendRenderedChunks(chunks, options);
+  return lastMessageId;
 }
 
+// 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.
 export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
   renderTelegramMessage: (
     text: string,
     options?: { mode?: TelegramRenderMode },
   ) => TelegramRenderedChunk[];
   replyTransport: TelegramReplyTransport<TReplyMarkup>;
+  sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
 }
 
 export interface TelegramRenderedMessageRuntime<TReplyMarkup> {
@@ -305,6 +474,7 @@ export interface TelegramRenderedMessageDeliveryRuntimeDeps<
     text: string,
     options?: { mode?: TelegramRenderMode },
   ) => TelegramRenderedChunk[];
+  sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
 }
 
 export function createTelegramRenderedMessageDeliveryRuntime<TReplyMarkup>(
@@ -320,6 +490,7 @@ export function createTelegramRenderedMessageDeliveryRuntime<TReplyMarkup>(
       renderTelegramMessage:
         deps.renderTelegramMessage ?? renderTelegramMessage,
       replyTransport,
+      sendRichMessage: deps.sendRichMessage,
     }),
   };
 }
@@ -342,18 +513,11 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
       );
     },
     sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
-      return sendTelegramMarkdownReply(
+      return sendTelegramNativeMarkdownReply(
+        chatId,
+        replyToMessageId,
         markdown,
-        {
-          renderTelegramMessage: deps.renderTelegramMessage,
-          sendRenderedChunks: (chunks, chunkOptions) =>
-            deps.replyTransport.sendRenderedChunks(chatId, chunks, {
-              replyToMessageId,
-              replyMarkup: chunkOptions?.replyMarkup as
-                | TReplyMarkup
-                | undefined,
-            }),
-        },
+        { sendRichMessage: deps.sendRichMessage },
         options,
       );
     },
@@ -431,23 +595,21 @@ export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
 }
 
 /**
- * Guest reply sender: renders Markdown → HTML, sends via answerGuestQuery.
- * Keeps guest rendering inside the replies domain so the orchestration layer
- * (index.ts) does not import from rendering.ts directly. */
+ * Guest reply sender: answers guest queries with native Rich Markdown content.
+ * Guest queries use InlineQueryResult input_message_content rather than chat
+ * sendRichMessage, so this stays as a dedicated guest transport adapter.
+ */
 export function createGuestMarkdownReplySender(deps: {
-  renderTelegramMessage: (
-    text: string,
-    options?: { mode?: TelegramRenderMode },
-  ) => TelegramRenderedChunk[];
   answerGuestQuery: (
     guestQueryId: string,
     text?: string,
-    options?: { parseMode?: string },
+    options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
   ) => Promise<void>;
 }) {
   return async (guestQueryId: string, markdown: string) => {
-    const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
-    const html = chunks.length > 0 ? chunks[0].text : markdown;
-    await deps.answerGuestQuery(guestQueryId, html, { parseMode: "HTML" });
+    const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
+    await deps.answerGuestQuery(guestQueryId, undefined, {
+      richMessage: { markdown: richMarkdown, skip_entity_detection: true },
+    });
   };
 }

package/lib/routing.ts

@@ -93,13 +93,13 @@ export interface TelegramInboundRouteRuntimeDeps<
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: Menu.TelegramReplyMarkup,
   ) => Promise<void>;
   sendInteractiveMessage?: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: Menu.TelegramReplyMarkup,
   ) => Promise<number | undefined>;
   deleteMessage?: (chatId: number, messageId: number) => Promise<void>;

package/lib/sections.ts

@@ -4,10 +4,12 @@
  * Owns section registration, global registry binding, token mapping, main-menu/settings row injection, and section callback dispatch
  */
 
-import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import {
+  assertTelegramCallbackData,
+  type TelegramInlineKeyboardMarkup,
+} from "./keyboard.ts";
 
 const SECTION_REGISTRY_KEY = "__piTelegramSectionRegistry__";
-const TELEGRAM_CALLBACK_DATA_MAX_BYTES = 64;
 
 // --- Core Types ---
 
@@ -22,7 +24,12 @@ export type TelegramSectionCallbackResult = "handled" | "pass";
 
 export interface TelegramSectionView {
   text: string;
-  parseMode?: "html" | "plain";
+  /**
+   * Source format for companion section content.
+   * Defaults to "html" for explicit Telegram UI markup; use "markdown"
+   * when a section naturally owns Markdown content, or "plain" for text.
+   */
+  parseMode?: "markdown" | "html" | "plain";
   replyMarkup?: TelegramInlineKeyboardMarkup;
 }
 
@@ -136,13 +143,13 @@ export interface TelegramSectionRuntimeDeps {
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<void>;
   sendInteractiveMessage: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
@@ -301,10 +308,6 @@ const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;
 
-function getUtf8ByteLength(value: string): number {
-  return new TextEncoder().encode(value).byteLength;
-}
-
 function sectionErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -317,13 +320,7 @@ function buildTelegramSectionCallbackData(
   const data = payload
     ? `section:${token}:${action}:${payload}`
     : `section:${token}:${action}`;
-  const byteLength = getUtf8ByteLength(data);
-  if (byteLength > TELEGRAM_CALLBACK_DATA_MAX_BYTES) {
-    throw new Error(
-      `Telegram section callback_data exceeds ${TELEGRAM_CALLBACK_DATA_MAX_BYTES} bytes (${byteLength}). Use a shorter action/payload or store state behind a compact key.`,
-    );
-  }
-  return data;
+  return assertTelegramCallbackData(data, "Telegram section callback_data");
 }
 
 function prependBackRow(
@@ -513,13 +510,13 @@ export interface TelegramSectionCallbackHandlerDeps {
     chatId: number,
     messageId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<void>;
   sendInteractiveMessage: (
     chatId: number,
     text: string,
-    mode: "html" | "plain",
+    mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;

package/lib/telegram-api.ts

@@ -193,11 +193,38 @@ export type TelegramSendMessageBody = Record<string, unknown> & {
   reply_parameters?: TelegramReplyParameters;
 };
 
+export type TelegramInputRichMessage =
+  | {
+      markdown: string;
+      html?: never;
+      is_rtl?: boolean;
+      skip_entity_detection?: boolean;
+    }
+  | {
+      html: string;
+      markdown?: never;
+      is_rtl?: boolean;
+      skip_entity_detection?: boolean;
+    };
+
+export type TelegramSendRichMessageBody = Record<string, unknown> & {
+  chat_id: number;
+  rich_message: TelegramInputRichMessage;
+  reply_markup?: unknown;
+  reply_parameters?: TelegramReplyParameters;
+};
+
+export type TelegramInputRichMessageContent = {
+  rich_message: TelegramInputRichMessage;
+};
+
 export type TelegramEditMessageTextBody = Record<string, unknown> & {
   chat_id: number;
   message_id: number;
-  text: string;
+  text?: string;
+  rich_message?: TelegramInputRichMessage;
   parse_mode?: "HTML";
+  reply_markup?: unknown;
 };
 
 export type TelegramSendMessageDraftBody = Record<string, unknown> & {
@@ -209,6 +236,13 @@ export type TelegramSendMessageDraftBody = Record<string, unknown> & {
   message_thread_id?: number;
 };
 
+export type TelegramSendRichMessageDraftBody = Record<string, unknown> & {
+  chat_id: number;
+  draft_id: number;
+  rich_message: TelegramInputRichMessage;
+  message_thread_id?: number;
+};
+
 interface TelegramApiResponse<T> {
   ok: boolean;
   result?: T;
@@ -234,6 +268,14 @@ export interface TelegramFileDownloadOptions {
   maxFileSizeBytes?: number;
 }
 
+export interface TelegramAnswerCallbackQueryOptions {
+  recordRuntimeEvent?: (
+    kind: "api",
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
 export interface TelegramApiClient {
   call: <TResponse>(
     method: string,
@@ -261,7 +303,7 @@ export interface TelegramApiClient {
   answerGuestQuery?: (
     guestQueryId: string,
     text?: string,
-    options?: { parseMode?: string },
+    options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
   ) => Promise<void>;
 }
 
@@ -314,6 +356,12 @@ export interface TelegramBridgeApiRuntime {
     },
   ) => Promise<boolean>;
   sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
+  sendRichMessage: (
+    body: TelegramSendRichMessageBody,
+  ) => Promise<TelegramSentMessage>;
+  sendRichMessageDraft: (
+    body: TelegramSendRichMessageDraftBody,
+  ) => Promise<boolean>;
   editMessageText: (
     body: TelegramEditMessageTextBody,
   ) => Promise<"edited" | "unchanged">;
@@ -324,7 +372,7 @@ export interface TelegramBridgeApiRuntime {
   answerGuestQuery: (
     guestQueryId: string,
     text?: string,
-    options?: { parseMode?: string },
+    options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
   ) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
   prepareTempDir: () => Promise<number>;
@@ -664,6 +712,7 @@ export async function answerTelegramCallbackQuery(
   botToken: string | undefined,
   callbackQueryId: string,
   text?: string,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): Promise<void> {
   try {
     await callTelegram<boolean>(
@@ -673,8 +722,10 @@ export async function answerTelegramCallbackQuery(
         ? { callback_query_id: callbackQueryId, text }
         : { callback_query_id: callbackQueryId },
     );
-  } catch {
-    // ignore
+  } catch (error) {
+    options.recordRuntimeEvent?.("api", error, {
+      method: "answerCallbackQuery",
+    });
   }
 }
 
@@ -700,12 +751,33 @@ export function createTelegramChatActionSender<TAction extends string>(
   return (chatId) => sendChatAction(chatId, action);
 }
 
+export function createTelegramNativeMarkdownDraftSender(deps: {
+  sendMessageDraft: TelegramBridgeApiRuntime["sendMessageDraft"];
+  sendRichMessageDraft: TelegramBridgeApiRuntime["sendRichMessageDraft"];
+}): TelegramBridgeApiRuntime["sendMessageDraft"] {
+  return (chatId, draftId, text, options) => {
+    if (text === undefined) {
+      return deps.sendMessageDraft(chatId, draftId, text, options);
+    }
+    return deps.sendRichMessageDraft({
+      chat_id: chatId,
+      draft_id: draftId,
+      rich_message: { markdown: text, skip_entity_detection: true },
+      ...(options?.message_thread_id !== undefined
+        ? { message_thread_id: options.message_thread_id }
+        : {}),
+    });
+  };
+}
+
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
-    client: createTelegramApiClient(deps.getBotToken),
+    client: createTelegramApiClient(deps.getBotToken, {
+      recordRuntimeEvent: deps.recordRuntimeEvent,
+    }),
     tempDir: getTelegramApiTempDir(),
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
@@ -824,6 +896,10 @@ export function createTelegramBridgeApiRuntime(
     },
     sendMessage: (body) =>
       callRecorded<TelegramSentMessage>("sendMessage", body),
+    sendRichMessage: (body) =>
+      callRecorded<TelegramSentMessage>("sendRichMessage", body),
+    sendRichMessageDraft: (body) =>
+      callRecorded<boolean>("sendRichMessageDraft", body),
     editMessageText: async (body) => {
       try {
         await deps.client.call("editMessageText", body);
@@ -834,20 +910,26 @@ export function createTelegramBridgeApiRuntime(
         throw error;
       }
     },
-    answerCallbackQuery: (callbackQueryId, text) => {
-      return deps.client.answerCallbackQuery(callbackQueryId, text);
+    answerCallbackQuery: async (callbackQueryId, text) => {
+      try {
+        await deps.client.answerCallbackQuery(callbackQueryId, text);
+      } catch (error) {
+        deps.recordRuntimeEvent("api", error, {
+          method: "answerCallbackQuery",
+        });
+      }
     },
     answerGuestQuery: (
       guestQueryId: string,
       text: string | undefined,
-      options: { parseMode?: string } | undefined,
+      options: { parseMode?: string; richMessage?: TelegramInputRichMessage } | undefined,
     ) => {
       const body: Record<string, unknown> = { guest_query_id: guestQueryId };
-      if (text !== undefined) {
-        const inputContent: Record<string, unknown> = {
-          message_text: text,
-        };
-        if (options?.parseMode) {
+      if (text !== undefined || options?.richMessage) {
+        const inputContent: Record<string, unknown> = options?.richMessage
+          ? { rich_message: options.richMessage }
+          : { message_text: text };
+        if (!options?.richMessage && options?.parseMode) {
           inputContent.parse_mode = options.parseMode;
         }
         body.result = {
@@ -876,6 +958,7 @@ export function createTelegramBridgeApiRuntime(
  */
 export function createTelegramApiClient(
   getBotToken: () => string | undefined,
+  options: TelegramAnswerCallbackQueryOptions = {},
 ): TelegramApiClient {
   return {
     call: async (method, body, options) => {
@@ -909,7 +992,12 @@ export function createTelegramApiClient(
       );
     },
     answerCallbackQuery: async (callbackQueryId, text) => {
-      await answerTelegramCallbackQuery(getBotToken(), callbackQueryId, text);
+      await answerTelegramCallbackQuery(
+        getBotToken(),
+        callbackQueryId,
+        text,
+        options,
+      );
     },
   };
 }

package/lib/updates.ts

@@ -406,7 +406,8 @@ export function buildTelegramUpdateExecutionPlan<
       return {
         kind: "guest",
         guestMessage: action.guestMessage,
-        shouldDeny: action.authorization.kind === "deny",
+        // Guest mode is an extension of an already paired bridge, not a pairing surface.
+        shouldDeny: action.authorization.kind !== "allow",
       };
   }
 }

package/package.json

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