polygram 0.7.2 → 0.7.4

package/.claude-plugin/plugin.json

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

@@ -15,6 +15,8 @@
       "attachmentConcurrency": 6,
       "queueWarnThreshold": 20,
       "replayWindowMs": 180000,
+      "_comment_chrome": "Opt-in to Claude Code's Chrome-extension browser-automation integration. Default false. Requires the 'Claude in Chrome' extension installed in the daemon-user's Chrome browser AND a live GUI session (Chrome must be running). See https://code.claude.com/docs/en/chrome. Per-chat override via `config.chats.<id>.chrome`.",
+      "chrome": false,
       "_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/deliver.js

@@ -33,6 +33,11 @@ async function deliverReplies({
   threadId = null,
   chunks,
   replyToMessageId = null,
+  // 0.7.4: optional quoted-snippet text for reply_parameters.quote (Telegram's
+  // highlighted-quote reply API, makes the reply bubble header show a specific
+  // snippet rather than the full first ~100 chars of the original message).
+  // Only attached on chunks[0] alongside reply_parameters.message_id.
+  quoteText = null,
   meta = {},
   logger = console,
 }) {
@@ -56,7 +61,11 @@ async function deliverReplies({
       // 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 };
+      params.reply_parameters = {
+        message_id: replyToMessageId,
+        allow_sending_without_reply: true,
+        ...(quoteText && quoteText.trim() ? { quote: quoteText.trim().slice(0, 1024) } : {}),
+      };
     }
     try {
       const res = await send(bot, 'sendMessage', params, meta);

package/lib/process-manager.js

@@ -284,6 +284,14 @@ class ProcessManager {
         // id means a new message (typically after a tool-result cycle).
         const messageId = event.message?.id;
         const added = extractAssistantText(event);
+        // 0.7.4 (item B): first sign Claude is doing real work on this
+        // pending. Fire onFirstStream ONCE, regardless of whether the
+        // assistant message has text or only tool_use blocks (some turns
+        // emit tool_use first with no preamble).
+        if (added || (Array.isArray(event.message?.content)
+            && event.message.content.some((b) => b?.type === 'tool_use'))) {
+          head.fireFirstStream?.();
+        }
         if (added) {
           // Pre-0.7.0 we did `streamText = streamText + '\n\n' + added`,
           // which DUPLICATED text on every update because `added` is
@@ -448,6 +456,20 @@ class ProcessManager {
         idleTimer: null,
         maxTimer: null,
         activated: false,
+        // 0.7.4 (item B): set true when the first stream event (assistant
+        // text or tool_use) arrives for this pending. Fires
+        // `context.onFirstStream` once. Used by polygram to flip the
+        // status reaction QUEUED → THINKING when Claude actually starts
+        // producing output, not when the pending becomes queue head
+        // (which can be ~hundreds of ms before the first token).
+        firstStreamFired: false,
+      };
+
+      pending.fireFirstStream = () => {
+        if (pending.firstStreamFired) return;
+        pending.firstStreamFired = true;
+        try { context?.onFirstStream?.(); }
+        catch (err) { this.logger.error(`[${entry.label}] onFirstStream: ${err.message}`); }
       };
 
       const fireTimeout = (reason) => {

package/lib/status-reactions.js

@@ -43,18 +43,48 @@ const STATES = {
 
 const TERMINAL_STATES = new Set(['DONE', 'ERROR', 'TIMEOUT']);
 const DEFAULT_THROTTLE_MS = 800;
+// 0.7.4 (item A): after this long with no setState() call (Claude is
+// silently chugging on a long tool / model latency), auto-flip to STALL
+// (🥱) so the user has a visible cue that the bot is alive but slow.
+// 10s matches OpenClaw's "yawn after 10s of nothing".
+const DEFAULT_STALL_MS = 10_000;
+// 30s without a heartbeat is "we're worried" territory — promote to
+// TIMEOUT (😨) so the user knows it might be stuck. Distinct from the
+// pm's 5-minute hard idle timeout, which actually rejects the turn.
+const DEFAULT_FREEZE_MS = 30_000;
 
-// 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).
+// Tool name → state classifier. Case-insensitive substring match so we
+// don't have to enumerate every existing or future tool. Order matters:
+// WEB checks first because "WebFetch" contains "fetch" but should map
+// to ⚡, not whatever the generic fetcher gets. Skill-prefixed tools
+// (e.g. "mcp__plugin_playwright_playwright__browser_click") are still
+// caught by the substring check.
+//
+// 0.7.4 (item C): pre-fix, anything not exactly matching a tiny regex
+// (e.g. WebSearch_v2, custom Bash variants, MCP-namespaced tools) fell
+// through to generic TOOL (🔥), losing the more-specific signal. The
+// substring match recovers the right state for both built-ins and most
+// MCP/skill tools without listing them by name.
 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';
+  const n = name.toLowerCase();
+  if (n.includes('web') || n.includes('fetch') || n.includes('browser') || n.includes('search')) return 'WEB';
+  // WRITING before CODING: "TodoWrite" contains both "todo" and "write" —
+  // we want it to land at ✍ (WRITING), not 👨‍💻 (CODING).
+  if (n.includes('todo') || n.includes('task') || n.includes('skill')) return 'WRITING';
+  if (n.includes('read') || n.includes('write') || n.includes('edit')
+      || n.includes('bash') || n.includes('grep') || n.includes('glob')
+      || n.includes('notebook')) return 'CODING';
   return 'TOOL';
 }
 
+// 0.7.4 (item J): generic, almost-universally-available fallbacks. Used
+// when a group's `available_reactions` allowlist excludes every emoji in
+// a state's preferred chain. Better to show *some* reaction (e.g. 👍 for
+// "done" in a group that only allows thumbs) than to silently emit
+// nothing and leave the user wondering whether the bot is alive.
+const GENERIC_FALLBACKS = ['👍', '👀', '🔥'];
+
 /**
  * Resolve the best-available emoji from a chain given an allowlist.
  * If allowlist is null/undefined, assume default-available set and
@@ -66,7 +96,11 @@ function resolveEmoji(chain, allowlist) {
   for (const emoji of chain) {
     if (allowed.has(emoji)) return emoji;
   }
-  // Nothing in the chain is allowed — signal "no reaction possible".
+  for (const emoji of GENERIC_FALLBACKS) {
+    if (allowed.has(emoji)) return emoji;
+  }
+  // Nothing in the chain or generic set is allowed — signal "no
+  // reaction possible".
   return null;
 }
 
@@ -85,14 +119,23 @@ function createReactionManager({
   apply,
   availableEmojis = null,
   throttleMs = DEFAULT_THROTTLE_MS,
+  stallMs = DEFAULT_STALL_MS,
+  freezeMs = DEFAULT_FREEZE_MS,
   logError = () => {},
 } = {}) {
   if (typeof apply !== 'function') throw new Error('apply function required');
   let currentState = null;
   let currentEmoji = null;
   let lastFlushTs = 0;
+  let lastSetStateTs = 0;
   let pendingTimer = null;
+  let stallTimer = null;
+  let freezeTimer = null;
   let stopped = false;
+  // States the auto-stall path may transition to. Once we've already
+  // shown STALL or TIMEOUT we don't downgrade or rearm — only an
+  // explicit setState() call (Claude resumed) can move us forward.
+  const STALL_PROMOTABLE = new Set(['THINKING', 'CODING', 'WEB', 'TOOL', 'WRITING']);
 
   const flush = async (stateName) => {
     if (stopped) return;
@@ -109,17 +152,51 @@ function createReactionManager({
     }
   };
 
+  const clearStallTimers = () => {
+    if (stallTimer) { clearTimeout(stallTimer); stallTimer = null; }
+    if (freezeTimer) { clearTimeout(freezeTimer); freezeTimer = null; }
+  };
+
+  const armStallTimers = () => {
+    clearStallTimers();
+    if (stopped) return;
+    if (!STALL_PROMOTABLE.has(currentState)) return;
+    stallTimer = setTimeout(() => {
+      stallTimer = null;
+      // Re-check state at fire time — caller may have advanced past a
+      // promotable state in the interim.
+      if (stopped || TERMINAL_STATES.has(currentState)) return;
+      if (!STALL_PROMOTABLE.has(currentState)) return;
+      flush('STALL');
+    }, stallMs);
+    stallTimer.unref?.();
+    freezeTimer = setTimeout(() => {
+      freezeTimer = null;
+      if (stopped || TERMINAL_STATES.has(currentState)) return;
+      flush('TIMEOUT');
+    }, freezeMs);
+    freezeTimer.unref?.();
+  };
+
   const setState = (stateName) => {
     if (stopped) return;
     if (!STATES[stateName]) return;
     currentState = stateName;
+    lastSetStateTs = Date.now();
 
-    // Terminal states flush immediately, bypassing throttle.
+    // Terminal states flush immediately, bypassing throttle, and
+    // disarm any pending stall promotion.
     if (TERMINAL_STATES.has(stateName)) {
       if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+      clearStallTimers();
       return flush(stateName);
     }
 
+    // Any explicit setState resets the stall clock — Claude clearly is
+    // doing *something*. Re-arm only if the new state is promotable
+    // (no point arming over QUEUED/STALL/TIMEOUT itself).
+    armStallTimers();
+
     const elapsed = Date.now() - lastFlushTs;
     if (elapsed >= throttleMs) {
       if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
@@ -137,6 +214,7 @@ function createReactionManager({
 
   const clear = async () => {
     if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    clearStallTimers();
     if (currentEmoji == null) return;
     currentEmoji = null;
     try { await apply(null); }
@@ -146,6 +224,7 @@ function createReactionManager({
   const stop = () => {
     stopped = true;
     if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    clearStallTimers();
   };
 
   return {
@@ -165,4 +244,7 @@ module.exports = {
   STATES,
   TERMINAL_STATES,
   DEFAULT_THROTTLE_MS,
+  DEFAULT_STALL_MS,
+  DEFAULT_FREEZE_MS,
+  GENERIC_FALLBACKS,
 };

package/lib/stream-reply.js

@@ -38,6 +38,12 @@ const DEFAULT_MIN_CHARS = 30;
 // identical to a viewer and halves the edit volume.
 const DEFAULT_THROTTLE_MS = 1000;
 
+// 0.7.4: floor matches OpenClaw's `Math.max(250, throttleMs)` clamp —
+// any value below 250ms would burn through Telegram's per-message edit-
+// rate budget faster than necessary. Defends against operator misconfig
+// (`streamThrottleMs: 50`) without rejecting the config outright.
+const THROTTLE_FLOOR_MS = 250;
+
 function createStreamer({
   send,                                   // async (text) -> { message_id }
   edit,                                   // async (msg_id, text) -> void
@@ -50,6 +56,7 @@ function createStreamer({
   cancel = clearTimeout,
   logger = console,
 } = {}) {
+  throttleMs = Math.max(THROTTLE_FLOOR_MS, throttleMs);
   let state = 'idle';       // 'idle' | 'live' | 'finalized'
   let msgId = null;
   let currentText = '';     // what's on screen right now (truncated to maxLen)

package/lib/telegram.js

@@ -111,6 +111,28 @@ 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;
+
+  // 0.7.4: empty-text short-circuit. Pre-fix, an empty params.text on
+  // sendMessage/editMessageText reached Telegram and 400'd with
+  // "message text is empty"; the row was marked failed and propagated
+  // as a user-facing "Hit a snag" — confusing because the bot didn't
+  // really fail. Throw a typed error before the API call so callers
+  // can detect + skip silently if appropriate.
+  if (method === 'sendMessage' || method === 'editMessageText') {
+    const t = params.text;
+    if (typeof t !== 'string' || t.length === 0) {
+      throw new Error(`telegram ${method}: text is empty`);
+    }
+  }
+  if (method === 'sendPhoto' || method === 'sendVideo'
+      || method === 'sendAudio' || method === 'sendDocument' || method === 'sendAnimation') {
+    // Caption is optional for media sends; only check if explicitly set
+    // to a non-string. Empty caption is fine (just send the media).
+    if (params.caption != null && typeof params.caption !== 'string') {
+      throw new Error(`telegram ${method}: caption must be a string when set`);
+    }
+  }
+
   // 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
@@ -199,7 +221,10 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   //
   // Each layer is a closure built per call; allocation cost is
   // negligible vs. network RTT.
-  const RETRY_AFTER_CAP_MS = 60_000;
+  // 0.7.4: aligned with OpenClaw's 30s cap. A misconfigured retry_after
+  // (Telegram occasionally returns 5+ minute hints during outages)
+  // shouldn't park the call beyond a reasonable user-attention budget.
+  const RETRY_AFTER_CAP_MS = 30_000;
   const tryOnce = async (p) => {
     try {
       return await rawAttempt(p);

package/package.json

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

@@ -204,6 +204,49 @@ function dbWrite(fn, context) {
   }
 }
 
+// 0.7.4 (item I): per-chat allowlist of available reactions.
+//
+// Telegram groups can restrict which emojis members may use as
+// reactions via `available_reactions`. When the bot is in such a group
+// and tries to apply a reaction outside the allowlist, the API returns
+// REACTION_INVALID and the user sees no progress signal at all.
+//
+// We probe via getChat() once per chat (cached forever — admins rarely
+// change the setting and we'll learn of changes the next bot restart),
+// derive the allowlist (or null = "default Telegram set, no
+// restriction"), and pass it into createReactionManager so resolveEmoji
+// can pick the best-allowed emoji from each state's chain.
+const reactionAllowlistCache = new Map();
+async function getReactionAllowlist(bot, chatId) {
+  if (reactionAllowlistCache.has(chatId)) return reactionAllowlistCache.get(chatId);
+  let allowlist = null;
+  try {
+    const chat = await bot.api.getChat(chatId);
+    const ar = chat?.available_reactions;
+    // Telegram returns:
+    //   - undefined / { type: 'all' }  → no restriction (all emojis allowed)
+    //   - { type: 'some', reactions: [{type, emoji}, ...] } → restricted
+    //   - { type: 'none' }              → reactions disabled entirely
+    if (ar?.type === 'some' && Array.isArray(ar.reactions)) {
+      allowlist = new Set(ar.reactions
+        .filter((r) => r?.type === 'emoji' && r.emoji)
+        .map((r) => r.emoji));
+    } else if (ar?.type === 'none') {
+      // Empty set — resolveEmoji will return null, the apply callback
+      // will short-circuit, and we won't waste API calls on a chat
+      // where reactions can't render at all.
+      allowlist = new Set();
+    }
+    // 'all' / undefined → leave allowlist null (chain[0] always wins).
+  } catch (err) {
+    console.error(`[reactions] getChat ${chatId} failed: ${err.message}`);
+    // On failure, cache null (assume default set) so we don't retry on
+    // every turn. A bot restart re-probes.
+  }
+  reactionAllowlistCache.set(chatId, allowlist);
+  return allowlist;
+}
+
 // Convenience for the most common dbWrite pattern: log an event.
 // Pre-0.6.9 every call site was dbWrite(() => db.logEvent(KIND, {...}),
 // `log ${KIND}`) — three repeated lines for one logical operation.
@@ -379,16 +422,23 @@ function extractAttachments(msg) {
 
 async function transcribeVoiceAttachments(downloaded, { chatId, msgId, label, botApi, threadId }) {
   const voiceCfg = config.bot?.voice || config.voice;
-  if (!voiceCfg?.enabled) return;
+  if (!voiceCfg?.enabled) return { ackEmitted: false };
   const provider = voiceCfg.provider || 'openai';
   const providerCfg = voiceCfg[provider] || {};
   const targets = downloaded.filter((a) => isVoiceAttachment(a) && a.path);
-  if (!targets.length) return;
+  if (!targets.length) return { ackEmitted: false };
 
   // Acknowledge receipt with a reaction so the user knows we heard them.
   // Cheap, robust (no state), and survives transcription failure.
+  // 0.7.4 (item G): we report `ackEmitted: true` so the caller can skip
+  // the reactor's QUEUED → 👀 transition. Pre-fix, 👂 was visible for
+  // ~milliseconds before 👀 overwrote it on the same message — wasted
+  // API call and confusing flicker. Now 👂 stays until Claude actually
+  // starts work and the reactor flips to THINKING (🤔).
   const ack = voiceCfg.ackReaction || '👂';
+  let ackEmitted = false;
   if (ack && botApi) {
+    ackEmitted = true;
     tg(botApi, 'setMessageReaction', {
       chat_id: chatId, message_id: msgId,
       reaction: [{ type: 'emoji', emoji: ack }],
@@ -432,7 +482,7 @@ async function transcribeVoiceAttachments(downloaded, { chatId, msgId, label, bo
   //     combined transcript so FTS finds "what Maria said" via the
   //     normal chat search path.
   const successful = targets.filter((a) => a.transcription?.text);
-  if (!successful.length) return;
+  if (!successful.length) return { ackEmitted };
   for (const a of successful) {
     if (a.id != null) {
       dbWrite(() => db.setAttachmentTranscription(a.id, JSON.stringify(a.transcription)),
@@ -443,6 +493,7 @@ async function transcribeVoiceAttachments(downloaded, { chatId, msgId, label, bo
   dbWrite(() => db.setMessageText({
     chat_id: chatId, msg_id: msgId, text: combinedText,
   }), 'persist voice transcription');
+  return { ackEmitted };
 }
 
 // Bounded concurrency for parallel fetches. A 10-photo album used to be
@@ -640,6 +691,19 @@ let pm = null; // ProcessManager, created in main()
 
 function spawnClaude(sessionKey, ctx) {
   const { chatConfig, existingSessionId, label, chatId } = ctx;
+  // 0.7.3: Claude Code's Chrome-extension integration (browser
+  // automation via the "Claude in Chrome" extension) is OPT-IN and
+  // NOT enabled by default in `claude`. Polygram lets chats turn it
+  // on via `config.chats.<id>.chrome: true` (chat-level wins) or
+  // `config.bot.chrome: true` (per-bot default). When opting in, the
+  // extension must be installed in the daemon-user's Chrome and the
+  // user must have a live Aqua session (so Chrome is running). Falls
+  // back to --no-chrome for chats that don't opt in (matches our
+  // pre-0.7.3 default — defensive against any "enabled by default"
+  // that might have been set in claude's persistent state).
+  const wantChrome = chatConfig.chrome != null
+    ? chatConfig.chrome === true
+    : config.bot?.chrome === true;
   const args = [
     '-p',
     '--input-format', 'stream-json',
@@ -648,7 +712,7 @@ function spawnClaude(sessionKey, ctx) {
     '--model', chatConfig.model || config.defaults.model,
     '--effort', chatConfig.effort || config.defaults.effort,
     '--permission-mode', 'bypassPermissions',
-    '--no-chrome',
+    wantChrome ? '--chrome' : '--no-chrome',
   ];
   if (chatConfig.agent) args.push('--agent', chatConfig.agent);
   if (existingSessionId) args.push('--resume', existingSessionId);
@@ -1636,9 +1700,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     }
   }
 
-  await transcribeVoiceAttachments(downloaded, {
+  const voiceAck = await transcribeVoiceAttachments(downloaded, {
     chatId, msgId: msg.message_id, label, botApi: bot, threadId,
-  });
+  }) || { ackEmitted: false };
 
   const prompt = formatPrompt(msg, sessionCtx, downloaded);
   const stopTyping = startTyping({
@@ -1771,6 +1835,11 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // notifications), updates in place, one emoji per message. Uses
   // setMessageReaction which skips the DB row (the tg() wrapper
   // short-circuits that method), so no transcript spam.
+  // 0.7.4 (item I): probe the chat's available_reactions allowlist on
+  // first turn (cached after). resolveEmoji uses this to pick the best
+  // emoji from each state's chain that's actually permitted in this
+  // group, falling back to a generic set (👍/👀/🔥) before giving up.
+  const availableEmojis = await getReactionAllowlist(bot, chatId);
   const reactor = createReactionManager({
     apply: async (emoji) => {
       const params = {
@@ -1781,13 +1850,20 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       await tg(bot, 'setMessageReaction', params,
         { source: 'status-reaction', botName: BOT_NAME });
     },
+    availableEmojis,
     logError: (m) => console.error(`[${label}] ${m}`),
   });
   // 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');
+  // 0.7.4 (item G): if voice ack (👂) was just emitted by
+  // transcribeVoiceAttachments, skip QUEUED — its 👀 would overwrite the
+  // ack within milliseconds, wasting an API call and flickering. Let 👂
+  // stay until THINKING flips it to 🤔 when Claude actually starts work.
+  if (!voiceAck.ackEmitted) {
+    reactor.setState('QUEUED');
+  }
 
   // Mark the inbound row terminal so boot replay doesn't pick it up
   // again. Must fire down EVERY non-throwing exit path (early returns
@@ -1806,7 +1882,12 @@ 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'),
+      // 0.7.4 (item B): fire THINKING when Claude actually starts
+      // emitting (first assistant text or tool_use). Pre-fix, onActivate
+      // (queue-head transition) flipped to THINKING the moment we wrote
+      // stdin, even though Claude could spend hundreds of ms loading.
+      // Result: long flat 🤔 with nothing happening; users assumed stall.
+      onFirstStream: () => reactor.setState('THINKING'),
     });
     const elapsed = ((Date.now() - t0) / 1000).toFixed(1);