polygram 0.4.1 → 0.4.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.4.1",
+  "version": "0.4.6",
   "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 and a history skill.",
   "keywords": [
     "telegram",

package/lib/media-group-buffer.js

@@ -0,0 +1,73 @@
+/**
+ * Buffer Telegram messages that share a `media_group_id` so they can be
+ * dispatched as ONE logical turn to Claude.
+ *
+ * Why: when a user uploads N photos "in one message," Telegram delivers N
+ * distinct Message updates (one per photo, all tagged with the same
+ * `media_group_id`). Without this buffer, polygram sees each photo as a
+ * separate turn — Claude answers the first and the others either queue
+ * behind it (consuming warm-process capacity) or fire their own turns
+ * with no text.
+ *
+ * Pattern (matches OpenClaw's `MEDIA_GROUP_TIMEOUT_MS`):
+ *   - Messages arriving faster than `flushMs` apart stay in the same
+ *     group; timer resets on each arrival.
+ *   - Group flushes `flushMs` after the LAST sibling arrives.
+ *   - Stragglers arriving after a flush create a new group (new turn).
+ *     Telegram usually ships all siblings within ~100ms, so 500ms of
+ *     headroom catches virtually everything.
+ *
+ * I/O-pure: accepts `timerFn`/`clearTimerFn` for test injection.
+ */
+
+const DEFAULT_FLUSH_MS = 500;
+
+function createMediaGroupBuffer({
+  flushMs = DEFAULT_FLUSH_MS,
+  onFlush,
+  timerFn = setTimeout,
+  clearTimerFn = clearTimeout,
+} = {}) {
+  if (typeof onFlush !== 'function') throw new Error('onFlush required');
+  const entries = new Map(); // key → { messages, timer }
+
+  const flushKey = (key) => {
+    const entry = entries.get(key);
+    if (!entry) return;
+    entries.delete(key);
+    // Defensive: onFlush errors must not break future group buffering.
+    try { onFlush(entry.messages, key); }
+    catch { /* caller can log if it cares */ }
+  };
+
+  const add = (key, msg) => {
+    let entry = entries.get(key);
+    if (!entry) {
+      entry = { messages: [], timer: null };
+      entries.set(key, entry);
+    }
+    entry.messages.push(msg);
+    if (entry.timer) clearTimerFn(entry.timer);
+    const t = timerFn(() => flushKey(key), flushMs);
+    // Don't keep the node event loop alive waiting for a buffered group
+    // that never grew further — especially in tests.
+    t?.unref?.();
+    entry.timer = t;
+  };
+
+  const flushAll = () => {
+    for (const key of Array.from(entries.keys())) {
+      const entry = entries.get(key);
+      if (entry?.timer) clearTimerFn(entry.timer);
+      flushKey(key);
+    }
+  };
+
+  return {
+    add,
+    flushAll,
+    get size() { return entries.size; },
+  };
+}
+
+module.exports = { createMediaGroupBuffer, DEFAULT_FLUSH_MS };

package/lib/process-manager.js

@@ -23,6 +23,15 @@ const DEFAULT_KILL_TIMEOUT_MS = 3000;
  * (they count as Claude activity) but are NOT rendered to Telegram.
  * Streaming every tool call to chat produces a noisy "_Calling X_"
  * ladder that adds no information users can act on.
+ *
+ * Trailing-colon normalisation: Claude writes preambles like "Checking
+ * this:" followed by a tool_use. Because we hide tool_use in the stream,
+ * the colon becomes an orphan pointing at invisible work. Replace a
+ * trailing `:` with `…` — the ellipsis reads as "doing it now" and
+ * preserves the natural flow. Only the LAST colon in the joined text is
+ * touched; mid-sentence colons ("Here's the plan: step 1, step 2")
+ * stay intact. Also guards against `::` sequences (code / emoticons) by
+ * requiring the preceding char to not also be `:`.
  */
 function extractAssistantText(event) {
   const blocks = event?.message?.content;
@@ -34,7 +43,7 @@ function extractAssistantText(event) {
       parts.push(b.text);
     }
   }
-  return parts.join('\n\n').trim();
+  return parts.join('\n\n').trim().replace(/([^:]):\s*$/, '$1…');
 }
 
 class ProcessManager {
@@ -272,9 +281,17 @@ class ProcessManager {
       entry.pending = { resolve, reject };
       entry.streamText = '';
 
+      // Timer handles kept in closure vars (not entry.pending), because
+      // the result-event handler in rl.on('line') sets entry.pending = null
+      // BEFORE calling the wrapped resolve. Reading from entry.pending
+      // after null-out gave undefined → clearTimeout was never called →
+      // the default 30-min maxTurnMs timer stayed armed and held Node's
+      // event loop open, hanging the test runner on CI.
+      let idleTimer = null;
+      let maxTimer = null;
       const clearTimers = () => {
-        if (entry.pending?.idleTimer) clearTimeout(entry.pending.idleTimer);
-        if (entry.pending?.maxTimer) clearTimeout(entry.pending.maxTimer);
+        if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+        if (maxTimer) { clearTimeout(maxTimer); maxTimer = null; }
       };
 
       // Timer fire path. New in 0.3.9: after rejecting, SIGTERM the
@@ -299,19 +316,25 @@ class ProcessManager {
       // Idle timeout: counts N seconds of SILENCE from Claude. Reset on
       // every assistant event so long productive turns (multi-tool
       // reasoning) don't falsely trip.
-      // .unref() so these timers don't hold the node event loop open in
-      // tests or when the parent process wants to exit. Real-world polygram
-      // stays alive via grammy's poll loop + stdin/stdout pipes; the timers
-      // don't need to keep it alive on their own.
+      // Note on .unref(): an earlier revision called unref() on both
+      // timers to avoid holding the node event loop open in tests. That
+      // broke Node's test runner on CI ("Promise resolution is still
+      // pending but the event loop has already resolved") — the runner
+      // detects unref'd timers as a drained loop and cancels awaiters
+      // before the timer can fire. Production polygram stays alive via
+      // grammy's poll loop + child process pipes; we don't need unref.
       const armIdle = () => setTimeout(
         () => fireTimeout(`Timeout: ${timeoutMs / 1000}s idle with no Claude activity`),
         timeoutMs,
-      ).unref();
-      entry.pending.idleTimer = armIdle();
+      );
+      idleTimer = armIdle();
+      entry.pending.idleTimer = idleTimer;
       entry.pending.resetIdleTimer = () => {
-        if (!entry.pending) return;
-        clearTimeout(entry.pending.idleTimer);
-        entry.pending.idleTimer = armIdle();
+        if (idleTimer) clearTimeout(idleTimer);
+        if (entry.pending) {
+          idleTimer = armIdle();
+          entry.pending.idleTimer = idleTimer;
+        }
       };
 
       // Wall-clock ceiling: fires at maxTurnMs regardless of activity.
@@ -319,13 +342,14 @@ class ProcessManager {
       // idle timer alive) but never produce a result. OpenClaw's only
       // timer was wall-clock; polygram's 0.3.5 change replaced it with
       // idle-reset, creating a gap this restores as a last-resort.
-      entry.pending.maxTimer = setTimeout(
+      maxTimer = setTimeout(
         () => fireTimeout(`Turn exceeded ${maxTurnMs / 1000}s wall-clock ceiling`),
         maxTurnMs,
-      ).unref();
+      );
+      entry.pending.maxTimer = maxTimer;
 
       // Legacy alias: some callers / tests refer to entry.pending.timer.
-      entry.pending.timer = entry.pending.idleTimer;
+      entry.pending.timer = idleTimer;
 
       const wrappedResolve = entry.pending.resolve;
       const wrappedReject = entry.pending.reject;
@@ -342,6 +366,7 @@ class ProcessManager {
         entry.pending = null;
         entry.inFlight = false;
         reject(err);
+        return;
       }
     });
   }

