polygram 0.3.5 → 0.4.0

package/lib/telegram.js

@@ -20,6 +20,52 @@
  */
 
 const crypto = require('crypto');
+const { toTelegramMarkdown } = require('./telegram-format');
+const { isSafeToRetry } = 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
+// string is specific enough to pattern-match; on hit we retry without the
+// thread param so the reply still lands in the chat root.
+const THREAD_NOT_FOUND_RE = /(Bad Request:\s*message thread not found|TOPIC_DELETED)/i;
+
+function isThreadNotFound(err) {
+  const msg = err && (err.description || err.message);
+  return typeof msg === 'string' && THREAD_NOT_FOUND_RE.test(msg);
+}
+
+// Short linear backoff before the single pre-connect retry. 150ms is long
+// enough for DNS / local network glitches to clear, short enough that a
+// user turn finishing doesn't notice.
+const PRE_CONNECT_RETRY_DELAY_MS = 150;
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// Methods whose `text` / `caption` fields we auto-format into MarkdownV2.
+// Anything else passes through untouched (setMessageReaction, sendSticker,
+// deleteMessage, etc. have no text to format).
+const FORMATTABLE_METHODS = new Set(['sendMessage', 'editMessageText']);
+
+// Apply Claude-markdown → Telegram-MarkdownV2 conversion in-place on the
+// params object. Skipped if:
+//   - Method doesn't carry formattable text.
+//   - Caller already set a parse_mode (respect explicit choice).
+//   - Caller opted out via meta.plainText.
+// On any conversion failure we silently fall through to plain text.
+function applyFormatting(method, params, meta) {
+  if (meta.plainText === true) return;
+  if (!FORMATTABLE_METHODS.has(method)) return;
+  if (params.parse_mode != null) return;
+  const field = params.text ? 'text' : (params.caption ? 'caption' : null);
+  if (!field) return;
+  const { text: converted, parseMode } = toTelegramMarkdown(params[field]);
+  if (parseMode) {
+    params[field] = converted;
+    params.parse_mode = parseMode;
+  }
+}
 
 // Synthetic negative msg_id for a pending outbound row. 48 random bits — the
 // birthday bound for collision within the (chat_id, msg_id) unique constraint
@@ -48,9 +94,15 @@ function deriveOutboundText(method, params, meta) {
 async function send({ bot, method, params, db = null, meta = {}, logger = console }) {
   const chatId = params.chat_id != null ? String(params.chat_id) : null;
   const threadId = params.message_thread_id != null ? String(params.message_thread_id) : null;
+  // Capture outbound text BEFORE markdown-escaping so the transcript stays
+  // human-readable. "Mr. O'Brien said 3.14" is searchable; "Mr\. O'Brien
+  // said 3\.14" is not. The user's chat view shows the rendered text, which
+  // matches the DB row modulo heading/bullet downgrades.
   const text = deriveOutboundText(method, params, meta);
   const tracksMessage = !METHODS_WITHOUT_MSG.has(method);
 
+  applyFormatting(method, params, meta);
+
   let rowId = null;
   if (db && tracksMessage && chatId) {
     const pendingId = nextPendingId();
@@ -73,16 +125,55 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   }
 
   let res;
+  const attempt = async (p) => bot.api.raw[method](p);
   try {
-    res = await bot.api.raw[method](params);
+    try {
+      res = await attempt(params);
+    } catch (err) {
+      // Pre-connect errors (DNS flap, TCP refused, net unreach) never
+      // reached Telegram, so retrying can't double-send. Retry ONCE after
+      // a short delay before treating as fatal. Post-connect errors
+      // (ETIMEDOUT, EPIPE, 5xx) are NOT retried — the message might have
+      // landed server-side.
+      if (isSafeToRetry(err)) {
+        try { db?.logEvent('telegram-retry', { chat_id: chatId, method, code: err.code, name: err.name }); }
+        catch {}
+        await sleep(PRE_CONNECT_RETRY_DELAY_MS);
+        res = await attempt(params);
+      } else {
+        throw err;
+      }
+    }
   } catch (err) {
-    if (rowId != null && db) {
-      try { db.markOutboundFailed(rowId, err.message); }
-      catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
-      try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: err.message }); }
-      catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
+    // Forum topic was deleted mid-turn — retry to chat root rather than
+    // failing the whole reply. Only for methods that accept a thread id
+    // (send*), and only once per call.
+    if (isThreadNotFound(err) && params.message_thread_id != null) {
+      const retryParams = { ...params };
+      delete retryParams.message_thread_id;
+      try {
+        logger.error?.(`[telegram] ${method}: thread gone, retrying without thread_id`);
+        res = await bot.api.raw[method](retryParams);
+        try { db?.logEvent('telegram-thread-fallback', { chat_id: chatId, method, original_thread_id: String(params.message_thread_id) }); }
+        catch {}
+      } catch (err2) {
+        if (rowId != null && db) {
+          try { db.markOutboundFailed(rowId, err2.message); }
+          catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
+          try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: err2.message }); }
+          catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
+        }
+        throw err2;
+      }
+    } else {
+      if (rowId != null && db) {
+        try { db.markOutboundFailed(rowId, err.message); }
+        catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
+        try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: err.message }); }
+        catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
+      }
+      throw err;
     }
