@llblab/pi-telegram 0.16.6 → 0.17.1

package/lib/preview.ts

@@ -1,6 +1,6 @@
 /**
  * Telegram preview streaming helpers
- * Zones: telegram outbound, streaming preview, rendering
+ * Zones: telegram outbound, native rich markdown drafts, fallback preview transport
  * Owns preview transport selection, runtime updates, and preview finalization
  */
 
@@ -11,22 +11,15 @@ import type {
   TelegramSentMessage,
 } from "./telegram-api.ts";
 import {
-  buildTelegramPreviewSnapshot,
-  MAX_MESSAGE_LENGTH,
-  renderMarkdownPreviewText,
-  renderTelegramMessage,
-  type TelegramPreviewRenderStrategy,
-  type TelegramPreviewSnapshot,
-  type TelegramRenderedChunk,
-  type TelegramRenderMode,
-} from "./rendering.ts";
-
-import { buildTelegramReplyParameters } from "./replies.ts";
+  buildTelegramReplyParameters,
+  normalizeTelegramNativeMarkdown,
+} from "./replies.ts";
 import { stripTelegramCommentMarkupForPreview } from "./outbound.ts";
 import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
-const TELEGRAM_PREVIEW_THROTTLE_MS = 750;
+const TELEGRAM_PREVIEW_THROTTLE_MS = 0;
 const TELEGRAM_DRAFT_ID_MAX = 2_147_483_647;
+const TELEGRAM_FALLBACK_PREVIEW_MESSAGE_MAX_CHARS = 4096;
 
 export type TelegramDraftSupport = "unknown" | "supported" | "unsupported";
 
@@ -37,7 +30,6 @@ export interface TelegramPreviewState {
   pendingText: string;
   lastSentText: string;
   lastSentParseMode?: "HTML";
-  lastSentStrategy?: TelegramPreviewRenderStrategy;
 }
 
 export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
@@ -56,7 +48,6 @@ export interface TelegramPreviewRuntimeDeps<
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
   maxMessageLength: number;
-  renderPreviewText: (markdown: string) => string;
   getDraftSupport: () => TelegramDraftSupport;
   setDraftSupport: (support: TelegramDraftSupport) => void;
   allocateDraftId: () => number;