package/lib/telegram.js

@@ -76,7 +76,18 @@ function nextPendingId() {
   return -(v + 1);
 }
 
-const METHODS_WITHOUT_MSG = new Set(['setMessageReaction', 'deleteMessage', 'editMessageReplyMarkup']);
+// Methods we don't insert a `messages` row for. Reactions/deletes/markup
+// edits never produced a chat message in the first place. editMessageText
+// DOES modify a message, but creating a new DB row per edit collides with
+// the UNIQUE(chat_id, msg_id) constraint on the 2nd edit — the stream
+// edits one bubble N times in a single turn. The initial sendMessage
+// already persisted the row; edits just update the live bubble.
+const METHODS_WITHOUT_MSG = new Set([
+  'setMessageReaction',
+  'deleteMessage',
+  'editMessageReplyMarkup',
+  'editMessageText',
+]);
 
 // Derive the row's `text` column. sendSticker has no text/caption, so we
 // synthesize `[sticker:<name>]` (or file_id as fallback) — without this the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.4.1",
+  "version": "0.4.6",
   "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

@@ -35,6 +35,7 @@ const { createStreamer } = require('./lib/stream-reply');
 const { isAbortRequest } = require('./lib/abort-detector');
 const { startTyping } = require('./lib/typing-indicator');
 const { createReactionManager, classifyToolName } = require('./lib/status-reactions');