-    throw err;
   }
 
   if (rowId != null && db) {

package/lib/typing-indicator.js

@@ -0,0 +1,143 @@
+/**
+ * Typing indicator with circuit breaker.
+ *
+ * Problem: sendChatAction('typing') is called every 4s while a turn is in
+ * flight. If the bot was removed from a chat, blocked by a user, or the
+ * chat was deleted, the API returns 401 Forbidden. The naive `.catch(()=>{})`
+ * that polygram had before meant we'd keep hammering the API for the
+ * duration of the (already-doomed) turn — hundreds of failed requests that
+ * chip away at rate-limit budget and drown real signal in logs.
+ *
+ * Fix (mirrors OpenClaw's createTelegramSendChatActionHandler pattern):
+ * per-chat circuit breaker with exponential backoff. After N consecutive
+ * 401s we suspend for this chat entirely — no more typing pings until the
+ * next successful turn resets the counter.
+ *
+ * State is per-chat so one dead chat doesn't silence the bot everywhere.
+ * We keep it in-memory (not DB-persisted) — restart clears and we'll find
+ * out again the first time we try; the cost of being re-wrong is just a
+ * handful of 401s, not worth persisting.
+ */
+
+const DEFAULT_INTERVAL_MS = 4000;
+const DEFAULT_MAX_CONSECUTIVE_401 = 10;
+const DEFAULT_MAX_BACKOFF_MS = 300_000; // 5 min — matches OpenClaw
+
+// Shared state keyed by chat_id. Exported via resetChatTypingState() for tests.
+const chatState = new Map();
+
+function getState(chatId) {
+  let s = chatState.get(chatId);
+  if (!s) {
+    s = { failures: 0, suspendedUntil: 0 };
+    chatState.set(chatId, s);
+  }
+  return s;
+}
+
+function isAuthFailure(err) {
+  const code = err?.error_code ?? err?.status;
+  const desc = err?.description || err?.message || '';
+  return code === 401 || code === 403 || /Forbidden|Unauthorized|bot was blocked|chat not found/i.test(desc);
+}
+
+// Exponential backoff: 1s, 2s, 4s, 8s, …, capped at maxBackoffMs.
+function backoffDelay(failures, maxBackoffMs) {
+  const ms = Math.min(maxBackoffMs, 1000 * Math.pow(2, Math.max(0, failures - 1)));
+  return ms;
+}
+
+/**
+ * Start the typing-indicator loop for a chat. Returns a stop function.
+ *
+ * @param {object} deps
+ * @param {import('grammy').Bot} deps.bot
+ * @param {string|number} deps.chatId
+ * @param {string} [deps.threadId]
+ * @param {number} [deps.intervalMs]
+ * @param {number} [deps.maxConsecutive401]
+ * @param {number} [deps.maxBackoffMs]
+ * @param {object} [deps.logger] - { error, log } — default console
+ * @param {(evt: {kind: string, chat_id: string, detail?: object}) => void} [deps.onEvent]
+ *     Hook for polygram's `events` DB log.
+ */
+function startTyping({
+  bot, chatId, threadId,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  maxConsecutive401 = DEFAULT_MAX_CONSECUTIVE_401,
+  maxBackoffMs = DEFAULT_MAX_BACKOFF_MS,
+  logger = console,
+  onEvent = null,
+} = {}) {
+  const key = String(chatId);
+  const opts = threadId ? { message_thread_id: threadId } : {};
+  let timer = null;
+  let stopped = false;
+
+  const tick = async () => {
+    if (stopped) return;
+    const s = getState(key);
+    if (s.suspendedUntil > Date.now()) return;
+    try {
+      await bot.api.sendChatAction(chatId, 'typing', opts);
+      // Success — reset failure counter.
+      if (s.failures > 0) {
+        onEvent?.({ kind: 'typing-recovered', chat_id: key, detail: { after_failures: s.failures } });
+      }
+      s.failures = 0;
+      s.suspendedUntil = 0;
+    } catch (err) {
+      if (!isAuthFailure(err)) {
+        // Other errors (network blip, 500, etc.): don't open the circuit.
+        // Let the next tick try again. Log once at high verbosity.
+        logger.error?.(`[typing] ${key}: ${err?.description || err?.message}`);
+        return;
+      }
+      s.failures += 1;
+      if (s.failures >= maxConsecutive401) {
+        // Circuit fully open — suspend for the maxBackoffMs window; won't
+        // try again until then. Successful turns (or a subsequent tick past
+        // the suspend window) will test the waters.
+        s.suspendedUntil = Date.now() + maxBackoffMs;
+        onEvent?.({ kind: 'typing-suspended', chat_id: key, detail: {
+          failures: s.failures, suspend_ms: maxBackoffMs,
+        } });
+        logger.error?.(`[typing] ${key}: ${s.failures} consecutive auth failures; suspending ${maxBackoffMs / 1000}s`);
+      } else {
+        // Partial open — back off for an exponentially growing window.
+        s.suspendedUntil = Date.now() + backoffDelay(s.failures, maxBackoffMs);
+      }
+    }
+  };
+
+  // Fire once immediately, then every intervalMs.
+  tick();
+  timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+
+  return () => {
+    stopped = true;
+    if (timer) clearInterval(timer);
+    timer = null;
+  };
+}
+
+function resetChatTypingState(chatId) {
+  if (chatId == null) chatState.clear();
+  else chatState.delete(String(chatId));
+}
+
+function getChatTypingState(chatId) {
+  return chatState.get(String(chatId));
+}
+
+module.exports = {
+  startTyping,
+  resetChatTypingState,
+  getChatTypingState,
+  isAuthFailure,
+  backoffDelay,
+  DEFAULT_INTERVAL_MS,
+  DEFAULT_MAX_CONSECUTIVE_401,
+  DEFAULT_MAX_BACKOFF_MS,
+};

package/migrations/005-polling-state.sql

@@ -0,0 +1,14 @@
+-- Persist grammy's update offset so a polygram restart doesn't re-process
+-- the entire getUpdates backlog from the last 24h. Grammy's in-memory
+-- offset resets to 0 on boot; Telegram replies with every unconfirmed
+-- update. For a bot that went down overnight with active chats, that can
+-- mean re-running dozens of turns on stale messages.
+--
+-- One row per bot. Row is upserted on every successful getUpdates batch
+-- that returned at least one update.
+
+CREATE TABLE IF NOT EXISTS polling_state (
+  bot_name       TEXT PRIMARY KEY,
+  last_update_id INTEGER NOT NULL,
+  ts             INTEGER NOT NULL
+);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "polygram",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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": {
     "polygram": "polygram.js",
     "polygram-split-db": "scripts/split-db.js",
     "polygram-ipc": "scripts/ipc-smoke.js",
-    "polygram-smoke": "scripts/smoke.js"
+    "polygram-doctor": "scripts/doctor.js"
   },
   "files": [
     "polygram.js",
@@ -16,7 +16,7 @@
     "migrations/",
     "scripts/split-db.js",
     "scripts/ipc-smoke.js",
-    "scripts/smoke.js",
+    "scripts/doctor.js",
     "skills/",
     "commands/",
     ".claude-plugin/",
@@ -61,6 +61,7 @@
   "type": "commonjs",
   "dependencies": {
     "better-sqlite3": "^12.9.0",
-    "grammy": "^1.42.0"
+    "grammy": "^1.42.0",
+    "telegramify-markdown": "^1.3.3"
   }
 }