polygram 0.6.16 → 0.7.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.6.16",
+  "version": "0.7.1",
   "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/README.md

@@ -364,7 +364,7 @@ foreign-chat clicks are rejected. Default-deny on IPC error.
 ## Development
 
 ```bash
-npm test           # 500 tests, 115 suites, node:test, no external services
+npm test           # 638 tests, 158 suites, node:test, no external services
 npm run coverage   # native test coverage (Node 22+, no devDeps)
 npm start -- --bot my-bot
 npm run split-db -- --config config.json --dry-run

package/lib/announces.js

@@ -0,0 +1,150 @@
+/**
+ * Subagent / informational announces — a thin OpenClaw-style helper for
+ * sending small "I'm doing X" messages to a chat without mixing into
+ * the main reply flow.
+ *
+ * Polygram's user-facing surface for "shumabit is working" is the
+ * status reaction on the user's message (👀 → 🤔 → tool icons →
+ * 👍/💥). For tool-heavy turns where the user wants more visibility
+ * — e.g. shumabit delegating to a subagent via Claude Code's Task
+ * tool — an opt-in announce can post a brief informational message
+ * to the chat. Off by default (`config.bots.<bot>.announceSubagents`
+ * or `config.chats.<id>.announceSubagents`), so existing chats see
+ * no behavior change.
+ *
+ * 0.7.1 redesign: factory-based with split read/write predicates
+ * (canAnnounce / markAnnounced) and lazy GC. Pre-0.7.1 had a
+ * module-scoped Map and a mutate-on-check `shouldAnnounce` predicate
+ * — both anti-patterns flagged in design review. The free-function
+ * API (`shouldAnnounce`, `announce`) is preserved for back-compat,
+ * delegating to a default singleton.
+ */
+
+const SUBAGENT_DEBOUNCE_MS = 30_000;
+
+/**
+ * Per-chat debounce tracker. Returns:
+ *   - canAnnounce(chatId): true if this chat hasn't announced within
+ *     the debounce window. Pure read, NO mutation — safe for
+ *     speculative checks.
+ *   - markAnnounced(chatId): records `now` as the last announce time
+ *     for this chat. Caller invokes after a successful send.
+ *   - sweep(): drops entries older than `2 * debounceMs`. Called lazily
+ *     on every canAnnounce check past a soft threshold.
+ *   - size(): for tests / diagnostics.
+ *   - clear(): for test isolation.
+ */
+function createAnnouncer({
+  debounceMs = SUBAGENT_DEBOUNCE_MS,
+  clock = Date.now,
+  sweepThreshold = 1000,
+} = {}) {
+  const lastAnnounceByChat = new Map();
+
+  function key(chatId) { return String(chatId); }
+
+  function sweep() {
+    const cutoff = clock() - 2 * debounceMs;
+    for (const [k, ts] of lastAnnounceByChat) {
+      if (ts < cutoff) lastAnnounceByChat.delete(k);
+    }
+  }
+
+  function canAnnounce(chatId) {
+    if (lastAnnounceByChat.size > sweepThreshold) sweep();
+    const prev = lastAnnounceByChat.get(key(chatId));
+    return prev == null || (clock() - prev) >= debounceMs;
+  }
+
+  function markAnnounced(chatId) {
+    lastAnnounceByChat.set(key(chatId), clock());
+  }
+
+  return {
+    canAnnounce, markAnnounced, sweep,
+    get size() { return lastAnnounceByChat.size; },
+    clear() { lastAnnounceByChat.clear(); },
+  };
+}
+
+// Default per-process state for the back-compat free-function API.
+// Pre-0.7.1, this was the only API. Long-running daemons should still
+// prefer createAnnouncer() for tests / multi-bot isolation, but
+// polygram.js's single-bot-per-process model means the singleton works
+// fine for the production path. The Map is pruned lazily inside
+// shouldAnnounce when it grows past the sweep threshold.
+const _defaultLastAnnouncements = new Map();
+const _DEFAULT_SWEEP_THRESHOLD = 1000;
+
+/**
+ * Back-compat: pre-0.7.1 callers used `shouldAnnounce(chatId, now?,
+ * debounceMs?)` which is a "predicate that mutates" — call site is
+ * `if (shouldAnnounce(id)) await sendAnnounce()`. The mutation happens
+ * eagerly. Preserved verbatim for callers; new code should use
+ * `createAnnouncer()` and the explicit canAnnounce/markAnnounced split.
+ *
+ * 0.7.1: added lazy sweep so the Map doesn't grow unbounded over a
+ * multi-week-uptime daemon.
+ */
+function shouldAnnounce(chatId, now = Date.now(), debounceMs = SUBAGENT_DEBOUNCE_MS) {
+  if (_defaultLastAnnouncements.size > _DEFAULT_SWEEP_THRESHOLD) {
+    const cutoff = now - 2 * debounceMs;
+    for (const [k, ts] of _defaultLastAnnouncements) {
+      if (ts < cutoff) _defaultLastAnnouncements.delete(k);
+    }
+  }
+  const key = String(chatId);
+  const prev = _defaultLastAnnouncements.get(key);
+  if (prev != null && now - prev < debounceMs) return false;
+  _defaultLastAnnouncements.set(key, now);
+  return true;
+}
+
+/**
+ * Reset the default singleton state (for tests). Not exported in
+ * production docs.
+ */
+function _resetDefaultAnnouncerForTests() {
+  _defaultLastAnnouncements.clear();
+}
+
+/**
+ * Send a plain-text announce (no markdown processing, no reply linkage).
+ * Caller passes `tg(bot, method, params, meta)` as `send` so we don't
+ * have to import the full lib/telegram.js dependency tree here.
+ */
+async function announce({
+  send,
+  bot,
+  chatId,
+  threadId = null,
+  text,
+  meta = {},
+  logger = console,
+}) {
+  if (!text) return null;
+  const params = {
+    chat_id: chatId,
+    text,
+    ...(threadId != null ? { message_thread_id: threadId } : {}),
+  };
+  try {
+    return await send(bot, 'sendMessage', params, {
+      ...meta,
+      source: meta.source || 'announce',
+      plainText: true,            // skip markdown→HTML
+      linkPreview: false,         // never preview-card for announces
+    });
+  } catch (err) {
+    logger.error?.(`[announce] failed: ${err.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  announce,
+  shouldAnnounce,
+  createAnnouncer,
+  SUBAGENT_DEBOUNCE_MS,
+  _resetDefaultAnnouncerForTests,
+};