+const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
 const {
   createStore: createApprovalsStore,
   matchesAnyPattern: matchesApprovalPattern,
@@ -230,6 +231,12 @@ function sanitizeFilename(name) {
 }
 
 function extractAttachments(msg) {
+  // Media-group bundling path: when we synthesised a single message from
+  // several siblings sharing a media_group_id, the merged attachment list
+  // was pre-computed in `_mergedAttachments`. Return it directly instead
+  // of running the per-field extraction against the primary message.
+  if (Array.isArray(msg._mergedAttachments)) return msg._mergedAttachments;
+
   const items = [];
   if (msg.document) {
     const d = msg.document;
@@ -548,6 +555,18 @@ async function enqueue(sessionKey, chatId, msg, bot) {
   if (!processing[sessionKey]) processQueue(sessionKey);
 }
 
+// Sessions the operator just /stop'd (or natural-language "стоп"). Entries
+// suppress the generic "Sorry, I couldn't process" reply below — the abort
+// handler already sent its own "Остановлено." ack, and the subsequent
+// handleMessage rejection from the killed subprocess would otherwise
+// spam a second contradictory message. Cleared on first use; long-lived
+// only if the abort kills something that never finishes rejecting.
+const abortedSessions = new Set();
+
+function markSessionAborted(sessionKey) {
+  abortedSessions.add(sessionKey);
+}
+
 async function processQueue(sessionKey) {
   processing[sessionKey] = true;
   while (queues[sessionKey]?.length > 0) {
@@ -555,6 +574,8 @@ async function processQueue(sessionKey) {
     try {
       await handleMessage(sessionKey, chatId, msg, bot);
     } catch (err) {
+      const wasAborted = abortedSessions.has(sessionKey);
+      if (wasAborted) abortedSessions.delete(sessionKey);
       // Raw err.message can carry host paths, DB columns, internal state.
       // Surface a generic message to the user; log the detail to events
       // so operators can still debug.
@@ -564,15 +585,18 @@ async function processQueue(sessionKey) {
         msg_id: msg?.message_id,
         error: err.message?.slice(0, 500),
         stack: err.stack?.split('\n').slice(0, 5).join('\n'),
+        aborted: wasAborted || undefined,
       }), 'log handler-error');
-      try {
-        await tg(bot, 'sendMessage', {
-          chat_id: chatId,
-          text: `Sorry, I couldn't process that message. The operator has been notified.`,
-          reply_parameters: { message_id: msg.message_id },
-        }, { source: 'error-reply', botName: BOT_NAME });
-      } catch (replyErr) {
-        console.error(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
+      if (!wasAborted) {
+        try {
+          await tg(bot, 'sendMessage', {
+            chat_id: chatId,
+            text: `Sorry, I couldn't process that message. The operator has been notified.`,
+            reply_parameters: { message_id: msg.message_id },
+          }, { source: 'error-reply', botName: BOT_NAME });
+        } catch (replyErr) {
+          console.error(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
+        }
       }
     }
   }
@@ -1143,11 +1167,21 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     }, outMetaBase),
     edit: async (messageId, text) => {
       try {
-        return await bot.api.editMessageText(chatId, messageId, text);
+        // Route edits through tg() so applyFormatting runs (MarkdownV2
+        // + escape). Going direct to bot.api.editMessageText would
+        // skip formatting and leave every edit rendering literal
+        // **bold** / `code` in the bubble — which was the visible bug
+        // in 0.4.2 where the initial send was formatted and every
+        // subsequent edit overwrote it with plain text.
+        return await tg(bot, 'editMessageText', {
+          chat_id: chatId,
+          message_id: messageId,
+          text,
+        }, { source: 'bot-reply-stream-edit', botName: BOT_NAME });
       } catch (err) {
-        // Stream-edit failures would otherwise be invisible — edits bypass
-        // tg() so there's no messages row reflecting the attempt. Log to
-        // events so stuck streams leave a forensic trail.
+        // Stream-edit failures would otherwise be invisible — edits
+        // don't insert a messages row by default (tg() does, but we
+        // want the failure path specifically surfaced). Log to events.
         dbWrite(() => db.logEvent('telegram-edit-failed', {
           chat_id: chatId, msg_id: messageId,
           api_error: err.message?.slice(0, 200),
@@ -1400,42 +1434,14 @@ function createBot(token) {
     return newChat;
   }
 
-  bot.on('message', async (ctx) => {
-    if (!isWellFormedMessage(ctx.message)) {
-      dbWrite(() => db.logEvent('malformed-update', {
-        bot: BOT_NAME,
-        update_id: ctx.update?.update_id,
-        reason: 'missing chat.id / message_id',
-      }), 'log malformed-update');
-      return;
-    }
-    const chatId = ctx.chat.id.toString();
-    let chatConfig = config.chats[chatId];
-
-    // Auto-onboarding: /pair <CODE> from an unconfigured private chat.
-    // Without this, the !chatConfig drop below would silently eat pair
-    // claims from DMs the operator hasn't pre-listed — defeating the
-    // whole point of pair codes (which exist to grant access without
-    // pre-configuration). Group chats are not auto-onboarded: they must
-    // still be added to config.json by the operator, because adding a
-    // group can affect multiple users.
-    if (!chatConfig && ctx.chat.type === 'private') {
-      const probe = (ctx.message.text || '').trim();
-      const pairMatch = /^\/pair(?:@\S+)?\s+(\S+)\s*$/.exec(probe);
-      if (pairMatch) {
-        chatConfig = await onboardPairedChat(ctx, pairMatch[1]);
-        if (!chatConfig) return;
-        recordInbound(ctx.message);
-        return;
-      }
-    }
+  // Shared post-validation dispatch. Called directly for single messages
+  // and for the synthesised "primary" of a media-group bundle.
+  const dispatchRegularMessage = async (msg) => {
+    const chatId = msg.chat.id.toString();
+    const chatConfig = config.chats[chatId];
     if (!chatConfig) return;
 
-    // Record every inbound msg, even unaddressed ones — needed for reply-to
-    // lookups and the transcript skill.
-    recordInbound(ctx.message);
-
-    const rawText = ctx.message.text || '';
+    const rawText = msg.text || '';
     const cleanText = mentionRe ? rawText.replace(mentionRe, '').trim() : rawText.trim();
 
     // Abort: skip the queue entirely. Matches bilingual natural-language
@@ -1445,23 +1451,43 @@ function createBot(token) {
     // the user sees the bot heard them — silent abort is worse than
     // acknowledged abort.
     if (isAbortRequest(cleanText)) {
-      const threadId = ctx.message.message_thread_id?.toString();
+      const threadId = msg.message_thread_id?.toString();
       const sessionKey = getSessionKey(chatId, threadId, chatConfig);
       const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
       const dropped = drainQueuesForChat(chatId);
+      // Mark BEFORE killing: the 'close' event fires almost immediately
+      // after SIGTERM, and processQueue's catch needs to see the flag to
+      // skip the generic error-reply. If we marked after, there'd be a
+      // race where the error-reply slips through.
+      if (hadActive) markSessionAborted(sessionKey);
       await pm.killChat(chatId).catch(() => {});
       dbWrite(() => db.logEvent('abort-requested', {
-        chat_id: chatId, user_id: ctx.message.from?.id || null,
+        chat_id: chatId, user_id: msg.from?.id || null,
         had_active: hadActive, queued_dropped: dropped,
         trigger: cleanText.slice(0, 40),
       }), 'log abort-requested');
+      // Reply in the same language the user aborted in. Cyrillic-detection
+      // is crude but reliable for ru/en (the only two cue sets we ship).
+      const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
+      const strs = {
+        en: {
+          stopped: 'Stopped.',
+          withDropped: (n) => `Stopped. Cleared ${n} queued message${n === 1 ? '' : 's'}.`,
+          nothing: 'Nothing to stop.',
+        },
+        ru: {
+          stopped: 'Остановлено.',
+          withDropped: (n) => `Остановлено. Очередь очищена (${n}).`,
+          nothing: 'Нечего останавливать.',
+        },
+      }[lang];
       const reply = hadActive || dropped
-        ? (dropped ? `Остановлено. Очередь очищена (${dropped}).` : 'Остановлено.')
-        : 'Нечего останавливать.';
+        ? (dropped ? strs.withDropped(dropped) : strs.stopped)
+        : strs.nothing;
       try {
         await tg(bot, 'sendMessage', {
           chat_id: chatId, text: reply,
-          reply_parameters: { message_id: ctx.message.message_id, allow_sending_without_reply: true },
+          reply_parameters: { message_id: msg.message_id, allow_sending_without_reply: true },
           ...(threadId && { message_thread_id: threadId }),
         }, { source: 'abort-ack', botName: BOT_NAME });
       } catch {}
@@ -1472,23 +1498,90 @@ function createBot(token) {
     const isAdminCmd = botAllowsCommands && ADMIN_CMD_RE.test(cleanText);
     const isPairClaim = PAIR_CLAIM_RE.test(cleanText);
     if (isAdminCmd || isPairClaim) {
-      ctx.message.text = cleanText;
-      const threadId = ctx.message.message_thread_id?.toString();
+      msg.text = cleanText;
+      const threadId = msg.message_thread_id?.toString();
       const sessionKey = getSessionKey(chatId, threadId, chatConfig);
-      await handleMessage(sessionKey, chatId, ctx.message, bot);
+      await handleMessage(sessionKey, chatId, msg, bot);
       return;
     }
 
-    if (!shouldHandle(ctx.message, chatConfig, botUsername)) return;
+    if (!shouldHandle(msg, chatConfig, botUsername)) return;
 
     if (botUsername) {
-      ctx.message.text = cleanText;
+      msg.text = cleanText;
     }
 
-    const threadId = ctx.message.message_thread_id?.toString();
+    const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+    await enqueue(sessionKey, chatId, msg, bot);
+  };
+
+  // Media-group buffer: coalesce multi-photo uploads (Telegram delivers
+  // each attachment as a separate Message sharing a `media_group_id`) into
+  // a single synthetic turn with all attachments merged. Timer resets on
+  // every new sibling, so as long as messages arrive faster than the
+  // DEFAULT_FLUSH_MS window apart they stay in the same bundle.
+  const mediaBuffer = createMediaGroupBuffer({
+    onFlush: (messages) => {
+      if (!messages || messages.length === 0) return;
+      // Primary = the (usually first) message with text/caption; that's
+      // where the user's actual prompt lives. Fall back to index 0 for
+      // all-media-no-text groups.
+      const primary = messages.find((m) => m.text || m.caption) || messages[0];
+      const merged = messages.flatMap((m) => extractAttachments(m));
+      const synthetic = { ...primary, _mergedAttachments: merged };
+      // Carry the primary's text verbatim (dispatchRegularMessage re-cleans
+      // the mention). Caption → text so downstream sees it uniformly.
+      if (!synthetic.text && synthetic.caption) synthetic.text = synthetic.caption;
+      dispatchRegularMessage(synthetic).catch((err) =>
+        console.error(`[${BOT_NAME}] media-group dispatch error: ${err.message}`));
+    },
+  });
+
+  bot.on('message', async (ctx) => {
+    if (!isWellFormedMessage(ctx.message)) {
+      dbWrite(() => db.logEvent('malformed-update', {
+        bot: BOT_NAME,
+        update_id: ctx.update?.update_id,
+        reason: 'missing chat.id / message_id',
+      }), 'log malformed-update');
+      return;
+    }
+    const chatId = ctx.chat.id.toString();
+    let chatConfig = config.chats[chatId];
+
+    // Auto-onboarding: /pair <CODE> from an unconfigured private chat.
+    // Without this, the !chatConfig drop below would silently eat pair
+    // claims from DMs the operator hasn't pre-listed — defeating the
+    // whole point of pair codes (which exist to grant access without
+    // pre-configuration). Group chats are not auto-onboarded: they must
+    // still be added to config.json by the operator, because adding a
+    // group can affect multiple users.
+    if (!chatConfig && ctx.chat.type === 'private') {
+      const probe = (ctx.message.text || '').trim();
+      const pairMatch = /^\/pair(?:@\S+)?\s+(\S+)\s*$/.exec(probe);
+      if (pairMatch) {
+        chatConfig = await onboardPairedChat(ctx, pairMatch[1]);
+        if (!chatConfig) return;
+        recordInbound(ctx.message);
+        return;
+      }
+    }
+    if (!chatConfig) return;
+
+    // Record every inbound msg, even unaddressed ones — needed for reply-to
+    // lookups and the transcript skill.
+    recordInbound(ctx.message);
+
+    // Multi-photo / album upload: Telegram delivers siblings as separate
+    // Messages sharing a media_group_id. Stash each and let the buffer
+    // dispatch them together 500ms after the last sibling arrives.
+    if (ctx.message.media_group_id) {
+      mediaBuffer.add(`${chatId}:${ctx.message.media_group_id}`, ctx.message);
+      return;
+    }
 
-    await enqueue(sessionKey, chatId, ctx.message, bot);
+    await dispatchRegularMessage(ctx.message);
   });
 
   bot.on('callback_query:data', async (ctx) => {