polygram 0.8.0-rc.39 → 0.8.0-rc.40

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.8.0-rc.39",
+  "version": "0.8.0-rc.40",
   "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/status-reactions.js

@@ -131,6 +131,12 @@ function classifyToolName(name) {
 // nothing and leave the user wondering whether the bot is alive.
 const GENERIC_FALLBACKS = ['👍', '👀', '🔥'];
 
+// Module-scope sentinel for flush()'s `fromStateOverride` parameter.
+// Distinguishes "caller didn't pass fromState" from "caller passed
+// null (= reactor had no prior state)". Module-scoped so we don't
+// allocate a fresh symbol on every flush call.
+const FROM_STATE_UNSET = Symbol('flush.fromState-unset');
+
 /**
  * Resolve the best-available emoji from a chain given an allowlist.
  * If allowlist is null/undefined, assume default-available set and
@@ -160,6 +166,20 @@ function resolveEmoji(chain, allowlist) {
  *     from getChat().available_reactions. Null/undefined = assume defaults.
  * @param {number} [deps.throttleMs]  minimum ms between non-terminal changes.
  * @param {(msg: string) => void} [deps.logError]
+ * @param {(transition: object) => void} [deps.onStateChange]
+ *     rc.39: called after every visible state transition (state OR
+ *     emoji change). Payload shape:
+ *     { fromState, toState, fromEmoji, toEmoji, source, ts }
+ *     where `source` is one of:
+ *       'manual'          — explicit setState() call
+ *       'cascade-deeper'  — auto-promotion to THINKING_DEEPER
+ *       'cascade-deepest' — auto-promotion to THINKING_DEEPEST
+ *       'stall-timer'     — auto STALL after stallMs
+ *       'freeze-timer'    — auto FREEZE after freezeMs
+ *       'clear'           — clear() call (toEmoji=null)
+ *     Used by polygram to emit `reactor-state` events to the events
+ *     table for forensic post-hoc reconstruction of any reaction
+ *     anomaly. Must be cheap + sync — fired in the hot setState path.
  */
 function createReactionManager({
   apply,
@@ -170,6 +190,7 @@ function createReactionManager({
   thinkingDeeperMs = DEFAULT_THINKING_DEEPER_MS,
   thinkingDeepestMs = DEFAULT_THINKING_DEEPEST_MS,
   logError = () => {},
+  onStateChange = null,
 } = {}) {
   if (typeof apply !== 'function') throw new Error('apply function required');
   let currentState = null;
@@ -202,14 +223,37 @@ function createReactionManager({
     'CODING', 'WEB', 'TOOL', 'WRITING',
   ]);
 
-  const flush = async (stateName) => {
+  const flush = async (stateName, source = 'manual', fromStateOverride = FROM_STATE_UNSET) => {
     if (stopped && !TERMINAL_STATES.has(stateName)) return;
     const spec = STATES[stateName];
     if (!spec) return;
     const emoji = resolveEmoji(spec.chain, availableEmojis);
     if (emoji === currentEmoji) return;
+    // For telemetry: prefer the caller-supplied fromState override
+    // (setState/cascade timers swap currentState BEFORE calling flush;
+    // we want the PRE-swap value in the event, not the post-swap
+    // self-loop). Sentinel symbol distinguishes "no override" from
+    // a legitimate `null` (= reactor had no prior state, e.g. very
+    // first setState in a fresh handleMessage).
+    const fromState = fromStateOverride === FROM_STATE_UNSET ? currentState : fromStateOverride;
+    const fromEmoji = currentEmoji;
     currentEmoji = emoji;
     lastFlushTs = Date.now();
+    // rc.39: emit telemetry on the visible-change moment. Fired
+    // synchronously so the events.table row's ts ordering matches
+    // the ordering of setMessageReaction calls. Wrapped in try/catch
+    // so a buggy onStateChange can't break the reactor.
+    if (typeof onStateChange === 'function') {
+      try {
+        onStateChange({
+          fromState, toState: stateName,
+          fromEmoji, toEmoji: emoji,
+          source, ts: lastFlushTs,
+        });
+      } catch (err) {
+        logError(`onStateChange threw: ${err?.message || err}`);
+      }
+    }
     // Chain through applyChain so concurrent flushes are sent to
     // Telegram serially in invocation order. Returning the chain
     // promise lets callers await this specific flush completing.
@@ -249,9 +293,12 @@ function createReactionManager({
       if (currentState !== 'THINKING') return;
       // Promote without going through setState — we want the visual
       // change but NOT to reset the deepest timer (which keeps
-      // counting from the original THINKING start).
+      // counting from the original THINKING start). Pass the PRE-swap
+      // state to flush() so the telemetry event records the actual
+      // transition (THINKING → THINKING_DEEPER), not a self-loop.
+      const before = currentState;
       currentState = 'THINKING_DEEPER';
-      flush('THINKING_DEEPER');
+      flush('THINKING_DEEPER', 'cascade-deeper', before);
     }, thinkingDeeperMs);
     deeperTimer.unref?.();
     deepestTimer = setTimeout(() => {
@@ -259,8 +306,9 @@ function createReactionManager({
       if (stopped) return;
       // Promote from THINKING or THINKING_DEEPER (NOT from CODING etc).
       if (currentState !== 'THINKING' && currentState !== 'THINKING_DEEPER') return;
+      const before = currentState;
       currentState = 'THINKING_DEEPEST';
-      flush('THINKING_DEEPEST');
+      flush('THINKING_DEEPEST', 'cascade-deepest', before);
     }, thinkingDeepestMs);
     deepestTimer.unref?.();
   };
@@ -275,13 +323,13 @@ function createReactionManager({
       // promotable state in the interim.
       if (stopped || TERMINAL_STATES.has(currentState)) return;
       if (!STALL_PROMOTABLE.has(currentState)) return;
-      flush('STALL');
+      flush('STALL', 'stall-timer');
     }, stallMs);
     stallTimer.unref?.();
     freezeTimer = setTimeout(() => {
       freezeTimer = null;
       if (stopped || TERMINAL_STATES.has(currentState)) return;
-      flush('TIMEOUT');
+      flush('TIMEOUT', 'freeze-timer');
     }, freezeMs);
     freezeTimer.unref?.();
   };
@@ -289,6 +337,12 @@ function createReactionManager({
   const setState = (stateName) => {
     if (stopped) return;
     if (!STATES[stateName]) return;
+    // rc.39: capture pre-swap state for telemetry. Pre-rc.39 the
+    // currentState was set BEFORE flush, so the onStateChange event's
+    // fromState always equalled toState (looked like a self-loop).
+    // Pass `before` through to flush so the audit trail records the
+    // real transition.
+    const before = currentState;
     currentState = stateName;
     lastSetStateTs = Date.now();
 
@@ -298,7 +352,7 @@ function createReactionManager({
       if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
       clearStallTimers();
       clearDeepeningTimers();
-      return flush(stateName);
+      return flush(stateName, 'manual', before);
     }
 
     // Any explicit setState resets the stall clock — Claude clearly is
@@ -326,7 +380,7 @@ function createReactionManager({
     // round-trip. User sees 👀 → 🤔 → 🔥 progress, smoothly
     // paced by network latency.
     if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
-    return flush(stateName);
+    return flush(stateName, 'manual', before);
   };
 
   const clear = async () => {
@@ -334,7 +388,22 @@ function createReactionManager({
     clearStallTimers();
     clearDeepeningTimers();
     if (currentEmoji == null) return;
+    const fromState = currentState;
+    const fromEmoji = currentEmoji;
     currentEmoji = null;
+    // rc.39: emit telemetry on clear (toEmoji=null is the "we let go
+    // of the message" signal). Mirrors the flush() path.
+    if (typeof onStateChange === 'function') {
+      try {
+        onStateChange({
+          fromState, toState: null,
+          fromEmoji, toEmoji: null,
+          source: 'clear', ts: Date.now(),
+        });
+      } catch (err) {
+        logError(`onStateChange threw: ${err?.message || err}`);
+      }
+    }
     // Same applyChain serialization as flush — clear() is a state
     // transition, just to "no emoji". Without chaining, a clear()
     // racing with a pending apply (e.g. THINKING flush in flight)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.8.0-rc.39",
+  "version": "0.8.0-rc.40",
   "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

@@ -2425,6 +2425,26 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     },
     availableEmojis,
     logError: (m) => console.error(`[${label}] ${m}`),
+    // rc.39: emit reactor-state events for forensic post-hoc
+    // reconstruction of any reaction anomaly (stuck reactions, dual
+    // emojis, unexpected ERROR transitions, etc.). Sync callback —
+    // logEvent is best-effort and never throws. One row per visible
+    // change moment; cascade/stall/freeze auto-promotions get
+    // their own `source` value so we can tell apart manual setState
+    // calls from timer-driven transitions.
+    onStateChange: ({ fromState, toState, fromEmoji, toEmoji, source, ts }) => {
+      logEvent('reactor-state', {
+        chat_id: chatId,
+        msg_id: msg.message_id,
+        session_key: sessionKey,
+        from_state: fromState,
+        to_state: toState,
+        from_emoji: fromEmoji,
+        to_emoji: toEmoji,
+        source,
+        ts,
+      });
+    },
   });
   // rc.32: skip QUEUED (👀) entirely for first-message-in-chain. Go
   // straight to THINKING (🤔). The 👀 → 🤔 two-hop didn't add