polygram 0.19.0 → 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.19.0",
+  "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/telegram/display-hint.js

@@ -95,9 +95,9 @@ 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.',
+  '**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 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.',
+  '**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.',
   '',

package/lib/telegram/rich-edit.js

@@ -4,12 +4,12 @@
  * 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,
+ * `{ 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).
- * 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.
+ * 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.
  */
@@ -18,25 +18,48 @@
 
 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) {
+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) => {
-    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) } };
+    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) };
+      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) }
+          ? { ...it, blocks: materializeMediaBlocks(it.blocks, makeInputFile, preflightMedia) }
           : it)),
       };
     }
@@ -70,7 +93,7 @@ function defaultMakeInputFile(source) {
  * @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}>}
+ * @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,
@@ -86,7 +109,37 @@ function createRichEditor({
   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: sanitizeFallbackText(sourceText),
@@ -94,12 +147,20 @@ function createRichEditor({
       return { result: res, wentRich: false };
     }
 
+    let fallbackKind = null;
     try {
       const res = await tg(bot, 'editMessageText', {
         chat_id: chatId,
         message_id: messageId,
-        rich_message: { blocks: materializeMediaBlocks(blocks, makeInputFile) },
+        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,
@@ -110,7 +171,14 @@ function createRichEditor({
       // 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,
@@ -118,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),
@@ -135,13 +205,49 @@ 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: sanitizeFallbackText(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 };
   };
 }