package/lib/deliver.js

@@ -0,0 +1,78 @@
+/**
+ * Chunked reply delivery primitive.
+ *
+ * `deliverReplies` is the polygram analog of OpenClaw's `deliverReplies` —
+ * a small loop over already-chunked text that sends each chunk as its own
+ * Telegram message via the `send()` wrapper from lib/telegram.js (which
+ * does write-before-send, HTML→plain fallback, and MESSAGE_NOT_MODIFIED
+ * swallowing).
+ *
+ * Polygram's old code path inlined a `for (chunk of chunkText(rest))` loop
+ * inside polygram.js with an ad-hoc `tg()` call. That worked, but mixed
+ * delivery concerns into the streaming-finalize logic, and made testing
+ * the multi-message path painful. With this primitive, the new
+ * "preview-becomes-final" flow in handleMessage (Phase 5) just calls:
+ *
+ *   await deliverReplies({ bot, chatId, threadId, chunks, replyToMessageId, ... })
+ *
+ * — and gets back `{ sent, failed }` arrays of message_ids per chunk.
+ *
+ * Behavior:
+ *   - Sends `chunks[0]` first with `reply_parameters` (so the answer
+ *     visually anchors to the user's question). Subsequent chunks omit
+ *     `reply_parameters` — chaining replies would clutter the chat.
+ *   - On chunk failure, logs and continues to the next chunk. We'd
+ *     rather deliver partial content than abort the whole reply.
+ *   - Empty input returns `{ sent: [], failed: [] }` immediately.
+ */
+
+async function deliverReplies({
+  bot,
+  send, // (bot, method, params, meta) → res — usually createSender(db, logger)(...) or tg
+  chatId,
+  threadId = null,
+  chunks,
+  replyToMessageId = null,
+  meta = {},
+  logger = console,
+}) {
+  if (!Array.isArray(chunks) || chunks.length === 0) {
+    return { sent: [], failed: [], results: [] };
+  }
+  // 0.7.1: results[] preserves correspondence with chunks[] — results[i]
+  // describes what happened to chunks[i]. sent[]/failed[] are projections
+  // for back-compat with callers that already use them; they no longer
+  // ambiguously mean "the i-th success/failure" vs "chunk i's outcome".
+  const results = [];
+  const sent = [];
+  const failed = [];
+  for (let i = 0; i < chunks.length; i++) {
+    const params = {
+      chat_id: chatId,
+      text: chunks[i],
+    };
+    if (threadId != null) params.message_thread_id = threadId;
+    if (i === 0 && replyToMessageId != null) {
+      // allow_sending_without_reply: long turns give the user time to
+      // delete their original message; without this flag Telegram
+      // rejects with MESSAGE_NOT_FOUND and the whole reply is lost.
+      params.reply_parameters = { message_id: replyToMessageId, allow_sending_without_reply: true };
+    }
+    try {
+      const res = await send(bot, 'sendMessage', params, meta);
+      const msgId = res?.message_id ?? null;
+      results.push({ index: i, status: 'ok', messageId: msgId });
+      sent.push(msgId);
+    } catch (err) {
+      logger.error?.(`[deliver] chunk ${i + 1}/${chunks.length} failed: ${err.message}`);
+      results.push({ index: i, status: 'fail', error: err.message });
+      failed.push({ index: i, error: err.message });
+      // Keep going — partial delivery is better than total loss. Caller
+      // should inspect failed.length and surface a warning to the user
+      // (see polygram.js handleMessage's stream-redeliver event log).
+    }
+  }
+  return { sent, failed, results };
+}
+
+module.exports = { deliverReplies };

