@llblab/pi-telegram 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.19.1: Settings Layer Hotfix
+
+- `[Settings]` Split the overloaded Rich Draft setting into two independent controls: `Draft previews` for live `sendRichMessageDraft` streaming and `Assistant rendering` for final-answer delivery mode. Impact: operators can hide/show in-progress drafts without changing how final Markdown is rendered.
+- `[Rendering]` Added persisted `assistantRendering: "rich" | "html"`, defaulting to Native Rich Markdown and allowing legacy Markdown-to-HTML final assistant replies when selected. Impact: renderer compatibility is explicit instead of being conflated with preview visibility.
+- `[Preview]` Kept `richDraftPreviews` as the stored draft-preview flag for compatibility, but renamed the Settings UI to `Draft previews`. Impact: existing configs keep working while the product vocabulary matches the Bot API layer.
+- `[Validation]` Updated menu/settings/reply regressions for the two-axis configuration model.
+
 ## 0.19.0: Telegram Companion Hub
 
 - `[Context]` Defined Rich Markdown as the model-answer membrane: complete assistant/guest model replies use native Rich Message delivery, while tool rows, reasoning/thinking blocks, menus, status, queue controls, settings, diagnostics, and other harness-owned surfaces stay on explicit Telegram HTML/plain rendering.

package/README.md

@@ -72,41 +72,41 @@ The first Telegram user to message the bot becomes the allowed owner. Other user
 
 ## Product Model
 
-| Lens                    | What `pi-telegram` owns                                                                            |
-| ----------------------- | -------------------------------------------------------------------------------------------------- |
-| Operator companion      | A phone-width control surface for a live Pi session                                                |
-| Runtime adapter         | Telegram turns mapped into Pi lifecycle, queueing, previews, final replies, and artifacts          |
-| Telegram UI harness     | Menus, settings, callbacks, Rich Markdown, drafts, active status, buttons, voice, and files        |
-| Multi-instance organism | One leader plus explicit visible followers routed through Telegram private-chat threads            |
-| Extension platform      | Commands, sections, status rows, update handlers, inbound/outbound handlers, and voice providers   |
-| Safety boundary         | No hidden Pi processes, no fake terminal, no PTY tricks, no arbitrary TUI slash-command forwarding |
+| Lens | What `pi-telegram` owns |
+| --- | --- |
+| Operator companion | A phone-width control surface for a live Pi session |
+| Runtime adapter | Telegram turns mapped into Pi lifecycle, queueing, previews, final replies, and artifacts |
+| Telegram UI harness | Menus, settings, callbacks, Rich Markdown, drafts, active status, buttons, voice, and files |
+| Multi-instance organism | One leader plus explicit visible followers routed through Telegram private-chat threads |
+| Extension platform | Commands, sections, status rows, update handlers, inbound/outbound handlers, and voice providers |
+| Safety boundary | No hidden Pi processes, no fake terminal, no PTY tricks, no arbitrary TUI slash-command forwarding |
 
 ## Feature Showcase
 
 `pi-telegram` is intentionally broad: it is a Telegram-shaped runtime surface, not only a message relay. This catalogue keeps the practical feature surface visible while detailed contracts stay in `/docs`.
 
