polygram 0.4.0 → 0.4.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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/db.js

@@ -8,7 +8,7 @@ const fs = require('fs');
 const path = require('path');
 const Database = require('better-sqlite3');
 
-const SCHEMA_VERSION = 4;
+const SCHEMA_VERSION = 5;
 
 function open(dbPath) {
   const db = new Database(dbPath);

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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;
@@ -1400,42 +1407,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,13 +1424,13 @@ 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);
       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');
@@ -1461,7 +1440,7 @@ function createBot(token) {
       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 +1451,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) => {