package/lib/net-errors.js

@@ -30,20 +30,55 @@ const PRE_CONNECT_ERROR_CODES = new Set([
 // Transient errors that are recoverable but may have made it partway. DO
 // NOT auto-retry these — the risk of double-delivery outweighs the gain.
 // Surface them to the caller and let humans decide.
+//
+// 0.7.0 added the UND_ERR_* family + ECONNABORTED / ERR_NETWORK to match
+// OpenClaw's set (extensions/telegram/src/network-errors.ts). Node 22+
+// uses undici as its default fetch impl, so these surface in real
+// production traffic — pre-0.7.0 we'd silently misclassify them as
+// non-network errors.
 const RECOVERABLE_ERROR_CODES = new Set([
-  'ETIMEDOUT',    // TCP timeout after connect (message may have landed)
-  'EPIPE',        // write after close — outcome indeterminate
-  'EAGAIN',       // socket would block — reader should retry
+  'ETIMEDOUT',          // TCP timeout after connect (message may have landed)
+  'EPIPE',              // write after close — outcome indeterminate
+  'EAGAIN',             // socket would block — reader should retry
+  'ESOCKETTIMEDOUT',    // socket-level timeout (axios/legacy node)
+  'ECONNABORTED',       // connection aborted by client (timeout-induced)
+  'ERR_NETWORK',        // generic network error code
+  'UND_ERR_CONNECT_TIMEOUT', // undici: connection timeout
+  'UND_ERR_HEADERS_TIMEOUT', // undici: response headers timeout
+  'UND_ERR_BODY_TIMEOUT',    // undici: response body timeout
+  'UND_ERR_SOCKET',          // undici: socket error
+  'UND_ERR_ABORTED',         // undici: request aborted
 ]);
 
 // Error.name values emitted by undici/node for transient conditions.
+// 0.7.0 added the undici-specific timeout error names; the new fetch
+// impl in Node 22+ surfaces these as `err.name` rather than `err.code`
+// in some shapes.
 const RECOVERABLE_ERROR_NAMES = new Set([
   'AbortError',
   'TimeoutError',
   'FetchError',
   'SocketError',
+  'ConnectTimeoutError',
+  'HeadersTimeoutError',
+  'BodyTimeoutError',
 ]);
 
+// Message-substring matchers for transient errors. undici sometimes
+// wraps a network failure in a generic "fetch failed" without setting
+// .code or .name — only the message tells us it's a network error.
+//
+// These are matched ONLY when the error doesn't already have a code or
+// name we recognise, to avoid double-counting and to keep the broad
+// matcher from catching unrelated errors that happen to include the
+// substring.
+const RECOVERABLE_MESSAGE_SNIPPETS = [
+  'fetch failed',
+  'undici',
+  'network error',
+  'network request',
+];
+
 function extractCode(err) {
   if (!err) return null;
   return err.code
@@ -67,6 +102,11 @@ function isSafeToRetry(err) {
   return code != null && PRE_CONNECT_ERROR_CODES.has(code);
 }
 
+function extractMessage(err) {
+  if (!err) return '';
+  return String(err.message || err.cause?.message || err.description || '').toLowerCase();
+}
+
 /**
  * Is this a transient network error — recoverable in the sense that the
  * connection may work next time, but NOT safe to auto-retry because the
@@ -80,6 +120,13 @@ function isTransientNetworkError(err) {
   }
   const name = extractName(err);
   if (name && RECOVERABLE_ERROR_NAMES.has(name)) return true;
+  // 0.7.0: only fall through to message-snippet matching when the
+  // error has no recognised code/name — avoids false-positive matches
+  // on unrelated errors that happen to mention "network".
+  const message = extractMessage(err);
+  if (message && RECOVERABLE_MESSAGE_SNIPPETS.some((s) => message.includes(s))) {
+    return true;
+  }
   return false;
 }
 
@@ -113,9 +160,11 @@ module.exports = {
   PRE_CONNECT_ERROR_CODES,
   RECOVERABLE_ERROR_CODES,
   RECOVERABLE_ERROR_NAMES,
+  RECOVERABLE_MESSAGE_SNIPPETS,
   isSafeToRetry,
   isTransientNetworkError,
   extractCode,
   extractName,
+  extractMessage,
   redactBotToken,
 };

package/lib/process-manager.js

@@ -59,6 +59,7 @@ class ProcessManager {
     onClose = null,       // (sessionKey, code, entry) → void
     onStreamChunk = null, // (sessionKey, partialText, entry) → void — routes to pendingQueue[0]
     onToolUse = null,     // (sessionKey, toolName, entry) → void — routes to pendingQueue[0]
+    onAssistantMessageStart = null, // (sessionKey, entry) → void — fires when a NEW top-level assistant message begins (after a previous one ended). Used by polygram.js to call streamer.forceNewMessage() so each assistant message gets its own bubble.
     onRespawn = null,     // (sessionKey, reason, entry) → void — fires after graceful drain-and-kill
   } = {}) {
     if (!spawnFn) throw new Error('spawnFn required');
@@ -72,6 +73,7 @@ class ProcessManager {
     this.onClose = onClose;
     this.onStreamChunk = onStreamChunk;
     this.onToolUse = onToolUse;
+    this.onAssistantMessageStart = onAssistantMessageStart;
     this.onRespawn = onRespawn;
     this.procs = new Map();
   }
@@ -275,12 +277,34 @@ class ProcessManager {
       }
 
       if (event.type === 'assistant' && head) {
-        if (this.onStreamChunk) {
-          const added = extractAssistantText(event);
-          if (added) {
-            head.streamText = head.streamText
-              ? `${head.streamText}\n\n${added}`
-              : added;
+        // 0.7.0 (Phase F): detect message_id transitions to split bubbles
+        // per top-level assistant message. Each Anthropic stream-json
+        // 'assistant' event carries event.message.id; the same id across
+        // events means cumulative updates to the same message, a new
+        // id means a new message (typically after a tool-result cycle).
+        const messageId = event.message?.id;
+        const added = extractAssistantText(event);
+        if (added) {
+          // Pre-0.7.0 we did `streamText = streamText + '\n\n' + added`,
+          // which DUPLICATED text on every update because `added` is
+          // the cumulative full text-so-far of the current assistant
+          // message (not a delta). 0.7.0 REPLACES instead — the new
+          // text is already cumulative — and uses messageId boundaries
+          // to fire onAssistantMessageStart for each new top-level
+          // assistant message. The streamer responds by force-creating
+          // a fresh bubble, so each assistant message gets its own.
+          const isNewMessage = head.lastAssistantMessageId != null
+            && messageId != null
+            && head.lastAssistantMessageId !== messageId
+            && head.streamText
+            && head.streamText.length > 0;
+          if (isNewMessage && this.onAssistantMessageStart) {
+            try { this.onAssistantMessageStart(sessionKey, entry); }
+            catch (err) { this.logger.error(`[${entry.label}] onAssistantMessageStart: ${err.message}`); }
+          }
+          if (messageId != null) head.lastAssistantMessageId = messageId;
+          head.streamText = added;
+          if (this.onStreamChunk) {
             try { this.onStreamChunk(sessionKey, head.streamText, entry); }
             catch (err) { this.logger.error(`[${entry.label}] onStreamChunk: ${err.message}`); }
           }

package/lib/sent-cache.js

@@ -0,0 +1,119 @@
+/**
+ * In-memory cache of message IDs the bot has sent, per chat.
+ *
+ * Port of OpenClaw's `sent-message-cache` (send-DVX_zY9w.js:1014-1041).
+ * Use case: filter the bot's own messages out of activation logic in
+ * group chats — a bot reply with a URL would otherwise auto-trigger
+ * a self-reply if the chat's activation rule includes "any message
+ * with a URL". Polygram's existing `messages` table can answer the
+ * same question via SQL (`direction = 'out' AND chat_id AND msg_id`),
+ * but the in-memory cache is O(1) for the high-frequency callers
+ * (every inbound message reaction handler).
+ *
+ * 24-hour TTL: Telegram messages older than 48h can't be reacted to
+ * anyway, so 24h is a comfortable working set. Per-chat cleanup runs
+ * lazily when the chat exceeds 100 entries.
+ */
+
+const TTL_MS = 24 * 60 * 60 * 1000;
+const CLEANUP_THRESHOLD = 100;
+// 0.7.1: hard cap on per-chat Map size. CLEANUP_THRESHOLD only drops
+// EXPIRED entries — if a busy chat sends >100 fresh messages within
+// 24h, GC finds nothing to drop and the inner Map grows unbounded.
+// Cap evicts oldest entries past this point regardless of TTL.
+const MAX_PER_CHAT = 500;
+// 0.7.1: outer Map sweep — drop chats whose inner Map has been empty
+// long enough that we're sure no live caller still references it.
+const OUTER_SWEEP_THRESHOLD = 1000;
+
+function createSentCache({
+  ttlMs = TTL_MS,
+  cleanupThreshold = CLEANUP_THRESHOLD,
+  maxPerChat = MAX_PER_CHAT,
+  outerSweepThreshold = OUTER_SWEEP_THRESHOLD,
+  clock = Date.now,
+} = {}) {
+  // chatKey → Map<msgId, ts>
+  const sentMessages = new Map();
+
+  function chatKey(chatId) { return String(chatId); }
+
+  function gcInner(entry) {
+    const cutoff = clock() - ttlMs;
+    for (const [id, ts] of entry) if (ts < cutoff) entry.delete(id);
+    // After TTL prune, if still over the hard cap, drop oldest entries
+    // (insertion order in Map iteration). This handles the busy-chat
+    // case where 1000 messages all sent within 24h would otherwise
+    // leak.
+    if (entry.size > maxPerChat) {
+      const dropCount = entry.size - maxPerChat;
+      let i = 0;
+      for (const id of entry.keys()) {
+        if (i >= dropCount) break;
+        entry.delete(id);
+        i += 1;
+      }
+    }
+  }
+
+  function gcOuter() {
+    // Drop chat entries that are entirely empty (their inner Map was
+    // drained by gcInner). Without this the outer Map's chatId set
+    // grows by one per ever-active-then-idle chat, slowly leaking.
+    for (const [k, entry] of sentMessages) {
+      if (entry.size === 0) sentMessages.delete(k);
+    }
+  }
+
+  function record(chatId, messageId) {
+    if (chatId == null || messageId == null) return;
+    const key = chatKey(chatId);
+    let entry = sentMessages.get(key);
+    if (!entry) {
+      entry = new Map();
+      sentMessages.set(key, entry);
+    }
+    entry.set(messageId, clock());
+    if (entry.size > cleanupThreshold) gcInner(entry);
+    // Periodic outer sweep — runs only when the outer Map gets crowded.
+    if (sentMessages.size > outerSweepThreshold) gcOuter();
+  }
+
+  function wasSent(chatId, messageId) {
+    if (chatId == null || messageId == null) return false;
+    const key = chatKey(chatId);
+    const entry = sentMessages.get(key);
+    if (!entry) return false;
+    const ts = entry.get(messageId);
+    if (ts == null) return false;
+    if (clock() - ts > ttlMs) {
+      entry.delete(messageId);
+      // If we just emptied the inner Map, drop the outer entry too.
+      if (entry.size === 0) sentMessages.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  function size() {
+    let total = 0;
+    for (const entry of sentMessages.values()) total += entry.size;
+    return total;
+  }
+
+  function chatCount() { return sentMessages.size; }
+
+  function clear() {
+    sentMessages.clear();
+  }
+
+  return { record, wasSent, size, chatCount, clear };
+}
+
+module.exports = {
+  createSentCache,
+  TTL_MS,
+  CLEANUP_THRESHOLD,
+  MAX_PER_CHAT,
+  OUTER_SWEEP_THRESHOLD,
+};