-| Surface              | What you can do                                                                                                                                          | Why it matters                                                                                                             |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Prompt intake        | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi.                                                               | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel.                         |
-| Queue control        | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item.                               | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. |
-| Operator menu        | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics.                                        | The bot is an operator panel, not a command cheat sheet.                                                                   |
-| Prompt templates     | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`.                                                                                  | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands.                             |
-| Model and thinking   | Switch model or reasoning level from Telegram through safe continuation flows.                                                                           | Mobile control can adjust execution strategy without tearing down the current session.                                     |
-| Compaction           | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics.                                             | Context maintenance is visible and safe from the phone.                                                                    |
-| Streaming previews   | Show native active status and, when enabled, Rich Markdown drafts while the agent is still working.                                                      | The operator can see progress without making draft rendering the baseline.                                                 |
-| Final Rich Markdown  | Deliver complete assistant/guest model replies through Telegram Rich Message APIs with safe splitting.                                                   | Meaningful model answers stay readable on narrow mobile screens without forcing generic HTML conversion.                   |
-| Bridge UI rendering  | Render tool rows, reasoning/technical steps, menus, queue controls, status, settings, diagnostics, and sections through explicit Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers.                 |
-| Inbound files        | Download inbound files to the Pi agent temp directory with size limits.                                                                                  | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files.                                            |
-| Outbound artifacts   | Return generated files through `telegram_attach` during active turns or explicit direct delivery.                                                        | Agents send real artifacts as files, not pasted blobs.                                                                     |
-| Voice input          | Route audio through configured command-template handlers, programmatic handlers, or STT providers.                                                       | Voice notes become usable prompt context.                                                                                  |
-| Voice output         | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers.                                                                         | Replies can become Telegram voice messages when the workflow calls for it.                                                 |
-| Buttons              | Turn top-level `telegram_button` comments into inline buttons.                                                                                           | Assistant-authored choices become native Telegram interactions.                                                            |
-| Callback routing     | Route known callbacks to the owner extension and unknown callbacks back into Pi.                                                                         | Companion extensions can build UI without polling Telegram themselves.                                                     |
-| Threaded Mode        | Run one leader plus visible follower Pi instances through named private-chat threads.                                                                    | One bot can host a local multi-instance Pi organism without hidden process spawning.                                       |
-| Reroute and restore  | Preserve unknown threads and offer explicit target choices.                                                                                              | Telegram client state can be repaired without silently deleting or hijacking prompts.                                      |
-| Extension sections   | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions.                                           | `pi-telegram` becomes a platform surface for other Pi extensions.                                                          |
-| Runtime diagnostics  | Use `/telegram-status` and recent runtime events for connection, role, queue, transport, and failure evidence.                                           | Debugging lives in the operator surface instead of hidden logs only.                                                       |
-| Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior.                                                                        | Remote access remains explicit, bounded, and understandable.                                                               |
+| Surface | What you can do | Why it matters |
+| --- | --- | --- |
+| Prompt intake | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi. | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel. |
+| Queue control | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item. | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. |
+| Operator menu | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics. | The bot is an operator panel, not a command cheat sheet. |
+| Prompt templates | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`. | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands. |
+| Model and thinking | Switch model or reasoning level from Telegram through safe continuation flows. | Mobile control can adjust execution strategy without tearing down the current session. |
+| Compaction | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics. | Context maintenance is visible and safe from the phone. |
+| Draft previews | Show native active status by default, or enable Telegram Rich Draft previews while the agent is still working. | The operator can hide/show in-progress text independently from final rendering. |
+| Assistant rendering | Choose Native Rich Markdown or legacy Markdown-to-HTML for final assistant replies. | Renderer compatibility is explicit instead of being conflated with draft previews. |
+| Bridge UI rendering | Render tool rows, reasoning/technical steps, menus, queue controls, status, settings, diagnostics, and sections through explicit Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers. |
+| Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. |
+| Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. |
+| Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. |
+| Voice output | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers. | Replies can become Telegram voice messages when the workflow calls for it. |
+| Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. |
+| Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
+| Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. |
+| Reroute and restore | Preserve unknown threads and offer explicit target choices. | Telegram client state can be repaired without silently deleting or hijacking prompts. |
+| Extension sections | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions. | `pi-telegram` becomes a platform surface for other Pi extensions. |
+| Runtime diagnostics | Use `/telegram-status` and recent runtime events for connection, role, queue, transport, and failure evidence. | Debugging lives in the operator surface instead of hidden logs only. |
+| Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior. | Remote access remains explicit, bounded, and understandable. |
 
 ## Core Loop
 
@@ -126,14 +126,14 @@ The bridge keeps Telegram responsive without stealing Pi's runtime model. Queuei
 
 Use these in the bot DM.
 
-| Command     | Purpose                                                 |
-| ----------- | ------------------------------------------------------- |
-| `/start`    | Pair when needed and open the main operator menu        |
-| `/compact`  | Confirm and run session compaction when safe            |
-| `/next`     | Dispatch the next queued turn, aborting first if needed |
-| `/continue` | Enqueue a priority continuation prompt                  |
-| `/abort`    | Abort the active run while preserving the queue         |
-| `/stop`     | Abort the active run and clear waiting Telegram turns   |
+| Command | Purpose |
+| --- | --- |
+| `/start` | Pair when needed and open the main operator menu |
+| `/compact` | Confirm and run session compaction when safe |
+| `/next` | Dispatch the next queued turn, aborting first if needed |
+| `/continue` | Enqueue a priority continuation prompt |
+| `/abort` | Abort the active run while preserving the queue |
+| `/stop` | Abort the active run and clear waiting Telegram turns |
 
 Hidden compatibility shortcuts: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings` jump into the same menu system.
 
@@ -141,12 +141,12 @@ Hidden compatibility shortcuts: `/help`, `/status`, `/model`, `/thinking`, `/que
 
 Run these inside Pi.
 
