polygram 0.6.12 → 0.6.14

package/.claude-plugin/plugin.json

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

@@ -110,7 +110,7 @@ Practical differences that matter for migration:
 
 ## Install
 
-Requires Node 20+.
+Requires Node 22+ (24 recommended; native test coverage is stable in 22).
 
 ```bash
 # Global binary:
@@ -256,11 +256,20 @@ Per-bot flags:
 
 - `allowConfigCommands: true` — enables `/model`, `/effort`, `/pair-code`,
   `/pairings`, `/unpair`.
-- `streamReplies: true` — live-edit the Telegram message as Claude works.
+- `streamMinChars` (default 30) — debounce before the first stream edit.
+- `streamThrottleMs` (default 1000, min 250) — stream edit cadence.
 - `voice: { enabled, provider: "openai"|"local", ... }` — Whisper
   transcription settings.
 - `approvals: { adminChatId, timeoutMs, gatedTools, ... }` — which tool
   calls require an inline-keyboard approval and where to post the card.
+- `attachmentConcurrency` (default 6) — parallel Telegram file
+  downloads per turn. Cap is conservative against Telegram's
+  ~30 req/s/bot rate limit.
+- `queueWarnThreshold` (default 20) — fires a `queue-depth-warning`
+  event when in-flight handlers for a session exceed this.
+- `replayWindowMs` (default 180000 = 3 min) — boot replay only
+  resurrects interrupted turns younger than this. Longer outages drop
+  the queue rather than re-dispatching ancient work.
 
 See `config.example.json` for the full schema.
 
@@ -351,7 +360,8 @@ foreign-chat clicks are rejected. Default-deny on IPC error.
 ## Development
 
 ```bash
-npm test        # 470 tests, 110 suites, node:test, no external services
+npm test           # 494 tests, 114 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
 npm run ipc-smoke -- my-bot
