polygram 0.17.12 → 0.18.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.17.12",
+  "version": "0.18.1",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/error/net.js

@@ -156,6 +156,13 @@ function redactBotToken(s) {
     .replace(/(bot_token=)[^&\s]+/gi, '$1<redacted>');
 }
 
+// redactBotToken() does not cover URL basic auth. Operator-configured API
+// roots may contain userinfo, which must be stripped before logging.
+function stripUrlCredentials(url) {
+  if (!url) return url;
+  return String(url).replace(/^(https?:\/\/)[^/@\s]+@/i, '$1');
+}
+
 module.exports = {
   PRE_CONNECT_ERROR_CODES,
   RECOVERABLE_ERROR_CODES,
@@ -167,4 +174,5 @@ module.exports = {
   extractName,
   extractMessage,
   redactBotToken,
+  stripUrlCredentials,
 };

package/lib/handlers/config-callback.js

@@ -17,6 +17,7 @@
 'use strict';
 
 const { toTelegramHtml } = require('../telegram/format');
+const { resolveRichTextEnabled } = require('../telegram/rich');
 const { getTopicConfig, getConfigWriteScope } = require('../session-key');
 
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
@@ -37,10 +38,14 @@ function createHandleConfigCallback({
 
   return async function handleConfigCallback(ctx) {
     const data = ctx.callbackQuery?.data || '';
-    const m = String(data).match(/^cfg:(model|effort):(\S+)$/);
+    const m = String(data).match(/^cfg:(model|effort|richtext):(\S+)$/);
     if (!m) return;
     const setting = m[1];
     const value = m[2];
+    // richText is stored as a boolean so inherited configuration can
+    // distinguish an explicit false value from an unset value.
+    const isRichText = setting === 'richtext';
+    const parsedValue = isRichText ? value === 'on' : value;
 
     const chatId = String(ctx.callbackQuery.message?.chat?.id || '');
     const chatConfig = config.chats[chatId];
@@ -53,10 +58,17 @@ function createHandleConfigCallback({
       return;
     }
 
-    const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
-    if (!validValues.includes(value)) {
-      await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
-      return;
+    if (isRichText) {
+      if (value !== 'on' && value !== 'off') {
+        await ctx.answerCallbackQuery({ text: 'Invalid richtext value' }).catch(() => {});
+        return;
+      }
+    } else {
+      const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
+      if (!validValues.includes(value)) {
+        await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
+        return;
+      }
     }
 
     // Write to the scope the card belongs to: a topic card targets THAT topic
@@ -65,14 +77,21 @@ function createHandleConfigCallback({
     // topic's effective value, not the chat root (2026-06-12 bug).
     const callbackThreadIdEarly = ctx.callbackQuery.message?.message_thread_id?.toString() || null;
     const { scope: writeScope, threadId: writeThreadId } =
-      getConfigWriteScope(chatConfig, callbackThreadIdEarly);
-    const oldValue = writeScope[setting] != null ? writeScope[setting] : chatConfig[setting];
-    if (oldValue === value) {
+      getConfigWriteScope(chatConfig, callbackThreadIdEarly, {
+        allowNonIsolatedTopic: setting === 'richtext',
+      });
+    // The persisted camel-case key differs from the lowercase callback
+    // label used alongside model and effort.
+    const configField = isRichText ? 'richText' : setting;
+    const oldValue = isRichText
+      ? resolveRichTextEnabled(config, chatId, callbackThreadIdEarly)
+      : (writeScope[configField] != null ? writeScope[configField] : chatConfig[configField]);
+    if (oldValue === parsedValue) {
       await ctx.answerCallbackQuery({ text: `Already ${value}` }).catch(() => {});
       return;
     }
 
-    writeScope[setting] = value;
+    writeScope[configField] = parsedValue;
     // Persist to config.json so the change survives a restart — without this,
     // every /model tap was lost on the next deploy (2026-06-12). Best-effort:
     // never let a disk hiccup swallow the in-memory change + live application.
@@ -81,15 +100,19 @@ function createHandleConfigCallback({
     const cmdUserId = ctx.callbackQuery.from?.id || null;
     const cmdUser = ctx.callbackQuery.from?.first_name || ctx.callbackQuery.from?.username || null;
     dbWrite(() => db.logConfigChange({
-      chat_id: chatId, thread_id: writeThreadId, field: setting,
-      old_value: oldValue, new_value: value,
+      chat_id: chatId, thread_id: writeThreadId, field: configField,
+      old_value: oldValue, new_value: parsedValue,
       user: cmdUser, user_id: cmdUserId, source: 'inline-button',
-    }), `log ${setting} change`);
+    }), `log ${configField} change`);
 
     // Graceful application to the topic's session. SDK pm applies live
     // via setModel / applyFlagSettings; chatConfig is already updated
     // on disk above so a missing live session still picks up the new
-    // value on its next cold spawn.
+    // value on its next cold spawn. richText is NOT a spawn-time flag —
+    // delivery reads it live at send time (lib/telegram/rich.js), so
+    // there is nothing to apply to a running session; only the system-
+    // prompt authoring hint lags to the next spawn, which the rich-text
+    // acknowledgement explains separately from model/effort changes.
     const callbackThreadId = callbackThreadIdEarly;
     const callbackSessionKey = getSessionKey(chatId, callbackThreadId, chatConfig);
     let applied = false;
@@ -111,8 +134,9 @@ function createHandleConfigCallback({
     // mirrors the /model command card (polygram.js). getTopicConfig returns {}
     // for the chat-level card.
     const _cbTopicCfg = getTopicConfig(chatConfig, callbackThreadId);
-    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId, _cbTopicCfg);
-    const newKeyboard = buildConfigKeyboard(chatConfig, showRow, _cbTopicCfg);
+    const effectiveRichText = resolveRichTextEnabled(config, chatId, callbackThreadId);
+    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId, _cbTopicCfg, effectiveRichText);
+    const newKeyboard = buildConfigKeyboard(chatConfig, showRow, _cbTopicCfg, effectiveRichText);
     try {
       const { text: html, parseMode } = toTelegramHtml(newInfo);
       await ctx.editMessageText(html, {
@@ -123,9 +147,11 @@ function createHandleConfigCallback({
       logger.error?.(`[${botName}] config-card edit failed: ${err.message}`);
     }
 
-    const ackText = anyActive
-      ? `${setting} → ${value} — switching when finished`
-      : `${setting} → ${value}`;
+    // Rich delivery changes immediately, but its authoring hint changes
+    // on the next session spawn; surface both timings in the acknowledgement.
+    const ackText = isRichText
+      ? (parsedValue ? 'Rich text → on (delivery live; agent authors for it next session)' : 'Rich text → off')
+      : (anyActive ? `${setting} → ${value} — switching when finished` : `${setting} → ${value}`);
     await ctx.answerCallbackQuery({ text: ackText }).catch(() => {});
   };
 }

package/lib/handlers/config-ui.js

@@ -19,6 +19,16 @@
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
 const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
+// Runtime callers pass the value resolved from the full config hierarchy.
+// Direct callers may omit it and retain the local topic/chat behavior.
+function resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText) {
+  if (typeof effectiveRichText === 'boolean') return effectiveRichText;
+  const pick = (v) => (typeof v === 'boolean' ? v : undefined);
+  return pick(topicConfig?.richText)
+    ?? pick(chatConfig?.richText)
+    ?? false;
+}
+
 // Mirrors what `claude --model <alias>` resolves to. Display only —
 // polygram passes the alias (opus / sonnet / haiku) and lets claude
 // resolve. Bump on Claude release.
@@ -35,7 +45,7 @@ const MODEL_VERSIONS_DESC = {
  * null for the chat-level card) wins over chatConfig so the ✓ matches what a
  * topic actually runs — mirrors the spawn-path precedence (topic > chat).
  */
-function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
+function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null, effectiveRichText) {
   const model = (topicConfig && topicConfig.model) || chatConfig.model;
   const effort = (topicConfig && topicConfig.effort) || chatConfig.effort;
   const rows = [];
@@ -51,6 +61,15 @@ function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
       callback_data: `cfg:effort:${e}`,
     })));
   }
+  // Rich text is a boolean toggle on the full config card. Model-only
+  // and effort-only cards keep their focused layouts.
+  if (show === 'all') {
+    const on = resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText);
+    rows.push([{
+      text: on ? '✓ Rich text: on' : 'Rich text: off',
+      callback_data: `cfg:richtext:${on ? 'off' : 'on'}`,
+    }]);
+  }
   return { inline_keyboard: rows };
 }
 
@@ -64,7 +83,7 @@ function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
  * @param {(db, sessionKey) => string|null} deps.getClaudeSessionId
  */
 function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
-  return function formatConfigInfoText(chatConfig, show, sessionKey, topicConfig = null) {
+  return function formatConfigInfoText(chatConfig, show, sessionKey, topicConfig = null, effectiveRichText) {
     const alive = pm.has(sessionKey) && !pm.get(sessionKey).closed;
     // Per-topic overrides win over chat-level for the displayed values,
     // mirroring the spawn path (polygram.js: topicConfig.agent ||
@@ -93,9 +112,17 @@ function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
     const effortLine = (runEffort && runEffort !== effort)
       ? `Effort: ${runEffort} (running) → ${effort} (pending — applies on your next message)`
       : `Effort: ${effort}`;
+    // Delivery reads richText live, while the authoring hint is fixed at
+    // session spawn. Explain that lag separately from model/effort,
+    // which have concrete running and configured values to compare.
+    const richText = resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText);
+    const richTextLine = richText
+      ? 'Rich text: on (headings/tables/checklists on qualifying replies; agent authors for it once this session next (re)spawns)'
+      : 'Rich text: off';
     const head =
       `${modelLine}\n` +
       `${effortLine}\n` +
+      `${richTextLine}\n` +
       `Agent: ${agent}\n` +
       `Process: ${alive ? 'warm' : 'cold'}\n` +
       `Session: ${sess}`;

package/lib/sdk/build-options.js

@@ -25,7 +25,8 @@
 
 const agentLoader = require('../agents/loader');
 const { getTopicConfig } = require('../session-key');
-const { appendDisplayHint } = require('../telegram/display-hint');
+const { appendDisplayHint, buildPolygramDisplayHint } = require('../telegram/display-hint');
+const { resolveRichTextEnabled } = require('../telegram/rich');
 
 // Env: SHADOW semantics — must enumerate every var the spawned
 // worker is allowed to see. Anything else is dropped.
@@ -162,7 +163,14 @@ function createBuildSdkOptions({
 
     // Append polygram's display constraints to the systemPrompt —
     // infrastructure-layer hint, not agent business logic.
-    composed.systemPrompt = appendDisplayHint(composed.systemPrompt);
+    //
+    // Resolve the authoring hint through the same topic→chat→bot→default
+    // precedence as delivery. The hint is fixed at spawn, while delivery
+    // reads the value live for each send.
+    composed.systemPrompt = appendDisplayHint(
+      composed.systemPrompt,
+      buildPolygramDisplayHint(resolveRichTextEnabled(config, chatId, threadId)),
+    );
     return composed;
   };
 }

package/lib/session-key.js

@@ -107,26 +107,17 @@ function getTopicConfig(chatConfig, threadId) {
 }
 
 /**
- * Resolve the config object a per-chat/topic setting (model/effort) should be
- * WRITTEN to, given where the command/card was used. When in a topic, return
- * (creating if needed) that topic's override entry — so a /model in the Music
- * topic targets Music alone and matches what the per-topic card displays,
- * instead of leaking to the chat root and every other topic that inherits it
- * (the 2026-06-12 "/model in Music does nothing" bug). At the chat level
- * (no thread), the writable scope is the chat config itself.
+ * Resolve the config object a per-chat/topic setting should be written to.
+ * Process-level settings use topic scope only for isolated sessions. A live
+ * delivery setting can opt into topic scope even when sessions are shared.
  *
  * @returns {{ scope: object, threadId: (string|null) }}
  */
-function getConfigWriteScope(chatConfig, threadId) {
+function getConfigWriteScope(chatConfig, threadId, { allowNonIsolatedTopic = false } = {}) {
   const tid = (threadId == null || threadId === '') ? null : String(threadId);
-  // Mirror getSessionKey's isolation rule: a per-topic override only takes
-  // effect when isolateTopics === true (otherwise every topic shares the
-  // chatId-keyed session and topics[tid].model is silently ignored — the
-  // 2026-06-12 review found the topic-scope fix re-broke /model on the DEFAULT
-  // non-isolated chats and made the card lie). So write the topic scope ONLY
-  // when isolated; otherwise write the chat root (the session that actually
-  // runs), and report threadId:null so the audit row reflects chat-level reach.
-  if (tid && chatConfig?.isolateTopics === true) {
+  // Process-scoped settings follow session isolation. Live delivery settings
+  // may explicitly keep topic scope because they are resolved per message.
+  if (tid && (chatConfig?.isolateTopics === true || allowNonIsolatedTopic)) {
     chatConfig.topics = chatConfig.topics || {};
     // A topic can be stored in the legacy / hand-edited form where the entry
     // is the bare name string (topics["329"] = "Advertising") rather than the

package/lib/telegram/api.js

@@ -100,9 +100,14 @@ const METHODS_WITHOUT_MSG = new Set([
 // Derive the row's `text` column. sendSticker has no text/caption, so we
 // synthesize `[sticker:<name>]` (or file_id as fallback) — without this the
 // transcript shows an empty outbound that's impossible to interpret later.
+// Rich edits carry source Markdown in meta.richSourceText because the API
+// payload has `rich_message` instead of `text`. Edits are excluded from
+// transcript persistence by METHODS_WITHOUT_MSG, but deriving meaningful
+// text here keeps the helper correct for any tracked rich-message caller.
 function deriveOutboundText(method, params, meta) {
   if (params.text) return params.text;
   if (params.caption) return params.caption;
+  if (params.rich_message) return meta.richSourceText || '[rich message]';
   if (method === 'sendSticker') {
     const label = meta.stickerName || params.sticker || 'unknown';
     return `[sticker:${label}]`;
@@ -153,11 +158,17 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   // as a user-facing "Hit a snag" — confusing because the bot didn't
   // really fail. Throw a typed error before the API call so callers
   // can detect + skip silently if appropriate.
-  if (method === 'sendMessage' || method === 'editMessageText') {
+  // A rich edit carries `rich_message` instead of `text`, so validate
+  // its block collection rather than applying the plain-text guard.
+  if (method === 'sendMessage' || (method === 'editMessageText' && params.rich_message == null)) {
     const t = params.text;
     if (typeof t !== 'string' || t.length === 0) {
       throw new Error(`telegram ${method}: text is empty`);
     }
+  } else if (method === 'editMessageText' && params.rich_message != null) {
+    if (!Array.isArray(params.rich_message.blocks) || params.rich_message.blocks.length === 0) {
+      throw new Error(`telegram ${method}: rich_message.blocks is empty`);
+    }
   }
   if (method === 'sendPhoto' || method === 'sendVideo'
       || method === 'sendAudio' || method === 'sendDocument' || method === 'sendAnimation') {

package/lib/telegram/display-hint.js

@@ -27,11 +27,10 @@
 
 const TELEGRAM_TABLE_WIDTH_BUDGET = 40;
 
-const POLYGRAM_DISPLAY_HINT = [
-  '## Telegram display rules',
-  '',
-  'Your replies render in the Telegram client. Phone is the design target.',
-  '',
+// Plain-mode guidance avoids structures that Telegram's HTML rendering
+// cannot display well. The prompt and delivery capability must agree so
+// the agent is not encouraged to author unsupported structures.
+const TABLES_AND_HEADERS_SECTION_PLAIN = [
   '### Tables — HARD RULE',
   '',
   `Before emitting any markdown table, count the longest row in characters (including pipes \`|\`, padding, and separator dashes). If that row is longer than ${TELEGRAM_TABLE_WIDTH_BUDGET}, you MUST NOT emit a table. Use row blocks instead.`,
@@ -57,19 +56,54 @@ const POLYGRAM_DISPLAY_HINT = [
   '- Headers `#`, `##`, `###` render as plain text — use **bold** for emphasis.',
   '- Horizontal rules render as a thin divider line.',
   '- Long replies stream in chunks; prefer concise structure over walls of text.',
+].join('\n');
+
+// Rich-mode guidance is limited to the constructs detected by
+// needsRichRendering so ordinary prose stays on the compact plain path.
+const TABLES_AND_HEADERS_SECTION_RICH = [
+  '### Rich formatting is available in this chat',
+  '',
+  'This chat has rich-text rendering enabled. Real Telegram markdown tables, headings (`#`/`##`/etc.), task lists, and collapsible `<details>` blocks now render as an actual structured message, not flattened text — use them when they make an answer clearer or easier to scan (a comparison, a set of steps, a key/value summary, a checklist tracking progress). No character-width budget applies to tables here; write a normal markdown table.',
+  '',
+  '**Task lists for progress:** `- [ ] pending step` / `- [x] done step` renders as a real checkbox list — the natural way to show multi-step progress as it happens.',
   '',
-  '### NEVER emit shell-context canned strings — HARD RULE',
+  '**Collapsible detail:** wrap verbose logs/diffs/output you want available but not front-and-center in `<details><summary>Label</summary>...</details>`.',
   '',
-  'You are running as a Telegram chat bot, NOT as a script being piped into a shell. Certain phrases are CLI-context boilerplate from the underlying environment and MUST NEVER appear in a reply, because the user sees them as a literal message from you and they look like a system error:',
+  'Not every reply needs this — plain prose is still right for a normal conversational answer. Reach for structure when the CONTENT is structured, not by default.',
   '',
-  '- `No response requested.`',
-  '- `No response needed.`',
-  '- `Continuing...` as a standalone reply',
-  '- Any other shell-prompt-style filler that acknowledges silence',
+  '### Other Telegram quirks',
   '',
-  'If a user message is short, ambiguous, or feels like a no-op acknowledgement (e.g. `okay`, `ok`, `yes`, `got it`, `thanks`), reply with a brief substantive line — acknowledge what you understood and what (if anything) you will do next. If you genuinely have nothing useful to say, ask ONE specific clarifying question. NEVER emit a placeholder or a shell-style canned string — the chat surface has no silent-no-op state. Every reply must be intentional content.',
+  '- Horizontal rules render as a thin divider line.',
+  '- Long replies stream in chunks; prefer concise structure over walls of text.',
 ].join('\n');
 
+function buildPolygramDisplayHint(richText = false) {
+  const tablesSection = richText ? TABLES_AND_HEADERS_SECTION_RICH : TABLES_AND_HEADERS_SECTION_PLAIN;
+  return [
+    '## Telegram display rules',
+    '',
+    'Your replies render in the Telegram client. Phone is the design target.',
+    '',
+    tablesSection,
+    '',
+    '### NEVER emit shell-context canned strings — HARD RULE',
+    '',
+    'You are running as a Telegram chat bot, NOT as a script being piped into a shell. Certain phrases are CLI-context boilerplate from the underlying environment and MUST NEVER appear in a reply, because the user sees them as a literal message from you and they look like a system error:',
+    '',
+    '- `No response requested.`',
+    '- `No response needed.`',
+    '- `Continuing...` as a standalone reply',
+    '- Any other shell-prompt-style filler that acknowledges silence',
+    '',
+    'If a user message is short, ambiguous, or feels like a no-op acknowledgement (e.g. `okay`, `ok`, `yes`, `got it`, `thanks`), reply with a brief substantive line — acknowledge what you understood and what (if anything) you will do next. If you genuinely have nothing useful to say, ask ONE specific clarifying question. NEVER emit a placeholder or a shell-style canned string — the chat surface has no silent-no-op state. Every reply must be intentional content.',
+  ].join('\n');
+}
+
+// Pre-computed default (richText:false) — kept as a named export for
+// backward compatibility with any caller/test that imported the old
+// constant directly.
+const POLYGRAM_DISPLAY_HINT = buildPolygramDisplayHint(false);
+
 /**
  * Append the polygram display hint to an existing systemPrompt option,
  * preserving the original shape (string / preset object / undefined).
@@ -111,5 +145,6 @@ function appendDisplayHint(systemPromptOpt, hint = POLYGRAM_DISPLAY_HINT) {
 module.exports = {
   POLYGRAM_DISPLAY_HINT,
   TELEGRAM_TABLE_WIDTH_BUDGET,
+  buildPolygramDisplayHint,
   appendDisplayHint,
 };

package/lib/telegram/format.js

@@ -108,6 +108,12 @@ function buildRenderer() {
     image({ href, text }) {
       return `<a href="${escapeHtmlAttr(href)}">${escapeHtml(text || href)}</a>`;
     },
+    // Task-list items (marked type:'checkbox', gfm) render as a literal
+    // ☐/☑ glyph. Telegram's parse_mode=HTML has no support for <input> —
+    // marked's default checkbox() renderer emits one, which Telegram
+    // rejects outright (400: Unsupported start tag "input"), degrading
+    // the WHOLE message to raw markdown via api.js's HTML→plain fallback.
+    checkbox({ checked }) { return checked ? '☑ ' : '☐ '; },
     list({ items, ordered, start }) {
       const depth = listDepth;
       listDepth += 1;
@@ -115,7 +121,10 @@ function buildRenderer() {
       const bullet = bulletFor(depth);
       try {
         const lines = items.map((item, i) => {
-          const marker = ordered ? `${(start || 1) + i}. ` : `${bullet} `;
+          // Task items carry their own checkbox() glyph as the visual
+          // marker (rendered inline below) — an extra bullet in front
+          // would double up ("• ☐ x").
+          const marker = item.task ? '' : (ordered ? `${(start || 1) + i}. ` : `${bullet} `);
           const { inline, blocks } = splitItemTokens(item.tokens);
           const leader = this.parser.parseInline(inline).trim();
           let line = `${indent}${marker}${leader}`;

package/lib/telegram/rich-edit.js

@@ -0,0 +1,94 @@
+/**
+ * Rich-message edit-with-fallback. Capability and content errors preserve
+ * the reply through a plain edit; transient errors remain visible to the
+ * streamer's retry/finalization logic.
+ */
+
+'use strict';
+
+/**
+ * @param {object} deps
+ * @param {(bot, method, params, meta) => Promise<*>} deps.tg
+ * @param {string} deps.botName
+ * @param {(kind: string, detail: object) => void} deps.logEvent
+ * @param {(s: string) => string} deps.redactBotToken
+ * @param {(err) => boolean} deps.isRichCapabilityError
+ * @param {(err) => boolean} deps.isRichContentError
+ * @param {() => boolean} deps.getRichKnownUnsupported
+ * @param {() => void} deps.setRichKnownUnsupported — marks the latch tripped
+ * @param {() => (string|null)} [deps.getApiRoot] — for the latch-trip log line only
+ * @param {(url: string) => string} [deps.stripUrlCreds] — strips basic-auth
+ *   userinfo from apiRoot before logging
+ * @returns {(args: {bot, chatId: string, threadId: (string|null), messageId: number, blocks: Array, sourceText: string}) => Promise<{result: *, wentRich: boolean}>}
+ */
+function createRichEditor({
+  tg,
+  botName,
+  logEvent,
+  redactBotToken,
+  isRichCapabilityError,
+  isRichContentError,
+  getRichKnownUnsupported = () => false,
+  setRichKnownUnsupported = () => {},
+  getApiRoot = () => null,
+  stripUrlCreds = (s) => s,
+} = {}) {
+  return async function richEditMessageText({ bot, chatId, threadId = null, messageId, blocks, sourceText }) {
+    if (getRichKnownUnsupported()) {
+      const res = await tg(bot, 'editMessageText', {
+        chat_id: chatId, message_id: messageId, text: sourceText,
+      }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
+      return { result: res, wentRich: false };
+    }
+
+    try {
+      const res = await tg(bot, 'editMessageText', {
+        chat_id: chatId,
+        message_id: messageId,
+        rich_message: { blocks },
+      }, { source: 'bot-reply-stream-edit-rich', botName, richSourceText: sourceText });
+      // Record successful rich deliveries without storing message content.
+      logEvent('rich-message-sent', {
+        chat_id: chatId, thread_id: threadId, bot: botName,
+        streaming: true, block_count: blocks.length,
+        char_count: sourceText?.length ?? null,
+      });
+      // The streamer commits rich state only when this marker is true.
+      return { result: res, wentRich: true };
+    } catch (err) {
+      if (isRichCapabilityError(err)) {
+        setRichKnownUnsupported();
+        logEvent('rich-capability-latched', {
+          chat_id: chatId, bot: botName,
+          api_root: stripUrlCreds(getApiRoot() || 'cloud'),
+          error: redactBotToken(err.message)?.slice(0, 200),
+        });
+      } else if (isRichContentError(err)) {
+        logEvent('rich-content-fallback', {
+          chat_id: chatId, bot: botName,
+          error: redactBotToken(err.message)?.slice(0, 200),
+        });
+      } else {
+        // Transient (5xx/timeout/etc) — not ours to reclassify as a
+        // fallback; rethrow so the caller's existing retry/error
+        // handling deals with it exactly as a plain-path edit failure
+        // would (streamer.js's flush()/finalize() catch + log + move on).
+        logEvent('telegram-edit-failed', {
+          chat_id: chatId, msg_id: messageId,
+          // Network errors can include the request URL and bot token.
+          api_error: redactBotToken(err.message)?.slice(0, 200),
+          bot: botName,
+        });
+        throw err;
+      }
+      // Preserve the same authored content and tell the streamer that the
+      // accepted payload is plain, so its delivery trackers stay accurate.
+      const fallbackRes = await tg(bot, 'editMessageText', {
+        chat_id: chatId, message_id: messageId, text: sourceText,
+      }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
+      return { result: fallbackRes, wentRich: false };
+    }
+  };
+}
+
+module.exports = { createRichEditor };

package/lib/telegram/rich.js

@@ -0,0 +1,397 @@
+/**
+ * Markdown → Telegram Bot API Rich Message blocks.
+ *
+ * Companion to format.js's markdown→HTML pipeline, not a replacement:
+ * this only runs when needsRichRendering() finds a construct (task list,
+ * table, <details>, heading) that the plain HTML pipeline can't express
+ * natively, AND the chat has opted in (config.richText). Everything else
+ * stays on the existing toTelegramHtml() path.
+ *
+ * Block text fields carry plain strings only. Inline bold, italic, and
+ * links are flattened rather than mapped to an unverified nested schema.
+ * This keeps formatting safe while still supporting headings, tables,
+ * checklists, and collapsible details.
+ *
+ * Bot API limits are enforced by Telegram itself:
+ * ≤32,768 chars, ≤500 blocks, ≤16 nesting levels, ≤50 media, ≤20 table
+ * columns.
+ */
+
+'use strict';
+
+const { Marked } = require('marked');
+const { getTopicConfig } = require('../session-key');
+
+// ─── Per-chat opt-in resolution ──────────────────────────────────────
+//
+// Match the standard per-chat override precedence: topic, chat, active
+// bot, then defaults. `config.bot` is already filtered to the active bot
+// during startup.
+function resolveRichTextEnabled(config, chatId, threadId = null) {
+  if (!config) return false;
+  const chat = config.chats?.[String(chatId)] || null;
+  const topicCfg = (chat && threadId != null) ? getTopicConfig(chat, String(threadId)) : null;
+  const pick = (v) => (typeof v === 'boolean' ? v : undefined);
+  const resolved = pick(topicCfg?.richText)
+    ?? pick(chat?.richText)
+    ?? pick(config.bot?.richText)
+    ?? pick(config.defaults?.richText);
+  return resolved === true;
+}
+
+// ─── Content-adaptive gate ───────────────────────────────────────────
+//
+// Rich rendering uses different typography than plain prose (Telegram's
+// own client renders it as a document, not a chat bubble) — sending
+// ordinary prose through it makes it look oversized with no Bot API knob
+// to correct it. So rich is
+// reserved for content that actually contains a structural construct the
+// plain pipeline can't express: task lists, tables, <details>, headings.
+// False negatives are always safe (falls through to the existing,
+// well-tested toTelegramHtml path); false positives risk the oversized-
+// prose problem, so keep these patterns specific, not broad.
+//
+// Regexes below are deliberately simple/anchored (single quantified
+// groups, no nested-quantifier ambiguity) to avoid catastrophic
+// backtracking on adversarial input — the content they scan is agent
+// output that can be influenced by a user asking the agent to echo a
+// crafted string. See tests/rich.test.js for the ReDoS regression guard.
+
+const TASK_ITEM_RE = /^[ \t]{0,3}[-*+][ \t]+\[[ xX]\][ \t]+/m;
+const TABLE_ROW_RE = /^[ \t]{0,3}\|?[ \t]*:?-{2,}:?[ \t]*\|/m;
+const DETAILS_RE = /<details[ \t>]/i;
+const HEADING_RE = /^#{1,6}[ \t]+\S/m;
+const FENCE_LINE_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
+
+// Code-fence content renders literally, so heading, checklist, and table
+// syntax inside a fence must not influence the rich-rendering decision.
+// Track fences with a line scan to keep the gate easy to reason about on
+// adversarial input.
+function stripFencedCodeBlocks(markdown) {
+  if (markdown.indexOf('`') === -1 && markdown.indexOf('~') === -1) return markdown;
+  const lines = markdown.split('\n');
+  const out = [];
+  // A CommonMark closing fence uses the opener's character, is at least
+  // as long, and has only trailing whitespace. Preserve the opener so a
+  // marker with trailing content cannot expose fenced syntax to the gate.
+  let fence = null; // { char, len } while inside a fence, else null
+  for (const line of lines) {
+    const m = FENCE_LINE_RE.exec(line);
+    if (m) {
+      const marker = m[1];
+      const char = marker[0];
+      const len = marker.length;
+      const trailing = line.slice(m[0].length);
+      if (!fence) {
+        fence = { char, len };
+        out.push('');
+        continue;
+      }
+      if (char === fence.char && len >= fence.len && trailing.trim() === '') {
+        fence = null;
+        out.push('');
+        continue;
+      }
+      // Same-or-different marker mid-fence with trailing content (or a
+      // shorter/mismatched marker) — still inside the block; scope it
+      // out like any other fenced line, don't treat as a toggle.
+      out.push(fence ? '' : line);
+      continue;
+    }
+    out.push(fence ? '' : line);
+  }
+  return out.join('\n');
+}
+
+function needsRichRendering(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return false;
+  const scoped = stripFencedCodeBlocks(markdown);
+  return TASK_ITEM_RE.test(scoped)
+      || TABLE_ROW_RE.test(scoped)
+      || DETAILS_RE.test(scoped)
+      || HEADING_RE.test(scoped);
+}
+
+// ─── marked instance for block-level tokenization ────────────────────
+//
+// Use a dedicated lexer because format.js's instance has an HTML-string
+// renderer and does not expose a reusable token tree. GFM is required for
+// task-list items and tables.
+const _lexer = new Marked({ gfm: true, breaks: false });
+
+function plainTextOf(tokens) {
+  // Flatten inline tokens (bold/italic/link/code-span/text) to their
+  // plain text content — see module doc for why. marked's Tokens carry
+  // `.text` on leaf nodes; walk recursively for nested inline tokens
+  // (e.g. bold-wrapping-a-link) so nothing is silently dropped.
+  if (!Array.isArray(tokens)) return '';
+  let out = '';
+  for (const t of tokens) {
+    if (t.type === 'text' || t.type === 'codespan' || t.type === 'escape') {
+      out += t.text ?? '';
+    } else if (t.type === 'link' || t.type === 'image') {
+      out += plainTextOf(t.tokens) || t.text || t.href || '';
+    } else if (t.type === 'br') {
+      out += '\n';
+    } else if (Array.isArray(t.tokens)) {
+      out += plainTextOf(t.tokens);
+    } else if (typeof t.text === 'string') {
+      out += t.text;
+    } else if (typeof t.raw === 'string') {
+      out += t.raw;
+    }
+  }
+  return out;
+}
+
+const DETAILS_BLOCK_RE = /<details[^>]*>(?:\s*<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/i;
+const DETAILS_OPEN_RE = /<details[^>]*>/i;
+const DETAILS_CLOSE_RE = /<\/details>/i;
+const SUMMARY_TAG_RE = /<summary[^>]*>([\s\S]*?)<\/summary>/i;
+const HTML_TAG_STRIP_RE = /<[^>]+>/g;
+const DEFAULT_DETAILS_SUMMARY = 'Details';
+
+// Convert one marked block-level token into zero or more RichBlock
+// objects. Returns an array (a single markdown token can occasionally
+// need zero blocks — e.g. a bare 'space' token — or, in principle,
+// more than one).
+function blockFromToken(token) {
+  switch (token.type) {
+    case 'paragraph': {
+      const text = plainTextOf(token.tokens);
+      if (!text.trim()) return [];
+      return [{ type: 'paragraph', text }];
+    }
+    case 'heading': {
+      const size = Math.min(6, Math.max(1, token.depth || 1));
+      return [{ type: 'heading', text: plainTextOf(token.tokens), size }];
+    }
+    case 'code': {
+      return [{ type: 'pre', text: token.text || '' }];
+    }
+    case 'blockquote': {
+      const blocks = blocksFromTokens(token.tokens);
+      if (!blocks.length) return [];
+      return [{ type: 'blockquote', blocks }];
+    }
+    case 'list': {
+      const items = (token.items || []).map((item, i) => listItemFromToken(item, token, i)).filter(Boolean);
+      if (!items.length) return [];
+      return [{ type: 'list', items }];
+    }
+    case 'table': {
+      const cellAlignment = (column) => {
+        const align = token.align?.[column];
+        return align === 'center' || align === 'right' ? align : 'left';
+      };
+      const headerRow = (token.header || []).map((cell, column) => ({
+        text: plainTextOf(cell.tokens),
+        is_header: true,
+        align: cellAlignment(column),
+        valign: 'top',
+      }));
+      const rows = (token.rows || []).map((row) =>
+        row.map((cell, column) => ({
+          text: plainTextOf(cell.tokens),
+          align: cellAlignment(column),
+          valign: 'top',
+        })));
+      const cells = [headerRow, ...rows];
+      return [{ type: 'table', cells }];
+    }
+    case 'hr': {
+      return [{ type: 'divider' }];
+    }
+    case 'html': {
+      // Only <details> is handled specially (it's an explicit gate
+      // trigger, DETAILS_RE above); any other raw HTML block is NOT
+      // passed through verbatim (that would reopen exactly the
+      // injection surface escapeHtml closes in format.js) — it's
+      // rendered as a plain paragraph with tags stripped, matching
+      // the plain-text-only invariant this module holds throughout.
+      const m = DETAILS_BLOCK_RE.exec(token.raw || token.text || '');
+      if (m) {
+        const summary = (m[1] || '').replace(HTML_TAG_STRIP_RE, '').trim();
+        const innerMarkdown = (m[2] || '').trim();
+        const blocks = innerMarkdown ? blocksFromTokens(_lexer.lexer(innerMarkdown)) : [];
+        return [{
+          type: 'details',
+          summary: summary || DEFAULT_DETAILS_SUMMARY,
+          blocks: blocks.length ? blocks : [{ type: 'paragraph', text: '' }],
+          is_open: false,
+        }];
+      }
+      const stripped = (token.text || token.raw || '').replace(HTML_TAG_STRIP_RE, '').trim();
+      if (!stripped) return [];
+      return [{ type: 'paragraph', text: stripped }];
+    }
+    case 'space':
+      return [];
+    default: {
+      // Unknown token type — fall back to its flattened text rather
+      // than dropping content silently.
+      const text = plainTextOf(token.tokens) || token.text || '';
+      if (!text.trim()) return [];
+      return [{ type: 'paragraph', text }];
+    }
+  }
+}
+
+function listItemFromToken(item, listToken, index) {
+  const { inline, blockTokens } = splitListItemTokens(item.tokens);
+  const leaderText = plainTextOf(inline);
+  const nestedBlocks = blocksFromTokens(blockTokens);
+  const blocks = [];
+  if (leaderText.trim() || !nestedBlocks.length) blocks.push({ type: 'paragraph', text: leaderText });
+  blocks.push(...nestedBlocks);
+
+  const out = { blocks };
+  if (item.task) {
+    out.has_checkbox = true;
+    if (item.checked) out.is_checked = true;
+  } else if (listToken.ordered) {
+    out.value = (typeof listToken.start === 'number' ? listToken.start : 1) + index;
+  }
+  return out;
+}
+
+// Mirrors format.js's splitItemTokens (BLOCK_TYPES boundary) — a list
+// item's tokens are a leading inline run followed by any block-level
+// tokens (nested list, code block, etc). Kept separate from format.js's
+// copy because rich blocks need nested block arrays rather than HTML.
+const LIST_ITEM_BLOCK_TYPES = new Set(['list', 'blockquote', 'code', 'table', 'paragraph', 'space', 'html', 'hr']);
+
+function splitListItemTokens(tokens) {
+  const inline = [];
+  const blockTokens = [];
+  let crossed = false;
+  for (const tok of tokens || []) {
+    if (LIST_ITEM_BLOCK_TYPES.has(tok.type)) {
+      crossed = true;
+      blockTokens.push(tok);
+    } else if (crossed) {
+      blockTokens.push({ type: 'paragraph', tokens: [tok] });
+    } else {
+      inline.push(tok);
+    }
+  }
+  return { inline, blockTokens };
+}
+
+// GFM tokenizes <details>...</details> as a SINGLE 'html' token only when
+// there's no blank line inside it; a blank line (very common in
+// agent-authored content — a summary line, then a blank line, then the
+// body) splits it into separate sibling tokens: an 'html' open token, the
+// nested content as normal block tokens, and an 'html' close token. This
+// scans the token STREAM (not a single token) for that open/close span so
+// details blocks with real paragraph content inside render correctly
+// rather than getting silently split into a stray open-tag paragraph +
+// unrelated nested blocks + a stray close-tag paragraph.
+function blocksFromTokens(tokens) {
+  const out = [];
+  const list = tokens || [];
+  let i = 0;
+  while (i < list.length) {
+    const t = list[i];
+    const raw = t.raw || t.text || '';
+    if (t.type === 'html' && DETAILS_OPEN_RE.test(raw) && !DETAILS_CLOSE_RE.test(raw)) {
+      const summaryMatch = SUMMARY_TAG_RE.exec(raw);
+      const summary = summaryMatch ? summaryMatch[1].replace(HTML_TAG_STRIP_RE, '').trim() : '';
+      const inner = [];
+      let j = i + 1;
+      for (; j < list.length; j++) {
+        const tj = list[j];
+        const rawj = tj.raw || tj.text || '';
+        if (tj.type === 'html' && DETAILS_CLOSE_RE.test(rawj)) break;
+        inner.push(tj);
+      }
+      const nestedBlocks = blocksFromTokens(inner);
+      out.push({
+        type: 'details',
+        summary: summary || DEFAULT_DETAILS_SUMMARY,
+        blocks: nestedBlocks.length ? nestedBlocks : [{ type: 'paragraph', text: '' }],
+        is_open: false,
+      });
+      i = j + 1; // skip past the close token (or to the end if never closed)
+      continue;
+    }
+    out.push(...blockFromToken(t));
+    i++;
+  }
+  return out;
+}
+
+/**
+ * toTelegramRichBlocks(markdown, opts) -> { blocks: RichBlock[], usedRich: boolean }
+ *
+ * opts.partial (boolean, default false) — streaming mode: when true, the
+ * last top-level block is held back rather than emitted. Growing text
+ * may have cut it off mid-structure (an unclosed table,
+ * a dangling list item). The caller re-calls this on every chunk, so the
+ * held-back tail simply appears (complete) on a later call once the
+ * source text has moved past it. Only applies when there's more than one
+ * top-level block — a single in-progress block is emitted as-is rather
+ * than producing an empty array (better to show a resizing paragraph
+ * than nothing).
+ */
+function toTelegramRichBlocks(markdown, opts = {}) {
+  const usedRich = needsRichRendering(markdown);
+  if (!usedRich) return { blocks: [], usedRich: false };
+
+  const tokens = _lexer.lexer(markdown);
+  let blocks = blocksFromTokens(tokens);
+
+  if (opts.partial && blocks.length > 1) {
+    blocks = blocks.slice(0, -1);
+  }
+
+  return { blocks, usedRich: true };
+}
+
+// ─── Error classification ────────────────────────────────────────────
+//
+// Capability errors (endpoint missing) latch
+// rich off permanently for this process; content errors (this payload
+// specifically) fall back once, never latch. An error matching NEITHER
+// must be treated as transient and fall through to the existing retry
+// path in api.js.
+
+// Unsupported new endpoints normally return 404. The existing
+// editMessageText endpoint can instead reject its `rich_message`
+// parameter with an unknown/unsupported-field response, so both shapes
+// identify a missing rich-message capability.
+const RICH_CAPABILITY_ERR_RE = /method\s*["']?(?:sendRichMessage|sendRichMessageDraft|editMessageText)["']?\s*not found|no such method|unknown method|method not found|(?:unknown|unsupported|unrecognized)\s+(?:parameter|field)s?\s*["']?rich_message["']?|rich_message\s*["']?\s*(?:is\s+)?(?:unknown|unsupported|unrecognized|not\s+supported)/i;
+
+function errorMessage(err) {
+  if (!err) return '';
+  return String(err.description || err.message || err.error_message || err);
+}
+
+function isRichCapabilityError(err) {
+  if (!err) return false;
+  const msg = errorMessage(err);
+  if (RICH_CAPABILITY_ERR_RE.test(msg)) return true;
+  // A 404 is sufficient because these checks only wrap rich-message calls.
+  const status = err.error_code ?? err.status ?? err.statusCode;
+  return status === 404;
+}
+
+const RICH_CONTENT_ERR_RE = /RICH_MESSAGE_[A-Z_]+|can'?t parse (?:input)?rich\s*block|rich message.*(?:too (?:many|long)|invalid)/i;
+
+function isRichContentError(err) {
+  if (!err) return false;
+  return RICH_CONTENT_ERR_RE.test(errorMessage(err));
+}
+
+module.exports = {
+  needsRichRendering,
+  toTelegramRichBlocks,
+  resolveRichTextEnabled,
+  isRichCapabilityError,
+  isRichContentError,
+  errorMessage,
+  // exported for tests / introspection, not part of the public contract
+  _plainTextOf: plainTextOf,
+  _blocksFromTokens: blocksFromTokens,
+  _stripFencedCodeBlocks: stripFencedCodeBlocks,
+};

package/lib/telegram/streamer.js

@@ -84,15 +84,37 @@ function createStreamer({
   // (only final bubble visible) for partner-facing chats that
   // prefer terse output.
   preserveIntermediateBubbles = true,
+  // Optional progressive rich-message rendering. A null callback keeps
+  // the streamer on its plain-text path.
+  //
+  // toRichPayload(text, { partial }) -> { blocks, usedRich } | null
+  //   Called on every flush/finalize with the CURRENT latestText/finalText
+  //   (untruncated — rich content is never char-truncated with a "..."
+  //   the way plain live-preview text is; partial:true tells it to hold
+  //   back a possibly-incomplete trailing block, see lib/telegram/rich.js).
+  //   usedRich:false (or a null return) means "not rich this tick" — the
+  //   streamer falls through to the existing plain-text path unchanged.
+  //   The callback may return a different result on each call when live
+  //   configuration or capability state changes.
+  toRichPayload = null,
+  // Rich messages have a larger Bot API character cap than plain
+  // messages, so rich edits and finalization must use this limit.
+  richMaxLen = 32768,
+  // Fires for each successful plain-to-rich transition. Caller wires this
+  // to instrumentation for the visible bubble-shape change.
+  onRichUpgrade = () => {},
 } = {}) {
   throttleMs = Math.max(THROTTLE_FLOOR_MS, throttleMs);
   let state = 'idle';       // 'idle' | 'live' | 'finalized'
   let msgId = null;
-  let currentText = '';     // what's on screen right now (truncated to maxLen)
+  let currentText = '';     // what's on screen right now (truncated to maxLen) — plain-path only
+  let currentRichJson = null; // JSON.stringify of the last-sent rich blocks, or null when not in rich mode
   let latestText = '';      // latest we've been told about
   let lastEditTs = 0;
   let pendingEdit = null;   // timer id
-  let flushPromise = null;  // ongoing edit promise (for back-pressure)
+  let flushPromise = null;  // serialized flush chain (for back-pressure)
+  let flushQueued = false;  // latest text changed while a flush was active
+  let bubbleGeneration = 0; // invalidates state commits from superseded bubbles
   // 0.7.2: msg_ids of bubbles that have been superseded by
   // forceNewMessage(). The caller (polygram.js handleMessage at
   // end-of-turn) reads getArchived() and issues deleteMessage on
@@ -185,24 +207,103 @@ function createStreamer({
     pendingEdit = schedule(flush, delay);
   }
 
+  // Decide the rich-vs-plain payload for the CURRENT latestText/finalText.
+  // Shared by flush() and finalize() so the "only attempt rich under the
+  // rich char cap" guard and the upgrade-event firing live in one place.
+  function resolveRichPayload(text, { partial }) {
+    if (!toRichPayload) return null;
+    if (text.length > richMaxLen) {
+      // Edge case, not fully engineered (documented limitation): a
+      // mid-stream reply that's ALREADY past the rich cap while still
+      // growing. Rather than flap into a truncated/ellipsis rich render
+      // (which has no real analog — rich has no "..." convention), skip
+      // rich for this tick; finalize()'s own overflow check (against
+      // richMaxLen) is what actually decides discard-and-redeliver-plain
+      // once streaming ends.
+      return null;
+    }
+    let payload;
+    try {
+      payload = toRichPayload(text, { partial });
+    } catch (err) {
+      logger.error?.(`[stream] toRichPayload threw, falling back to plain: ${err.message}`);
+      return null;
+    }
+    return payload && payload.usedRich ? payload : null;
+  }
+
   async function flush() {
     pendingEdit = null;
     if (state !== 'live' || msgId == null) return;
-    const next = truncateForLive(latestText);
-    if (next === currentText) return;
+
+    if (flushPromise) {
+      flushQueued = true;
+      return flushPromise;
+    }
+
+    const run = (async () => {
+      do {
+        flushQueued = false;
+        await flushOnce();
+      } while (flushQueued && state === 'live' && msgId != null);
+    })();
+    flushPromise = run;
+    try {
+      await run;
+    } finally {
+      if (flushPromise === run) flushPromise = null;
+    }
+  }
+
+  async function flushOnce() {
+    if (state !== 'live' || msgId == null) return;
+    const editMsgId = msgId;
+    const generation = bubbleGeneration;
+    const sourceText = latestText;
+
+    const richPayload = resolveRichPayload(sourceText, { partial: true });
+    if (richPayload) {
+      const json = JSON.stringify(richPayload.blocks);
+      if (json === currentRichJson) return; // no structural change since last edit
+      const wasRich = currentRichJson !== null;
+      lastEditTs = clock();
+      try {
+        // Keep the source beside its blocks so a content-error fallback
+        // can render the same Markdown through the plain-text path.
+        const editResult = await edit(editMsgId, {
+          rich: true, blocks: richPayload.blocks, sourceText,
+        });
+        if (generation !== bubbleGeneration || msgId !== editMsgId) return;
+        // A rich editor can resolve successfully after sending the same
+        // source as plain fallback. Track what actually landed.
+        const wentRich = editResult == null || editResult.wentRich !== false;
+        if (wentRich) {
+          currentRichJson = json;
+          if (!wasRich) onRichUpgrade();
+        } else {
+          currentText = sourceText;
+          currentRichJson = null;
+        }
+      } catch (err) {
+        logger.error(`[stream] rich edit failed: ${err.message}`);
+      }
+      return;
+    }
+
+    const next = truncateForLive(sourceText);
+    if (currentRichJson === null && next === currentText) return;
     lastEditTs = clock();
-    currentText = next;
     try {
-      flushPromise = edit(msgId, currentText);
-      await flushPromise;
+      await edit(editMsgId, next);
+      if (generation !== bubbleGeneration || msgId !== editMsgId) return;
+      currentText = next;
+      currentRichJson = null;
     } catch (err) {
       // Non-fatal — maybe 429 or transient. Log and keep going; next
       // chunk will retry. The HTML→plain fallback in lib/telegram.js
       // already handles the most common cause (parse error from
       // truncate cutting mid-tag).
       logger.error(`[stream] edit failed: ${err.message}`);
-    } finally {
-      flushPromise = null;
     }
   }
 
@@ -242,9 +343,12 @@ function createStreamer({
     }
     msgId = null;
     currentText = '';
+    currentRichJson = null; // new bubble starts plain — see toRichPayload doc
     latestText = '';
     state = 'idle';
     lastEditTs = 0;
+    flushQueued = false;
+    bubbleGeneration += 1;
   }
 
   // 0.7.0: delete the current bubble via the injected deleteMessage
@@ -311,6 +415,40 @@ function createStreamer({
     let body = applyTransform(finalText ?? latestText);
     if (errorSuffix) body = `${body}\n\n⚠️ ${errorSuffix}`;
 
+    // Finalization evaluates the complete body, so no trailing block is
+    // held back as potentially incomplete.
+    const richPayload = resolveRichPayload(body, { partial: false });
+    if (richPayload) {
+      // Rich finalization uses the rich-message cap; applying the smaller
+      // plain-message cap would unnecessarily redeliver valid rich bodies.
+      if (body.length > richMaxLen) {
+        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true };
+      }
+      const json = JSON.stringify(richPayload.blocks);
+      if (json === currentRichJson) {
+        return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
+      }
+      const wasRich = currentRichJson !== null;
+      try {
+        const editResult = await edit(msgId, { rich: true, blocks: richPayload.blocks, sourceText: body });
+        // A fallback still delivered the final content, but as plain text.
+        const wentRich = editResult == null || editResult.wentRich !== false;
+        if (wentRich) {
+          currentRichJson = json;
+          if (!wasRich) onRichUpgrade();
+        } else {
+          currentText = body;
+          currentRichJson = null;
+        }
+        return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
+      } catch (err) {
+        logger.error(`[stream] final rich edit failed: ${err.message}`);
+        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false };
+      }
+    }
+
+    // Plain finalization uses the regular message cap.
+    //
     // If body overflows the single-message cap, the caller needs to
     // discard this bubble and redeliver via chunks. Don't try to edit.
     if (body.length > maxLen) {
@@ -322,13 +460,14 @@ function createStreamer({
     // without redelivering. If it fails (e.g. parse error after our
     // wrapper exhausts its retry, or a 5xx), caller should discard
     // and redeliver — the bubble's content is unreliable.
-    if (body === currentText) {
+    if (currentRichJson === null && body === currentText) {
       // Already correct — no edit needed.
       return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
     }
     try {
       await edit(msgId, body);
       currentText = body;
+      currentRichJson = null;
       return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
     } catch (err) {
       logger.error(`[stream] final edit failed: ${err.message}`);
@@ -353,6 +492,8 @@ function createStreamer({
     get state() { return state; },
     get msgId() { return msgId; },
     get currentText() { return currentText; },
+    get isRichMode() { return currentRichJson !== null; },
+    get currentRichBlocks() { return currentRichJson ? JSON.parse(currentRichJson) : null; },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.17.12",
+  "version": "0.18.1",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {
@@ -63,7 +63,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.123",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shumkov/orchestra": "^0.4.0",
+    "@shumkov/orchestra": "^0.4.2",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/polygram.js

@@ -96,6 +96,12 @@ const { createStore: createPairingsStore, parseTtl: parsePairingTtl } = require(
 const { transcribe: transcribeVoice, isVoiceAttachment } = require('./lib/telegram/voice');
 const { createStreamer } = require('./lib/telegram/streamer');
 const { chunkMarkdownText } = require('./lib/telegram/chunk');
+const {
+  toTelegramRichBlocks, resolveRichTextEnabled, isRichCapabilityError, isRichContentError,
+} = require('./lib/telegram/rich');
+const { createRichEditor } = require('./lib/telegram/rich-edit');
+const { buildPolygramDisplayHint } = require('./lib/telegram/display-hint');
+const { redactBotToken, stripUrlCredentials } = require('./lib/error/net');
 // F#23: shared agent-reply helper. parseResponse + sanitizer + chunked
 // delivery + inline sticker/react in one place. Wired into both the
 // channels dispatcher (F#1) and the autonomous-wakeup handler (F#23).
@@ -299,6 +305,23 @@ function logEvent(kind, detail) {
   dbWrite(() => db.logEvent(kind, detail), `log ${kind}`);
 }
 
+// One bot runs per process, so rich-message capability can be represented
+// by one process-wide boolean rather than a per-connection map. Set once by
+// isRichCapabilityError (endpoint missing/404) and never cleared for the
+// process lifetime — retrying a permanently-missing endpoint on every
+// future send is wasteful. Transient errors must not set the latch.
+let richKnownUnsupported = false;
+
+// Extracted to lib/telegram/rich-edit.js so the capability/content/
+// transient error-classification + fallback wiring is directly unit-
+// testable. Constructed in main() (like `tg` itself, just below),
+// NOT here at module load time — BOT_NAME/config are `let`s still
+// `null`/`undefined` at this point; capturing them by destructuring now
+// would bake in stale values permanently, unlike `logEvent`, which is
+// safe to reference early because it's a stable function that does its
+// own live lookups internally when called.
+let richEditMessageText;
+
 // 0.15 secret redaction (agent-flagged path): the agent marks a secret it saw
 // in the user's message with `[redact:<secret>]`. parseResponse / stripInlineTags
 // strip the marker so nothing leaks to the user; here we wipe the literal from
@@ -819,8 +842,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     // showed "Agent: shumabit" instead of music-curation:music-curator
     // (2026-06-03). getTopicConfig returns {} when there's no active topic.
     const _cardTopicCfg = getTopicConfig(chatConfig, threadIdStr || null);
-    const info = formatConfigInfoText(chatConfig, show, sessionKey, _cardTopicCfg);
-    const reply_markup = buildConfigKeyboard(chatConfig, show, _cardTopicCfg);
+    const effectiveRichText = resolveRichTextEnabled(config, chatId, threadIdStr || null);
+    const info = formatConfigInfoText(chatConfig, show, sessionKey, _cardTopicCfg, effectiveRichText);
+    const reply_markup = buildConfigKeyboard(chatConfig, show, _cardTopicCfg, effectiveRichText);
     await sendReply(info, { params: { reply_markup } });
     return;
   }
@@ -981,11 +1005,35 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // eliminates the "stuck at 15min typing" complaint from the non-streaming
   // code path. For short responses the streamer stays idle and we fall
   // through to the normal send path via finalize() returning streamed=false.
+  // Gate rich delivery on the per-chat/topic opt-in and the process-wide
+  // capability latch. Returning null forces the streamer's plain-text
+  // path — same contract for "not opted in", "capability known
+  // unsupported", and "content doesn't need it" (needsRichRendering
+  // inside toTelegramRichBlocks handles the last one).
+  // Rich delivery is limited to this interactive streamer instance.
+  // A reply that never crosses minChars (stays idle → delivered via
+  // deliverReplies) and any non-streaming send path — autonomous-wakeup/
+  // auto-resume/autosteer via lib/telegram/process-agent-reply.js, cron/
+  // IPC sends — never render rich even when richText is on and the
+  // content qualifies. Those delivery paths intentionally remain plain.
+  // Re-read both controls for every flush so a config change or a
+  // capability result applies to the turn already in progress.
+  const toRichPayload = (text, opts) => {
+    if (richKnownUnsupported || !resolveRichTextEnabled(config, chatId, threadId)) return null;
+    return toTelegramRichBlocks(text, opts);
+  };
+
   const streamer = createStreamer({
     // rc.67: pre-process every chunk to strip recognised
     // [sticker:NAME] / [react:EMOJI] tags BEFORE the bubble or DB row
     // captures them. See stripInlineTagsForStreamer above.
     transformText: stripInlineTagsForStreamer,
+    toRichPayload,
+    onRichUpgrade: () => {
+      // Record the visible transition when an existing plain bubble
+      // becomes rich during streaming.
+      logEvent('rich-streaming-upgrade', { chat_id: chatId, thread_id: threadId, bot: BOT_NAME });
+    },
     send: async (text) => {
       const params = {
         chat_id: chatId, text,
@@ -1001,7 +1049,17 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       }
       return tg(bot, 'sendMessage', params, outMetaBase);
     },
-    edit: async (messageId, text) => {
+    edit: async (messageId, payload) => {
+      // The streamer emits either a plain string or a rich payload with
+      // blocks and their source Markdown. Rich error classification and
+      // fallback live in rich-edit.js so this wiring stays focused.
+      if (payload && typeof payload === 'object' && payload.rich) {
+        return richEditMessageText({
+          bot, chatId, threadId, messageId,
+          blocks: payload.blocks, sourceText: payload.sourceText,
+        });
+      }
+      const text = payload;
       try {
         // Route edits through tg() so applyFormatting runs (MarkdownV2
         // + escape). Going direct to bot.api.editMessageText would
@@ -2279,6 +2337,18 @@ async function main() {
     db = dbClient.open(DB_PATH);
     console.log(`[db] opened ${DB_PATH}`);
     tg = createSender(db, console, config);
+    richEditMessageText = createRichEditor({
+      tg,
+      botName: BOT_NAME,
+      logEvent,
+      redactBotToken,
+      isRichCapabilityError,
+      isRichContentError,
+      getRichKnownUnsupported: () => richKnownUnsupported,
+      setRichKnownUnsupported: () => { richKnownUnsupported = true; },
+      getApiRoot: () => config.bot?.apiRoot || null,
+      stripUrlCreds: stripUrlCredentials,
+    });
     pairings = createPairingsStore(db.raw);
     approvals = createApprovalsStore(db.raw);
     const migration = migrateJsonToDb(db, SESSIONS_JSON_PATH, config.chats);
@@ -2635,7 +2705,9 @@ async function main() {
     pmDefault: 'sdk',
     // The CLI append-system-prompt's FIRST block — origin hard-required this into every
     // CliProcess. Without it, cli chats lose the Telegram table/markdown display rules.
-    displayHint: require('./lib/telegram/display-hint').POLYGRAM_DISPLAY_HINT,
+    // A resolver (not a static string) so each cli-backed chat gets its own richText
+    // state — orchestra's factory calls this per spawn with the spawning chat/topic.
+    displayHint: (chatId, threadId) => buildPolygramDisplayHint(resolveRichTextEnabled(config, chatId, threadId)),
     // Backend-default outbound cap fallback (per-spawn buildSpawnContext override
     // normally supersedes this; kept so any context-less spawn still gets the backend
     // default rather than orchestra's neutral 100MB).