polygram 0.18.2 → 0.20.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.20.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 media:** use the unchanged `![caption](/abs/path/to/file.ext)` syntax on its own line. Local `.jpg`, `.jpeg`, `.png`, and `.webp` files become photos; `.mp4` becomes video; `.gif` becomes animation. Use an absolute path inside your workspace or the attachments staging dir. An unreachable path or unsupported type degrades to a plain "(media unavailable)" line — it will not error. Always accompany media with at least a sentence of substantive text.',
+  '',
+  '**Grouping media:** wrap consecutive supported media in `<tg-collage>…</tg-collage>` (grid) or `<tg-slideshow>…</tg-slideshow>` (swipeable) to send them as one mixed-media block.',
+  '',
   '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,79 @@
  * 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>', fingerprint: '…' }` envelopes at the typed
+ * media field (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).
+ * Cached file IDs or envelope→InputFile materialization happen HERE, on a
+ * cloned tree, immediately before each send attempt — so the caller's
+ * blocks stay serializable while local sources are revalidated at delivery.
+ * 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');
+
+const MEDIA_SOURCE_CHANGED = 'RICH_MEDIA_SOURCE_CHANGED';
+const MEDIA_BLOCK_KINDS = new Set(['photo', 'video', 'animation']);
+
+// Clone the block tree, replacing local source envelopes with uploadable
+// files while preserving each block's concrete media kind.
+function materializeMediaBlocks(blocks, makeInputFile, preflightMedia = null) {
+  return (blocks || []).map((b) => {
+    const kind = b?.type;
+    const inputMedia = MEDIA_BLOCK_KINDS.has(kind) ? b[kind] : null;
+    if (inputMedia && typeof inputMedia === 'object'
+        && inputMedia.media && typeof inputMedia.media === 'object'
+        && typeof inputMedia.media.source === 'string') {
+      const checked = typeof preflightMedia === 'function'
+        ? preflightMedia(inputMedia.media, kind)
+        : {
+          ok: true,
+          value: typeof inputMedia.media.fileId === 'string' && inputMedia.media.fileId
+            ? inputMedia.media.fileId
+            : inputMedia.media,
+        };
+      if (!checked?.ok) {
+        const err = new Error('Rich media source changed before upload');
+        err.code = MEDIA_SOURCE_CHANGED;
+        throw err;
+      }
+      const media = checked.value || inputMedia.media;
+      return {
+        ...b,
+        [kind]: {
+          ...inputMedia,
+          media: typeof media === 'string' ? media : makeInputFile(media.source),
+        },
+      };
+    }
+    if (b && Array.isArray(b.blocks)) {
+      return { ...b, blocks: materializeMediaBlocks(b.blocks, makeInputFile, preflightMedia) };
+    }
+    if (b && Array.isArray(b.items)) {
+      return {
+        ...b,
+        items: b.items.map((it) => (it && Array.isArray(it.blocks)
+          ? { ...it, blocks: materializeMediaBlocks(it.blocks, makeInputFile, preflightMedia) }
+          : 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,7 +88,12 @@
  * @param {() => (string|null)} [deps.getApiRoot] — for the latch-trip log line only
  * @param {(url: string) => string} [deps.stripUrlCreds] — strips basic-auth
  *   userinfo from apiRoot before logging
- * @returns {(args: {bot, chatId: string, threadId: (string|null), messageId: number, blocks: Array, sourceText: string}) => Promise<{result: *, wentRich: boolean}>}
+ * @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, phase?: string, mediaContext?: object, hadReplyAnchor?: boolean}) => Promise<{result: *, wentRich: boolean, bubbleRemoved?: boolean}>}
  */
 function createRichEditor({
   tg,
@@ -32,31 +106,79 @@ function createRichEditor({
   setRichKnownUnsupported = () => {},
   getApiRoot = () => null,
   stripUrlCreds = (s) => s,
+  makeInputFile = defaultMakeInputFile,
+  sanitizeFallbackText = (s) => s,
 } = {}) {
-  return async function richEditMessageText({ bot, chatId, threadId = null, messageId, blocks, sourceText }) {
+  async function rescueBestEffort({
+    mediaContext,
+    blocks,
+    options,
+    chatId,
+    threadId,
+  }) {
+    try {
+      await mediaContext.rescueBlocks(blocks, options);
+    } catch (err) {
+      // Text may already have landed, so a rescue failure must not escape
+      // into finalization and cause that text to be delivered again.
+      mediaContext.recordUnexpectedMediaFailure?.();
+      logEvent('rich-media-rescue-failed', {
+        chat_id: chatId, thread_id: threadId, bot: botName,
+        error_class: err?.name || 'Error',
+      });
+    }
+  }
+
+  return async function richEditMessageText({
+    bot,
+    chatId,
+    threadId = null,
+    messageId,
+    blocks,
+    sourceText,
+    phase = 'preview',
+    mediaContext = null,
+    hadReplyAnchor = false,
+  }) {
     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 };
     }
 
+    let fallbackKind = null;
     try {
       const res = await tg(bot, 'editMessageText', {
         chat_id: chatId,
         message_id: messageId,
-        rich_message: { blocks },
+        rich_message: {
+          blocks: materializeMediaBlocks(
+            blocks,
+            makeInputFile,
+            mediaContext?.preflightMedia,
+          ),
+        },
       }, { source: 'bot-reply-stream-edit-rich', botName, richSourceText: sourceText });
+      mediaContext?.learnRichResult?.(blocks, res);
       // 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.
       return { result: res, wentRich: true };
     } catch (err) {
-      if (isRichCapabilityError(err)) {
+      if (err?.code === MEDIA_SOURCE_CHANGED) {
+        fallbackKind = 'content-error';
+        logEvent('rich-content-fallback', {
+          chat_id: chatId, bot: botName,
+          error: 'media-source-changed',
+        });
+      } else if (isRichCapabilityError(err)) {
+        fallbackKind = 'capability';
         setRichKnownUnsupported();
         logEvent('rich-capability-latched', {
           chat_id: chatId, bot: botName,
@@ -64,6 +186,8 @@ function createRichEditor({
           error: redactBotToken(err.message)?.slice(0, 200),
         });
       } else if (isRichContentError(err)) {
+        fallbackKind = 'content-error';
+        mediaContext?.evictCachedBlocks?.(blocks);
         logEvent('rich-content-fallback', {
           chat_id: chatId, bot: botName,
           error: redactBotToken(err.message)?.slice(0, 200),
@@ -81,14 +205,50 @@ function createRichEditor({
         });
         throw err;
       }
-      // Preserve the same authored content and tell the streamer that the
-      // accepted payload is plain, so its delivery trackers stay accurate.
-      const fallbackRes = await tg(bot, 'editMessageText', {
-        chat_id: chatId, message_id: messageId, text: sourceText,
-      }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
-      return { result: fallbackRes, wentRich: false };
     }
+
+    const fallbackText = sanitizeFallbackText(sourceText);
+    const canRescue = fallbackKind === 'content-error'
+      && (phase === 'final' || phase === 'seal')
+      && mediaContext
+      && typeof mediaContext.rescueBlocks === 'function';
+
+    if (canRescue && !fallbackText.trim()) {
+      const bubbleRemoved = typeof mediaContext.deletePlaceholder === 'function'
+        ? await mediaContext.deletePlaceholder(messageId)
+        : false;
+      await rescueBestEffort({
+        mediaContext,
+        blocks,
+        options: {
+          trigger: 'content-error',
+          anchorFirst: bubbleRemoved && hadReplyAnchor,
+        },
+        chatId,
+        threadId,
+      });
+      return { result: null, wentRich: false, bubbleRemoved };
+    }
+
+    // Preserve the same authored content and tell the streamer that the
+    // accepted payload is plain, so its delivery trackers stay accurate.
+    // If this edit fails, no rescue has started and finalize remains the
+    // single owner of discard/redelivery.
+    const fallbackRes = await tg(bot, 'editMessageText', {
+      chat_id: chatId, message_id: messageId, text: fallbackText,
+    }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
+
+    if (canRescue) {
+      await rescueBestEffort({
+        mediaContext,
+        blocks,
+        options: { trigger: 'content-error' },
+        chatId,
+        threadId,
+      });
+    }
+    return { result: fallbackRes, wentRich: false };
   };
 }
 
-module.exports = { createRichEditor };
+module.exports = { createRichEditor, materializeMediaBlocks };