polygram 0.18.2 → 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.2",
+  "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

@@ -95,6 +95,10 @@ const TABLES_AND_HEADERS_SECTION_RICH = [
   '',
   '**Collapsible detail:** wrap verbose logs/diffs/output you want available but not front-and-center in `<details><summary>Label</summary>...</details>`.',
   '',
+  '**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,7 +3,8 @@
  *
  * Companion to format.js's markdown→HTML pipeline, not a replacement:
  * this only runs when needsRichRendering() finds a construct (task list,
- * table, <details>, heading, blockquote, divider) that the plain HTML
+ * 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.
@@ -64,6 +65,10 @@ 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
@@ -106,9 +111,11 @@ 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)
@@ -117,6 +124,14 @@ function needsRichRendering(markdown) {
       || 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 ────────────────────
 //
 // Use a dedicated lexer because format.js's instance has an HTML-string
@@ -156,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,
@@ -163,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 }];
@@ -214,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 [];
@@ -244,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 };
@@ -303,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 }
  *
@@ -338,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);
@@ -346,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 };
 }
 
@@ -365,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 '';
@@ -395,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.2",
+  "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);