polygram 0.3.5 → 0.4.0

package/.claude-plugin/plugin.json

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

@@ -117,35 +117,39 @@ For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 
 ## Health check
 
-Every install includes a round-trip smoke test:
+Every install includes `polygram-doctor` for operational diagnostics:
 
 ```bash
-polygram-smoke --bot my-bot --to <admin-chat-id>
+polygram-doctor --bot my-bot
 ```
 
-Exits 0 on success, 1 on any step failure. It verifies:
+Runs static checks without touching live chats: config parseable,
+DB schema current, IPC socket up, Telegram `getMe` succeeds, recent
+errors from the last 24h, stuck pending outbound rows, pending
+approvals. Exits 0 on pass, 1 on any failure (add `--strict` to
+fail on warnings too).
 
-1. **IPC ping** — the per-bot unix socket is up
-2. **Outbound round-trip** — IPC `send` op → Telegram API → returns a `msg_id`
-3. **DB read-back** — that `msg_id` is in the `messages` table with
-   `direction='out'`, `status='sent'`, matching text
-
-A sample passing run:
+Output:
 
 ```
-✅ ipc-ping — bot=my-bot
-✅ outbound-send — msg_id=12345
-✅ db-readback — sent row confirmed (source=polygram-smoke)
-
-polygram-smoke: PASS  my-bot  2026-04-22T15:30:00.000Z
+✅ config — bot found, 4 chat(s), admin=68861949
+✅ db — schema v5
+✅ ipc — socket responsive, bot=my-bot
+✅ telegram — @my_bot (My Bot)
+✅ recent-errors — no failure events in last 24h
+✅ pending-outbound — no stale pending outbound rows
+✅ approvals — no pending approvals
+
+7 ok / 0 warn / 0 fail  (bot=my-bot)
 ```
 
-Flags: `--db <path>` or `POLYGRAM_DB` for non-default DB location;
-`--timeout-ms <ms>` (default 8000).
+Flags: `--json` for machine-readable output, `--db <path>` /
+`POLYGRAM_DB` for non-default DB location, `--timeout-ms <ms>`
+(default 8000), `--strict` to exit 1 on warnings.
 
-The test sends a tagged message (`polygram-smoke:<timestamp>`) silently
-to the target chat. Use your own DM as `--to` so the marker arrives
-somewhere you control.
+For a full outbound round-trip verification (the old `polygram-smoke`),
+add `--roundtrip --to <chat_id>`. That sends a silent tagged message
+and verifies it lands in the DB with `status=sent`.
 
 ## Install as a Claude Code plugin
 

package/config.example.json

@@ -8,9 +8,17 @@
       "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
       "adminChatId": "123456789",
       "needsToken": false,
