polygram 0.10.0-rc.2 → 0.10.0-rc.21

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.2",
+  "version": "0.10.0-rc.21",
   "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 plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/autosteered-refs.js

@@ -46,12 +46,22 @@
  *   logged to opts.logger?.error — they never block clearing of
  *   subsequent refs.
  * @param {{ error?: (msg: string) => void }} [opts.logger]
+ * @param {number} [opts.minIntervalMs=250]
+ *   minimum gap (ms) between successive applyClear calls inside a
+ *   single clear() loop. Telegram's setMessageReaction rate limit
+ *   is ~5/sec/chat; 250ms (4/sec) stays under that. Pass 0 to
+ *   disable pacing in tests / contexts where the underlying applyClear
+ *   doesn't talk to a rate-limited API. Only the GAP between calls
+ *   is paced — the first call fires immediately, single-ref clears
+ *   incur no delay. L7 fix 2026-05-16: was unpaced, exceeded the
+ *   Telegram cap under N≥6 autosteers per turn.
  * @returns {AutosteeredRefs}
  */
-function createAutosteeredRefs({ applyClear, logger = console } = {}) {
+function createAutosteeredRefs({ applyClear, logger = console, minIntervalMs = 250 } = {}) {
   if (typeof applyClear !== 'function') {
     throw new TypeError('applyClear function required');
   }
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   /** @type {Map<string, MsgRef[]>} */
   const refs = new Map();
 
@@ -79,7 +89,15 @@ function createAutosteeredRefs({ applyClear, logger = console } = {}) {
     if (!list || list.length === 0) return 0;
     refs.delete(sessionKey);
     let cleared = 0;
-    for (const ref of list) {
+    // L7: pace inter-call gaps to stay under Telegram's
+    // setMessageReaction rate limit (~5/sec/chat). The first call
+    // fires immediately — pacing applies only to the gap BEFORE the
+    // 2nd+ call. minIntervalMs=0 disables pacing entirely.
+    for (let i = 0; i < list.length; i += 1) {
+      const ref = list[i];
+      if (i > 0 && minIntervalMs > 0) {
+        await sleep(minIntervalMs);
+      }
       try {
         await applyClear(ref);
         cleared += 1;

package/lib/claude-bin.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolve + verify the pinned claude CLI binary for the tmux backend.
+ *
+ * Why this exists: the tmux backend reads claude CLI INTERNAL
+ * artefacts (JSONL events, queue-operation semantics, TUI banner
+ * ASCII, READY hint strings, stop_reason values) — none a stable
+ * public contract. polygram pins ONE version
+ * (CLAUDE_CLI_PINNED_VERSION in lib/process/tmux-process.js) and
+ * must spawn THAT binary, never whatever `claude` on $PATH happens
+ * to resolve to.
+ *
+ * Before this module the tmux runner spawned the bare string
+ * `claude`, resolved through $PATH. The claude CLI installs each
+ * version as a standalone binary at
+ *   ~/.local/share/claude/versions/<version>
+ * and points ~/.local/bin/claude (a symlink) at the active one.
+ * Its auto-updater re-points that symlink whenever a new version
+ * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
+ * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
+ *
+ * Spawning the ABSOLUTE versioned path is immune to that: the
+ * updater only ADDS new version files, it never overwrites an
+ * existing one. `versions/2.1.142` stays byte-identical forever.
+ */
+
+/**
+ * Absolute path to the pinned claude binary.
+ *
+ * Resolution order:
+ *   1. POLYGRAM_CLAUDE_BIN env — explicit override (non-standard
+ *      installs, CI, hosts where the layout differs).
+ *   2. ~/.local/share/claude/versions/<version> — the standard
+ *      claude-CLI install location.
+ *
+ * The returned path is NOT guaranteed to exist — callers verify
+ * via verifyPinnedClaudeBin().
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {string} absolute path
+ */
+function resolvePinnedClaudeBin(version) {
+  const override = process.env.POLYGRAM_CLAUDE_BIN;
+  if (override) return override;
+  return path.join(os.homedir(), '.local', 'share', 'claude', 'versions', version);
+}
+
+/**
+ * Verify the pinned binary exists and is executable.
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {{ ok: boolean, path: string, reason?: string }}
+ *   ok=true → path is a spawnable binary.
+ *   ok=false → reason carries an operator-actionable message.
+ */
+function verifyPinnedClaudeBin(version) {
+  const binPath = resolvePinnedClaudeBin(version);
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return { ok: true, path: binPath };
+  } catch (err) {
+    const code = err && err.code ? err.code : (err && err.message) || 'unknown';
+    return {
+      ok: false,
+      path: binPath,
+      reason: `pinned claude CLI v${version} not found or not executable at `
+        + `${binPath} (${code}). Install it with \`claude install ${version}\` `
+        + 'or set POLYGRAM_CLAUDE_BIN to the correct binary path.',
+    };
+  }
+}
+
+module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin };

package/lib/db/sessions.js

@@ -95,4 +95,100 @@ function getClaudeSessionId(db, sessionKey) {
   return row?.claude_session_id || null;
 }
 
-module.exports = { migrateJsonToDb, getClaudeSessionId, countSessions };
+// ─── S2: session-config drift ────────────────────────────────────────
+//
+// A stored `sessions` row records the config the claude session was
+// SPAWNED under (agent / cwd / pm_backend). Those three are
+// spawn-identity: they are baked into the process at spawn time —
+// `--agent`, the tmux/SDK working dir, the backend class — and cannot
+// be changed on a live session. If the chat/topic config has drifted
+// from the stored row, `--resume`-ing the old session forces claude
+// to run under a config it was never built for. shumorobot
+// 2026-05-17 22:03, topic :3: the row was agent=shumabit / cwd=$HOME
+// / sdk (created before the Music topic got its per-topic override);
+// resuming it under agent=music-curation:music-curator /
+// cwd=.../Music/rekordbox / tmux left the TUI never signalling ready.
+//
+// model + effort are deliberately EXCLUDED from the invalidating set.
+// They are NOT spawn-identity: a live `/model` or `/effort` change is
+// pushed into the running session by `pm.setModel` /
+// `pm.applyFlagSettings` with no respawn (lib/handlers/slash-commands.js,
+// lib/handlers/config-callback.js). Including them here would
+// destructively drop the whole session — discarding all context — on
+// every model switch, double-handling what the live-apply path
+// already covers cleanly. The stored model/effort columns are
+// informational, not identity.
+const SPAWN_IDENTITY_FIELDS = ['agent', 'cwd', 'pm_backend'];
+
+/**
+ * Decide whether a stored session can be resumed for the next spawn,
+ * or whether config drift means it must be dropped and re-spawned
+ * fresh.
+ *
+ * On drift the stale row is DELETED here — so the very next spawn
+ * mints a fresh claude_session_id under the correct config and the
+ * `onInit` callback re-upserts the row. This self-heals every
+ * pre-migration stale row across all chats with no manual SQL.
+ *
+ * @param {object|null} db          — DB handle (null → fresh spawn)
+ * @param {string} sessionKey
+ * @param {object} resolved         — freshly-resolved spawn config
+ * @param {string} [resolved.agent]
+ * @param {string} [resolved.cwd]
+ * @param {string} [resolved.backend] — 'sdk' | 'tmux' (resolved by
+ *   process/factory.js pickBackend); compared to the row's pm_backend
+ * @returns {{ existingSessionId: string|null, drift: object|null }}
+ *   existingSessionId — pass to start() for --resume, or null for a
+ *     fresh spawn (no stored row, or drift dropped it)
+ *   drift — null when no drift; otherwise { fields, before, after }
+ *     for the `session-config-drift` telemetry event
+ */
+function resolveSessionForSpawn(db, sessionKey, resolved = {}) {
+  if (!db) return { existingSessionId: null, drift: null };
+  const row = db.getSession(sessionKey);
+  if (!row || !row.claude_session_id) {
+    return { existingSessionId: null, drift: null };
+  }
+
+  // Normalise: a missing field on either side is treated as equal to
+  // a missing field on the other (both null/undefined → no drift).
+  const after = {
+    agent: resolved.agent || null,
+    cwd: resolved.cwd || null,
+    pm_backend: resolved.backend || null,
+  };
+  const before = {
+    agent: row.agent || null,
+    cwd: row.cwd || null,
+    pm_backend: row.pm_backend || null,
+  };
+  const drifted = SPAWN_IDENTITY_FIELDS.filter((f) => {
+    // If the resolved config does not specify a field, do not treat
+    // it as drift — we have nothing to compare against.
+    if (after[f] == null) return false;
+    return before[f] !== after[f];
+  });
+
+  if (drifted.length === 0) {
+    return { existingSessionId: row.claude_session_id, drift: null };
+  }
+
+  // Drift: drop the stale row so the next spawn is fresh + correct.
+  db.clearSessionId(sessionKey);
+  return {
+    existingSessionId: null,
+    drift: {
+      fields: drifted,
+      before: { ...before, claude_session_id: row.claude_session_id },
+      after,
+    },
+  };
+}
+
+module.exports = {
+  migrateJsonToDb,
+  getClaudeSessionId,
+  resolveSessionForSpawn,
+  countSessions,
+  SPAWN_IDENTITY_FIELDS,
+};

package/lib/handlers/autosteer.js

@@ -69,9 +69,15 @@ function createAutosteerHandlers({
     if (!entry?.inFlight) return { autosteered: false };
 
     const priority = priorityFor(chatConfig, config);
+    // rc.7: pass the autosteered msg_id through to the backend so the
+    // tmux backend can route an extra-turn reply back to Telegram if
+    // the TUI dequeues the paste as a fresh user turn (NEW-TURN path).
+    // SDK backend ignores msgId — its PostToolBatch fold path
+    // guarantees one combined reply via the primary pm.send.
     const ok = pm.injectUserMessage(sessionKey, {
       content: prompt,
       priority,
+      msgId: msg.message_id,
     });
     if (!ok) return { autosteered: false };