@@ -383,11 +393,10 @@ tests/*.test.js                   node:test
 - Claude Code only. No abstraction over other AIs.
 - macOS LaunchAgent plists included; Linux systemd units are not (easy
   to adapt).
-- On FileVault-on macOS, the daemon's LaunchAgents fire via shumabit's
-  own GUI login — there's no auto-start without the keychain being
-  unlocked, so a one-time Fast User Switch into the daemon's user
-  after each reboot is the supported pattern. See
-  `skills/infrastructure/SKILL.md` in the source repo for details.
+- On FileVault-on macOS, the daemon's LaunchAgents fire via the daemon
+  user's own GUI login — there's no auto-start without the keychain
+  being unlocked, so a one-time Fast User Switch into the daemon's
+  user after each reboot is the supported pattern.
 
 ## Roadmap
 

package/config.example.json

@@ -11,6 +11,10 @@
       "_comment_stream": "Streaming is always on. `streamMinChars` sets the initial-send debounce (default 30) — short responses below that stay idle until the final result. `streamThrottleMs` sets the edit cadence (default 1000ms, min 250).",
       "streamMinChars": 30,
       "streamThrottleMs": 1000,
+      "_comment_ops_tunings": "Optional per-bot operational knobs. `attachmentConcurrency` caps parallel Telegram file downloads per turn (default 6, well under Telegram's 30 req/s/bot limit). `queueWarnThreshold` fires a `queue-depth-warning` event when in-flight handlers exceed it (default 20). `replayWindowMs` bounds boot replay so an outage longer than this won't resurrect ancient interrupted turns (default 180000 = 3 min).",
+      "attachmentConcurrency": 6,
+      "queueWarnThreshold": 20,
+      "replayWindowMs": 180000,
       "_comment_pairedChatDefaults": "When a user sends /pair <CODE> from a private chat that isn't in config.chats yet, polygram auto-creates a chat entry using these defaults (merged over top-level `defaults`). Leave out `cwd` at your peril — without it, auto-onboarded DMs have no working directory and pairing will fail.",
       "pairedChatDefaults": {
         "agent": "admin",

package/lib/attachments.js

@@ -35,19 +35,23 @@ function filterAttachments(attachments, opts = {}) {
       rejected.push({ att: a, reason: `mime not allowed (${mime || 'unknown'})` });
       continue;
     }
-    const size = a.size || 0;
-    // Telegram sometimes reports file_size=0 or omits it. Those bypass the
-    // cap here but the download step MUST re-check Content-Length and actual
-    // bytes — see downloadAttachments in polygram.js.
-    if (size > maxFileBytes) {
-      rejected.push({ att: a, reason: `exceeds per-file cap (${maxFileBytes} bytes, got ${size})` });
+    const reported = a.size || 0;
+    // Telegram sometimes reports file_size=0 or omits it. Pre-0.6.14
+    // those bypassed the cumulative cap entirely (totalBytes + 0 always
+    // ≤ maxTotalBytes), so 5 size-0 attachments could blow through the
+    // 20 MB total cap. Treat unknown sizes as worst-case (= per-file
+    // cap) for budgeting; the per-file cap is still enforced live by
+    // the streaming download in polygram.js.
+    const sizeForBudget = reported > 0 ? reported : maxFileBytes;
+    if (reported > maxFileBytes) {
+      rejected.push({ att: a, reason: `exceeds per-file cap (${maxFileBytes} bytes, got ${reported})` });
       continue;
     }
-    if (totalBytes + size > maxTotalBytes) {
+    if (totalBytes + sizeForBudget > maxTotalBytes) {
       rejected.push({ att: a, reason: `exceeds total size cap (${maxTotalBytes} bytes)` });
       continue;
     }
-    totalBytes += size;
+    totalBytes += sizeForBudget;
     accepted.push(a);
   }
   return { accepted, rejected, totalBytes };

package/lib/db.js

@@ -338,22 +338,29 @@ function wrap(db) {
     // Prevents double-processing if a redelivered/replayed message has
     // already been answered.
     //
-    // We also count rows in the special 'failed crashed-mid-send' state
-    // as "probably sent" for dedupe. Those rows were created when polygram
-    // crashed AFTER inserting the pending row but before marking it sent
-    // — the API call may or may not have actually reached Telegram. The
-    // boot-time markStalePending sweep flips them to 'failed' with the
-    // 'crashed-mid-send' sentinel error. Treating them as un-replied
-    // (status='sent' only) caused boot replay to re-dispatch and Telegram
-    // delivered the SAME answer twice. Treating them as replied risks the
-    // opposite (the user never got a reply because the API truly failed
-    // before reaching Telegram), but a missed reply is recoverable —
-    // the user resends — while a duplicate reply is not.
+    // Three states count as "probably sent":
+    //   - 'sent': the happy path.
+    //   - 'failed' with error='crashed-mid-send': polygram crashed
+    //     after inserting the pending row but before markOutboundSent.
+    //     The boot-time markStalePending sweep flipped them to this.
+    //   - 'pending' (0.6.14): markStalePending only flips rows older
+    //     than 60s, so a fast restart (boot replay fires in <60s) leaves
+    //     fresh pending rows in 'pending' state. Without counting them
+    //     here, the inbound looks unanswered and gets re-dispatched →
+    //     Telegram already delivered the original reply → duplicate.
+    //
+    // Treating ambiguous states as "replied" costs us occasional missed
+    // replies (recoverable: user resends) to prevent duplicates
+    // (irrecoverable: user has to mentally dedupe two answers).
     hasOutboundReplyTo({ chat_id, msg_id }) {
       const row = db.prepare(`
         SELECT 1 FROM messages
          WHERE chat_id = ? AND direction = 'out' AND reply_to_id = ?
-           AND (status = 'sent' OR (status = 'failed' AND error = 'crashed-mid-send'))
+           AND (
+             status = 'sent'
+             OR status = 'pending'
+             OR (status = 'failed' AND error = 'crashed-mid-send')
+           )
          LIMIT 1
       `).get(chat_id, msg_id);
       return !!row;

package/lib/media-group-buffer.js

@@ -21,19 +21,35 @@
  */
 
 const DEFAULT_FLUSH_MS = 500;
