polygram 0.4.10 → 0.4.12

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "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 = 5;
+const SCHEMA_VERSION = 6;
 
 function open(dbPath) {
   const db = new Database(dbPath);
@@ -300,6 +300,64 @@ function wrap(db) {
         ON CONFLICT(bot_name) DO UPDATE SET last_update_id = excluded.last_update_id, ts = excluded.ts
       `).run(botName, lastUpdateId, Date.now());
     },
+
+    // Inbound handler lifecycle — see migrations/006-inbound-handler-status.sql.
+    // Called by handleMessage as the turn progresses. Used by boot replay to
+    // find work that was interrupted by a crash or restart.
+    setInboundHandlerStatus({ chat_id, msg_id, status }) {
+      return db.prepare(`
+        UPDATE messages SET handler_status = ?
+        WHERE chat_id = ? AND msg_id = ? AND direction = 'in'
+      `).run(status, chat_id, msg_id);
+    },
+
+    // Find inbound messages that were being processed when polygram stopped.
+    // Scoped by bot_name via the chat_id → config mapping, so each bot only
+    // replays its own turns on boot. Scoped by olderThanMs (default 30 min)
+    // so we never resurrect ancient messages after a long outage.
+    getReplayCandidates({ chatIds, olderThanMs = 30 * 60 * 1000, limit = 100 } = {}) {
+      if (!Array.isArray(chatIds) || chatIds.length === 0) return [];
+      const cutoff = Date.now() - olderThanMs;
+      const placeholders = chatIds.map(() => '?').join(',');
+      return db.prepare(`
+        SELECT id, chat_id, thread_id, msg_id, user, user_id, text, reply_to_id,
+               attachments_json, ts, handler_status
+          FROM messages
+         WHERE direction = 'in'
+           AND handler_status IN ('dispatched', 'processing', 'replay-pending')
+           AND chat_id IN (${placeholders})
+           AND ts > ?
+         ORDER BY ts ASC
+         LIMIT ?
+      `).all(...chatIds, cutoff, limit);
+    },
+
+    // Dedupe check: did we already send an outbound reply to this inbound?
+    // Prevents double-processing if a redelivered/replayed message has
+    // already been answered.
+    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'
+         LIMIT 1
+      `).get(chat_id, msg_id);
+      return !!row;
+    },
+
+    // On shutdown, mark any inbound rows still in-flight so the boot replay
+    // knows to pick them up. `sessionKey`s narrow the update to the sessions
+    // we're draining (useful if we ever do partial shutdown; otherwise leave
+    // null to mark all dispatched/processing rows for a bot).
+    markReplayPending({ botName, since }) {
+      const cutoff = since ?? Date.now() - 30 * 60 * 1000;
+      return db.prepare(`
+        UPDATE messages SET handler_status = 'replay-pending'
+         WHERE direction = 'in'
+           AND handler_status IN ('dispatched', 'processing')
+           AND bot_name = ?
+           AND ts > ?
+      `).run(botName, cutoff);
+    },
   };
 }
 

package/lib/process-manager.js

@@ -100,11 +100,52 @@ class ProcessManager {
     }
     if (this.procs.size >= this.cap) {
       const evicted = await this.evictLRU();
-      if (!evicted) throw new Error('LRU full: all processes in-flight');
+      if (!evicted) {
+        // All sessions are in-flight — wait for one to drain, then retry.
+        // Waiters are held in `this._lruWaiters` FIFO and signalled when any
+        // pending queue empties (see _maybeSignalLruWaiter).
+        await this._awaitLruSlot();
+        // After waking, try the whole path again — the evictLRU may now
+        // succeed, or an existing session may have been spawned for this key.
+        return this.getOrSpawn(sessionKey, spawnContext);
+      }
     }
     return this._spawn(sessionKey, spawnContext);
   }
 