-      "streamReplies": true,
+      "_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": 500,
+      "streamThrottleMs": 1000,
+      "_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",
+        "cwd": "/Users/you/admin-agent",
+        "model": "sonnet",
+        "effort": "medium",
+        "timeout": 600
+      },
       "voice": {
         "enabled": true,
         "provider": "openai",

package/lib/abort-detector.js

@@ -0,0 +1,63 @@
+/**
+ * Detect "stop working on the current turn" signals in natural language.
+ *
+ * Mirrors OpenClaw's isAbortRequestText semantics: users should be able to
+ * say "stop" / "подожди" / "cancel" / or just `/stop` and have polygram
+ * interrupt the in-flight turn instead of queueing the message behind it.
+ *
+ * Conservative on purpose. False positives hijack user intent — "stop using
+ * emoji" should NOT abort. So we require:
+ *   1. The message (after stripping leading @-mention + trailing punctuation)
+ *      must be an exact match against a known abort phrase, OR
+ *   2. It must start with an explicit slash command: /stop, /abort, /cancel.
+ *
+ * Not detected (on purpose):
+ *   - "wait a sec while I finish typing" → too long, real content
+ *   - "stop using markdown" → has trailing content
+ *   - "I said stop" → not at start / not exact match
+ */
+
+const ABORT_PHRASES = new Set([
+  // English
+  'stop', 'wait', 'cancel', 'abort', 'halt',
+  'hold on', 'hold up', 'nevermind', 'never mind', 'nvm',
+  'forget it', 'forget that',
+  // Russian
+  'стоп', 'подожди', 'подожди-ка', 'остановись', 'остановить',
+  'отмена', 'отставить', 'прекрати', 'прекращай', 'хватит',
+  'забей', 'не надо', 'отмени',
+]);
+
+const ABORT_SLASH_RE = /^\/(stop|abort|cancel)(\s|$|@)/i;
+
+// Strip leading @botname mentions ("@shumobot stop" → "stop"). Matches any
+// @-prefixed word up to the first whitespace — loose because we check the
+// remainder against an allowlist anyway.
+const LEADING_MENTION_RE = /^@\S+\s+/;
+
+// Trailing punctuation that doesn't change the meaning.
+const TRAILING_PUNCT_RE = /[.!?,;:\s]+$/;
+
+function normalize(text) {
+  if (typeof text !== 'string') return '';
+  return text
+    .trim()
+    .replace(LEADING_MENTION_RE, '')
+    .replace(TRAILING_PUNCT_RE, '')
+    .toLowerCase();
+}
+
+function isAbortRequest(text) {
+  if (!text || typeof text !== 'string') return false;
+  // Explicit slash command: /stop, /abort, /cancel (optionally @-suffixed)
+  if (ABORT_SLASH_RE.test(text.trim())) return true;
+
+  const n = normalize(text);
+  if (!n) return false;
+  // Cap length: a long message that happens to start with "stop" is real
+  // content, not an abort. 40 chars covers all phrases above with headroom.
+  if (n.length > 40) return false;
+  return ABORT_PHRASES.has(n);
+}
+
+module.exports = { isAbortRequest, ABORT_PHRASES };

package/lib/db.js

@@ -285,6 +285,21 @@ function wrap(db) {
       if (botName) return markStalePendingForBotStmt.run(cutoff, botName);
       return markStalePendingStmt.run(cutoff);
     },
+
+    // Polling offset persistence — see migrations/005-polling-state.sql.
+    // Exposed as its own pair of calls (not lazy-prepared) so tests can
+    // round-trip them without going through the full polygram boot flow.
+    getPollingOffset(botName) {
+      const row = db.prepare('SELECT last_update_id FROM polling_state WHERE bot_name = ?').get(botName);
+      return row?.last_update_id ?? 0;
+    },
+    savePollingOffset(botName, lastUpdateId) {
+      db.prepare(`
+        INSERT INTO polling_state (bot_name, last_update_id, ts)
+        VALUES (?, ?, ?)
+        ON CONFLICT(bot_name) DO UPDATE SET last_update_id = excluded.last_update_id, ts = excluded.ts
+      `).run(botName, lastUpdateId, Date.now());
+    },
   };
 }
 

package/lib/net-errors.js

@@ -0,0 +1,94 @@
+/**
+ * Network error classification + safe-retry helpers.
+ *
+ * Polygram's outbound policy has been "write DB row first, then send; never
+ * auto-retry" — correctly paranoid about double-sends. That leaves a gap
+ * though: transient pre-connect failures (DNS flap, local network blip,
+ * TCP refused) never actually hit Telegram. Retrying them once is safe
+ * because the request never reached the server — no risk of delivering
+ * the same message twice.
+ *
+ * Set names and error codes ported from OpenClaw's extensions/telegram/
+ * src/network-errors.ts, which came from production experience.
+ */
+
+// Pre-connect errors: the TCP/TLS handshake never completed, so the HTTP
+// request never went out. Retry is idempotent by definition.
+const PRE_CONNECT_ERROR_CODES = new Set([
+  'ECONNREFUSED',  // nothing listening on target port
+  'ENOTFOUND',     // DNS failed
+  'EAI_AGAIN',     // DNS timeout / temporary failure
+  'ENETUNREACH',   // no route to host (WAN drop)
+  'EHOSTUNREACH',  // host unreachable (local firewall / sleep)
+  'ECONNRESET',    // peer sent RST before reply — *usually* safe to retry;
+                   // technically the server might have started processing
+                   // before resetting. Include conservatively because the
+                   // alternative is a lost message. Telegram doesn't commit
+                   // a sendMessage server-side until it returns 200.
+]);
+
+// 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.
+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
+]);
+
+// Error.name values emitted by undici/node for transient conditions.
+const RECOVERABLE_ERROR_NAMES = new Set([
+  'AbortError',
+  'TimeoutError',
+  'FetchError',
+  'SocketError',
+]);
+
+function extractCode(err) {
+  if (!err) return null;
+  return err.code
+    || err.cause?.code
+    || err.errno
+    || null;
+}
+
+function extractName(err) {
+  if (!err) return null;
+  return err.name || err.cause?.name || null;
+}
+
+/**
+ * Can we safely retry this error ONCE without risking double-delivery?
+ * Only true for errors that definitionally occurred before the HTTP request
+ * reached the server.
+ */
+function isSafeToRetry(err) {
+  const code = extractCode(err);
+  return code != null && PRE_CONNECT_ERROR_CODES.has(code);
+}
+
+/**
+ * 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
+ * message might have landed?
+ */
+function isTransientNetworkError(err) {
+  if (!err) return false;
+  const code = extractCode(err);
+  if (code && (PRE_CONNECT_ERROR_CODES.has(code) || RECOVERABLE_ERROR_CODES.has(code))) {
+    return true;
+  }
+  const name = extractName(err);
+  if (name && RECOVERABLE_ERROR_NAMES.has(name)) return true;
+  return false;
+}
+
+module.exports = {
+  PRE_CONNECT_ERROR_CODES,
+  RECOVERABLE_ERROR_CODES,
+  RECOVERABLE_ERROR_NAMES,
+  isSafeToRetry,
+  isTransientNetworkError,
+  extractCode,
+  extractName,
+};

