polygram 0.19.0 → 0.20.0

package/lib/telegram/rich.js

@@ -171,11 +171,11 @@ const SUMMARY_TAG_RE = /<summary[^>]*>([\s\S]*?)<\/summary>/i;
 const HTML_TAG_STRIP_RE = /<[^>]+>/g;
 const DEFAULT_DETAILS_SUMMARY = 'Details';
 
-// ─── Media (photo / collage / slideshow) ─────────────────────────────
+// ─── Media (photo / video / animation / wrappers) ────────────────────
 //
-// 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
+// Image markdown maps to typed Telegram media blocks after resolution;
+// <tg-collage>/<tg-slideshow> wrapper tags (Telegram's own rich-markdown
+// dialect) group supported media 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,
@@ -522,8 +522,8 @@ function blocksFromTokens(tokens) {
 // 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';
+  if (unavailable) return d.caption ? `${d.caption} (media unavailable)` : '(media unavailable)';
+  return d.caption ? `📎 ${d.caption}` : '📎 media';
 }
 
 // Depth-first, document-order collection of media descriptors across
@@ -546,13 +546,16 @@ function collectMediaDescriptors(blocks, list = []) {
   return list;
 }
 
-function photoBlockFrom(result, caption) {
-  const block = { type: 'photo', photo: { type: 'photo', media: result.media } };
+const MEDIA_BLOCK_KINDS = new Set(['photo', 'video', 'animation']);
+
+function mediaBlockFrom(result, caption) {
+  const kind = MEDIA_BLOCK_KINDS.has(result?.kind) ? result.kind : 'photo';
+  const block = { type: kind, [kind]: { type: kind, media: result.media } };
   if (caption) block.caption = { text: caption };
   return block;
 }
 
-// Replace descriptor blocks with real photo/collage/slideshow blocks
+// Replace descriptor blocks with real media/wrapper 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.
@@ -562,27 +565,30 @@ function substituteMediaBlocks(blocks, results, cursor = { i: 0 }) {
     if (b.type === '_media') {
       const r = results ? results[cursor.i] : null;
       cursor.i += 1;
-      if (r && r.media) out.push(photoBlockFrom(r, b.caption));
+      if (r && r.media) out.push(mediaBlockFrom(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)` });
+        out.push({ type: 'paragraph', text: `📎 ${b.kind} (${b.items.length} media items)` });
         continue;
       }
-      const photos = [];
+      const mediaBlocks = [];
       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));
+        if (r && r.media) mediaBlocks.push(mediaBlockFrom(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 (mediaBlocks.length === 1) out.push(mediaBlocks[0]);
+      else if (mediaBlocks.length > 1) out.push({ type: b.kind, blocks: mediaBlocks });
       if (unavailable > 0) {
-        out.push({ type: 'paragraph', text: `(${unavailable} image${unavailable === 1 ? '' : 's'} unavailable)` });
+        out.push({
+          type: 'paragraph',
+          text: `(${unavailable} media item${unavailable === 1 ? '' : 's'} unavailable)`,
+        });
       }
     } else if (Array.isArray(b.blocks) || Array.isArray(b.items)) {
       const clone = { ...b };
@@ -600,12 +606,12 @@ function substituteMediaBlocks(blocks, results, cursor = { i: 0 }) {
   return out;
 }
 
-// Count media attachments in an emitted block tree (photo blocks plus
-// collage/slideshow children) — the media_count instrumentation field.
+// Count media attachments in an emitted block tree, including wrapper
+// and container children — the media_count instrumentation field.
 function countMediaBlocks(blocks) {
   let n = 0;
   for (const b of blocks || []) {
-    if (b.type === 'photo') n += 1;
+    if (MEDIA_BLOCK_KINDS.has(b.type)) n += 1;
     else if (b.type === 'collage' || b.type === 'slideshow') n += countMediaBlocks(b.blocks);
     else {
       if (Array.isArray(b.blocks)) n += countMediaBlocks(b.blocks);
@@ -664,7 +670,8 @@ function stripMediaMarkdown(markdown) {
     clean = clean.replace(TRAILING_IMAGE_FRAGMENT_RE, '');
     out.push(clean);
   }
-  return out.join('\n');
+  const projected = out.join('\n');
+  return projected.trim() ? projected : '';
 }
 
 /**
@@ -681,11 +688,12 @@ function stripMediaMarkdown(markdown) {
  * 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
+ * index-aligned with the descriptors; each accepted result is
+ * `{ kind, media }`, where media is an https URL string or a JSON-safe
+ * `{ source, fingerprint, fileId? }` envelope that rich-edit.js validates
+ * before using a cached ID or materializing a grammy InputFile. Rejections
+ * carry `{ rejected }`. NEVER called in partial mode — streaming ticks
+ * must not touch the filesystem; media renders 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

package/lib/telegram/streamer.js

@@ -45,7 +45,7 @@ const DEFAULT_THROTTLE_MS = 1000;
 const THROTTLE_FLOOR_MS = 250;
 
 function createStreamer({
-  send,                                   // async (text) -> { message_id }
+  send,                    // async (text) -> { message_id, _hadReplyAnchor? }
   edit,                                   // async (msg_id, text) -> void
   deleteMessage = null,                   // async (msg_id) -> void  [optional]
   minChars = DEFAULT_MIN_CHARS,
@@ -87,13 +87,17 @@ function createStreamer({
   // Optional progressive rich-message rendering. A null callback keeps
   // the streamer on its plain-text path.
   //
-  // toRichPayload(text, { partial }) -> { blocks, usedRich } | null
+  // toRichPayload(text, { partial }) ->
+  //   { blocks, usedRich, rescueEntries? } | null
   //   Called on every flush/finalize with the CURRENT latestText/finalText
   //   (untruncated — rich content is never char-truncated with a "..."
   //   the way plain live-preview text is; partial:true tells it to hold
   //   back a possibly-incomplete trailing block, see lib/telegram/rich.js).
   //   usedRich:false (or a null return) means "not rich this tick" — the
   //   streamer falls through to the existing plain-text path unchanged.
+  //   Final media-bearing payloads include rescueEntries. The streamer
+  //   carries them into redelivery results and uses their presence to
+  //   decide whether a detached intermediate bubble needs sealing.
   //   The callback may return a different result on each call when live
   //   configuration or capability state changes.
   toRichPayload = null,
@@ -107,6 +111,7 @@ function createStreamer({
   throttleMs = Math.max(THROTTLE_FLOOR_MS, throttleMs);
   let state = 'idle';       // 'idle' | 'live' | 'finalized'
   let msgId = null;
+  let hadReplyAnchor = false;
   let currentText = '';     // what's on screen right now (truncated to maxLen) — plain-path only
   let currentRichJson = null; // JSON.stringify of the last-sent rich blocks, or null when not in rich mode
   let latestText = '';      // latest we've been told about
@@ -114,6 +119,8 @@ function createStreamer({
   let pendingEdit = null;   // timer id
   let flushPromise = null;  // serialized flush chain (for back-pressure)
   let flushQueued = false;  // latest text changed while a flush was active
+  let initialSendPromise = null; // active generation's initial send
+  let sealChain = Promise.resolve(); // detached bubbles, in boundary order
   let bubbleGeneration = 0; // invalidates state commits from superseded bubbles
   // 0.7.2: msg_ids of bubbles that have been superseded by
   // forceNewMessage(). The caller (polygram.js handleMessage at
@@ -175,21 +182,36 @@ function createStreamer({
     // delivered via the caller's normal path on finalize().
     if (state === 'idle') {
       if (text.length < minChars) return;
+      const generation = bubbleGeneration;
       state = 'live';
       currentText = truncateForLive(text);
+      let sendPromise;
       try {
-        const res = await send(currentText);
+        sendPromise = Promise.resolve(send(currentText));
+      } catch (err) {
+        sendPromise = Promise.reject(err);
+      }
+      initialSendPromise = sendPromise;
+      try {
+        const res = await sendPromise;
+        if (generation !== bubbleGeneration) return;
         msgId = res?.message_id ?? null;
+        hadReplyAnchor = res?._hadReplyAnchor === true;
         lastEditTs = clock();
         if (msgId == null) {
           // Caller failed to get a message_id — revert to idle; finalize
           // will fall through to normal send path.
           state = 'idle';
           msgId = null;
+          hadReplyAnchor = false;
         }
       } catch (err) {
+        if (generation !== bubbleGeneration) return;
         logger.error(`[stream] initial send failed: ${err.message}`);
         state = 'idle';
+        hadReplyAnchor = false;
+      } finally {
+        if (initialSendPromise === sendPromise) initialSendPromise = null;
       }
       return;
     }
@@ -210,9 +232,9 @@ function createStreamer({
   // Decide the rich-vs-plain payload for the CURRENT latestText/finalText.
   // Shared by flush() and finalize() so the "only attempt rich under the
   // rich char cap" guard and the upgrade-event firing live in one place.
-  function resolveRichPayload(text, { partial }) {
+  function resolveRichPayload(text, { partial, allowOverflow = false }) {
     if (!toRichPayload) return null;
-    if (text.length > richMaxLen) {
+    if (text.length > richMaxLen && !allowOverflow) {
       // Edge case, not fully engineered (documented limitation): a
       // mid-stream reply that's ALREADY past the rich cap while still
       // growing. Rather than flap into a truncated/ellipsis rich render
@@ -241,11 +263,15 @@ function createStreamer({
       return flushPromise;
     }
 
+    const generation = bubbleGeneration;
     const run = (async () => {
       do {
         flushQueued = false;
         await flushOnce();
-      } while (flushQueued && state === 'live' && msgId != null);
+      } while (flushQueued
+        && generation === bubbleGeneration
+        && state === 'live'
+        && msgId != null);
     })();
     flushPromise = run;
     try {
@@ -272,6 +298,7 @@ function createStreamer({
         // can render the same Markdown through the plain-text path.
         const editResult = await edit(editMsgId, {
           rich: true, blocks: richPayload.blocks, sourceText,
+          phase: 'preview', hadReplyAnchor,
         });
         if (generation !== bubbleGeneration || msgId !== editMsgId) return;
         // A rich editor can resolve successfully after sending the same
@@ -307,6 +334,62 @@ function createStreamer({
     }
   }
 
+  function appendSealJob(job, label = 'seal') {
+    const run = sealChain.then(job);
+    sealChain = run.catch((err) => {
+      const errorClass = err?.name || 'Error';
+      logger.error?.(`[stream] ${label} failed (${errorClass})`);
+    });
+    return sealChain;
+  }
+
+  async function drainSeals() {
+    while (true) {
+      const pending = sealChain;
+      await pending;
+      if (pending === sealChain) return;
+    }
+  }
+
+  async function awaitDetached(promise, label) {
+    try {
+      await promise;
+    } catch (err) {
+      logger.error?.(`[stream] ${label} failed (${err?.name || 'Error'})`);
+    }
+  }
+
+  async function sealBubble(snapshot) {
+    let targetMsgId = snapshot.msgId;
+    let targetHadReplyAnchor = snapshot.hadReplyAnchor;
+
+    if (snapshot.initialSendPromise) {
+      const res = await snapshot.initialSendPromise;
+      targetMsgId = res?.message_id ?? targetMsgId;
+      targetHadReplyAnchor = res?._hadReplyAnchor === true;
+    }
+    if (snapshot.flushPromise) {
+      await awaitDetached(snapshot.flushPromise, 'detached bubble flush');
+    }
+    if (targetMsgId == null || snapshot.sourceText.length > richMaxLen || !toRichPayload) return;
+
+    const payload = toRichPayload(snapshot.sourceText, { partial: false });
+    if (!payload?.usedRich || !Array.isArray(payload.rescueEntries)
+      || payload.rescueEntries.length === 0) {
+      return;
+    }
+    const json = JSON.stringify(payload.blocks);
+    if (json === snapshot.currentRichJson) return;
+
+    await edit(targetMsgId, {
+      rich: true,
+      blocks: payload.blocks,
+      sourceText: snapshot.sourceText,
+      phase: 'seal',
+      hadReplyAnchor: targetHadReplyAnchor,
+    });
+  }
+
   // 0.7.0: explicitly drain any pending edit. Useful when the caller
   // is about to make a finalize/discard decision and wants the bubble's
   // visual state to be accurate (no stale half-rendered text under a
@@ -314,6 +397,7 @@ function createStreamer({
   async function flushDraft() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; await flush(); }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
   }
 
   // Reset bubble state so the next onChunk creates a NEW message.
@@ -330,18 +414,29 @@ function createStreamer({
   // rc.44 reverts to the 0.7.0 preserve-all default. Opt back into
   // the 0.7.2 behaviour with `preserveIntermediateBubbles: false`.
   //
-  // When preserving, we still cancel the pending throttled edit (it
-  // wouldn't fire after we transition to a new bubble anyway) but
-  // there may be a recently-flushed edit in flight whose result we
-  // don't await — the bubble will display whatever its last
-  // successful edit landed, which is typically very close to the
-  // segment's final text (throttle is 250ms; segments take seconds).
+  // The old bubble is detached synchronously. Preserved bubbles enqueue
+  // one final media-aware edit behind any request already targeting that
+  // message; terse bubbles retain late initial-send ids for cleanup.
   function forceNewMessage() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
-    if (msgId != null && !preserveIntermediateBubbles) {
-      archived.push(msgId);
-    }
+    const snapshot = {
+      sourceText: latestText,
+      msgId,
+      hadReplyAnchor,
+      currentRichJson,
+      initialSendPromise,
+      flushPromise,
+    };
+    const hadOutgoingMessage = state === 'live'
+      && (snapshot.msgId != null || snapshot.initialSendPromise != null);
+
+    // Detach in-flight work before resetting. Conditional identity checks
+    // in onChunk()/flush() keep old completions from clearing new promises
+    // or committing state into the next generation.
+    initialSendPromise = null;
+    flushPromise = null;
     msgId = null;
+    hadReplyAnchor = false;
     currentText = '';
     currentRichJson = null; // new bubble starts plain — see toRichPayload doc
     latestText = '';
@@ -349,6 +444,27 @@ function createStreamer({
     lastEditTs = 0;
     flushQueued = false;
     bubbleGeneration += 1;
+
+    if (!hadOutgoingMessage) return;
+
+    if (preserveIntermediateBubbles) {
+      appendSealJob(() => sealBubble(snapshot));
+      return;
+    }
+
+    if (snapshot.msgId != null) archived.push(snapshot.msgId);
+    if (snapshot.initialSendPromise || snapshot.flushPromise) {
+      appendSealJob(async () => {
+        if (snapshot.initialSendPromise) {
+          const res = await snapshot.initialSendPromise;
+          const lateMsgId = res?.message_id ?? null;
+          if (lateMsgId != null) archived.push(lateMsgId);
+        }
+        if (snapshot.flushPromise) {
+          await awaitDetached(snapshot.flushPromise, 'detached bubble cleanup flush');
+        }
+      }, 'detached bubble cleanup');
+    }
   }
 
   // 0.7.0: delete the current bubble via the injected deleteMessage
@@ -365,6 +481,7 @@ function createStreamer({
   async function discard() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
     const idToDelete = msgId;
     state = 'finalized';
     msgId = null;
@@ -399,6 +516,7 @@ function createStreamer({
     if (state === 'finalized') return { streamed: false, msgId, finalEditOk: false, overflow: false };
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
 
     if (state === 'idle') {
       state = 'finalized';
@@ -414,15 +532,20 @@ function createStreamer({
     // apples-to-apples (currentText was already transformed in onChunk).
     let body = applyTransform(finalText ?? latestText);
     if (errorSuffix) body = `${body}\n\n⚠️ ${errorSuffix}`;
+    const finalHadReplyAnchor = hadReplyAnchor;
 
     // Finalization evaluates the complete body, so no trailing block is
     // held back as potentially incomplete.
-    const richPayload = resolveRichPayload(body, { partial: false });
+    const richPayload = resolveRichPayload(body, { partial: false, allowOverflow: true });
     if (richPayload) {
       // Rich finalization uses the rich-message cap; applying the smaller
       // plain-message cap would unnecessarily redeliver valid rich bodies.
       if (body.length > richMaxLen) {
-        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true };
+        return {
+          streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true,
+          rescueEntries: richPayload.rescueEntries || [],
+          hadReplyAnchor: finalHadReplyAnchor,
+        };
       }
       const json = JSON.stringify(richPayload.blocks);
       if (json === currentRichJson) {
@@ -430,7 +553,10 @@ function createStreamer({
       }
       const wasRich = currentRichJson !== null;
       try {
-        const editResult = await edit(msgId, { rich: true, blocks: richPayload.blocks, sourceText: body });
+        const editResult = await edit(msgId, {
+          rich: true, blocks: richPayload.blocks, sourceText: body,
+          phase: 'final', hadReplyAnchor: finalHadReplyAnchor,
+        });
         // A fallback still delivered the final content, but as plain text.
         const wentRich = editResult == null || editResult.wentRich !== false;
         if (wentRich) {
@@ -440,10 +566,20 @@ function createStreamer({
           currentText = body;
           currentRichJson = null;
         }
+        if (editResult?.bubbleRemoved) {
+          msgId = null;
+          currentText = '';
+          currentRichJson = null;
+          hadReplyAnchor = false;
+        }
         return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
       } catch (err) {
         logger.error(`[stream] final rich edit failed: ${err.message}`);
-        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false };
+        return {
+          streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false,
+          rescueEntries: richPayload.rescueEntries || [],
+          hadReplyAnchor: finalHadReplyAnchor,
+        };
       }
     }
 
@@ -485,6 +621,7 @@ function createStreamer({
     finalize,
     flushDraft,
     forceNewMessage,
+    drainSeals,
     discard,
     archive,
     getArchived,

package/package.json

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