-| Command                | Purpose                                                            |
-| ---------------------- | ------------------------------------------------------------------ |
-| `/telegram-setup`      | Save or update the bot token                                       |
-| `/telegram-connect`    | Start polling and acquire Telegram transport ownership             |
-| `/telegram-disconnect` | Stop polling and release ownership                                 |
-| `/telegram-status`     | Inspect connection, mode, queue, transport, and recent diagnostics |
+| Command | Purpose |
+| --- | --- |
+| `/telegram-setup` | Save or update the bot token |
+| `/telegram-connect` | Start polling and acquire Telegram transport ownership |
+| `/telegram-disconnect` | Stop polling and release ownership |
+| `/telegram-status` | Inspect connection, mode, queue, transport, and recent diagnostics |
 
 ## Main Surfaces
 
@@ -160,7 +160,7 @@ Messages sent while Pi is busy become queued turns. Priority lanes support contr
 
 ### Native Rich Markdown
 
-Rich Markdown is the model-answer membrane. Complete assistant and guest model replies use Telegram's native Rich Message APIs, while tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces use explicit Telegram HTML/plain rendering. This keeps meaningful model-authored answers visually distinct from bridge-owned operational UI. Streaming previews may use rich-message drafts when enabled; final replies persist through `sendRichMessage`.
+Rich Markdown is the default model-answer membrane. Complete assistant and guest model replies use Telegram's native Rich Message APIs, while tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces use explicit Telegram HTML/plain rendering. This keeps meaningful model-authored answers visually distinct from bridge-owned operational UI. Two Settings controls keep the layers separate: `Draft previews` toggles live `sendRichMessageDraft` frames, while `Assistant rendering` chooses final-answer delivery (`rich` Native Rich Markdown or `html` legacy Markdown-to-HTML).
 
 ### Files And Artifacts
 
@@ -184,25 +184,25 @@ Classic private DM mode is the base product mode. When Telegram private-chat Thr
 - Unknown threads are preserved and offered explicit reroute/restore choices.
 - Telegram never launches hidden Pi processes.
 
-| Mode          | Best for                                                 | Runtime shape                                                                 |
-| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| Classic DM    | One live Pi session controlled from one private bot chat | One polling owner, one queue/runtime surface                                  |
-| Threaded Mode | Several visible Pi terminals sharing one bot             | One leader owns transport; followers route through named private-chat threads |
+| Mode | Best for | Runtime shape |
+| --- | --- | --- |
+| Classic DM | One live Pi session controlled from one private bot chat | One polling owner, one queue/runtime surface |
+| Threaded Mode | Several visible Pi terminals sharing one bot | One leader owns transport; followers route through named private-chat threads |
 
 ## Environment Configuration
 
 Most controls live in Pi commands or the Telegram menu. Environment variables remain for bootstrap and transport boundaries:
 
-| Area                      | Variables                                                                                      |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| Bot token bootstrap       | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_KEY`                     |
-| HTTP proxy                | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, plus `NODE_USE_ENV_PROXY=1` or Node `--use-env-proxy` |
-| Telegram network family   | `PI_TELEGRAM_NETWORK_FAMILY`=auto                                                              | ipv4 | ipv6 | ipv4-fallback` |
-| Agent data root           | `PI_CODING_AGENT_DIR`                                                                          |
-| Inbound file limit        | `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES`, `TELEGRAM_MAX_FILE_SIZE_BYTES`                           |
-| Outbound attachment limit | `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES`, `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`              |
+| Area | Variables |
+| --- | --- |
+| Bot token bootstrap | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_KEY` |
+| HTTP proxy | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, plus `NODE_USE_ENV_PROXY=1` or Node `--use-env-proxy` |
+| Telegram network family | `PI_TELEGRAM_NETWORK_FAMILY=auto`, `ipv4`, `ipv6`, or `ipv4-fallback` |
+| Agent data root | `PI_CODING_AGENT_DIR` |
+| Inbound file limit | `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES`, `TELEGRAM_MAX_FILE_SIZE_BYTES` |
+| Outbound attachment limit | `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES`, `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` |
 
-Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, native Rich Markdown replies, and native Telegram active status for long-running turns.
+Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistantRendering: "rich"` for final replies, `richDraftPreviews: false` for no live draft text by default, and native Telegram active status for long-running turns.
 
 ## Extension Platform
 