package/lib/process-manager.js

@@ -16,10 +16,13 @@ const DEFAULT_CAP = 10;
 const DEFAULT_KILL_TIMEOUT_MS = 3000;
 
 /**
- * Pull text from a stream-json `assistant` event.
+ * Pull user-visible text from a stream-json `assistant` event.
  * Claude Code emits one event per assistant step; each carries a
- * `message.content[]` of blocks. Text blocks have `{type:'text', text:'…'}`;
- * tool_use blocks we summarise inline so the user sees what Claude is doing.
+ * `message.content[]` of blocks. Only `text` blocks are returned —
+ * `tool_use` blocks still trigger the idle-timer reset in the caller
+ * (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.
  */
 function extractAssistantText(event) {
   const blocks = event?.message?.content;
@@ -29,8 +32,6 @@ function extractAssistantText(event) {
     if (!b) continue;
     if (b.type === 'text' && typeof b.text === 'string') {
       parts.push(b.text);
-    } else if (b.type === 'tool_use' && b.name) {
-      parts.push(`_Calling \`${b.name}\`…_`);
     }
   }
   return parts.join('\n\n').trim();
@@ -47,6 +48,7 @@ class ProcessManager {
     onResult = null,     // (sessionKey, event) → void (turn result)
     onClose = null,      // (sessionKey, code) → void
     onStreamChunk = null,// (sessionKey, partialText, entry) → void (per assistant event)
+    onToolUse = null,    // (sessionKey, toolName, entry) → void (per tool_use block)
   } = {}) {
     if (!spawnFn) throw new Error('spawnFn required');
     this.cap = cap;
@@ -58,6 +60,7 @@ class ProcessManager {
     this.onResult = onResult;
     this.onClose = onClose;
     this.onStreamChunk = onStreamChunk;
+    this.onToolUse = onToolUse;
     this.procs = new Map();
   }
 
@@ -188,6 +191,19 @@ class ProcessManager {
             catch (err) { this.logger.error(`[${entry.label}] onStreamChunk: ${err.message}`); }
           }
         }