@@ -81,21 +72,6 @@ export interface TelegramPreviewRuntimeDeps<
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<unknown>;
-  renderTelegramMessage: (
-    text: string,
-    options?: { mode?: TelegramRenderMode },
-  ) => TelegramRenderedChunk[];
-  sendRenderedChunks: (
-    chatId: number,
-    chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>;
-  editRenderedMessage: (
-    chatId: number,
-    messageId: number,
-    chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>;
   canSend?: () => boolean;
   recordRuntimeEvent?: (
     category: string,
@@ -162,7 +138,6 @@ export interface TelegramPreviewControllerDeps<
 > {
   getDefaultReplyToMessageId?: () => number | undefined;
   maxMessageLength?: number;
-  renderPreviewText?: (markdown: string) => string;
   initialDraftSupport?: TelegramDraftSupport;
   sendDraft: (
     chatId: number,
@@ -186,22 +161,6 @@ export interface TelegramPreviewControllerDeps<
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<unknown>;
-  renderTelegramMessage?: (
-    text: string,
-    options?: { mode?: TelegramRenderMode },
-  ) => TelegramRenderedChunk[];
-  sendRenderedChunks: (
-    chatId: number,
-    chunks: TelegramRenderedChunk[],
-    replyToMessageId: number | undefined,
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>;
-  editRenderedMessage: (
-    chatId: number,
-    messageId: number,
-    chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>;
   canSend?: () => boolean;
   throttleMs?: number;
   maxDraftId?: number;
@@ -229,12 +188,6 @@ export interface TelegramPreviewController<
   flush: (chatId: number) => Promise<void>;
   scheduleFlush: (chatId: number) => void;
   finalize: (chatId: number, replyToMessageId?: number) => Promise<boolean>;
-  finalizeMarkdown: (
-    chatId: number,
-    markdown: string,
-    replyToMessageId?: number,
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<boolean>;
 }
 
 export interface TelegramPreviewMessageTransportDeps {
@@ -271,55 +224,13 @@ export function createTelegramPreviewMessageTransport(
   };
 }
 
-export interface TelegramPreviewRenderedChunkTransportDeps<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> {
-  sendRenderedChunks: (
-    chatId: number,
-    chunks: TelegramRenderedChunk[],
-    options?: {
-      replyToMessageId?: number;
-      replyMarkup?: TReplyMarkup;
-    },
-  ) => Promise<number | undefined>;
-  editRenderedMessage: (
-    chatId: number,
-    messageId: number,
-    chunks: TelegramRenderedChunk[],
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>;
-}
-
-export function createTelegramPreviewRenderedChunkTransport<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
-  deps: TelegramPreviewRenderedChunkTransportDeps<TReplyMarkup>,
-): Pick<
-  TelegramPreviewControllerDeps<TReplyMarkup>,
-  "sendRenderedChunks" | "editRenderedMessage"
-> {
-  return {
-    sendRenderedChunks: (chatId, chunks, replyToMessageId, options) =>
-      deps.sendRenderedChunks(chatId, chunks, {
-        replyToMessageId,
-        ...(options?.replyMarkup ? { replyMarkup: options.replyMarkup } : {}),
-      }),
-    editRenderedMessage: (chatId, messageId, chunks, options) =>
-      deps.editRenderedMessage(chatId, messageId, chunks, options),
-  };
-}
-
 export type TelegramPreviewControllerRuntimeDeps<
   TReplyMarkup = TelegramPreviewReplyMarkup,
 > = Omit<
   TelegramPreviewControllerDeps<TReplyMarkup>,
-  | "sendMessage"
-  | "editMessageText"
-  | "sendRenderedChunks"
-  | "editRenderedMessage"
+  "sendMessage" | "editMessageText"
 > &
-  TelegramPreviewMessageTransportDeps &
-  TelegramPreviewRenderedChunkTransportDeps<TReplyMarkup>;
+  TelegramPreviewMessageTransportDeps;
 
 export function createTelegramPreviewControllerRuntime<
   TReplyMarkup = TelegramPreviewReplyMarkup,
@@ -329,7 +240,6 @@ export function createTelegramPreviewControllerRuntime<
   return createTelegramPreviewController({
     getDefaultReplyToMessageId: deps.getDefaultReplyToMessageId,
     maxMessageLength: deps.maxMessageLength,
-    renderPreviewText: deps.renderPreviewText,
     initialDraftSupport: deps.initialDraftSupport,
     sendDraft: deps.sendDraft,
     ...createTelegramPreviewMessageTransport({
@@ -337,11 +247,6 @@ export function createTelegramPreviewControllerRuntime<
       editMessageText: deps.editMessageText,
       buildReplyParameters: deps.buildReplyParameters,
     }),
-    renderTelegramMessage: deps.renderTelegramMessage,
-    ...createTelegramPreviewRenderedChunkTransport({
-      sendRenderedChunks: deps.sendRenderedChunks,
-      editRenderedMessage: deps.editRenderedMessage,
-    }),
     throttleMs: deps.throttleMs,
     maxDraftId: deps.maxDraftId,
     setTimer: deps.setTimer,
@@ -357,13 +262,94 @@ export interface TelegramAssistantPreviewRuntimeDeps<
   getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
   isAssistantMessage: (message: TMessage) => boolean;
   getMessageText: (message: TMessage) => string;
+  sendMarkdownReply: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>;
+  editMarkdownMessage?: (
+    chatId: number,
+    messageId: number,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<unknown>;
 }
 
 export type TelegramAssistantPreviewRuntime<
   TMessage,
   TReplyMarkup = TelegramPreviewReplyMarkup,
 > = TelegramPreviewController<TReplyMarkup> &
-  TelegramAssistantMessagePreviewHooks<TMessage>;
+  TelegramAssistantMessagePreviewHooks<TMessage> & {
+    finalizeMarkdown: (
+      chatId: number,
+      markdown: string,
+      replyToMessageId?: number,
+      options?: { replyMarkup?: TReplyMarkup },
+    ) => Promise<boolean>;
+  };
+
+export function createTelegramNativeMarkdownMessageEditor<TReplyMarkup>(deps: {
+  editMessageText: (body: TelegramEditMessageTextBody) => Promise<unknown>;
+}): (
+  chatId: number,
+  messageId: number,
+  markdown: string,
+  options?: { replyMarkup?: TReplyMarkup },
+) => Promise<unknown> {
+  return (chatId, messageId, markdown, options) =>
+    deps.editMessageText({
+      chat_id: chatId,
+      message_id: messageId,
+      rich_message: {
+        markdown: normalizeTelegramNativeMarkdown(markdown),
+        skip_entity_detection: true,
+      },
+      ...(options?.replyMarkup ? { reply_markup: options.replyMarkup } : {}),
+    });
+}
+
+export function createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>(deps: {
+  getState: () => TelegramPreviewRuntimeState | undefined;
+  clear: (chatId: number) => Promise<void>;
+  discard?: () => void;
+  sendMarkdownReply: (
+    chatId: number,
+    replyToMessageId: number | undefined,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>;
+  editMarkdownMessage?: (
+    chatId: number,
+    messageId: number,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<unknown>;
+}): (
+  chatId: number,
+  markdown: string,
+  replyToMessageId?: number,
+  options?: { replyMarkup?: TReplyMarkup },
+) => Promise<boolean> {
+  return async (chatId, markdown, replyToMessageId, options) => {
+    const state = deps.getState();
+    if (state?.mode === "message" && state.messageId !== undefined) {
+      try {
+        await deps.editMarkdownMessage?.(chatId, state.messageId, markdown, options);
+        await deps.clear(chatId);
+        return true;
+      } catch {
+        // Fall through to a fresh native Rich Message so final text is not lost.
+      }
+    }
+    if (state?.flushPromise) {
+      await state.flushPromise.catch(() => {});
+    }
+    await deps.sendMarkdownReply(chatId, replyToMessageId, markdown, options);
+    deps.discard?.();
+    return true;
+  };
+}
 
 export function createTelegramAssistantPreviewRuntime<
   TMessage,
@@ -372,8 +358,16 @@ export function createTelegramAssistantPreviewRuntime<
   deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>,
 ): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup> {
   const controller = createTelegramPreviewControllerRuntime(deps);
+  const finalizeMarkdownPreview = createTelegramNativeMarkdownPreviewFinalizer({
+    getState: controller.getState,
+    clear: controller.clear,
+    discard: () => controller.setState(undefined),
+    sendMarkdownReply: deps.sendMarkdownReply,
+    editMarkdownMessage: deps.editMarkdownMessage,
+  });
   return {
     ...controller,
+    finalizeMarkdown: finalizeMarkdownPreview,
     ...createTelegramAssistantMessagePreviewHooks({
       getActiveTurn: deps.getActiveTurn,
       isAssistantMessage: deps.isAssistantMessage,
@@ -381,7 +375,7 @@ export function createTelegramAssistantPreviewRuntime<
       setState: controller.setState,
       createPreviewState: controller.createState,
       finalizePreview: controller.finalize,
-      finalizeMarkdownPreview: controller.finalizeMarkdown,
+      finalizeMarkdownPreview,
       getMessageText: deps.getMessageText,
       schedulePreviewFlush: controller.scheduleFlush,
     }),
@@ -401,9 +395,8 @@ export function createTelegramPreviewController<
       setTimeout(callback, ms));
   const throttleMs = deps.throttleMs ?? TELEGRAM_PREVIEW_THROTTLE_MS;
   const maxDraftId = deps.maxDraftId ?? TELEGRAM_DRAFT_ID_MAX;
-  const maxMessageLength = deps.maxMessageLength ?? MAX_MESSAGE_LENGTH;
-  const renderPreview = deps.renderPreviewText ?? renderMarkdownPreviewText;
-  const renderMessage = deps.renderTelegramMessage ?? renderTelegramMessage;
+  const maxMessageLength =
+    deps.maxMessageLength ?? TELEGRAM_FALLBACK_PREVIEW_MESSAGE_MAX_CHARS;
   let draftSupport = deps.initialDraftSupport ?? "unknown";
   let nextDraftId = 0;
   const getRuntimeDeps = (
@@ -419,7 +412,6 @@ export function createTelegramPreviewController<
       nextState.flushTimer = undefined;
     },
     maxMessageLength,
-    renderPreviewText: renderPreview,
     getDraftSupport: () => draftSupport,
     setDraftSupport: (support) => {
       draftSupport = support;
@@ -437,15 +429,6 @@ export function createTelegramPreviewController<
         replyToMessageId ?? deps.getDefaultReplyToMessageId?.(),
       ),
     editMessageText: deps.editMessageText,
-    renderTelegramMessage: renderMessage,
-    sendRenderedChunks: (chatId, chunks, options) =>
-      deps.sendRenderedChunks(
-        chatId,
-        chunks,
-        replyToMessageId ?? deps.getDefaultReplyToMessageId?.(),
-        options,
-      ),
-    editRenderedMessage: deps.editRenderedMessage,
     canSend: deps.canSend,
     recordRuntimeEvent: deps.recordRuntimeEvent,
   });
@@ -465,6 +448,10 @@ export function createTelegramPreviewController<
     flush: (chatId) => flushTelegramPreview(chatId, getRuntimeDeps()),
     scheduleFlush: (chatId) => {
       if (!state || state.flushTimer) return;
+      if (throttleMs <= 0) {
+        void flushTelegramPreview(chatId, getRuntimeDeps());
+        return;
+      }
       state.flushTimer = setTimer(() => {
         void flushTelegramPreview(chatId, getRuntimeDeps());
       }, throttleMs);
@@ -472,13 +459,6 @@ export function createTelegramPreviewController<
     },
     finalize: (chatId, replyToMessageId) =>
       finalizeTelegramPreview(chatId, getRuntimeDeps(replyToMessageId)),
-    finalizeMarkdown: (chatId, markdown, replyToMessageId, options) =>
-      finalizeTelegramMarkdownPreview(
-        chatId,
-        markdown,
-        getRuntimeDeps(replyToMessageId),
-        options,
-      ),
   };
 }
 
@@ -554,10 +534,7 @@ export function buildTelegramPreviewFinalText(
 ): string | undefined {
   const finalText = state.pendingText.trim();
   if (finalText) return finalText;
-  if (
-    state.lastSentStrategy === "rich-stable-blocks" ||
-    state.lastSentParseMode === "HTML"
-  ) {
+  if (state.lastSentParseMode === "HTML") {
     return undefined;
   }
   return state.lastSentText.trim() || undefined;
@@ -580,14 +557,16 @@ export function allocateTelegramDraftId(
   return currentDraftId >= maxDraftId ? 1 : currentDraftId + 1;
 }
 
+interface TelegramNativeMarkdownPreviewSnapshot {
+  text: string;
+  sourceText: string;
+}
+
 export function shouldUseTelegramDraftPreview(options: {
   draftSupport: TelegramDraftSupport;
-  snapshot?: TelegramPreviewSnapshot;
+  snapshot?: TelegramNativeMarkdownPreviewSnapshot;
 }): boolean {
-  return (
-    options.draftSupport !== "unsupported" &&
-    (options.snapshot === undefined || options.snapshot.strategy === "plain")
-  );
+  return options.draftSupport !== "unsupported";
 }
 
 export async function clearTelegramPreview<
@@ -595,12 +574,43 @@ export async function clearTelegramPreview<
 >(
   chatId: number,
   deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
+  options: { awaitFlush?: boolean } = {},
 ): Promise<void> {
-  void chatId;
   const state = deps.getState();
   if (!state) return;
   deps.clearScheduledFlush(state);
+  if (state.flushPromise && options.awaitFlush !== false) {
+    state.flushRequested = false;
+    await state.flushPromise.catch(() => {});
+    if (deps.getState() !== state) return;
+  }
   deps.setState(undefined);
+  if (state.mode === "draft" && state.draftId !== undefined) {
+    try {
+      await deps.sendDraft(chatId, state.draftId, undefined);
+    } catch (error) {
+      deps.recordRuntimeEvent?.("preview", error, {
+        phase: "clear-draft",
+        chatId,
+        draftId: state.draftId,
+      });
+    }
+  }
+}
+
+function buildTelegramNativeMarkdownPreviewSnapshot(
+  state: TelegramPreviewState,
+  maxMessageLength: number,
+): TelegramNativeMarkdownPreviewSnapshot | undefined {
+  const sourceText = state.pendingText.trim();
+  if (!sourceText || sourceText === state.lastSentText) return undefined;
+  return {
+    text:
+      sourceText.length > maxMessageLength
+        ? sourceText.slice(0, maxMessageLength)
+        : sourceText,
+    sourceText,
+  };
 }
 
 async function performTelegramPreviewFlush<
@@ -611,15 +621,13 @@ async function performTelegramPreviewFlush<
   deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
 ): Promise<void> {
   if (deps.canSend && !deps.canSend()) {
-    await clearTelegramPreview(chatId, deps);
+    await clearTelegramPreview(chatId, deps, { awaitFlush: false });
     return;
   }
-  const snapshot = buildTelegramPreviewSnapshot({
+  const snapshot = buildTelegramNativeMarkdownPreviewSnapshot(
     state,
-    maxMessageLength: deps.maxMessageLength,
-    renderPreviewText: deps.renderPreviewText,
-    renderTelegramMessage: deps.renderTelegramMessage,
-  });
+    deps.maxMessageLength,
+  );
   if (!snapshot) return;
   if (
     shouldUseTelegramDraftPreview({
@@ -630,35 +638,32 @@ async function performTelegramPreviewFlush<
     const draftId = state.draftId ?? deps.allocateDraftId();
     state.draftId = draftId;
     try {
-      await deps.sendDraft(chatId, draftId, snapshot.text);
+      await deps.sendDraft(
+        chatId,
+        draftId,
+        normalizeTelegramNativeMarkdown(snapshot.sourceText),
+      );
       deps.setDraftSupport("supported");
       state.mode = "draft";
       state.lastSentText = snapshot.text;
-      state.lastSentParseMode = snapshot.parseMode;
-      state.lastSentStrategy = snapshot.strategy;
+      state.lastSentParseMode = undefined;
       return;
     } catch {
       deps.setDraftSupport("unsupported");
     }
   }
   if (state.messageId === undefined) {
-    const sent = await deps.sendMessage(chatId, snapshot.text, {
-      parseMode: snapshot.parseMode,
-    });
+    const sent = await deps.sendMessage(chatId, snapshot.text, undefined);
     state.messageId = sent.message_id;
     state.mode = "message";
     state.lastSentText = snapshot.text;
-    state.lastSentParseMode = snapshot.parseMode;
-    state.lastSentStrategy = snapshot.strategy;
+    state.lastSentParseMode = undefined;
     return;
   }
-  await deps.editMessageText(chatId, state.messageId, snapshot.text, {
-    parseMode: snapshot.parseMode,
-  });
+  await deps.editMessageText(chatId, state.messageId, snapshot.text, undefined);
   state.mode = "message";
   state.lastSentText = snapshot.text;
-  state.lastSentParseMode = snapshot.parseMode;
-  state.lastSentStrategy = snapshot.strategy;
+  state.lastSentParseMode = undefined;
 }
 
 export async function flushTelegramPreview<
@@ -719,49 +724,9 @@ export async function finalizeTelegramPreview<
   }
   if (state.mode === "draft") {
     await deps.sendMessage(chatId, finalText);
-    await clearTelegramPreview(chatId, deps);
+    deps.setState(undefined);
     return true;
   }
   deps.setState(undefined);
   return state.messageId !== undefined;
 }
-
-export async function finalizeTelegramMarkdownPreview<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
-  chatId: number,
-  markdown: string,
-  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
-  options?: { replyMarkup?: TReplyMarkup },
-): Promise<boolean> {
-  const state = deps.getState();
-  if (!state) return false;
-  if (deps.canSend && !deps.canSend()) {
-    await clearTelegramPreview(chatId, deps);
-    return false;
-  }
-  await flushTelegramPreview(chatId, deps);
-  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
-  if (chunks.length === 0) {
-    await clearTelegramPreview(chatId, deps);
-    return false;
-  }
-  try {
-    if (state.mode === "draft") {
-      await deps.sendRenderedChunks(chatId, chunks, options);
-      await clearTelegramPreview(chatId, deps);
-      return true;
-    }
-    if (state.messageId === undefined) return false;
-    await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
-    deps.setState(undefined);
-    return true;
-  } catch (error) {
-    deps.recordRuntimeEvent?.("preview", error, {
-      phase: "finalize-markdown",
-      chatId,
-      messageId: state.messageId,
-    });
-    return false;
-  }
-}

package/lib/prompts.ts

@@ -28,13 +28,13 @@ Telegram-originated turn context:
 - Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 
 Telegram-visible output:
-- Telegram is often phone-width; keep tables, dense list items, and compact text blocks at or below 37 visible cells when possible.
-- Count display width, not raw characters: emoji and some glyphs are wide, so prefer shorter labels when unsure.
-- Wide monospace blocks can become unreadable on mobile; use them only when structure or literal code requires them.
+- Telegram is mobile-first: keep answers easy to scan, use headings/lists when useful, and avoid unnecessarily huge blocks of text.
+- For formulas, use math delimiters like \`$E = mc^2$\` for inline formulas and \`$$\\nE = mc^2\\n$$\` for block formulas; do not wrap formulas in backticks unless they should render as literal code.
+- Use inline code for short copyable literals (commands, paths, IDs, symbols); avoid wide monospace blocks unless structure or literal code requires them.
 - For requested/generated files, call \`telegram_attach(local_path)\`; during Telegram turns it attaches files to the active reply, and during explicit local/TUI Telegram-delivery requests it sends files directly to the paired/default chat or an explicit \`chat_id\`. If a local/TUI user explicitly asks to send a text message to Telegram, use \`telegram_message\` with Markdown text; embed the same top-level \`telegram_button\` comments when inline prompt buttons are needed, because Telegram buttons must belong to a message. Direct local/TUI Telegram delivery requires this π instance to own \`/telegram-connect\`; if ownership is elsewhere, connect/take over first instead of bypassing the lock.
 
 Native outbound actions:
-- Use normal Markdown for visible text. Use top-level column-zero hidden Markdown comments outside code, quotes, and lists only for native actions; the bridge strips them after agent_end and turns them into Telegram-native artifacts/reply_markup. Do not render button JSON, do not invent standalone button tools, and do not call/register transport/TTS/text-to-OGG tools for ordinary Telegram-turn voice/buttons.
+- Use normal Rich Markdown for visible text. Use top-level column-zero hidden Markdown comments outside code, quotes, and lists only for native actions; the bridge strips them after agent_end and turns them into Telegram-native artifacts/reply_markup. Do not render button JSON, do not invent standalone button tools, and do not call/register transport/TTS/text-to-OGG tools for ordinary Telegram-turn voice/buttons.
 - \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line text, or \`<!-- telegram_voice: Short summary -->\` for one-line text with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
 - \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts. Do not put button comments inline after visible text, inside code fences, block quotes, lists, or indented examples; those are literal Markdown, not buttons.
 - If only hidden action comments would remain, add visible parent text like "Choose one:" so Telegram has a message to attach buttons to.