package/docs/architecture.md

@@ -223,15 +223,15 @@ During active Telegram-owned turns, assistant message start/update hooks re-arm
 
 ### Rendering And Delivery
 
-Rich Markdown is the model-answer membrane. Complete assistant replies send final Markdown directly as `InputRichMessage.markdown` through `sendRichMessage`, and guest replies use native Rich Markdown through `InputRichMessageContent` in `answerGuestQuery` results. Tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces stay on explicit Telegram HTML/plain rendering. Streaming previews may use `sendRichMessageDraft` when enabled and when draft delivery succeeds. The bridge still strips top-level assistant action comments before delivery and may split output only for Telegram transport limits.
+Rich Markdown is the default model-answer membrane. Complete assistant replies send final Markdown directly as `InputRichMessage.markdown` through `sendRichMessage` when `assistantRendering` is `rich`, and through the legacy Markdown-to-HTML renderer when `assistantRendering` is `html`; guest replies use native Rich Markdown through `InputRichMessageContent` in `answerGuestQuery` results. Tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces stay on explicit Telegram HTML/plain rendering. Streaming previews may use `sendRichMessageDraft` only when Draft previews are enabled and draft delivery succeeds. The bridge still strips top-level assistant action comments before delivery and may split output only for Telegram transport limits.
 
 Assistant delivery guarantees:
 
-- Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML.
+- Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistantRendering: "html"` for compatibility.
 - Before native Rich Markdown delivery, the bridge normalizes known Bot-API-fragile source forms without changing visible meaning, including space-after-marker blockquotes and dollar-prefixed ticker atoms that Telegram may otherwise treat as unterminated math.
 - Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text.
 - Long native Markdown replies are split only at Telegram Rich Message transport limits; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.
-- When enabled, streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.
+- When Draft previews are enabled, streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.
 - Preview flushes are serialized so older edits cannot race newer drafts; final delivery waits for active draft flushes and does not perform a post-final draft-clear call.
 
 UI/compat rendering guarantees:

package/index.ts

@@ -443,6 +443,7 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     sendMessage,
     sendRichMessage,
+    getAssistantRenderingMode: configControls.getAssistantRenderingMode,
     editMessage: editTelegramMessageText,
   });
   const { replyTransport, editInteractiveMessage, sendInteractiveMessage } =

package/lib/config.ts

@@ -47,6 +47,8 @@ export interface ResolvedTelegramTimeConfig {
   timezone: string;
 }
 
+export type TelegramAssistantRenderingMode = "rich" | "html";
+
 export interface TelegramConfig {
   botToken?: string;
   botUsername?: string;
@@ -58,6 +60,7 @@ export interface TelegramConfig {
   outboundHandlers?: TelegramOutboundHandlerConfig[];
   proactivePush?: boolean;
   richDraftPreviews?: boolean;
+  assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
     replyMode?: "manual" | "mirror" | "always";
     /** Whether to attach the provider's transcriptText as caption on voice messages */
@@ -277,6 +280,26 @@ export function createTelegramRichDraftPreviewsSetter(
   };
 }
 
+export function createTelegramAssistantRenderingModeGetter(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => TelegramAssistantRenderingMode {
+  return () => {
+    const mode = configStore.get().assistantRendering;
+    return mode === "html" ? "html" : "rich";
+  };
+}
+
+export function createTelegramAssistantRenderingModeSetter(
+  configStore: TelegramMutableConfigStore,
+): (mode: TelegramAssistantRenderingMode) => Promise<void> {
+  return async (mode) => {
+    await loadLatestTelegramConfig(configStore);
+    const config = { ...configStore.get(), assistantRendering: mode };
+    configStore.set(config);
+    await configStore.persist(config);
+  };
+}
+
 export function createTelegramVoiceReplyModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => "manual" | "mirror" | "always" {
@@ -416,6 +439,10 @@ export function createTelegramConfigControls(
       createTelegramRichDraftPreviewsChecker(configStore),
     setRichDraftPreviewsEnabled:
       createTelegramRichDraftPreviewsSetter(configStore),
+    getAssistantRenderingMode:
+      createTelegramAssistantRenderingModeGetter(configStore),
+    setAssistantRenderingMode:
+      createTelegramAssistantRenderingModeSetter(configStore),
     getVoiceReplyMode: createTelegramVoiceReplyModeGetter(configStore),
     isVoiceReplyModeConfigured:
       createTelegramVoiceReplyModeConfiguredChecker(configStore),

package/lib/menu-settings.ts

@@ -8,7 +8,10 @@ import {
   getTelegramExtensionSettingsRows,
   type TelegramSectionRegistry,
 } from "./sections.ts";
-import type { TelegramTimeMode } from "./config.ts";
+import type {
+  TelegramAssistantRenderingMode,
+  TelegramTimeMode,
+} from "./config.ts";
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
 import type { MenuModel } from "./model.ts";
@@ -19,6 +22,7 @@ export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 export interface TelegramSettingsStateDeps {
   isProactivePushEnabled: () => boolean;
   areRichDraftPreviewsEnabled: () => boolean;
+  getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getTimeInjectionMode: () => TelegramTimeMode;
   getVoiceReplyMode: () => TelegramVoiceReplyMode;
   isVoiceReplyModeConfigured: () => boolean;
@@ -27,6 +31,9 @@ export interface TelegramSettingsStateDeps {
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
   setProactivePushEnabled: (enabled: boolean) => Promise<void>;
   setRichDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
+  setAssistantRenderingMode: (
+    mode: TelegramAssistantRenderingMode,
+  ) => Promise<void>;
   setVoiceReplyMode: (
     mode: TelegramVoiceReplyMode | undefined,
   ) => Promise<void>;
@@ -118,8 +125,9 @@ export interface TelegramSettingsMenuRuntimeDeps<
 
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
-export const RICH_DRAFT_PREVIEWS_SETTINGS_TITLE =
-  "<b>📝 Rich draft previews:</b>";
+export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
+export const ASSISTANT_RENDERING_SETTINGS_TITLE =
+  "<b>🧾 Assistant rendering:</b>";
 export const TIME_INJECTION_MODE_SETTINGS_TITLE =
   "<b>🕒 Time injection mode:</b>";
 export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
@@ -155,14 +163,27 @@ export function buildProactivePushSettingsText(
   ].join("\n");
 }
 
-export function buildRichDraftPreviewsSettingsText(enabled: boolean): string {
+export function buildDraftPreviewsSettingsText(enabled: boolean): string {
+  return [
+    `${DRAFT_PREVIEWS_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
+    "",
+    "Show live answer drafts while the model is answering.",
+    "",
+    "<code>-</code> <code>off</code> (default): show native active status, then send one final answer.",
+    "<code>-</code> <code>on</code>: stream safe Telegram Rich Draft frames before the final answer.",
+  ].join("\n");
+}
+
+export function buildAssistantRenderingSettingsText(
+  mode: TelegramAssistantRenderingMode,
+): string {
   return [
-    `${RICH_DRAFT_PREVIEWS_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
+    `${ASSISTANT_RENDERING_SETTINGS_TITLE} <code>${mode}</code>`,
     "",
-    "Show progressive Rich Markdown draft previews while the model is answering.",
+    "Choose how final assistant Markdown answers are delivered.",
     "",
-    "<code>-</code> <code>off</code> (default): show native active status, then send the final Rich Markdown answer.",
-    "<code>-</code> <code>on</code>: also stream safe Rich Markdown draft previews before the final answer.",
+    "<code>-</code> <code>rich</code> (default): use Telegram Native Rich Markdown.",
+    "<code>-</code> <code>html</code>: use the legacy Markdown-to-HTML renderer.",
   ].join("\n");
 }
 
@@ -200,12 +221,35 @@ export function buildTimeInjectionModeSettingsText(
 
 export function buildTelegramSettingsMenuReplyMarkup(
   proactivePushEnabled: boolean,
-  richDraftPreviewsEnabled: boolean,
-  voiceReplyMode: TelegramVoiceReplyMode,
-  timeInjectionMode: TelegramTimeMode,
-  sectionRegistry?: TelegramSectionRegistry,
+  draftPreviewsEnabled: boolean,
+  assistantRenderingModeOrVoiceReplyMode: TelegramAssistantRenderingMode | TelegramVoiceReplyMode,
+  voiceReplyModeOrTimeInjectionMode: TelegramVoiceReplyMode | TelegramTimeMode,
+  timeInjectionModeOrSectionRegistry?: TelegramTimeMode | TelegramSectionRegistry,
+  sectionRegistryOrVoiceReplyModeConfigured?: TelegramSectionRegistry | boolean,
   voiceReplyModeConfigured = true,
 ): TelegramSettingsMenuReplyMarkup {
+  const hasRenderingMode =
+    assistantRenderingModeOrVoiceReplyMode === "rich" ||
+    assistantRenderingModeOrVoiceReplyMode === "html";
+  const assistantRenderingMode: TelegramAssistantRenderingMode = hasRenderingMode
+    ? assistantRenderingModeOrVoiceReplyMode
+    : "rich";
+  const voiceReplyMode = hasRenderingMode
+    ? (voiceReplyModeOrTimeInjectionMode as TelegramVoiceReplyMode)
+    : (assistantRenderingModeOrVoiceReplyMode as TelegramVoiceReplyMode);
+  const timeInjectionMode = hasRenderingMode
+    ? (timeInjectionModeOrSectionRegistry as TelegramTimeMode)
+    : (voiceReplyModeOrTimeInjectionMode as TelegramTimeMode);
+  const sectionRegistry = hasRenderingMode
+    ? (sectionRegistryOrVoiceReplyModeConfigured as
+        | TelegramSectionRegistry
+        | undefined)
+    : (timeInjectionModeOrSectionRegistry as TelegramSectionRegistry | undefined);
+  const effectiveVoiceReplyModeConfigured = hasRenderingMode
+    ? voiceReplyModeConfigured
+    : typeof sectionRegistryOrVoiceReplyModeConfigured === "boolean"
+      ? sectionRegistryOrVoiceReplyModeConfigured
+      : true;
   const rows: Array<Array<{ text: string; callback_data: string }>> = [
     [{ text: "⬆️ Main menu", callback_data: "menu:back" }],
   ];
@@ -221,7 +265,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
       {
         text: `👄 Voice reply: ${getTelegramSettingsStateValueLabel(
           getVoiceReplyModeLabel(
-            getVoiceReplyModeSetting(voiceReplyMode, voiceReplyModeConfigured),
+            getVoiceReplyModeSetting(voiceReplyMode, effectiveVoiceReplyModeConfigured),
           ),
         )}`,
         callback_data: "settings:open:voice-reply",
@@ -235,8 +279,14 @@ export function buildTelegramSettingsMenuReplyMarkup(
     ],
     [
       {
-        text: `📝 Rich drafts: ${richDraftPreviewsEnabled ? "on" : "off"}`,
-        callback_data: "settings:open:rich-drafts",
+        text: `📝 Draft previews: ${draftPreviewsEnabled ? "on" : "off"}`,
+        callback_data: "settings:open:draft-previews",
+      },
+    ],
+    [
+      {
+        text: `🧾 Rendering: ${assistantRenderingMode}`,
+        callback_data: "settings:open:assistant-rendering",
       },
     ],
     [
@@ -262,6 +312,7 @@ export async function openTelegramSettingsMenu<
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.areRichDraftPreviewsEnabled(),
+      deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
       deps.getTimeInjectionMode(),
       sectionRegistry,
@@ -294,7 +345,7 @@ export function buildProactivePushSettingsReplyMarkup(
   };
 }
 
-export function buildRichDraftPreviewsSettingsReplyMarkup(
+export function buildDraftPreviewsSettingsReplyMarkup(
   enabled: boolean,
 ): TelegramSettingsMenuReplyMarkup {
   return {
@@ -303,17 +354,34 @@ export function buildRichDraftPreviewsSettingsReplyMarkup(
       [
         {
           text: enabled ? "🟢 On" : "⚫️ On",
-          callback_data: "settings:set:rich-drafts:on",
+          callback_data: "settings:set:draft-previews:on",
         },
         {
           text: enabled ? "⚫️ Off" : "🟡 Off",
-          callback_data: "settings:set:rich-drafts:off",
+          callback_data: "settings:set:draft-previews:off"
         },
       ],
     ],
   };
 }
 
+export function buildAssistantRenderingSettingsReplyMarkup(
+  mode: TelegramAssistantRenderingMode,
+): TelegramSettingsMenuReplyMarkup {
+  const modes: TelegramAssistantRenderingMode[] = ["rich", "html"];
+  return {
+    inline_keyboard: [
+      [{ text: "⬆️ Back", callback_data: "settings:list" }],
+      ...modes.map((value) => [
+        {
+          text: `${value === mode ? "🟢 " : ""}${value}`,
+          callback_data: `settings:set:assistant-rendering:${value}`,
+        },
+      ]),
+    ],
+  };
+}
+
 export function buildTimeInjectionModeSettingsReplyMarkup(
   mode: TelegramTimeMode,
 ): TelegramSettingsMenuReplyMarkup {
@@ -364,6 +432,7 @@ export async function updateTelegramSettingsMenuMessage(
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
       deps.areRichDraftPreviewsEnabled(),
+      deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
       deps.getTimeInjectionMode(),
       sectionRegistry,
@@ -382,13 +451,23 @@ export async function updateProactivePushSettingsMessage(
   );
 }
 
-export async function updateRichDraftPreviewsSettingsMessage(
+export async function updateDraftPreviewsSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const enabled = deps.areRichDraftPreviewsEnabled();
   await deps.updateSettingsMessage(
-    buildRichDraftPreviewsSettingsText(enabled),
-    buildRichDraftPreviewsSettingsReplyMarkup(enabled),
+    buildDraftPreviewsSettingsText(enabled),
+    buildDraftPreviewsSettingsReplyMarkup(enabled),
+  );
+}
+
+export async function updateAssistantRenderingSettingsMessage(
+  deps: TelegramSettingsMenuCallbackDeps,
+): Promise<void> {
+  const mode = deps.getAssistantRenderingMode();
+  await deps.updateSettingsMessage(
+    buildAssistantRenderingSettingsText(mode),
+    buildAssistantRenderingSettingsReplyMarkup(mode),
   );
 }
 
@@ -429,8 +508,13 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "settings:open:rich-drafts") {
-    await updateRichDraftPreviewsSettingsMessage(deps);
+  if (data === "settings:open:draft-previews" || data === "settings:open:rich-drafts") {
+    await updateDraftPreviewsSettingsMessage(deps);
+    await deps.answerCallbackQuery(callbackQueryId);
+    return true;
+  }
+  if (data === "settings:open:assistant-rendering") {
+    await updateAssistantRenderingSettingsMessage(deps);
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
@@ -487,18 +571,29 @@ export async function handleTelegramSettingsMenuCallbackAction(
     }
   }
   if (
+    data === "settings:set:draft-previews:on" ||
+    data === "settings:set:draft-previews:off" ||
     data === "settings:set:rich-drafts:on" ||
     data === "settings:set:rich-drafts:off"
   ) {
     const enabled = data.endsWith(":on");
     await deps.setRichDraftPreviewsEnabled(enabled);
-    await updateRichDraftPreviewsSettingsMessage(deps);
+    await updateDraftPreviewsSettingsMessage(deps);
     await deps.answerCallbackQuery(
       callbackQueryId,
-      `Rich draft previews ${enabled ? "enabled" : "disabled"}`,
+      `Draft previews ${enabled ? "enabled" : "disabled"}`,
     );
     return true;
   }
+  if (data.startsWith("settings:set:assistant-rendering:")) {
+    const mode = data.slice("settings:set:assistant-rendering:".length);
+    if (mode === "rich" || mode === "html") {
+      await deps.setAssistantRenderingMode(mode);
+      await updateAssistantRenderingSettingsMessage(deps);
+      await deps.answerCallbackQuery(callbackQueryId, `Rendering: ${mode}`);
+      return true;
+    }
+  }
   if (
     data === "settings:set:proactive:on" ||
     data === "settings:set:proactive:off"
@@ -530,6 +625,7 @@ export function createTelegramSettingsMenuRuntime<
           getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
           isProactivePushEnabled: deps.isProactivePushEnabled,
           areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+          getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
@@ -549,6 +645,7 @@ export function createTelegramSettingsMenuRuntime<
         {
           isProactivePushEnabled: deps.isProactivePushEnabled,
           areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+          getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
@@ -588,6 +685,8 @@ export function createTelegramSettingsMenuRuntime<
           return true;
         }
         if (
+          query.data === "settings:set:draft-previews:on" ||
+          query.data === "settings:set:draft-previews:off" ||
           query.data === "settings:set:rich-drafts:on" ||
           query.data === "settings:set:rich-drafts:off"
         ) {
@@ -595,10 +694,18 @@ export function createTelegramSettingsMenuRuntime<
           await deps.setRichDraftPreviewsEnabled(enabled);
           await deps.answerCallbackQuery(
             query.id,
-            `Rich draft previews ${enabled ? "enabled" : "disabled"}`,
+            `Draft previews ${enabled ? "enabled" : "disabled"}`,
           );
           return true;
         }
+        if (query.data.startsWith("settings:set:assistant-rendering:")) {
+          const mode = query.data.slice("settings:set:assistant-rendering:".length);
+          if (mode === "rich" || mode === "html") {
+            await deps.setAssistantRenderingMode(mode);
+            await deps.answerCallbackQuery(query.id, `Rendering: ${mode}`);
+            return true;
+          }
+        }
         const hasTimeInjectionPrefix = query.data.startsWith(
           "settings:set:time-injection:",
         );
@@ -630,11 +737,13 @@ export function createTelegramSettingsMenuRuntime<
       return handleTelegramSettingsMenuCallbackAction(query.id, query.data, {
         isProactivePushEnabled: deps.isProactivePushEnabled,
         areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+        getAssistantRenderingMode: deps.getAssistantRenderingMode,
         getVoiceReplyMode: deps.getVoiceReplyMode,
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
         setProactivePushEnabled: deps.setProactivePushEnabled,
         setRichDraftPreviewsEnabled: deps.setRichDraftPreviewsEnabled,
+        setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setVoiceReplyMode: deps.setVoiceReplyMode,
         setTimeInjectionMode: deps.setTimeInjectionMode,
         updateSettingsMessage: (text, replyMarkup) =>

package/lib/replies.ts

@@ -678,6 +678,8 @@ export async function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
 // 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 type TelegramAssistantRenderingMode = "rich" | "html";
+
 export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
   renderTelegramMessage: (
     text: string,
@@ -685,6 +687,7 @@ export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
   ) => TelegramRenderedChunk[];
   replyTransport: TelegramReplyTransport<TReplyMarkup>;
   recordOwnership?: TelegramReplyOwnershipRecorder["record"];
+  getAssistantRenderingMode?: () => TelegramAssistantRenderingMode;
   sendRichMessage: (
     body: TelegramSendRichMessageBody,
   ) => Promise<TelegramSentMessage>;
@@ -732,6 +735,7 @@ export interface TelegramRenderedMessageDeliveryRuntimeDeps<
     text: string,
     options?: { mode?: TelegramRenderMode },
   ) => TelegramRenderedChunk[];
+  getAssistantRenderingMode?: () => TelegramAssistantRenderingMode;
   sendRichMessage: (
     body: TelegramSendRichMessageBody,
   ) => Promise<TelegramSentMessage>;
@@ -752,6 +756,7 @@ export function createTelegramRenderedMessageDeliveryRuntime<TReplyMarkup>(
         deps.renderTelegramMessage ?? renderTelegramMessage,
       replyTransport,
       recordOwnership: deps.recordOwnership,
+      getAssistantRenderingMode: deps.getAssistantRenderingMode,
       sendRichMessage: deps.sendRichMessage,
     }),
   };
@@ -777,13 +782,19 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
       );
     },
     sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
-      if (typeof options?.target?.threadId === "number" && replyToMessageId && replyToMessageId > 0) {
+      const renderingMode = deps.getAssistantRenderingMode?.() ?? "rich";
+      if (
+        renderingMode === "html" ||
+        (typeof options?.target?.threadId === "number" &&
+          replyToMessageId !== undefined &&
+          replyToMessageId > 0)
+      ) {
         return deps.replyTransport.sendRenderedChunks(
           chatId,
           deps.renderTelegramMessage(markdown, { mode: "markdown" }),
           {
-            replyMarkup: options.replyMarkup,
-            target: options.target,
+            replyMarkup: options?.replyMarkup,
+            target: options?.target,
             replyToMessageId,
           },
         );

package/package.json

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