+        // Emit tool_use blocks separately so callers (e.g. status reactions)
+        // can react to each tool name without re-parsing stream text.
+        if (this.onToolUse) {
+          const blocks = event.message?.content;
+          if (Array.isArray(blocks)) {
+            for (const b of blocks) {
+              if (b?.type === 'tool_use' && b.name) {
+                try { this.onToolUse(sessionKey, b.name, entry); }
+                catch (err) { this.logger.error(`[${entry.label}] onToolUse: ${err.message}`); }
+              }
+            }
+          }
+        }
       }
       if (event.type === 'result' && entry.pending) {
         const { resolve } = entry.pending;
@@ -238,7 +254,7 @@ class ProcessManager {
     return entry;
   }
 
-  send(sessionKey, prompt, { timeoutMs = 600_000 } = {}) {
+  send(sessionKey, prompt, { timeoutMs = 600_000, maxTurnMs = 30 * 60_000 } = {}) {
     return new Promise((resolve, reject) => {
       const entry = this.procs.get(sessionKey);
       if (!entry || entry.closed) return reject(new Error('No process for session'));
@@ -256,27 +272,65 @@ class ProcessManager {
       entry.pending = { resolve, reject };
       entry.streamText = '';
 
-      // Idle timeout: counts N seconds of SILENCE from Claude, not total
-      // wall-clock. Long multi-tool turns that produce visible progress
-      // (streaming chunks, tool_use events) should not time out as long as
-      // they're actively working. onStreamChunk resets this below.
-      const arm = () => setTimeout(() => {
-        if (entry.pending) {
-          entry.pending = null;
-          entry.inFlight = false;
-          reject(new Error(`Timeout: ${timeoutMs / 1000}s idle with no Claude activity`));
-        }
-      }, timeoutMs);
-      entry.pending.timer = arm();
+      const clearTimers = () => {
+        if (entry.pending?.idleTimer) clearTimeout(entry.pending.idleTimer);
+        if (entry.pending?.maxTimer) clearTimeout(entry.pending.maxTimer);
+      };
+
+      // Timer fire path. New in 0.3.9: after rejecting, SIGTERM the
+      // subprocess. Previously we only rejected the promise and left the
+      // stuck claude running — the next message would write stdin to a
+      // zombie process. Killing fires the 'close' handler which cleans
+      // up the LRU entry, so the next send() gets a fresh spawn.
+      const fireTimeout = (reason) => {
+        if (!entry.pending) return;
+        clearTimers();
+        entry.pending = null;
+        entry.inFlight = false;
+        try { entry.proc.kill('SIGTERM'); } catch {}
+        this._logEvent('turn-timeout', {
+          session_key: sessionKey,
+          chat_id: entry.chatId,
+          reason,
+        });
+        reject(new Error(reason));
+      };
+
+      // Idle timeout: counts N seconds of SILENCE from Claude. Reset on
+      // every assistant event so long productive turns (multi-tool
+      // reasoning) don't falsely trip.
+      // .unref() so these timers don't hold the node event loop open in
+      // tests or when the parent process wants to exit. Real-world polygram
+      // stays alive via grammy's poll loop + stdin/stdout pipes; the timers
+      // don't need to keep it alive on their own.
+      const armIdle = () => setTimeout(
+        () => fireTimeout(`Timeout: ${timeoutMs / 1000}s idle with no Claude activity`),
+        timeoutMs,
+      ).unref();
+      entry.pending.idleTimer = armIdle();
       entry.pending.resetIdleTimer = () => {
-        if (entry.pending?.timer) clearTimeout(entry.pending.timer);
-        if (entry.pending) entry.pending.timer = arm();
+        if (!entry.pending) return;
+        clearTimeout(entry.pending.idleTimer);
+        entry.pending.idleTimer = armIdle();
       };
 
+      // Wall-clock ceiling: fires at maxTurnMs regardless of activity.
+      // Catches stuck API calls that emit occasional events (keeping the
+      // idle timer alive) but never produce a result. OpenClaw's only
+      // timer was wall-clock; polygram's 0.3.5 change replaced it with
+      // idle-reset, creating a gap this restores as a last-resort.
+      entry.pending.maxTimer = setTimeout(
+        () => fireTimeout(`Turn exceeded ${maxTurnMs / 1000}s wall-clock ceiling`),
+        maxTurnMs,
+      ).unref();
+
+      // Legacy alias: some callers / tests refer to entry.pending.timer.
+      entry.pending.timer = entry.pending.idleTimer;
+
       const wrappedResolve = entry.pending.resolve;
       const wrappedReject = entry.pending.reject;
-      entry.pending.resolve = (r) => { if (entry.pending?.timer) clearTimeout(entry.pending.timer); wrappedResolve(r); };
-      entry.pending.reject = (e) => { if (entry.pending?.timer) clearTimeout(entry.pending.timer); wrappedReject(e); };
+      entry.pending.resolve = (r) => { clearTimers(); wrappedResolve(r); };
+      entry.pending.reject = (e) => { clearTimers(); wrappedReject(e); };
 
       try {
         entry.proc.stdin.write(JSON.stringify({
@@ -284,7 +338,7 @@ class ProcessManager {
           message: { role: 'user', content: prompt },
         }) + '\n');
       } catch (err) {
-        if (entry.pending?.timer) clearTimeout(entry.pending.timer);
+        clearTimers();
         entry.pending = null;
         entry.inFlight = false;
         reject(err);

package/lib/status-reactions.js

@@ -0,0 +1,168 @@
+/**
+ * Status-reaction state machine.
+ *
+ * Goal: give users a silent, non-intrusive progress signal during a turn.
+ * Telegram bot reactions are delivered quietly (no notification), update
+ * in place, and one emoji per message. Perfect for state like
+ * "thinking → coding → web → done".
+ *
+ * The state machine below translates Claude's stream-json event stream
+ * into a small set of states, each mapped to an emoji. The caller
+ * (usually polygram's handleMessage) holds a ReactionManager instance
+ * and calls setState() at transition points.
+ *
+ * Design choices:
+ *   - We pick emojis from Telegram's default-available set so groups
+ *     that haven't customised `available_reactions` still work. Callers
+ *     can pass an allowlist probed from getChat().available_reactions
+ *     for groups that have — we fall back through a chain for each
+ *     state until we find an allowed one.
+ *   - Rate-limit changes to every 800ms (Telegram allows ~1/s per
+ *     message). Intermediate states are dropped.
+ *   - Terminal states (DONE/ERROR/TIMEOUT) always flush, ignoring
+ *     throttle, so the user sees the final outcome.
+ *   - On abort or cleanup we clear the reaction entirely rather than
+ *     leaving a stale "thinking" emoji.
+ */
+
+// Ordered fallback chains — first emoji is the preferred one; follow-ups
+// are progressively safer. All endings in this list are in Telegram's
+// default available reactions as of 2026-04.
+const STATES = {
+  QUEUED:   { label: 'queued',   chain: ['👀', '🤔']       },
+  THINKING: { label: 'thinking', chain: ['🤔']             },
+  CODING:   { label: 'coding',   chain: ['👨‍💻', '✍', '🤔'] },
+  WEB:      { label: 'web',      chain: ['⚡', '🔥', '🤔']  },
+  TOOL:     { label: 'tool',     chain: ['🔥', '🤔']       },
+  WRITING:  { label: 'writing',  chain: ['✍', '🤔']        },
+  DONE:     { label: 'done',     chain: ['👍']             },
+  ERROR:    { label: 'error',    chain: ['🤯', '🤔']       },
+  STALL:    { label: 'stall',    chain: ['🥱', '🤔']       },
+  TIMEOUT:  { label: 'timeout',  chain: ['😨', '🤯']       },
+};
+
+const TERMINAL_STATES = new Set(['DONE', 'ERROR', 'TIMEOUT']);
+const DEFAULT_THROTTLE_MS = 800;
+
+// Tool name → state classifier. Case-insensitive contains for tool names
+// that share a category (Read/Write/Edit are all "coding"; WebFetch +
+// WebSearch are "web"; everything else is generic TOOL).
+function classifyToolName(name) {
+  if (typeof name !== 'string' || !name) return 'TOOL';
+  if (/^(Web)/i.test(name)) return 'WEB';
+  if (/^(Bash|Read|Write|Edit|NotebookEdit|Glob|Grep)$/.test(name)) return 'CODING';
+  if (/^(TodoWrite|Task)$/.test(name)) return 'WRITING';
+  return 'TOOL';
+}
+
+/**
+ * Resolve the best-available emoji from a chain given an allowlist.
+ * If allowlist is null/undefined, assume default-available set and
+ * return the first entry.
+ */
+function resolveEmoji(chain, allowlist) {
+  if (!allowlist) return chain[0];
+  const allowed = allowlist instanceof Set ? allowlist : new Set(allowlist);
+  for (const emoji of chain) {
+    if (allowed.has(emoji)) return emoji;
+  }
+  // Nothing in the chain is allowed — signal "no reaction possible".
+  return null;
+}
+
+/**
+ * Create a reaction manager for a single turn.
+ *
+ * @param {object} deps
+ * @param {(emoji: string|null) => Promise<void>} deps.apply   invoked with the
+ *     resolved emoji when state changes. `null` means "clear reaction".
+ * @param {string[]|Set<string>|null} [deps.availableEmojis]  allowlist probed
+ *     from getChat().available_reactions. Null/undefined = assume defaults.
+ * @param {number} [deps.throttleMs]  minimum ms between non-terminal changes.
+ * @param {(msg: string) => void} [deps.logError]
+ */
+function createReactionManager({
+  apply,
+  availableEmojis = null,
+  throttleMs = DEFAULT_THROTTLE_MS,
+  logError = () => {},
+} = {}) {
+  if (typeof apply !== 'function') throw new Error('apply function required');
+  let currentState = null;
+  let currentEmoji = null;
+  let lastFlushTs = 0;
+  let pendingTimer = null;
+  let stopped = false;
+
+  const flush = async (stateName) => {
+    if (stopped) return;
+    const spec = STATES[stateName];
+    if (!spec) return;
+    const emoji = resolveEmoji(spec.chain, availableEmojis);
+    if (emoji === currentEmoji) return;
+    currentEmoji = emoji;
+    lastFlushTs = Date.now();
+    try {
+      await apply(emoji);
+    } catch (err) {
+      logError(`reaction apply failed (${stateName} → ${emoji}): ${err?.message || err}`);
+    }
+  };
+
+  const setState = (stateName) => {
+    if (stopped) return;
+    if (!STATES[stateName]) return;
+    currentState = stateName;
+
+    // Terminal states flush immediately, bypassing throttle.
+    if (TERMINAL_STATES.has(stateName)) {
+      if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+      return flush(stateName);
+    }
+
+    const elapsed = Date.now() - lastFlushTs;
+    if (elapsed >= throttleMs) {
+      if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+      return flush(stateName);
+    }
+    // Inside throttle window: schedule for the soonest safe flush.
+    if (!pendingTimer) {
+      pendingTimer = setTimeout(() => {
+        pendingTimer = null;
+        flush(currentState);
+      }, throttleMs - elapsed);
+      pendingTimer.unref?.();
+    }
+  };
+
+  const clear = async () => {
+    if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    if (currentEmoji == null) return;
+    currentEmoji = null;
+    try { await apply(null); }
+    catch (err) { logError(`reaction clear failed: ${err?.message || err}`); }
+  };
+
+  const stop = () => {
+    stopped = true;
+    if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+  };
+
+  return {
+    setState,
+    clear,
+    stop,
+    // Introspection for tests:
+    get currentState() { return currentState; },
+    get currentEmoji() { return currentEmoji; },
+  };
+}
+
+module.exports = {
+  createReactionManager,
+  classifyToolName,
+  resolveEmoji,
+  STATES,
+  TERMINAL_STATES,
+  DEFAULT_THROTTLE_MS,
+};

package/lib/stream-reply.js

@@ -16,7 +16,11 @@
  */
 
 const DEFAULT_MIN_CHARS = 30;
-const DEFAULT_THROTTLE_MS = 500;
+// Matches OpenClaw's edit throttle. 500ms was edit-storm territory on long
+// turns — every token burst triggered an API call, risking 429s and burning
+// Telegram's edit-rate budget faster than necessary. 1000ms feels
+// identical to a viewer and halves the edit volume.
+const DEFAULT_THROTTLE_MS = 1000;
 
 function createStreamer({
   send,                                   // async (text) -> { message_id }

package/lib/telegram-format.js

@@ -0,0 +1,36 @@
+/**
+ * Convert Claude's CommonMark output into Telegram-safe MarkdownV2.
+ *
+ * Why: Claude emits standard GitHub-flavoured markdown (headings, bullets,
+ * `**bold**`, fenced code). Telegram does NOT support headings or bullet
+ * lists natively; `**bold**` is `*bold*` in its dialect; and MarkdownV2
+ * requires escaping `_*[]()~\`>#+-=|{}.!` in non-formatted text. Sending
+ * Claude's raw markdown with no parse_mode shows literal `**` and `#`
+ * in chat; sending it with parse_mode: MarkdownV2 crashes with "can't
+ * parse entities" the moment Claude writes a period or exclamation mark.
+ *
+ * telegramify-markdown handles both concerns: downgrades unsupported
+ * constructs (headings → bold, bullets → `•`) and escapes reserved chars.
+ *
+ * We wrap it here rather than calling it inline so:
+ *   - Swapping libraries later is a one-file change.
+ *   - Fallback-on-throw is centralised (if conversion explodes, we send
+ *     the original text with no parse_mode — worse formatting, but the
+ *     message still arrives).
+ */
+
+const telegramify = require('telegramify-markdown');
+
+function toTelegramMarkdown(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text, parseMode: null };
+  }
+  try {
+    const converted = telegramify(text, 'escape');
+    return { text: converted, parseMode: 'MarkdownV2' };
+  } catch {
+    return { text, parseMode: null };
+  }
+}
+
+module.exports = { toTelegramMarkdown };