polygram 0.18.1 → 0.19.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "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/process/channels-tool-dispatcher.js

@@ -317,6 +317,9 @@ function createChannelsToolDispatcher({
           }
           try {
             const ext = path.extname(check.resolved).toLowerCase();
+            // Deliberately broader than rich-media.js's PHOTO_EXTENSIONS:
+            // sendPhoto accepts .gif as a photo message, while a rich
+            // photo BLOCK cannot carry an animation.
             const isImage = ['.jpg', '.jpeg', '.png', '.gif', '.webp'].includes(ext);
             const method = isImage ? 'sendPhoto' : 'sendDocument';
             const fieldName = isImage ? 'photo' : 'document';

package/lib/telegram/display-hint.js

@@ -63,13 +63,43 @@ const TABLES_AND_HEADERS_SECTION_PLAIN = [
 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.',
+  'This chat has rich-text rendering enabled. Real Telegram markdown tables, headings (`#`/`##`/etc.), task lists, collapsible `<details>` blocks, blockquotes (`>`), and dividers (`---`) now render as an actual structured message, not flattened text. 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.',
+  '**Use the real construct instead of faking it with bold text and emoji.** In plain-mode chats you had to fake structure with **bold** pseudo-headers, emoji bullets (✅ ❓ 🕓, •, etc.), and plain-text separator lines, because headings and checkboxes rendered as flattened text there. That workaround is unnecessary here and looks worse than the real thing. When you catch yourself about to write a bold pseudo-heading or an emoji-bulleted list, use the actual construct instead:',
+  '',
+  '- A named group of items (e.g. "ready to apply" / "needs your input" / "deferred") → a real heading (`## Ready to apply`), not `**Ready to apply:**`.',
+  '- A list of items each with a yes/no/pending state (approve this? confirm that?) → a real task list (`- [ ] item`), not `• item` with an emoji glued on.',
+  '- A comparison or key/value summary → a real markdown table.',
+  '- A quoted aside, caveat, or callout you want visually set apart → a real blockquote (`> like this`), not a bold prefix.',
+  '- A visual break between distinct sections of a long reply → a real divider (`---` on its own line), the same way you already reach for it, but now it renders as a divider instead of literal dashes.',
+  '- Verbose supporting detail (a diff, a log, raw output) you want available but not front-and-center → `<details><summary>Label</summary>...</details>`.',
+  '',
+  'Worked example — triaging a batch of items into groups, each item with its own state:',
+  '',
+  '```',
+  '## Ready to apply',
+  '',
+  '- [ ] Merge the two lists into one (#18)',
+  '- [ ] Fix the delivery-time wording (#4)',
+  '',
+  '## Need your input',
+  '',
+  '- [ ] Hemming service — confirm we can offer it (#11)',
+  '',
+  '## Deferred to v2',
+  '',
+  '- [ ] Size-guide page (#16)',
+  '```',
+  '',
+  '**Task lists for progress:** `- [ ] pending step` / `- [x] done step` renders as a real checkbox list — the natural way to show multi-step progress, a batch of items awaiting confirmation, or anything else with a per-item done/pending state.',
   '',
   '**Collapsible detail:** wrap verbose logs/diffs/output you want available but not front-and-center in `<details><summary>Label</summary>...</details>`.',
   '',
-  '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.',
+  '**Inline images:** write `![caption](/abs/path/to/shot.png)` on its own line to place a photo inline at that point in the reply — screenshots, plots, before/after comparisons. Absolute path only, inside your workspace or the attachments staging dir; png/jpg/webp only (no gif). A path you can\'t reach, or any other file type, degrades to a plain "(image unavailable)" line — it will not error. Always accompany an image with at least a sentence of text.',
+  '',
+  '**Grouping images:** wrap consecutive images in `<tg-collage>…</tg-collage>` (grid) or `<tg-slideshow>…</tg-slideshow>` (swipeable) to send them as one block instead of separate photos.',
+  '',
+  'Not every reply needs this — plain prose is still right for a normal conversational answer with no distinct items or sections. Reach for structure when the CONTENT is structured, not by default.',
   '',
   '### Other Telegram quirks',
   '',

package/lib/telegram/rich-edit.js

@@ -2,10 +2,56 @@
  * 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.
+ *
+ * Media handling: blocks arrive JSON-safe — local files as
+ * `{ source: '<realpath>' }` envelopes at photo.media (rich.js emits
+ * them that way because the streamer dedups payloads via JSON.stringify,
+ * which a grammy InputFile would break: its toJSON throws by design).
+ * The envelope→InputFile materialization happens HERE, on a cloned
+ * tree, immediately before each send attempt — so the caller's blocks
+ * stay serializable and every retry gets a fresh path-backed InputFile.
+ * Fallback edits go through sanitizeFallbackText so a media-bearing
+ * reply degrades without rendering absolute local paths into the chat.
  */
 
 'use strict';
 
+const { countMediaBlocks } = require('./rich');
+
+// Clone the block tree, replacing { source } envelopes at photo.media
+// with uploadable files. Only the photo-block envelope shape is
+// materialized — everything else passes through untouched.
+function materializeMediaBlocks(blocks, makeInputFile) {
+  return (blocks || []).map((b) => {
+    if (b && b.type === 'photo'
+        && b.photo && typeof b.photo === 'object'
+        && b.photo.media && typeof b.photo.media === 'object'
+        && typeof b.photo.media.source === 'string') {
+      return { ...b, photo: { ...b.photo, media: makeInputFile(b.photo.media.source) } };
+    }
+    if (b && Array.isArray(b.blocks)) {
+      return { ...b, blocks: materializeMediaBlocks(b.blocks, makeInputFile) };
+    }
+    if (b && Array.isArray(b.items)) {
+      return {
+        ...b,
+        items: b.items.map((it) => (it && Array.isArray(it.blocks)
+          ? { ...it, blocks: materializeMediaBlocks(it.blocks, makeInputFile) }
+          : it)),
+      };
+    }
+    return b;
+  });
+}
+
+function defaultMakeInputFile(source) {
+  // Lazy require keeps unit tests free of the grammy dependency; the
+  // InputFile MUST be path-backed (never a stream/supplier) so api.js's
+  // 429/pre-connect retries can re-read it.
+  const { InputFile } = require('grammy');
+  return new InputFile(source);
+}
+
 /**
  * @param {object} deps
  * @param {(bot, method, params, meta) => Promise<*>} deps.tg
@@ -19,6 +65,11 @@
  * @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
+ * @param {(source: string) => *} [deps.makeInputFile] — { source } envelope →
+ *   uploadable file for grammy (test seam)
+ * @param {(text: string) => string} [deps.sanitizeFallbackText] — applied to
+ *   sourceText on every plain-fallback edit (polygram wires
+ *   stripMediaMarkdown; default identity preserves legacy callers)
  * @returns {(args: {bot, chatId: string, threadId: (string|null), messageId: number, blocks: Array, sourceText: string}) => Promise<{result: *, wentRich: boolean}>}
  */
 function createRichEditor({
@@ -32,11 +83,13 @@ function createRichEditor({
   setRichKnownUnsupported = () => {},
   getApiRoot = () => null,
   stripUrlCreds = (s) => s,
+  makeInputFile = defaultMakeInputFile,
+  sanitizeFallbackText = (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,
+        chat_id: chatId, message_id: messageId, text: sanitizeFallbackText(sourceText),
       }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
       return { result: res, wentRich: false };
     }
@@ -45,12 +98,13 @@ function createRichEditor({
       const res = await tg(bot, 'editMessageText', {
         chat_id: chatId,
         message_id: messageId,
-        rich_message: { blocks },
+        rich_message: { blocks: materializeMediaBlocks(blocks, makeInputFile) },
       }, { 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,
+        media_count: countMediaBlocks(blocks),
         char_count: sourceText?.length ?? null,
       });
       // The streamer commits rich state only when this marker is true.
@@ -84,11 +138,11 @@ function createRichEditor({
       // 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,
+        chat_id: chatId, message_id: messageId, text: sanitizeFallbackText(sourceText),
       }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
       return { result: fallbackRes, wentRich: false };
     }
   };
 }
 
-module.exports = { createRichEditor };
+module.exports = { createRichEditor, materializeMediaBlocks };

package/lib/telegram/rich-media.js

@@ -0,0 +1,162 @@
+/**
+ * Rich-message media resolver — turns agent-authored image srcs into
+ * uploadable media values for photo blocks, enforcing the same trust
+ * boundary as reply(files).
+ *
+ * The renderer (rich.js) stays filesystem-free; every impure decision
+ * lives here: src classification, path allowlisting, extension and
+ * size gating, and the per-message media budget. Returned local-file
+ * media are JSON-safe `{ source: '<realpath>' }` envelopes — the
+ * grammy InputFile is materialized later, in rich-edit.js, because an
+ * InputFile inside the block tree would break the streamer's
+ * JSON.stringify payload dedup (InputFile.toJSON throws by design).
+ *
+ * src classification is a trichotomy decided by a literal prefix test,
+ * never a URL parser (a colon in a local path must not read as a
+ * scheme):
+ *   1. http(s):// URL   → passed through; Telegram fetches it
+ *                          server-side (its 5 MB URL-photo limit
+ *                          applies). Rejected when the bot runs
+ *                          through a self-hosted Bot API server
+ *                          (allowUrlMedia=false) — whether that server
+ *                          fetches the URL from inside the operator's
+ *                          network (an SSRF surface) is unverified.
+ *   2. absolute path    → realpath + allowlist via the same
+ *                          validateAttachmentPath used by reply(files);
+ *                          the RESOLVED path is what gets uploaded, so
+ *                          symlink games can't dodge the check.
+ *   3. anything else    → rejected (data:, file:, tg:, attach:,
+ *                          relative paths). A literal agent-authored
+ *                          attach:// string must never reach grammy —
+ *                          it would dangle against a multipart part
+ *                          that doesn't exist.
+ *
+ * Rejections degrade to placeholder paragraphs upstream; the reply
+ * always delivers. Events log reason classes only — never the raw src
+ * (URLs can embed credentials, paths leak workspace structure).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { validateAttachmentPath } = require('../process/channels-tool-dispatcher');
+
+// Telegram's per-photo upload ceiling (multipart). Distinct from the
+// document caps in attachments.js — photos are capped tighter than
+// documents by the Bot API.
+const PHOTO_UPLOAD_CEILING = 10 * 1024 * 1024;
+
+// Bound on the SINGLE multipart request that carries every photo of a
+// reply (media upload happens in one finalize edit). Matches
+// attachments.js's MAX_TOTAL_BYTES posture.
+const MAX_TOTAL_MEDIA_BYTES = 50 * 1024 * 1024;
+
+// Rich messages allow ≤50 media attachments in total (Bot API "Rich
+// Message Limits"), wrapper children included. Enforced here, on the
+// flattened descriptor list, so Telegram never rejects the whole reply
+// over attachment #51.
+const MAX_MEDIA_PER_MESSAGE = 50;
+
+// Photo-block source selection (NOT a security control — the path
+// allowlist is; Telegram validates actual bytes server-side). .gif is
+// deliberately absent: it maps to an animation block, which this
+// module doesn't emit — unlike channels-tool-dispatcher's image list,
+// which includes .gif because sendPhoto accepts it as a photo message.
+const PHOTO_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
+
+const HTTP_URL_RE = /^https?:\/\//i;
+
+/**
+ * @param {object} deps
+ * @param {string[]} deps.allowedRoots — absolute roots media paths must
+ *   resolve under (same builder as reply(files): buildAllowedRoots)
+ * @param {number} [deps.maxPhotoBytes] — per-file cap, already clamped
+ *   to PHOTO_UPLOAD_CEILING by the caller
+ * @param {number} [deps.maxTotalMediaBytes] — per-reply budget
+ * @param {boolean} [deps.allowUrlMedia] — false when a self-hosted Bot
+ *   API server is configured (see module doc)
+ * @param {(kind: string, detail: object) => void} [deps.logEvent]
+ * @param {(p: string, roots: string[]) => {ok: boolean, resolved?: string, error?: string}} [deps.validatePath]
+ * @param {(p: string) => number} [deps.fileSize]
+ * @returns {(descriptors: Array<{src: string, caption: string}>) => Array<{media?: (string|{source: string}), rejected?: string}>}
+ */
+function createRichMediaResolver({
+  allowedRoots = [],
+  maxPhotoBytes = PHOTO_UPLOAD_CEILING,
+  maxTotalMediaBytes = MAX_TOTAL_MEDIA_BYTES,
+  allowUrlMedia = true,
+  logEvent = null,
+  validatePath = validateAttachmentPath,
+  fileSize = (p) => fs.statSync(p).size,
+} = {}) {
+  return function resolveMedia(descriptors) {
+    const results = [];
+    const reasons = [];
+    let accepted = 0;
+    let totalBytes = 0;
+
+    const reject = (reason) => {
+      reasons.push(reason);
+      results.push({ rejected: reason });
+    };
+
+    for (const d of descriptors || []) {
+      const src = typeof d?.src === 'string' ? d.src : '';
+      if (!src) { reject('empty-src'); continue; }
+      if (accepted >= MAX_MEDIA_PER_MESSAGE) { reject('media-cap'); continue; }
+
+      if (HTTP_URL_RE.test(src)) {
+        if (!allowUrlMedia) { reject('url-local-api'); continue; }
+        accepted += 1;
+        results.push({ media: src });
+        continue;
+      }
+
+      if (!path.isAbsolute(src)) {
+        // Covers relative paths AND every non-http scheme (data:,
+        // file:, tg:, attach:, …) — none of them start with "/".
+        reject('not-absolute');
+        continue;
+      }
+
+      const check = validatePath(src, allowedRoots);
+      if (!check.ok) { reject('path'); continue; }
+
+      if (!PHOTO_EXTENSIONS.has(path.extname(check.resolved).toLowerCase())) {
+        reject('extension');
+        continue;
+      }
+
+      let bytes;
+      try { bytes = fileSize(check.resolved); }
+      catch { reject('unreadable'); continue; }
+      if (bytes > maxPhotoBytes) { reject('too-large'); continue; }
+      if (totalBytes + bytes > maxTotalMediaBytes) { reject('total-budget'); continue; }
+
+      totalBytes += bytes;
+      accepted += 1;
+      results.push({ media: { source: check.resolved } });
+    }
+
+    if (reasons.length && typeof logEvent === 'function') {
+      try {
+        logEvent('rich-media-rejected', {
+          rejected_count: reasons.length,
+          accepted_count: accepted,
+          reasons: reasons.slice(0, 10),
+        });
+      } catch { /* instrumentation must never break delivery */ }
+    }
+
+    return results;
+  };
+}
+
+module.exports = {
+  createRichMediaResolver,
+  PHOTO_UPLOAD_CEILING,
+  MAX_TOTAL_MEDIA_BYTES,
+  MAX_MEDIA_PER_MESSAGE,
+  PHOTO_EXTENSIONS,
+};

package/lib/telegram/rich.js

@@ -3,9 +3,11 @@
  *
  * 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.
+ * table, <details>, heading, blockquote, divider, image, or a
+ * <tg-collage>/<tg-slideshow> media wrapper) 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.
@@ -61,6 +63,12 @@ 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 BLOCKQUOTE_RE = /^[ \t]{0,3}>[ \t]?\S/m;
+const DIVIDER_RE = /^[ \t]{0,3}(-{3,}|\*{3,}|_{3,})[ \t]*$/m;
+// Markdown image syntax and Telegram's own collage/slideshow wrapper
+// tags trigger rich so photos can render inline as media blocks.
+const IMAGE_RE = /!\[[^\]\n]*\]\([^)\n]+\)/;
+const MEDIA_WRAP_RE = /<tg-(?:collage|slideshow)[ \t>]/i;
 const FENCE_LINE_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
 
 // Code-fence content renders literally, so heading, checklist, and table
@@ -103,13 +111,25 @@ function stripFencedCodeBlocks(markdown) {
   return out.join('\n');
 }
 
-function needsRichRendering(markdown) {
-  if (typeof markdown !== 'string' || markdown.length === 0) return false;
-  const scoped = stripFencedCodeBlocks(markdown);
+// Non-media triggers, kept separate so the media-drop demotion in
+// toTelegramRichBlocks can ask "would this content be rich WITHOUT its
+// images?" — if not, and no image resolved, the reply goes plain rather
+// than rendering prose-only rich blocks (the oversized-prose problem).
+function hasNonMediaTrigger(scoped) {
   return TASK_ITEM_RE.test(scoped)
       || TABLE_ROW_RE.test(scoped)
       || DETAILS_RE.test(scoped)
-      || HEADING_RE.test(scoped);
+      || HEADING_RE.test(scoped)
+      || BLOCKQUOTE_RE.test(scoped)
+      || DIVIDER_RE.test(scoped);
+}
+
+function needsRichRendering(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return false;
+  const scoped = stripFencedCodeBlocks(markdown);
+  return hasNonMediaTrigger(scoped)
+      || IMAGE_RE.test(scoped)
+      || MEDIA_WRAP_RE.test(scoped);
 }
 
 // ─── marked instance for block-level tokenization ────────────────────
@@ -151,6 +171,107 @@ const SUMMARY_TAG_RE = /<summary[^>]*>([\s\S]*?)<\/summary>/i;
 const HTML_TAG_STRIP_RE = /<[^>]+>/g;
 const DEFAULT_DETAILS_SUMMARY = 'Details';
 
+// ─── Media (photo / collage / slideshow) ─────────────────────────────
+//
+// Image markdown maps to Telegram photo blocks; <tg-collage>/<tg-slideshow>
+// wrapper tags (Telegram's own rich-markdown dialect) group images into
+// collage/slideshow blocks. The renderer emits internal DESCRIPTOR
+// blocks (_media/_mediaGroup) carrying only { src, caption } strings;
+// toTelegramRichBlocks substitutes them via the injected resolveMedia
+// (final mode) or with placeholder paragraphs (streaming/partial mode,
+// or when no resolver is wired). Emitted block trees therefore never
+// contain a raw agent-authored path, and never contain anything that
+// can't survive JSON.stringify (the streamer dedups payloads that way;
+// grammy InputFile instances would throw — they're materialized later,
+// in rich-edit.js).
+//
+// Wrapper-span extraction deliberately scans the token stream (like the
+// <details> handling below) instead of using a lazy [\s\S]*? block
+// regex — an unclosed wrapper over a large body would make such a regex
+// backtrack, and this text is agent output a user can influence.
+const MEDIA_WRAP_OPEN_RE = /<tg-(collage|slideshow)(?:[ \t][^>]*)?>/i;
+const MEDIA_WRAP_CLOSE_RE = /<\/tg-(?:collage|slideshow)>/i;
+// Extraction form of IMAGE_RE: alt, src, optional quoted title. Single
+// negated character classes only — linear on adversarial input.
+const IMAGE_MD_G_RE = /!\[([^\]\n]*)\]\(([^)\s]+)(?:[ \t]+"([^"\n]*)")?\)/g;
+
+function mediaDescriptor(src, caption) {
+  return { type: '_media', src: src || '', caption: (caption || '').trim() };
+}
+
+// Pull image markdown out of a raw text span (used for wrapper bodies
+// that arrive as one opaque html token).
+function extractMediaItems(text) {
+  const items = [];
+  IMAGE_MD_G_RE.lastIndex = 0;
+  let m;
+  while ((m = IMAGE_MD_G_RE.exec(text)) !== null) {
+    items.push(mediaDescriptor(m[2], m[1] || m[3]));
+  }
+  return items;
+}
+
+// True if any inline token in the subtree is an image or a media
+// wrapper tag — the cheap pre-check that lets media-free paragraphs
+// keep the existing single-plainTextOf path untouched.
+function inlineHasMedia(tokens) {
+  for (const t of tokens || []) {
+    if (t.type === 'image') return true;
+    if (t.type === 'html' && MEDIA_WRAP_RE.test(t.raw || t.text || '')) return true;
+    if (Array.isArray(t.tokens) && inlineHasMedia(t.tokens)) return true;
+  }
+  return false;
+}
+
+// Split a paragraph's inline tokens into paragraph text runs, _media
+// descriptors, and _mediaGroup spans (inline <tg-collage>…</tg-collage>
+// on one line). Recurses only into bare 'text' containers (marked nests
+// list-item content that way); images inside links/bold stay flattened
+// to their alt text by plainTextOf — splitting mid-link would produce
+// stranger output than the flattening does.
+function blocksFromInlineTokens(inlineTokens) {
+  const out = [];
+  let textRun = [];
+  let group = null;
+  const flushText = () => {
+    if (!textRun.length) return;
+    const text = plainTextOf(textRun);
+    textRun = [];
+    if (text.trim()) out.push({ type: 'paragraph', text });
+  };
+  const walk = (tokens) => {
+    for (const t of tokens || []) {
+      if (t.type === 'image') {
+        const d = mediaDescriptor(t.href, plainTextOf(t.tokens) || t.text || t.title);
+        if (group) group.items.push(d);
+        else { flushText(); out.push(d); }
+      } else if (t.type === 'html') {
+        const raw = t.raw || t.text || '';
+        const open = MEDIA_WRAP_OPEN_RE.exec(raw);
+        if (!group && open && !MEDIA_WRAP_CLOSE_RE.test(raw)) {
+          flushText();
+          group = { type: '_mediaGroup', kind: open[1].toLowerCase(), items: [] };
+        } else if (group && MEDIA_WRAP_CLOSE_RE.test(raw)) {
+          if (group.items.length) out.push(group);
+          group = null;
+        } else {
+          textRun.push(t);
+        }
+      } else if (t.type === 'text' && Array.isArray(t.tokens) && inlineHasMedia(t.tokens)) {
+        walk(t.tokens);
+      } else {
+        textRun.push(t);
+      }
+    }
+  };
+  walk(inlineTokens);
+  // Unclosed inline wrapper: keep whatever images it collected rather
+  // than dropping content.
+  if (group && group.items.length) out.push(group);
+  flushText();
+  return out;
+}
+
 // 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,
@@ -158,6 +279,9 @@ const DEFAULT_DETAILS_SUMMARY = 'Details';
 function blockFromToken(token) {
   switch (token.type) {
     case 'paragraph': {
+      if (inlineHasMedia(token.tokens)) {
+        return blocksFromInlineTokens(token.tokens);
+      }
       const text = plainTextOf(token.tokens);
       if (!text.trim()) return [];
       return [{ type: 'paragraph', text }];
@@ -209,17 +333,36 @@ function blockFromToken(token) {
       // 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 || '');
+      const src = token.raw || token.text || '';
+      const m = DETAILS_BLOCK_RE.exec(src);
       if (m) {
+        // An html token can carry content around the <details> span (an
+        // HTML block runs until a blank line, so trailing prose or even a
+        // second <details> lands in the same token). Emit that content
+        // too rather than dropping it with the matched span.
+        const out = [];
+        const prefix = src.slice(0, m.index).replace(HTML_TAG_STRIP_RE, '').trim();
+        if (prefix) out.push({ type: 'paragraph', text: prefix });
         const summary = (m[1] || '').replace(HTML_TAG_STRIP_RE, '').trim();
         const innerMarkdown = (m[2] || '').trim();
         const blocks = innerMarkdown ? blocksFromTokens(_lexer.lexer(innerMarkdown)) : [];
-        return [{
+        out.push({
           type: 'details',
           summary: summary || DEFAULT_DETAILS_SUMMARY,
           blocks: blocks.length ? blocks : [{ type: 'paragraph', text: '' }],
           is_open: false,
-        }];
+        });
+        const suffix = src.slice(m.index + m[0].length);
+        if (suffix.trim()) out.push(...blocksFromTokens(_lexer.lexer(suffix)));
+        return out;
+      }
+      // A whole <tg-collage>/<tg-slideshow> span in one token (GFM
+      // produces this when the wrapper body has no blank lines).
+      const wrap = MEDIA_WRAP_OPEN_RE.exec(token.raw || token.text || '');
+      if (wrap && MEDIA_WRAP_CLOSE_RE.test(token.raw || token.text || '')) {
+        const items = extractMediaItems(token.raw || token.text || '');
+        if (!items.length) return [];
+        return [{ type: '_mediaGroup', kind: wrap[1].toLowerCase(), items }];
       }
       const stripped = (token.text || token.raw || '').replace(HTML_TAG_STRIP_RE, '').trim();
       if (!stripped) return [];
@@ -239,10 +382,15 @@ function blockFromToken(token) {
 
 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 });
+  if (inlineHasMedia(inline)) {
+    blocks.push(...blocksFromInlineTokens(inline));
+    if (!blocks.length && !nestedBlocks.length) blocks.push({ type: 'paragraph', text: '' });
+  } else {
+    const leaderText = plainTextOf(inline);
+    if (leaderText.trim() || !nestedBlocks.length) blocks.push({ type: 'paragraph', text: leaderText });
+  }
   blocks.push(...nestedBlocks);
 
   const out = { blocks };
@@ -298,29 +446,227 @@ function blocksFromTokens(tokens) {
       const summaryMatch = SUMMARY_TAG_RE.exec(raw);
       const summary = summaryMatch ? summaryMatch[1].replace(HTML_TAG_STRIP_RE, '').trim() : '';
       const inner = [];
+      let closeRaw = null;
       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;
+        if (tj.type === 'html' && DETAILS_CLOSE_RE.test(rawj)) { closeRaw = rawj; break; }
         inner.push(tj);
       }
       const nestedBlocks = blocksFromTokens(inner);
+      // The close tag's html token can carry content on adjacent lines
+      // (an HTML block runs until a blank line): text before </details>
+      // belongs inside the collapsible body, text after it is ordinary
+      // top-level content following the details block.
+      let after = '';
+      if (closeRaw != null) {
+        const cm = DETAILS_CLOSE_RE.exec(closeRaw);
+        const before = closeRaw.slice(0, cm.index).replace(HTML_TAG_STRIP_RE, '').trim();
+        if (before) nestedBlocks.push({ type: 'paragraph', text: before });
+        after = closeRaw.slice(cm.index + cm[0].length);
+      }
       out.push({
         type: 'details',
         summary: summary || DEFAULT_DETAILS_SUMMARY,
         blocks: nestedBlocks.length ? nestedBlocks : [{ type: 'paragraph', text: '' }],
         is_open: false,
       });
+      if (after.trim()) out.push(...blocksFromTokens(_lexer.lexer(after)));
       i = j + 1; // skip past the close token (or to the end if never closed)
       continue;
     }
+    // <tg-collage>/<tg-slideshow> split across tokens by blank lines —
+    // same open/close span scan as <details> above. Images among the
+    // inner tokens become the group's items; any non-media inner
+    // content is emitted after the group rather than dropped.
+    if (t.type === 'html' && MEDIA_WRAP_OPEN_RE.test(raw) && !MEDIA_WRAP_CLOSE_RE.test(raw)) {
+      const kind = MEDIA_WRAP_OPEN_RE.exec(raw)[1].toLowerCase();
+      // An UNCLOSED wrapper with no blank lines arrives as one html
+      // token whose raw already contains the image lines — they are
+      // not sibling tokens, so the span scan below can't see them.
+      // Extract them from the open token itself or they'd be silently
+      // dropped when the close tag never arrives (truncated stream,
+      // malformed agent output).
+      const items = extractMediaItems(raw);
+      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' && MEDIA_WRAP_CLOSE_RE.test(rawj)) break;
+        inner.push(tj);
+      }
+      const innerBlocks = blocksFromTokens(inner);
+      const rest = [];
+      for (const b of innerBlocks) {
+        if (b.type === '_media') items.push({ type: '_media', src: b.src, caption: b.caption });
+        else if (b.type === '_mediaGroup') items.push(...b.items);
+        else rest.push(b);
+      }
+      if (items.length) out.push({ type: '_mediaGroup', kind, items });
+      out.push(...rest);
+      i = j + 1;
+      continue;
+    }
     out.push(...blockFromToken(t));
     i++;
   }
   return out;
 }
 
+// ─── Media descriptor substitution ───────────────────────────────────
+
+// Placeholder paragraph text for a media descriptor that isn't (or
+// can't be) materialized. Uses the agent's own caption when present —
+// never a filesystem-derived basename, which for a rejected path would
+// echo the target filename into the visible chat.
+function mediaPlaceholderText(d, { unavailable = false } = {}) {
+  if (unavailable) return d.caption ? `${d.caption} (image unavailable)` : '(image unavailable)';
+  return d.caption ? `🖼 ${d.caption}` : '🖼 image';
+}
+
+// Depth-first, document-order collection of media descriptors across
+// the block tree (wrapper children flattened) — the single array
+// resolveMedia sees, which is what keeps the message-scoped media cap
+// honest.
+function collectMediaDescriptors(blocks, list = []) {
+  for (const b of blocks || []) {
+    if (b.type === '_media') {
+      list.push({ src: b.src, caption: b.caption });
+    } else if (b.type === '_mediaGroup') {
+      for (const it of b.items) list.push({ src: it.src, caption: it.caption });
+    } else {
+      if (Array.isArray(b.blocks)) collectMediaDescriptors(b.blocks, list);
+      if (Array.isArray(b.items)) {
+        for (const it of b.items) if (Array.isArray(it.blocks)) collectMediaDescriptors(it.blocks, list);
+      }
+    }
+  }
+  return list;
+}
+
+function photoBlockFrom(result, caption) {
+  const block = { type: 'photo', photo: { type: 'photo', media: result.media } };
+  if (caption) block.caption = { text: caption };
+  return block;
+}
+
+// Replace descriptor blocks with real photo/collage/slideshow blocks
+// (when `results` — index-aligned with collectMediaDescriptors order —
+// is provided) or with placeholder paragraphs (streaming / no resolver).
+// `cursor` threads the shared descriptor index through the recursion.
+function substituteMediaBlocks(blocks, results, cursor = { i: 0 }) {
+  const out = [];
+  for (const b of blocks || []) {
+    if (b.type === '_media') {
+      const r = results ? results[cursor.i] : null;
+      cursor.i += 1;
+      if (r && r.media) out.push(photoBlockFrom(r, b.caption));
+      else if (results) out.push({ type: 'paragraph', text: mediaPlaceholderText(b, { unavailable: true }) });
+      else out.push({ type: 'paragraph', text: mediaPlaceholderText(b) });
+    } else if (b.type === '_mediaGroup') {
+      if (!results) {
+        cursor.i += b.items.length;
+        out.push({ type: 'paragraph', text: `🖼 ${b.kind} (${b.items.length} images)` });
+        continue;
+      }
+      const photos = [];
+      let unavailable = 0;
+      for (const it of b.items) {
+        const r = results[cursor.i];
+        cursor.i += 1;
+        if (r && r.media) photos.push(photoBlockFrom(r, it.caption));
+        else unavailable += 1;
+      }
+      if (photos.length === 1) out.push(photos[0]);
+      else if (photos.length > 1) out.push({ type: b.kind, blocks: photos });
+      if (unavailable > 0) {
+        out.push({ type: 'paragraph', text: `(${unavailable} image${unavailable === 1 ? '' : 's'} unavailable)` });
+      }
+    } else if (Array.isArray(b.blocks) || Array.isArray(b.items)) {
+      const clone = { ...b };
+      if (Array.isArray(b.blocks)) clone.blocks = substituteMediaBlocks(b.blocks, results, cursor);
+      if (Array.isArray(b.items)) {
+        clone.items = b.items.map((it) => (Array.isArray(it.blocks)
+          ? { ...it, blocks: substituteMediaBlocks(it.blocks, results, cursor) }
+          : it));
+      }
+      out.push(clone);
+    } else {
+      out.push(b);
+    }
+  }
+  return out;
+}
+
+// Count media attachments in an emitted block tree (photo blocks plus
+// collage/slideshow children) — the media_count instrumentation field.
+function countMediaBlocks(blocks) {
+  let n = 0;
+  for (const b of blocks || []) {
+    if (b.type === 'photo') n += 1;
+    else if (b.type === 'collage' || b.type === 'slideshow') n += countMediaBlocks(b.blocks);
+    else {
+      if (Array.isArray(b.blocks)) n += countMediaBlocks(b.blocks);
+      if (Array.isArray(b.items)) {
+        for (const it of b.items) if (Array.isArray(it.blocks)) n += countMediaBlocks(it.blocks);
+      }
+    }
+  }
+  return n;
+}
+
+// Project media markdown out of plain fallback text: image syntax
+// degrades to its caption text, wrapper tags disappear, and a dangling
+// UNTERMINATED trailing image fragment ("![shot](/User…" still being
+// streamed, or malformed output missing its ")") is cut — the fragment
+// is exactly the shape that carries a raw absolute path, and it's what
+// live plain previews would otherwise render before the rich upgrade
+// kicks in. Fenced code is left untouched (image syntax inside a fence
+// is literal content). Used on every plain-text surface a rich-enabled
+// chat's reply can reach: live preview edits, fallback edits, and
+// chunked redelivery.
+const MEDIA_WRAP_TAG_G_RE = /<\/?tg-(?:collage|slideshow)(?:[ \t][^>]*)?>/gi;
+// An image opener at end-of-line that never completed: "![", "![alt",
+// "![alt]", "![alt](", "![alt](/partial/pa…". Single negated classes,
+// optional groups anchored at $ — linear.
+const TRAILING_IMAGE_FRAGMENT_RE = /!\[[^\]\n]*(?:\][ \t]*(?:\([^)\n]*)?)?$/;
+
+function stripMediaMarkdown(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return markdown;
+  if (markdown.indexOf('![') === -1 && markdown.indexOf('<tg-') === -1) return markdown;
+  const lines = markdown.split('\n');
+  const out = [];
+  // Fence tracking mirrors stripFencedCodeBlocks (same open/close
+  // semantics) but keeps every line — only non-fenced lines are
+  // rewritten.
+  let fence = null;
+  for (const line of lines) {
+    const m = FENCE_LINE_RE.exec(line);
+    if (m) {
+      const marker = m[1];
+      const trailing = line.slice(m[0].length);
+      if (!fence) fence = { char: marker[0], len: marker.length };
+      else if (marker[0] === fence.char && marker.length >= fence.len && trailing.trim() === '') fence = null;
+      out.push(line);
+      continue;
+    }
+    if (fence) { out.push(line); continue; }
+    IMAGE_MD_G_RE.lastIndex = 0;
+    let clean = line
+      .replace(IMAGE_MD_G_RE, (_all, alt, _src, title) => (alt || title || '').trim())
+      .replace(MEDIA_WRAP_TAG_G_RE, '');
+    // Only a fragment on the FINAL line can still be completed by
+    // text that hasn't streamed in yet; earlier lines can't (image
+    // syntax never spans lines), so a fragment there is plain
+    // malformed output — cut it the same way.
+    clean = clean.replace(TRAILING_IMAGE_FRAGMENT_RE, '');
+    out.push(clean);
+  }
+  return out.join('\n');
+}
+
 /**
  * toTelegramRichBlocks(markdown, opts) -> { blocks: RichBlock[], usedRich: boolean }
  *
@@ -333,6 +679,17 @@ function blocksFromTokens(tokens) {
  * 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).
+ *
+ * opts.resolveMedia (descriptors: [{src, caption}]) -> results[] —
+ * index-aligned with the descriptors; each result is `{ media }` (an
+ * https URL string or a JSON-safe `{ source: '<realpath>' }` envelope
+ * that rich-edit.js later materializes into a grammy InputFile) or a
+ * falsy/rejected marker. NEVER called in partial mode — streaming ticks
+ * must not touch the filesystem; images render as placeholder
+ * paragraphs until finalize. Absent resolver → placeholders too.
+ * When media was the ONLY gate trigger and none of it resolved, the
+ * whole render demotes to `usedRich: false` so prose doesn't ship as
+ * oversized rich paragraphs.
  */
 function toTelegramRichBlocks(markdown, opts = {}) {
   const usedRich = needsRichRendering(markdown);
@@ -341,10 +698,38 @@ function toTelegramRichBlocks(markdown, opts = {}) {
   const tokens = _lexer.lexer(markdown);
   let blocks = blocksFromTokens(tokens);
 
+  const descriptors = collectMediaDescriptors(blocks);
+  let results = null;
+  let resolvedCount = 0;
+  if (descriptors.length && !opts.partial && typeof opts.resolveMedia === 'function') {
+    try {
+      const r = opts.resolveMedia(descriptors);
+      if (Array.isArray(r)) {
+        results = r;
+        resolvedCount = r.filter((x) => x && x.media).length;
+      }
+    } catch {
+      results = null; // resolver failure degrades to placeholders, never crashes the reply
+    }
+  }
+  if (descriptors.length) {
+    blocks = substituteMediaBlocks(blocks, results);
+  }
+
   if (opts.partial && blocks.length > 1) {
     blocks = blocks.slice(0, -1);
   }
 
+  if (descriptors.length && !opts.partial && resolvedCount === 0
+      && !hasNonMediaTrigger(stripFencedCodeBlocks(markdown))) {
+    return { blocks: [], usedRich: false };
+  }
+
+  // An empty rich payload is never sendable (Telegram rejects
+  // rich_message with no blocks; api.js refuses it before the call) —
+  // whatever produced it, plain is the honest degrade.
+  if (!blocks.length) return { blocks: [], usedRich: false };
+
   return { blocks, usedRich: true };
 }
 
@@ -360,7 +745,14 @@ function toTelegramRichBlocks(markdown, opts = {}) {
 // 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;
+//
+// "rich message must be non-empty" is a capability shape too, observed
+// live on a Bot API 10.1 self-hosted server: it accepts sendRichMessage
+// but predates the 10.2 `blocks` field, silently ignores it, and sees
+// an "empty" InputRichMessage. api.js refuses genuinely empty payloads
+// before any network call, so this response to a payload we sent can
+// only mean the server cannot read typed blocks — latch, don't retry.
+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)|rich message must be non-empty/i;
 
 function errorMessage(err) {
   if (!err) return '';
@@ -390,8 +782,11 @@ module.exports = {
   isRichCapabilityError,
   isRichContentError,
   errorMessage,
+  stripMediaMarkdown,
+  countMediaBlocks,
   // exported for tests / introspection, not part of the public contract
   _plainTextOf: plainTextOf,
   _blocksFromTokens: blocksFromTokens,
   _stripFencedCodeBlocks: stripFencedCodeBlocks,
+  _collectMediaDescriptors: collectMediaDescriptors,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "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": {

package/polygram.js

@@ -49,7 +49,7 @@ const { extractAssistantText } = require('@shumkov/orchestra');
 // and reused by createChannelsToolDispatcher inside main() — Claude replies
 // containing code blocks or HTML-style tags aren't split mid-element by the
 // size cap.
-const { createChannelsToolDispatcher } = require('./lib/process/channels-tool-dispatcher');
+const { createChannelsToolDispatcher, buildAllowedRoots } = require('./lib/process/channels-tool-dispatcher');
 const { createTmuxRunner } = require('@shumkov/orchestra');
 const { sweepTmuxOrphans } = require('@shumkov/orchestra').orphanSweep;
 // rc.42: autosteer-buffer module deleted. Native SDK priority push
@@ -98,7 +98,9 @@ const { createStreamer } = require('./lib/telegram/streamer');
 const { chunkMarkdownText } = require('./lib/telegram/chunk');
 const {
   toTelegramRichBlocks, resolveRichTextEnabled, isRichCapabilityError, isRichContentError,
+  stripMediaMarkdown,
 } = require('./lib/telegram/rich');
+const { createRichMediaResolver, PHOTO_UPLOAD_CEILING } = require('./lib/telegram/rich-media');
 const { createRichEditor } = require('./lib/telegram/rich-edit');
 const { buildPolygramDisplayHint } = require('./lib/telegram/display-hint');
 const { redactBotToken, stripUrlCredentials } = require('./lib/error/net');
@@ -1018,9 +1020,48 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // 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.
+  // Media (photo/collage/slideshow) resolution for rich replies. Same
+  // trust boundary as reply(files): roots are the per-session staging
+  // dir plus the session's spawn cwd (topic override wins, mirroring
+  // getSessionSpawnIdentity) — path-set parity with the channels
+  // dispatcher, which builds its roots from the same inputs. URL media
+  // is disabled when a self-hosted Bot API server is configured (its
+  // URL-fetch origin is unverified — see lib/telegram/rich-media.js).
+  const _mediaTopicCfg = getTopicConfig(chatConfig, threadIdStr || null);
+  const resolveRichMedia = createRichMediaResolver({
+    allowedRoots: buildAllowedRoots({
+      sessionKey,
+      sessionCwd: _mediaTopicCfg.cwd || chatConfig.cwd || null,
+    }),
+    maxPhotoBytes: Math.min(
+      PHOTO_UPLOAD_CEILING,
+      resolveMaxFileOverride(config, chatId, threadId) ?? PHOTO_UPLOAD_CEILING,
+    ),
+    allowUrlMedia: !config.bot?.apiRoot,
+    logEvent: (kind, detail) => logEvent(kind, {
+      chat_id: chatId, thread_id: threadId, bot: BOT_NAME, ...detail,
+    }),
+  });
   const toRichPayload = (text, opts) => {
     if (richKnownUnsupported || !resolveRichTextEnabled(config, chatId, threadId)) return null;
-    return toTelegramRichBlocks(text, opts);
+    return toTelegramRichBlocks(text, { ...opts, resolveMedia: resolveRichMedia });
+  };
+  // Plain-path text hygiene for rich-enabled chats: the live preview
+  // streams PLAIN until the rich gate trips (and stays plain if the
+  // capability latch fires), so a reply's image markdown — including a
+  // still-incomplete trailing "![shot](/abs/pa…" fragment — would
+  // otherwise render its raw local path into the visible bubble.
+  // Degrade media markdown to caption text on every plain send/edit.
+  // The streamer's internal dedup state keeps the UNsanitized text on
+  // both sides of its comparisons, so this stays a display-only
+  // transform (same class as tg()'s markdown→HTML conversion).
+  const sanitizeLiveText = (text) => {
+    if (!resolveRichTextEnabled(config, chatId, threadId)) return text;
+    const clean = stripMediaMarkdown(text);
+    // An image-only chunk can sanitize to nothing; keep the bubble
+    // alive with a minimal placeholder rather than tripping tg()'s
+    // empty-text guard.
+    return clean.trim() ? clean : '…';
   };
 
   const streamer = createStreamer({
@@ -1036,7 +1077,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     },
     send: async (text) => {
       const params = {
-        chat_id: chatId, text,
+        chat_id: chatId, text: sanitizeLiveText(text),
         ...(threadId && { message_thread_id: threadId }),
       };
       if (!firstBubbleSent) {
@@ -1070,7 +1111,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         return await tg(bot, 'editMessageText', {
           chat_id: chatId,
           message_id: messageId,
-          text,
+          text: sanitizeLiveText(text),
         }, { source: 'bot-reply-stream-edit', botName: BOT_NAME });
       } catch (err) {
         // Stream-edit failures would otherwise be invisible — edits
@@ -1078,7 +1119,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         // want the failure path specifically surfaced). Log to events.
         logEvent('telegram-edit-failed', {
           chat_id: chatId, msg_id: messageId,
-          api_error: err.message?.slice(0, 200),
+          // Network errors can embed the request URL, which carries the
+          // bot token — redact before persisting, matching rich-edit.js
+          // and api.js's handling of the same error class.
+          api_error: redactBotToken(err.message)?.slice(0, 200),
           bot: BOT_NAME,
         });
         throw err;
@@ -1696,7 +1740,14 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         // send the body as proper chunks.
         try { await streamer.discard(); }
         catch (err) { console.error(`[${label}] discard failed: ${err.message}`); }
-        const chunks = chunkMarkdownText(parsed.text, TG_CHUNK_BUDGET);
+        // Rich-enabled chats may carry media markdown; the plain
+        // redelivery can't upload it, and a raw `![cap](/abs/path)`
+        // would render the local path into the chat. Degrade images to
+        // their captions (images are not delivered on this path).
+        const redeliverText = resolveRichTextEnabled(config, chatId, threadId)
+          ? stripMediaMarkdown(parsed.text)
+          : parsed.text;
+        const chunks = chunkMarkdownText(redeliverText, TG_CHUNK_BUDGET);
         const r = await deliverReplies({
           bot,
           send: (b, method, params, m) => tg(b, method, params, m),
@@ -1774,7 +1825,13 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // 0.7.0: use markdown-aware chunker + deliverReplies primitive.
       // The old chunkText was newline/byte-only; chunkMarkdownText also
       // respects code-fence boundaries (closes + reopens across chunks).
-      const chunks = chunkMarkdownText(parsed.text, TG_CHUNK_BUDGET);
+      // Short replies never went live-rich, so image markdown from a
+      // rich-enabled chat degrades to caption text here too — never a
+      // raw local path in the bubble.
+      const shortText = resolveRichTextEnabled(config, chatId, threadId)
+        ? stripMediaMarkdown(parsed.text)
+        : parsed.text;
+      const chunks = chunkMarkdownText(shortText, TG_CHUNK_BUDGET);
       await deliverReplies({
         bot,
         send: (b, method, params, m) => tg(b, method, params, m),
@@ -2348,6 +2405,7 @@ async function main() {
       setRichKnownUnsupported: () => { richKnownUnsupported = true; },
       getApiRoot: () => config.bot?.apiRoot || null,
       stripUrlCreds: stripUrlCredentials,
+      sanitizeFallbackText: stripMediaMarkdown,
     });
     pairings = createPairingsStore(db.raw);
     approvals = createApprovalsStore(db.raw);