+// 0.6.14 caps. The buffer is a single in-memory Map shared across every
+// chat the bot serves; without bounds a hostile sender (or buggy client)
+// could keep entries retained indefinitely by drip-feeding siblings under
+// the flushMs window, OR balloon a single entry's messages array to the
+// point of OOM. Reasonable defaults for typical Telegram album behavior:
+// max 10 messages per group (Telegram's own album limit), max 64 entries
+// in flight (one per active chat is plenty), and a hard 5s wall-clock
+// retention regardless of arrivals.
+const DEFAULT_MAX_MESSAGES_PER_GROUP = 10;
+const DEFAULT_MAX_ENTRIES = 64;
+const DEFAULT_MAX_AGE_MS = 5_000;
 
 function createMediaGroupBuffer({
   flushMs = DEFAULT_FLUSH_MS,
+  maxMessagesPerGroup = DEFAULT_MAX_MESSAGES_PER_GROUP,
+  maxEntries = DEFAULT_MAX_ENTRIES,
+  maxAgeMs = DEFAULT_MAX_AGE_MS,
   onFlush,
   timerFn = setTimeout,
   clearTimerFn = clearTimeout,
+  nowFn = Date.now,
 } = {}) {
   if (typeof onFlush !== 'function') throw new Error('onFlush required');
-  const entries = new Map(); // key → { messages, timer }
+  const entries = new Map(); // key → { messages, timer, firstAddedTs }
 
   const flushKey = (key) => {
     const entry = entries.get(key);
     if (!entry) return;
+    if (entry.timer) clearTimerFn(entry.timer);
     entries.delete(key);
     // Defensive: onFlush errors must not break future group buffering.
     try { onFlush(entry.messages, key); }
@@ -43,10 +59,32 @@ function createMediaGroupBuffer({
   const add = (key, msg) => {
     let entry = entries.get(key);
     if (!entry) {
-      entry = { messages: [], timer: null };
+      // Cap total entries: if we're at the limit, force-flush the oldest
+      // first. Avoids unbounded memory if a hostile sender spams keys.
+      if (entries.size >= maxEntries) {
+        const oldestKey = entries.keys().next().value;
+        if (oldestKey !== undefined) flushKey(oldestKey);
+      }
+      entry = { messages: [], timer: null, firstAddedTs: nowFn() };
       entries.set(key, entry);
     }
     entry.messages.push(msg);
+
+    // Per-group size cap: flush immediately when we hit the limit.
+    if (entry.messages.length >= maxMessagesPerGroup) {
+      flushKey(key);
+      return;
+    }
+
+    // Per-group wall-clock cap: don't let drip-feeding indefinitely
+    // postpone the flush via the resetting timer. If the group has been
+    // open longer than maxAgeMs, flush now even though new siblings keep
+    // arriving.
+    if (nowFn() - entry.firstAddedTs >= maxAgeMs) {
+      flushKey(key);
+      return;
+    }
+
     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

package/lib/net-errors.js

@@ -83,6 +83,32 @@ function isTransientNetworkError(err) {
   return false;
 }
 
+/**
+ * Strip Telegram bot tokens from a message string before logging or
+ * persisting. The fetch-CDN URL embeds `bot${TOKEN}` literally, but
+ * various error stringifiers / proxy layers may leak the same token in
+ * other shapes — URL-encoded in query strings, percent-encoded
+ * (`bot1234%3AAAH…`), or as a bare `Authorization: Bearer …` header.
+ *
+ * Telegram tokens have the canonical shape `\d{8,10}:[A-Za-z0-9_-]{35}`
+ * — match on that shape directly so the leading `bot` literal isn't
+ * load-bearing. Three patterns:
+ *   1. `bot1234567:AAH…` (canonical, used by the file CDN URL)
+ *   2. `bot1234567%3AAAH…` (URL-encoded `:`)
+ *   3. bare token shape anywhere in the string
+ *
+ * Pattern 3 is intentionally broad — false positives (some random
+ * `1234567:abcdef…35chars` that isn't a token) are vanishingly rare.
+ */
+function redactBotToken(s) {
+  if (!s) return s;
+  return String(s)
+    .replace(/bot\d+(?::|%3A)[A-Za-z0-9_%-]+/gi, 'bot<redacted>')
+    .replace(/\b\d{8,10}:[A-Za-z0-9_-]{35}\b/g, '<redacted-token>')
+    .replace(/(Authorization:\s*Bearer\s+)\S+/gi, '$1<redacted>')
+    .replace(/(bot_token=)[^&\s]+/gi, '$1<redacted>');
+}
+
 module.exports = {
   PRE_CONNECT_ERROR_CODES,
   RECOVERABLE_ERROR_CODES,
@@ -91,4 +117,5 @@ module.exports = {
   isTransientNetworkError,
   extractCode,
   extractName,
+  redactBotToken,
 };

package/lib/telegram.js

@@ -21,7 +21,7 @@
 
 const crypto = require('crypto');
 const { toTelegramMarkdown } = require('./telegram-format');
-const { isSafeToRetry } = require('./net-errors');
+const { isSafeToRetry, redactBotToken } = require('./net-errors');
 
 // Topic deletion race: a user can delete a forum topic while a turn is in
 // flight, turning a valid `message_thread_id` into a 404. Telegram's error
@@ -175,18 +175,23 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
         catch {}
       } catch (err2) {
         if (rowId != null && db) {
-          try { db.markOutboundFailed(rowId, err2.message); }
+          // 0.6.14: redact bot tokens before persisting err.message —
+          // some undici/network error shapes embed the request URL
+          // (which carries `bot${TOKEN}`) into err.message.
+          const safe2 = redactBotToken(err2.message);
+          try { db.markOutboundFailed(rowId, safe2); }
           catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
-          try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: err2.message }); }
+          try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: safe2 }); }
           catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
         }
         throw err2;
       }
     } else {
       if (rowId != null && db) {
-        try { db.markOutboundFailed(rowId, err.message); }
+        const safe = redactBotToken(err.message);
+        try { db.markOutboundFailed(rowId, safe); }
         catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
-        try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: err.message }); }
+        try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: safe }); }
         catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
       }
       throw err;

