polygram 0.6.16 → 0.7.1

package/lib/stream-reply.js

@@ -1,15 +1,31 @@
 /**
  * Live streaming-reply state machine for a single turn.
  *
- * Lifecycle per turn:
+ * Lifecycle:
  *   idle  -> (text >= minChars) -> live
  *   live  -> (subsequent chunks) -> live       (throttled edits)
- *   idle|live -> finalize(finalText) -> done
+ *   live  -> flushDraft()         -> live      (drains pending edit)
+ *   live  -> forceNewMessage()    -> idle      (next chunk = new bubble)
+ *   live  -> discard()            -> finalized (bubble deleted)
+ *   any   -> finalize(finalText)  -> finalized
  *
  * The streamer never talks to Telegram directly — callers inject
- * `send(text)` (returns {message_id}) and `edit(msg_id, text)`. That keeps
- * polygram.js in charge of transcript writes, sticker/reaction routing, and
- * error handling; this module is just a cadence machine.
+ * `send(text)`, `edit(msg_id, text)`, and (optional) `deleteMessage(msg_id)`.
+ * That keeps polygram.js in charge of transcript writes, sticker/reaction
+ * routing, and error handling; this module is just a cadence machine.
+ *
+ * `finalize()` returns a rich result so the caller can decide whether the
+ * preview's last edit IS the final reply, or whether to discard the
+ * preview and redeliver via deliverReplies (overflow / final edit failed):
+ *
+ *   { kind: implicit, see flags below }
+ *   { streamed: false }                                  — never went live
+ *   { streamed: true, finalEditOk: true }                — preview = final
+ *   { streamed: true, finalEditOk: false, overflow: true } — body too long
+ *   { streamed: true, finalEditOk: false, overflow: false } — edit failed
+ *
+ * Short replies preview-becomes-final (no flicker, single bubble); long
+ * replies preview-deleted-redelivered (chunks land at chat bottom).
  *
  * Test-friendly: inject `clock` (now() fn) and `schedule` (setTimeout-like)
  * so a fake clock can drive throttle timing deterministically.
@@ -25,6 +41,7 @@ const DEFAULT_THROTTLE_MS = 1000;
 function createStreamer({
   send,                                   // async (text) -> { message_id }
   edit,                                   // async (msg_id, text) -> void
+  deleteMessage = null,                   // async (msg_id) -> void  [optional]
   minChars = DEFAULT_MIN_CHARS,
   throttleMs = DEFAULT_THROTTLE_MS,
   maxLen = 4096,
@@ -41,7 +58,12 @@ function createStreamer({
   let pendingEdit = null;   // timer id
   let flushPromise = null;  // ongoing edit promise (for back-pressure)
 
-  function truncate(s) {
+  // LIVE-EDIT truncation only — used during streaming when latestText
+  // overshoots maxLen. The trailing "..." signals to the user that more
+  // is coming. Finalize doesn't truncate: overflow is handled by
+  // signalling the caller to discard-and-redeliver via chunkMarkdownText,
+  // which preserves all content without any byte-cut.
+  function truncateForLive(s) {
     if (s.length <= maxLen) return s;
     return s.slice(0, maxLen - 3) + '...';
   }
@@ -56,7 +78,7 @@ function createStreamer({
     if (state === 'idle') {
       if (text.length < minChars) return;
       state = 'live';
-      currentText = truncate(text);
+      currentText = truncateForLive(text);
       try {
         const res = await send(currentText);
         msgId = res?.message_id ?? null;
@@ -90,7 +112,7 @@ function createStreamer({
   async function flush() {
     pendingEdit = null;
     if (state !== 'live' || msgId == null) return;
-    const next = truncate(latestText);
+    const next = truncateForLive(latestText);
     if (next === currentText) return;
     lastEditTs = clock();
     currentText = next;
@@ -98,38 +120,132 @@ function createStreamer({
       flushPromise = edit(msgId, currentText);
       await flushPromise;
     } catch (err) {
-      // Non-fatal — maybe 429. Log and keep going; next chunk will retry.
+      // Non-fatal — maybe 429 or transient. Log and keep going; next
+      // chunk will retry. The HTML→plain fallback in lib/telegram.js
+      // already handles the most common cause (parse error from
+      // truncate cutting mid-tag).
       logger.error(`[stream] edit failed: ${err.message}`);
     } finally {
       flushPromise = null;
     }
   }
 
+  // 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
+  // pending timer).
+  async function flushDraft() {
+    if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; await flush(); }
+    if (flushPromise) { try { await flushPromise; } catch {} }
+  }
+
+  // Reset bubble state so the next onChunk creates a NEW message.
+  // Used by `onAssistantMessageStart` in process-manager.js when Claude
+  // emits a new top-level assistant message mid-turn (post tool-result):
+  // we want it in its own bubble below the previous one, not appended
+  // via editMessageText to the original.
+  function forceNewMessage() {
+    if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
+    // Don't await flushPromise — the caller has decided to start a new
+    // message; whatever the old bubble shows is "done".
+    msgId = null;
+    currentText = '';
+    latestText = '';
+    state = 'idle';
+    lastEditTs = 0;
+  }
+
+  // 0.7.0: delete the current bubble via the injected deleteMessage
+  // callback. Used when the final reply overflows the preview's single-
+  // message capacity, so handleMessage will discard the preview and
+  // redeliver via deliverReplies (chunks land at chat bottom).
+  //
+  // Works whether state is 'live' OR 'finalized' — handleMessage's
+  // typical flow is finalize() → finalEditOk false → discard. The
+  // bubble's msgId is preserved through finalize so we can still
+  // delete it. If deleteMessage isn't provided, we just transition
+  // state without touching Telegram — the bubble stays at its last
+  // edited content, becoming a vestigial "head" of the conversation.
+  async function discard() {
+    if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
+    if (flushPromise) { try { await flushPromise; } catch {} }
+    const idToDelete = msgId;
+    state = 'finalized';
+    msgId = null;
+    let deleted = false;
+    if (idToDelete && typeof deleteMessage === 'function') {
+      try {
+        await deleteMessage(idToDelete);
+        deleted = true;
+      } catch (err) {
+        // Telegram rejects deletions of messages older than 48h or
+        // already-deleted ones. Non-fatal — the redelivery happens
+        // either way.
+        logger.warn?.(`[stream] discard deleteMessage failed: ${err.message}`);
+      }
+    }
+    return { msgId: idToDelete, deleted };
+  }
+
+  // 0.7.0: snapshot for callers that want to track the bubble's id
+  // for later cleanup (e.g. archive a superseded preview when
+  // forceNewMessage was called and the previous bubble should be
+  // deleted at end-of-turn).
+  function archive() {
+    return { msgId, currentText };
+  }
+
+  // 0.7.0: rich result. `finalEditOk` tells caller whether the preview
+  // can stand as the final reply (true) or needs to be replaced via
+  // discard + deliverReplies (false). `overflow` is the one specific
+  // reason: body wouldn't fit in a single Telegram message.
   async function finalize(finalText, { errorSuffix = null } = {}) {
-    if (state === 'finalized') return { streamed: false, msgId };
+    if (state === 'finalized') return { streamed: false, msgId, finalEditOk: false, overflow: false };
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
     if (flushPromise) { try { await flushPromise; } catch {} }
 
     if (state === 'idle') {
       state = 'finalized';
-      return { streamed: false, msgId: null };
+      return { streamed: false, msgId: null, finalEditOk: false, overflow: false };
     }
 
-    // live → finalize: one last edit with the full answer.
+    // live → finalize.
     state = 'finalized';
     let body = finalText ?? latestText;
     if (errorSuffix) body = `${body}\n\n⚠️ ${errorSuffix}`;
-    const next = truncate(body);
-    if (next !== currentText) {
-      try { await edit(msgId, next); currentText = next; }
-      catch (err) { logger.error(`[stream] final edit failed: ${err.message}`); }
+
+    // If body overflows the single-message cap, the caller needs to
+    // discard this bubble and redeliver via chunks. Don't try to edit.
+    if (body.length > maxLen) {
+      return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true };
+    }
+
+    // Body fits. Try one last edit to bring the bubble to the final
+    // text. If that succeeds, preview-IS-final and caller can return
+    // without redelivering. If it fails (e.g. parse error after our
+    // wrapper exhausts its retry, or a 5xx), caller should discard
+    // and redeliver — the bubble's content is unreliable.
+    if (body === currentText) {
+      // Already correct — no edit needed.
+      return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
+    }
+    try {
+      await edit(msgId, body);
+      currentText = body;
+      return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
+    } catch (err) {
+      logger.error(`[stream] final edit failed: ${err.message}`);
+      return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false };
     }
-    return { streamed: true, msgId, finalText: next };
   }
 
   return {
     onChunk,
     finalize,
+    flushDraft,
+    forceNewMessage,
+    discard,
+    archive,
     // Introspection for tests:
     get state() { return state; },
     get msgId() { return msgId; },

package/lib/telegram-chunk.js

@@ -0,0 +1,288 @@
+/**
+ * Markdown-aware chunking for Telegram-bound replies.
+ *
+ * Direct port of OpenClaw's chunkMarkdownText. The naive byte-cut
+ * chunker we shipped before this would land boundaries mid-word and
+ * mid-HTML-tag, which Telegram's parse_mode=HTML rejected with
+ * `400 can't parse entities` — bubbles froze and content got dropped.
+ *
+ * Guarantees:
+ *
+ *   1. No chunk exceeds `limit`.
+ *   2. Breaks prefer newlines over whitespace over hard-cut.
+ *   3. Code fences (```...```) are never broken silently — if a chunk
+ *      would land inside a fence, we close it on chunk N and re-open
+ *      with the same marker + language on chunk N+1, so each chunk is
+ *      independently parseable.
+ *   4. Parenthesised expressions `(...)` aren't broken at whitespace
+ *      inside the parens (avoids splitting markdown-link syntax like
+ *      `[label](http://example.com/...)`).
+ *
+ * Plain `chunkText` (no fence handling) is exported for callers that
+ * already know the input has no markdown — primarily code paths
+ * handling raw user input echoes or non-text payloads.
+ */
+
+// ─── Code-fence span detection ──────────────────────────────────────
+
+// Scan `buffer` for ```...``` and ~~~...~~~ fences. Returns the span list
+// of matched (open, close) pairs. An unclosed open fence at end-of-input
+// is treated as if it closes at end (so the chunker can still split inside
+// safely).
+function parseFenceSpans(buffer) {
+  const spans = [];
+  let open;
+  let offset = 0;
+  while (offset <= buffer.length) {
+    const nextNewline = buffer.indexOf('\n', offset);
+    const lineEnd = nextNewline === -1 ? buffer.length : nextNewline;
+    const line = buffer.slice(offset, lineEnd);
+    // Fence opens/closes start with up to 3 spaces of indent then 3+ of
+    // ` or ~. The "info string" after the marker (language hint) doesn't
+    // affect span boundaries.
+    const match = line.match(/^( {0,3})(`{3,}|~{3,})(.*)$/);
+    if (match) {
+      const indent = match[1];
+      const marker = match[2];
+      const markerChar = marker[0];
+      const markerLen = marker.length;
+      if (!open) {
+        open = { start: offset, markerChar, markerLen, openLine: line, marker, indent };
+      } else if (open.markerChar === markerChar && markerLen >= open.markerLen) {
+        // Closing fence must use the SAME char and at least as many of them.
+        // Different-char or shorter sequences are part of the body.
+        spans.push({
+          start: open.start, end: lineEnd,
+          openLine: open.openLine, marker: open.marker, indent: open.indent,
+        });
+        open = undefined;
+      }
+    }
+    if (nextNewline === -1) break;
+    offset = nextNewline + 1;
+  }
+  if (open) {
+    // Unclosed at EOF — treat as spanning to end so a later break-point
+    // inside knows it's "in fence".
+    spans.push({
+      start: open.start, end: buffer.length,
+      openLine: open.openLine, marker: open.marker, indent: open.indent,
+    });
+  }
+  return spans;
+}
+
+function findFenceSpanAt(spans, index) {
+  // Strict inequality: a break at exactly span.start is just before the
+  // opening fence (safe). At span.end, just after the close (also safe).
+  return spans.find((span) => index > span.start && index < span.end);
+}
+
+function isSafeFenceBreak(spans, index) {
+  return !findFenceSpanAt(spans, index);
+}
+
+// ─── Paren-aware break-point scan ───────────────────────────────────
+
+// Find the last newline / last whitespace in `window` that's NOT inside
+// `(...)` parens. Used by both plain and markdown chunkers.
+//
+// `isAllowed(i)` is consulted before every candidate — passed by the
+// markdown chunker to skip break points inside fence spans.
+function scanParenAwareBreakpoints(window, isAllowed = () => true) {
+  let lastNewline = -1;
+  let lastWhitespace = -1;
+  let depth = 0;
+  for (let i = 0; i < window.length; i++) {
+    if (!isAllowed(i)) continue;
+    const char = window[i];
+    if (char === '(') { depth += 1; continue; }
+    if (char === ')' && depth > 0) { depth -= 1; continue; }
+    if (depth !== 0) continue;
+    if (char === '\n') lastNewline = i;
+    else if (/\s/.test(char)) lastWhitespace = i;
+  }
+  return { lastNewline, lastWhitespace };
+}
+
+// ─── Chunkers ────────────────────────────────────────────────────────
+
+// Common early-out: empty / fits-in-one returns directly so the loop
+// bodies can assume there's real work to do. `limit ≤ 0` is treated as
+// a programmer error and throws — silently returning [text] would let
+// a misread config pass through a body that exceeds Telegram's actual
+// 4096-char cap, which the chunker exists to prevent.
+function resolveChunkEarlyReturn(text, limit) {
+  if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) {
+    throw new RangeError(`chunk limit must be a positive number; got ${limit}`);
+  }
+  if (text == null || text === '') return [];
+  if (typeof text !== 'string') {
+    throw new TypeError(`chunk text must be a string; got ${typeof text}`);
+  }
+  if (text.length <= limit) return [text];
+  return undefined;
+}
+
+// Generic break-resolver loop shared with markdown variant. The resolver
+// receives a `window` (text.slice(0, limit)) and returns where to break.
+// Negative / out-of-range break indices fall back to hard-cut at limit.
+function chunkTextByBreakResolver(text, limit, resolveBreakIndex) {
+  if (!text) return [];
+  if (text.length <= limit) return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > limit) {
+    const candidateBreak = resolveBreakIndex(remaining.slice(0, limit));
+    const breakIdx = Number.isFinite(candidateBreak) && candidateBreak > 0 && candidateBreak <= limit
+      ? candidateBreak
+      : limit;
+    const chunk = remaining.slice(0, breakIdx).trimEnd();
+    if (chunk.length > 0) chunks.push(chunk);
+    // If we broke on a separator (whitespace), consume it — don't carry it
+    // to the start of the next chunk where it'd just be trimmed anyway.
+    const brokeOnSeparator = breakIdx < remaining.length && /\s/.test(remaining[breakIdx]);
+    const nextStart = Math.min(remaining.length, breakIdx + (brokeOnSeparator ? 1 : 0));
+    remaining = remaining.slice(nextStart).trimStart();
+  }
+  if (remaining.length) chunks.push(remaining);
+  return chunks;
+}
+
+// Plain-text chunker: respects parens but ignores fences. Cheaper than
+// chunkMarkdownText when caller knows the input has no code blocks.
+function chunkText(text, limit) {
+  const early = resolveChunkEarlyReturn(text, limit);
+  if (early !== undefined) return early;
+  return chunkTextByBreakResolver(text, limit, (window) => {
+    const { lastNewline, lastWhitespace } = scanParenAwareBreakpoints(window);
+    return lastNewline > 0 ? lastNewline : lastWhitespace;
+  });
+}
+
+// Strip leading newlines from the remainder after a chunk break — they
+// would otherwise show up as blank lines at the top of the next bubble.
+function stripLeadingNewlines(value) {
+  let i = 0;
+  while (i < value.length && value[i] === '\n') i++;
+  return i > 0 ? value.slice(i) : value;
+}
+
+// Inside a code-fence, prefer the last newline (line boundary) — but only
+// inside the safe break region. Falls back to whitespace, then hard-cut.
+function pickSafeBreakIndex(window, spans) {
+  const { lastNewline, lastWhitespace } = scanParenAwareBreakpoints(
+    window,
+    (index) => isSafeFenceBreak(spans, index),
+  );
+  if (lastNewline > 0) return lastNewline;
+  if (lastWhitespace > 0) return lastWhitespace;
+  return -1;
+}
+
+// Markdown-aware chunker. The whole point of 0.7.0 over the previous
+// `lastIndexOf('\n', maxLen)` chunker.
+//
+// Flow per iteration:
+//   1. Parse fence spans of the remainder.
+//   2. Pick the best (newline > whitespace) break inside `[0..limit]`
+//      that's NOT inside a fence. Fall back to hard-cut at limit.
+//   3. If the break did land inside a fence (no safe alternative was
+//      reachable), search backwards for a newline within the fence body
+//      that still fits with a closing-fence appended; if found, split
+//      the fence — close it on this chunk and reopen with the same
+//      marker+language on the next.
+//   4. Append the chunk; advance `remaining` past the break + the
+//      reopened fence header (if any).
+function chunkMarkdownText(text, limit) {
+  const early = resolveChunkEarlyReturn(text, limit);
+  if (early !== undefined) return early;
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > limit) {
+    const spans = parseFenceSpans(remaining);
+    const softBreak = pickSafeBreakIndex(remaining.slice(0, limit), spans);
+    let breakIdx = softBreak > 0 ? softBreak : limit;
+    const initialFence = isSafeFenceBreak(spans, breakIdx) ? undefined : findFenceSpanAt(spans, breakIdx);
+    let fenceToSplit = initialFence;
+    if (initialFence) {
+      // The break landed inside a fence. We may still split the fence,
+      // but only if there's room for a closing line within the limit.
+      const closeLine = `${initialFence.indent}${initialFence.marker}`;
+      const maxIdxIfNeedNewline = limit - (closeLine.length + 1); // need a \n separator
+      if (maxIdxIfNeedNewline <= 0) {
+        // Even the close line wouldn't fit — give up and hard-cut.
+        // Caller will see a malformed chunk, but that's a degenerate
+        // input case (limit smaller than the close marker).
+        fenceToSplit = undefined;
+        breakIdx = limit;
+      } else {
+        // Look for a newline inside the fence body that's late enough
+        // to make progress (past the open line + at least one body line)
+        // and early enough that close line fits.
+        const minProgressIdx = Math.min(
+          remaining.length,
+          initialFence.start + initialFence.openLine.length + 2,
+        );
+        const maxIdxIfAlreadyNewline = limit - closeLine.length;
+        let pickedNewline = false;
+        let lastNewline = remaining.lastIndexOf('\n', Math.max(0, maxIdxIfAlreadyNewline - 1));
+        while (lastNewline !== -1) {
+          const candidateBreak = lastNewline + 1;
+          if (candidateBreak < minProgressIdx) break;
+          const candidateFence = findFenceSpanAt(spans, candidateBreak);
+          if (candidateFence && candidateFence.start === initialFence.start) {
+            breakIdx = Math.max(1, candidateBreak);
+            pickedNewline = true;
+            break;
+          }
+          lastNewline = remaining.lastIndexOf('\n', lastNewline - 1);
+        }
+        if (!pickedNewline) {
+          if (minProgressIdx > maxIdxIfAlreadyNewline) {
+            // No safe in-fence newline found and no room to add one —
+            // give up on splitting this fence; hard-cut at limit.
+            fenceToSplit = undefined;
+            breakIdx = limit;
+          } else {
+            // Force the break; chunker will append a synthetic newline
+            // before the close line.
+            breakIdx = Math.max(minProgressIdx, maxIdxIfNeedNewline);
+          }
+        }
+      }
+      // Re-check the break: if our adjusted index is no longer inside
+      // the same fence, don't try to split it.
+      const fenceAtBreak = findFenceSpanAt(spans, breakIdx);
+      fenceToSplit = fenceAtBreak && fenceAtBreak.start === initialFence.start ? fenceAtBreak : undefined;
+    }
+    let rawChunk = remaining.slice(0, breakIdx);
+    if (!rawChunk) break;
+    const brokeOnSeparator = breakIdx < remaining.length && /\s/.test(remaining[breakIdx]);
+    const nextStart = Math.min(remaining.length, breakIdx + (brokeOnSeparator ? 1 : 0));
+    let next = remaining.slice(nextStart);
+    if (fenceToSplit) {
+      // Close the fence on this chunk; reopen with the same marker line
+      // (preserving language hint) on the next.
+      const closeLine = `${fenceToSplit.indent}${fenceToSplit.marker}`;
+      rawChunk = rawChunk.endsWith('\n') ? `${rawChunk}${closeLine}` : `${rawChunk}\n${closeLine}`;
+      next = `${fenceToSplit.openLine}\n${next}`;
+    } else {
+      // Strip stray leading newlines on the next chunk so it doesn't
+      // open with blank lines.
+      next = stripLeadingNewlines(next);
+    }
+    chunks.push(rawChunk);
+    remaining = next;
+  }
+  if (remaining.length) chunks.push(remaining);
+  return chunks;
+}
+
+module.exports = {
+  chunkText,
+  chunkMarkdownText,
+  // Internals exported for tests; not part of the stable API.
+  parseFenceSpans,
+  scanParenAwareBreakpoints,
+};

package/lib/telegram-format.js

@@ -272,4 +272,110 @@ function toTelegramHtml(text) {
 
 function toTelegramMarkdown(text) { return toTelegramHtml(text); }
 
-module.exports = { toTelegramMarkdown, toTelegramHtml, wrapFileReferencesInHtml, escapeHtml };
+// 0.7.0 (Phase K) audit note: polygram's `toTelegramHtml` is functionally
+// aligned with OpenClaw's `markdownToTelegramHtml` + `renderTelegramHtmlText`
+// (extensions/telegram, send.ts:828-898). Both produce parse_mode=HTML
+// output, both run `wrapFileReferencesInHtml` as a post-processor, and
+// both handle the same set of formatting features (bold, italic, code,
+// pre/fence, links, lists, spoilers, blockquotes, tables).
+//
+// OpenClaw uses an internal markdown-IR (markdownToIR → renderTelegramHtml);
+// polygram uses `marked` + custom renderers. Both work; the IR approach
+// is more amenable to multi-output (HTML / plain / Slack), but polygram
+// only needs HTML so the regex-based path is simpler.
+//
+// The HTML→plain fallback shipped in 0.7.0 phase 2 makes converter
+// correctness less load-bearing: if any edge case slips through and
+// Telegram rejects the HTML, we automatically retry as plain text and
+// no content is lost.
+
+// ─── Telegram error classification ──────────────────────────────────
+
+// Ported from OpenClaw (`send-DVX_zY9w.js:1075-1077`). HTML parse errors
+// fire when our markdown→HTML conversion produces malformed output (e.g.
+// the streamer's truncate cut mid-tag pre-0.7.0). Caller reacts by
+// retrying the same call as plain text without parse_mode.
+const HTML_PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;
+
+// 'message is not modified' fires when an editMessageText payload
+// matches the current message text exactly. Not a real failure — the
+// streamer's debounced edit just happened to land on a no-op. Swallow
+// to keep error logs clean. The phrase is unique enough that we don't
+// need to guard with a 400 prefix (grammy strips the status code in
+// some error shapes).
+const MESSAGE_NOT_MODIFIED_RE = /message is not modified|MESSAGE_NOT_MODIFIED/i;
+
+// grammy attaches the underlying API error in different shapes
+// depending on transport. Walk the candidates and pick the first
+// stringifiable message.
+function errorMessage(err) {
+  if (!err) return '';
+  return String(err.description || err.message || err.error_message || err);
+}
+
+function isHtmlParseError(err) {
+  return HTML_PARSE_ERR_RE.test(errorMessage(err));
+}
+
+function isMessageNotModifiedError(err) {
+  return MESSAGE_NOT_MODIFIED_RE.test(errorMessage(err));
+}
+
+// 0.7.0 (Phase G): 429 rate-limit detection + retry_after extraction.
+// Telegram returns "Too Many Requests: retry after N" (HTTP 429) when the
+// per-bot rate limit is hit (~30 req/s). N is in seconds. grammy attaches
+// retry_after as `err.parameters.retry_after` in some shapes; otherwise
+// we parse it out of the message string.
+const RATE_LIMIT_RE = /too many requests|429|retry after (\d+)/i;
+
+function isRateLimitError(err) {
+  if (!err) return false;
+  return RATE_LIMIT_RE.test(errorMessage(err));
+}
+
+// Returns retry_after in milliseconds, or null if not a 429 / not parseable.
+function getRetryAfterMs(err) {
+  if (!err) return null;
+  // grammy / Telegram Bot API: err.parameters.retry_after (seconds)
+  const fromParams = err.parameters?.retry_after ?? err.error_parameters?.retry_after;
+  if (typeof fromParams === 'number' && Number.isFinite(fromParams)) {
+    return Math.max(0, fromParams * 1000);
+  }
+  // Fall back to parsing the message: "retry after 5" / "retry after 12 seconds"
+  const m = errorMessage(err).match(/retry after (\d+)/i);
+  if (m) return Math.max(0, parseInt(m[1], 10) * 1000);
+  return null;
+}
+
+// ─── Caption length policy ──────────────────────────────────────────
+
+// Telegram caps captions on sendPhoto / sendVideo / sendAudio /
+// sendDocument at 1024 chars (vs 4096 for sendMessage). When a caption
+// would exceed this, OpenClaw's choice is to send the media WITHOUT a
+// caption and follow up with the text as a separate sendMessage. This
+// is simpler than splitting mid-caption (which would visually fragment
+// the description across the media bubble and a follow-up). Reused
+// here for any future skill that wants to send media with rich text.
+const TELEGRAM_MAX_CAPTION_LENGTH = 1024;
+
+function splitTelegramCaption(text) {
+  const trimmed = (text || '').trim();
+  if (!trimmed) return { caption: undefined, followUpText: undefined };
+  if (trimmed.length > TELEGRAM_MAX_CAPTION_LENGTH) {
+    return { caption: undefined, followUpText: trimmed };
+  }
+  return { caption: trimmed, followUpText: undefined };
+}
+
+module.exports = {
+  toTelegramMarkdown,
+  toTelegramHtml,
+  wrapFileReferencesInHtml,
+  escapeHtml,
+  isHtmlParseError,
+  isMessageNotModifiedError,
+  splitTelegramCaption,
+  TELEGRAM_MAX_CAPTION_LENGTH,
+  isRateLimitError,
+  getRetryAfterMs,
+};