+  // Hold a promise pair per waiter. _maybeSignalLruWaiter shifts the oldest
+  // waiter when a slot might have freed up. Each waiter has its own timer
+  // that rejects with 'LRU wait timeout' if no slot appears in time.
+  _awaitLruSlot({ timeoutMs = 5 * 60_000 } = {}) {
+    if (!this._lruWaiters) this._lruWaiters = [];
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject };
+      const timer = setTimeout(() => {
+        const idx = this._lruWaiters.indexOf(waiter);
+        if (idx !== -1) this._lruWaiters.splice(idx, 1);
+        this._logEvent('lru-wait-timeout', { cap: this.cap, queued_waiters: this._lruWaiters.length });
+        reject(new Error(`LRU wait timeout after ${timeoutMs / 1000}s`));
+      }, timeoutMs);
+      waiter.timer = timer;
+      this._lruWaiters.push(waiter);
+      this._logEvent('lru-wait', { cap: this.cap, queued_waiters: this._lruWaiters.length });
+    });
+  }
+
+  _maybeSignalLruWaiter() {
+    if (!this._lruWaiters || this._lruWaiters.length === 0) return;
+    // Only signal if there's actually capacity now (a session went idle
+    // or closed). Otherwise keep waiters sleeping for the next chance.
+    let hasIdle = false;
+    for (const v of this.procs.values()) {
+      if (!v.inFlight) { hasIdle = true; break; }
+    }
+    if (!hasIdle && this.procs.size >= this.cap) return;
+    const w = this._lruWaiters.shift();
+    clearTimeout(w.timer);
+    w.resolve();
+  }
+
   async evictLRU() {
     let victim = null;
     for (const [k, v] of this.procs) {
@@ -267,6 +308,8 @@ class ProcessManager {
           entry.pendingQueue[0].activate();
         } else {
           entry.inFlight = false;
+          // An entry just went idle → an LRU waiter might be able to run now.
+          this._maybeSignalLruWaiter();
           // Graceful drain-and-respawn: if caller asked for a respawn
           // (e.g. /model change) and we just emptied the queue, kill now
           // and fire onRespawn so the caller can post confirmation.
@@ -293,6 +336,8 @@ class ProcessManager {
         p.reject(new Error(`Process exited (code ${code})`));
       }
       this.procs.delete(sessionKey);
+      // A slot freed up → maybe an LRU waiter can run now.
+      this._maybeSignalLruWaiter();
       if (code !== 0 && ctx.existingSessionId && this.db?.clearSessionId) {
         this._logEvent('resume-fail', { session_key: sessionKey, session_id: ctx.existingSessionId, code });
         try { this.db.clearSessionId(sessionKey); } catch (err) {
@@ -410,6 +455,11 @@ class ProcessManager {
           maxTurnMs,
         );
         pending.maxTimer = maxTimer;
+        // Give callers a hook so they can transition user-visible state
+        // (e.g. status reaction "👀 queued" → "🤔 thinking") the moment
+        // Claude actually starts this pending, not the moment it arrived.
+        try { context?.onActivate?.(); }
+        catch (err) { this.logger.error(`[${entry.label}] onActivate: ${err.message}`); }
       };
 
       pending.resetIdleTimer = () => {

package/migrations/006-inbound-handler-status.sql

@@ -0,0 +1,27 @@
+-- Track the lifecycle state of inbound message processing so a polygram
+-- restart (SIGTERM, crash) can replay any turns that were in progress.
+--
+-- The existing `status` column on messages already tracks OUTBOUND state
+-- ('pending' / 'sent' / 'failed'). Rather than overload it with inbound
+-- semantics, add a dedicated column.
+--
+-- States for inbound:
+--   received  — row inserted by recordInbound, nothing else has happened
+--   dispatched — handleMessage started (attachment download, voice, format)
+--   processing — pm.send has written the prompt to claude's stdin
+--   replied    — outbound reply was sent successfully
+--   replay-pending — marked by graceful shutdown to be replayed on next boot
+--
+-- NULL is valid (for historical rows inserted before this migration).
+--
+-- The boot replay loop scans for rows where:
+--   direction = 'in'
+--   AND handler_status IN ('dispatched', 'processing', 'replay-pending')
+--   AND ts > now() - REPLAY_WINDOW_MS  (default 30 min — anything older is stale)
+-- and re-dispatches them.
+
+ALTER TABLE messages ADD COLUMN handler_status TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_messages_handler_status
+  ON messages(handler_status, ts)
+  WHERE handler_status IS NOT NULL;

package/package.json

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

@@ -562,15 +562,29 @@ async function sendToProcess(sessionKey, prompt, context = {}) {
 const CONCURRENT_WARN_THRESHOLD = 20;
 const inFlightHandlers = new Map(); // sessionKey → count
 
-// Sessions the operator just /stop'd (or natural-language "стоп"). Entries
-// suppress the generic "Sorry, I couldn't process" reply — the abort
-// handler already sent its own "Остановлено." ack, and handleMessage
-// rejections from the killed subprocess would otherwise spam a second
-// contradictory message.
-const abortedSessions = new Set();
+// Sessions the operator just /stop'd (or natural-language "стоп"). Keyed
+// by sessionKey → timestamp of abort. ANY pending that rejects within
+// ABORT_GRACE_MS of the mark is considered abort-caused — its generic
+// error reply is suppressed and the streamer warning is skipped.
+//
+// Timestamp model (vs the earlier "delete after first read" Set) fixes
+// the case where multiple pendings were in-flight at abort time: all of
+// them reject with "Process killed", all of them should be silent, not
+// just the first one.
+const ABORT_GRACE_MS = 15_000;
+const abortedSessions = new Map();
 
 function markSessionAborted(sessionKey) {
-  abortedSessions.add(sessionKey);
+  abortedSessions.set(sessionKey, Date.now());
+  // Sweep old entries opportunistically.
+  for (const [k, ts] of abortedSessions) {
+    if (Date.now() - ts > ABORT_GRACE_MS * 2) abortedSessions.delete(k);
+  }
+}
+
+function isSessionRecentlyAborted(sessionKey) {
+  const ts = abortedSessions.get(sessionKey);
+  return ts != null && (Date.now() - ts) < ABORT_GRACE_MS;
 }
 
 // Called by bot.on('message') for every regular (non-admin, non-pair)
@@ -586,9 +600,15 @@ function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
     }), 'log queue-depth-warning');
   }
   handleMessage(sessionKey, chatId, msg, bot).catch((err) => {
-    const wasAborted = abortedSessions.has(sessionKey);
-    if (wasAborted) abortedSessions.delete(sessionKey);
+    const wasAborted = isSessionRecentlyAborted(sessionKey);
     console.error(`[${sessionKey}] Error:`, err.message);
+    // Mark the row as 'failed' so boot replay doesn't re-dispatch it.
+    // Exception: aborted sessions → 'aborted' (same — not replayable).
+    // Shutdown case handled separately in the SIGTERM handler.
+    dbWrite(() => db.setInboundHandlerStatus({
+      chat_id: chatId, msg_id: msg.message_id,
+      status: wasAborted ? 'aborted' : 'failed',
+    }), 'set handler_status=failed/aborted');
     dbWrite(() => db.logEvent('handler-error', {
       chat_id: chatId, session_key: sessionKey,
       msg_id: msg?.message_id,
@@ -964,6 +984,12 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   const chatConfig = config.chats[chatId];
   if (!chatConfig) return;
 
+  // Mark the inbound row as 'dispatched' so the boot replay loop knows
+  // this turn started. Cleared to 'replied' (or 'failed') when done.
+  dbWrite(() => db.setInboundHandlerStatus({
+    chat_id: chatId, msg_id: msg.message_id, status: 'dispatched',
+  }), 'set handler_status=dispatched');
+
   const text = msg.text || msg.caption || '';
   const threadId = msg.message_thread_id;
   const threadIdStr = threadId?.toString() || null;
@@ -1246,7 +1272,11 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     },
     logError: (m) => console.error(`[${label}] ${m}`),
   });
-  reactor.setState('THINKING');
+  // Start at QUEUED (👀) so user sees their message was received but
+  // not yet being worked on. pm calls context.onActivate when this
+  // pending becomes the queue head (Claude is actually starting it),
+  // at which point we flip to THINKING (🤔).
+  reactor.setState('QUEUED');
 
   try {
     // Pass streamer + reactor as per-turn context. pm's callbacks pick
@@ -1254,6 +1284,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     // get routed to their own streamer/reactor.
     const result = await sendToProcess(sessionKey, prompt, {
       streamer, reactor, sourceMsgId: msg.message_id,
+      onActivate: () => reactor.setState('THINKING'),
     });
     const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
 
@@ -1329,25 +1360,32 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     }
 
     console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
+    // Success: mark the inbound row 'replied' so boot replay doesn't
+    // pick it up again on restart.
+    dbWrite(() => db.setInboundHandlerStatus({
+      chat_id: chatId, msg_id: msg.message_id, status: 'replied',
+    }), 'set handler_status=replied');
   } catch (err) {
-    // Generic suffix — err.message can leak internal paths/state.
-    await streamer.finalize('', { errorSuffix: 'stream interrupted' }).catch(() => {});
-    // Signal the failure to the user's message reaction. Timeout gets its
-    // own face; anything else is generic error.
-    if (/wall-clock ceiling|idle with no Claude activity/i.test(err?.message || '')) {
-      reactor.setState('TIMEOUT');
+    // If the user just aborted this session, silently finalise the stream
+    // without the scary "⚠ stream interrupted" banner. The user has already
+    // seen their "Остановлено." ack; adding a warning to the partial bubble
+    // just reads as "something crashed".
+    const abortedByUser = isSessionRecentlyAborted(sessionKey);
+    if (abortedByUser) {
+      await streamer.finalize('').catch(() => {});
+      // Leave reaction as-is — no 🤯 / 😨; user asked for stop.
     } else {
-      reactor.setState('ERROR');
+      await streamer.finalize('', { errorSuffix: 'stream interrupted' }).catch(() => {});
+      if (/wall-clock ceiling|idle with no Claude activity/i.test(err?.message || '')) {
+        reactor.setState('TIMEOUT');
+      } else {
+        reactor.setState('ERROR');
+      }
     }
     throw err;
   } finally {
     stopTyping();
-    // streamer is per-turn and not stored in any session Map in 0.4.8
-    // Give the reactor a beat to flush the terminal state (DONE/ERROR/TIMEOUT
-    // bypass throttle so this is instant in practice; the stop() below
-    // guards against any late transition leaking after the turn ends).
     reactor.stop();
-    // reactor is per-turn and not stored in any session Map in 0.4.8
   }
 }
 
@@ -1930,22 +1968,69 @@ async function main() {
 
   bot = createBot(config.bot.token);
 
-  const shutdown = () => {
+  // Graceful shutdown: stop accepting new inbound, drain in-flight pendings
+  // up to SHUTDOWN_DRAIN_MS, then mark anything still unfinished so boot
+  // replay picks it up. Prevents "Sorry, I couldn't process that message"
+  // from showing on every restart.
+  const SHUTDOWN_DRAIN_MS = 30_000;
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     console.log('\nShutting down...');
+    // 1. Stop accepting new inbound first so nothing new queues behind the drain.
     if (bot && bot._stop) bot._stop();
+
+    // 2. Drain in-flight handlers. Wait for inFlightHandlers to empty or
+    //    SHUTDOWN_DRAIN_MS to elapse. pm handlers resolve naturally when
+    //    result events arrive; the dispatcher's .finally decrements.
+    const drainStart = Date.now();
+    while (inFlightHandlers.size > 0) {
+      if (Date.now() - drainStart >= SHUTDOWN_DRAIN_MS) break;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    const drainElapsed = Date.now() - drainStart;
+    let remaining = 0;
+    for (const n of inFlightHandlers.values()) remaining += n;
+
+    // 3. Anything still in-flight → mark in DB as replay-pending so the
+    //    next polygram boot re-dispatches it. User never sees an error.
+    if (remaining > 0 && db) {
+      try {
+        const res = db.markReplayPending({ botName: BOT_NAME });
+        dbWrite(() => db.logEvent('shutdown-drain', {
+          bot: BOT_NAME,
+          in_flight: remaining,
+          replay_marked: res?.changes ?? 0,
+          elapsed_ms: drainElapsed,
+        }), 'log shutdown-drain');
+        console.log(`[shutdown] drained ${drainElapsed}ms, ${remaining} still in-flight, ${res?.changes ?? 0} rows marked replay-pending`);
+      } catch (err) {
+        console.error(`[shutdown] markReplayPending failed: ${err.message}`);
+      }
+    } else if (db) {
+      dbWrite(() => db.logEvent('shutdown-drain', {
+        bot: BOT_NAME,
+        in_flight: 0,
+        elapsed_ms: drainElapsed,
+      }), 'log shutdown-drain');
+      console.log(`[shutdown] clean drain in ${drainElapsed}ms`);
+    }
+
+    // 4. Remaining shutdown: approvals sweeper, IPC, resolve hook waiters,
+    //    kill pm subprocesses, close DB.
     if (approvalSweepTimer) clearInterval(approvalSweepTimer);
     if (ipcCloser) ipcCloser.close().catch(() => {});
     try { fs.unlinkSync(ipcServer.secretPathFor(BOT_NAME)); } catch {}
-    // Resolve any blocked hook waiters so Claude processes don't hang.
     for (const list of approvalWaiters.values()) {
       for (const fn of list) { try { fn('cancelled', 'polygram shutting down'); } catch {} }
     }
     approvalWaiters.clear();
-    if (pm) pm.shutdown().catch(() => {});
+    if (pm) await pm.shutdown().catch(() => {});
     if (db) {
       try { db.logEvent('polygram-stop'); db.raw.close(); } catch {}
     }
-    setTimeout(() => process.exit(0), 1000);
+    setTimeout(() => process.exit(0), 100);
   };
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
@@ -1970,6 +2055,65 @@ async function main() {
   }
   approvalSweepTimer = startApprovalSweeper();
 
+  // Boot replay: re-dispatch any inbound turns that were interrupted by
+  // the previous polygram's shutdown or crash. These are rows marked
+  // 'dispatched', 'processing', or 'replay-pending' (set by the SIGTERM
+  // handler) — all within the last 30 min so we don't resurrect ancient
+  // work. Dedupe against already-sent outbound replies in case the
+  // previous instance DID answer before dying.
+  try {
+    const chatIds = Object.keys(config.chats);
+    if (chatIds.length > 0) {
+      const candidates = db.getReplayCandidates({ chatIds });
+      let replayed = 0;
+      let skipped = 0;
+      for (const row of candidates) {
+        if (db.hasOutboundReplyTo({ chat_id: row.chat_id, msg_id: row.msg_id })) {
+          // Already replied — just mark so we don't look at it again.
+          db.setInboundHandlerStatus({
+            chat_id: row.chat_id, msg_id: row.msg_id, status: 'replied',
+          });
+          skipped += 1;
+          continue;
+        }
+        // Reconstruct a minimal grammy-like Message object. Enough for
+        // dispatchRegularMessage (mention detect, abort, admin cmds,
+        // shouldHandle, enqueue). Attachments carry file_ids so the
+        // normal download path re-fetches on replay.
+        const reconstructed = {
+          chat: { id: Number(row.chat_id), type: row.chat_id.startsWith('-') ? 'supergroup' : 'private' },
+          message_id: row.msg_id,
+          from: { id: row.user_id, first_name: row.user },
+          text: row.text || '',
+          date: Math.floor(row.ts / 1000),
+          ...(row.thread_id && { message_thread_id: Number(row.thread_id) }),
+          ...(row.reply_to_id && { reply_to_message: { message_id: row.reply_to_id } }),
+        };
+        // Attach already-extracted attachments via the media-group shortcut
+        // field so extractAttachments picks them up without re-parsing
+        // grammy fields that don't exist on this reconstructed object.
+        if (row.attachments_json) {
+          try {
+            reconstructed._mergedAttachments = JSON.parse(row.attachments_json);
+          } catch {}
+        }
+        const chatConfig = config.chats[row.chat_id];
+        if (!chatConfig) { skipped += 1; continue; }
+        const sessionKey = getSessionKey(row.chat_id, row.thread_id, chatConfig);
+        dispatchHandleMessage(sessionKey, row.chat_id, reconstructed, bot);
+        replayed += 1;
+      }
+      if (candidates.length > 0) {
+        console.log(`[replay] ${replayed} turns re-dispatched, ${skipped} skipped (already replied or no chat config)`);
+        dbWrite(() => db.logEvent('replay-on-boot', {
+          bot: BOT_NAME, replayed, skipped, total: candidates.length,
+        }), 'log replay-on-boot');
+      }
+    }
+  } catch (err) {
+    console.error(`[replay] boot replay failed: ${err.message}`);
+  }
+
   console.log(`[${BOT_NAME}] Starting...`);
   const pollPromise = pollBot(bot).catch(err => {
     console.error(`[${BOT_NAME}] Fatal:`, err.message);