package/ops/polygram.plist.example

@@ -22,7 +22,7 @@
     <key>ProgramArguments</key>
     <array>
         <string>/opt/homebrew/bin/node</string>
-        <string>/Users/YOURNAME/polygram/bridge.js</string>
+        <string>/Users/YOURNAME/polygram/polygram.js</string>
         <string>--bot</string>
         <string>BOTNAME</string>
     </array>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "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": {
@@ -26,12 +26,14 @@
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
+    "coverage": "node --test --experimental-test-coverage tests/*.test.js",
+    "coverage:lcov": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info tests/*.test.js",
     "start": "node polygram.js",
     "split-db": "node scripts/split-db.js",
     "ipc-smoke": "node scripts/ipc-smoke.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "keywords": [
     "telegram",

package/polygram.js

@@ -34,6 +34,7 @@ const { transcribe: transcribeVoice, isVoiceAttachment } = require('./lib/voice'
 const { createStreamer } = require('./lib/stream-reply');
 const { isAbortRequest } = require('./lib/abort-detector');
 const { startTyping } = require('./lib/typing-indicator');
+const { redactBotToken } = require('./lib/net-errors');
 const { createReactionManager, classifyToolName } = require('./lib/status-reactions');
 const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
 const {
@@ -449,15 +450,46 @@ async function downloadOneAttachment(bot, token, chatId, msg, chatDir, att) {
     const url = `https://api.telegram.org/file/bot${token}/${fileInfo.file_path}`;
     const res = await fetch(url);
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    // Defense in depth: re-check size at download time. Telegram can
-    // omit file_size from the Message, or its value may not match what
-    // the CDN actually serves. Trust Content-Length and fall back to
-    // buffering with a ceiling.
+    // Three-layer size enforcement, in order of cheapness:
+    //   1. Content-Length header — fail-fast before reading any body.
+    //   2. Streaming chunk-by-chunk accumulation — abort the moment the
+    //      cumulative byte count crosses the cap. This is the layer that
+    //      protects against an attacker omitting Content-Length: pre-0.6.14
+    //      we read the whole `res.arrayBuffer()` into RAM first and only
+    //      then checked the size. With the per-bot ATTACHMENT_DOWNLOAD_
+    //      CONCURRENCY default of 6, six unbounded reads in flight could
+    //      pin arbitrary RSS — real OOM angle for a malicious upload.
+    //   3. Final post-buffer check is now redundant but cheap; left as
+    //      defense-in-depth in case the streaming logic is ever changed.
     const cl = parseInt(res.headers.get('content-length') || '0', 10);
     if (cl > MAX_FILE_BYTES) {
       throw new Error(`content-length ${cl} exceeds per-file cap ${MAX_FILE_BYTES}`);
     }
-    const buf = Buffer.from(await res.arrayBuffer());
+    let total = 0;
+    const chunks = [];
+    if (res.body && typeof res.body.getReader === 'function') {
+      const reader = res.body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > MAX_FILE_BYTES) {
+          try { await reader.cancel(); } catch {}
+          throw new Error(`stream ${total}+ bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
+        }
+        chunks.push(value);
+      }
+    } else {
+      // Fallback for runtimes without WHATWG streams (shouldn't fire on
+      // Node 22+). Same arrayBuffer path as before, with the post-check.
+      const ab = await res.arrayBuffer();
+      if (ab.byteLength > MAX_FILE_BYTES) {
+        throw new Error(`body ${ab.byteLength} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
+      }
+      chunks.push(new Uint8Array(ab));
+      total = ab.byteLength;
+    }
+    const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
     if (buf.length > MAX_FILE_BYTES) {
       throw new Error(`body ${buf.length} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
     }
@@ -503,10 +535,11 @@ async function downloadOneAttachment(bot, token, chatId, msg, chatDir, att) {
     // requirement) and some undici/network error variants stringify
     // the request including the URL into err.message. Persisting that
     // raw to attachments.download_error or stderr would leak the bot
-    // token to anyone with DB or log access. Strip any `bot<token>`
-    // pattern from the reason before storing/logging.
+    // token. 0.6.14: centralized in net-errors.redactBotToken which
+    // also handles URL-encoded (%3A) variants and bare token shapes
+    // missed by the original regex.
     const raw = (err.message || 'unknown').slice(0, 200);
-    const reason = raw.replace(/bot\d+:[A-Za-z0-9_-]+/g, 'bot<redacted>');
+    const reason = redactBotToken(raw);
     console.error(`[attach] download failed for ${att.name}: ${reason}`);
     dbWrite(() => db.markAttachmentFailed(att.id, reason),
       `markAttachmentFailed ${att.id}`);
@@ -779,17 +812,20 @@ function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
     console.error(`[${sessionKey}] Error:`, err.message);
     // Mark the row terminal so the right thing happens on next boot:
     // - aborted: user explicitly stopped → 'aborted' (not replayable)
-    // - shutting down: the error is "Process exited" / "Process killed"
-    //   from the SIGINT/SIGTERM tearing down claude mid-turn. Mark
-    //   'replay-pending' so the next boot picks it up via
-    //   getReplayCandidates. Pre-0.6.12 we marked 'failed' here, which
-    //   excluded the row from replay — a clean restart between user
-    //   send and reply silently dropped the turn forever.
+    // - shutting down on a NEW turn: 'replay-pending' so the next
+    //   boot picks it up via getReplayCandidates. Pre-0.6.12 we marked
+    //   'failed' here, which excluded the row from replay — a clean
+    //   restart between user send and reply silently dropped the turn.
+    // - shutting down on a REPLAY turn (msg._isReplay=true): keep
+    //   'replay-attempted' so the one-shot guard from 0.6.4 still
+    //   holds. Without this, a replay interrupted by another shutdown
+    //   would be promoted to 'replay-pending' and the next boot would
+    //   replay it AGAIN — infinite loop on chained shutdowns.
     // - everything else: 'failed' (genuine claude crash / timeout etc).
     const status = wasAborted
       ? 'aborted'
       : isShuttingDown
-        ? 'replay-pending'
+        ? (isReplay ? 'replay-attempted' : 'replay-pending')
         : 'failed';
     dbWrite(() => db.setInboundHandlerStatus({
       chat_id: chatId, msg_id: msg.message_id, status,
@@ -1162,16 +1198,21 @@ async function handleApprovalCallback(ctx) {
     id, status, by: userId, user, bot: BOT_NAME,
   });
 
-  // Edit the card to show the decision.
+  // Edit the card to show the decision. 0.6.14: routed through tg() so
+  // the edit gets the same write-before-send DB row, plain-text policy
+  // (no parse_mode injection from tool input), and logged failure
+  // surface as every other outbound. Pre-0.6.14 this called
+  // ctx.api.editMessageText directly — same bypass class as the two
+  // already-routed in 0.6.8 (approval-timeout and pair-onboarding).
   try {
     const fresh = approvals.getById(id);
-    await ctx.api.editMessageText(
-      row.approver_chat_id,
-      row.approver_msg_id,
-      approvalCardText(fresh, {
+    await tg(bot, 'editMessageText', {
+      chat_id: row.approver_chat_id,
+      message_id: row.approver_msg_id,
+      text: approvalCardText(fresh, {
         resolvedBy: `${status === 'approved' ? '✅ Approved' : '❌ Denied'} by ${user || userId}`,
       }),
-    );
+    }, { source: 'approval-card-decision', botName: BOT_NAME, plainText: true });
   } catch (err) {
     console.error(`[${BOT_NAME}] edit approval card failed: ${err.message}`);
   }