polygram 0.8.0 → 0.9.0-rc.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.8.0",
+  "version": "0.9.0-rc.2",
   "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/{agent-loader.js → agents/loader.js}

@@ -1,13 +1,11 @@
 /**
- * Per-chat agent loader for the SDK migration (Phase 1 step 14 /
- * v4 plan §6.5.5).
+ * Per-chat agent loader.
  *
- * Background: today's CLI pm passes `--agent <name>` on spawn; the
- * Claude CLI then loads that agent's content. Phase 0 gate 15 was
- * DEFER — the SDK's `Options.agents` is for in-memory subagent
- * definitions (the Task tool), NOT a "run THIS query AS this agent"
- * mechanism. So polygram reads the agent file itself and passes its
- * content as `systemPrompt`.
+ * polygram reads the per-chat agent file itself and passes its
+ * content as `systemPrompt`. The SDK's `Options.agents` is for
+ * in-memory subagent definitions (the Task tool), NOT a "run THIS
+ * query AS this agent" mechanism — so we resolve the agent file
+ * out-of-band and inject the system prompt directly.
  *
  * Search order (rc.13+ — supports BOTH Claude Code's standard
  * single-file convention AND polygram's pre-0.8.0 directory layout):

package/lib/{approvals.js → approvals/store.js}

@@ -11,7 +11,7 @@
  */
 
 const crypto = require('crypto');
-const { canonicalizeToolInput } = require('./canonical-json');
+const { canonicalizeToolInput } = require('../canonical-json');
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 // 16 random bytes → 22 base64url chars ≈ 128 bits of entropy. Prevents
@@ -103,15 +103,27 @@ function matchesAnyPattern(toolName, toolInput, patterns = []) {
 function createStore(rawDb, now = () => Date.now()) {
   const insertStmt = rawDb.prepare(`
     INSERT INTO pending_approvals (
-      bot_name, turn_id, requester_chat_id, approver_chat_id,
+      bot_name, turn_id, tool_use_id, requester_chat_id, approver_chat_id,
       tool_name, tool_input_json, tool_input_digest,
       callback_token, requested_ts, timeout_ts
     ) VALUES (
-      @bot_name, @turn_id, @requester_chat_id, @approver_chat_id,
+      @bot_name, @turn_id, @tool_use_id, @requester_chat_id, @approver_chat_id,
       @tool_name, @tool_input_json, @tool_input_digest,
       @callback_token, @requested_ts, @timeout_ts
     )
   `);
+  // 0.9.0-cleanup commit 10: stronger dedup via tool_use_id when the
+  // SDK provides one. tool_use_id is the SDK's stable per-call ID;
+  // unlike the legacy (turn_id, tool_input_digest) tuple, it survives
+  // JSON-key reordering between retries within a turn. Migration 010
+  // added the column + partial index `idx_pending_approvals_tool_use_id`
+  // which had been unused since rc.6 because no insert path populated
+  // the column. issue() now does.
+  const findDedupByToolUseIdStmt = rawDb.prepare(`
+    SELECT * FROM pending_approvals
+     WHERE bot_name = ? AND tool_use_id = ? AND status = 'pending'
+     LIMIT 1
+  `);
   const findDedupStmt = rawDb.prepare(`
     SELECT * FROM pending_approvals
      WHERE bot_name = ? AND turn_id IS ? AND tool_input_digest = ?
@@ -143,7 +155,8 @@ function createStore(rawDb, now = () => Date.now()) {
 
   return {
     issue({
-      bot_name, turn_id = null, requester_chat_id, approver_chat_id,
+      bot_name, turn_id = null, tool_use_id = null,
+      requester_chat_id, approver_chat_id,
       tool_name, tool_input, timeoutMs = DEFAULT_TIMEOUT_MS,
     }) {
       if (!bot_name) throw new Error('bot_name required');
@@ -164,13 +177,23 @@ function createStore(rawDb, now = () => Date.now()) {
       // the existing row and insert two. SQLite's UPSERT would also work if
       // we added a UNIQUE partial index in a migration; keeping this in
       // application code avoids a schema bump.
+      //
+      // 0.9.0: prefer dedup by SDK's stable tool_use_id when available.
+      // The legacy (turn_id, tool_input_digest) tuple survives only when
+      // the SDK doesn't provide a tool_use_id (cron-driven sends, IPC
+      // callers from older Claude versions). Both code paths route
+      // through the same INSERT below; the only thing that varies is
+      // which existing row counts as a "match."
       let row, reused = false;
       const tx = rawDb.transaction(() => {
-        const existing = findDedupStmt.get(bot_name, turn_id, tool_input_digest);
+        const existing = tool_use_id
+          ? findDedupByToolUseIdStmt.get(bot_name, tool_use_id)
+          : findDedupStmt.get(bot_name, turn_id, tool_input_digest);
         if (existing) { row = existing; reused = true; return; }
         const res = insertStmt.run({
           bot_name,
           turn_id,
+          tool_use_id,
           requester_chat_id: String(requester_chat_id),
           approver_chat_id: String(approver_chat_id),
           tool_name,

package/lib/{approval-ui.js → approvals/ui.js}

@@ -1,8 +1,7 @@
 /**
  * Pure UI builders for the approval flow's Telegram surface.
  *
- *   - 2-button keyboard (CLI pm IPC approval-hook flow)
- *   - 4-button keyboard (rc.6 SDK pm canUseTool flow with persisted
+ *   - 4-button keyboard (SDK pm canUseTool flow with persisted
  *     "Always allow / Always deny" via chat_tool_decisions)
  *   - Card text with friendly heading + clipped tool_input body
  *
@@ -13,20 +12,6 @@
 
 'use strict';
 
-/**
- * 2-button keyboard for the legacy IPC approval flow.
- * @param {number|string} approvalId
- * @param {string} token
- */
-function buildApprovalKeyboard(approvalId, token) {
-  return {
-    inline_keyboard: [[
-      { text: '✅ Approve', callback_data: `approve:${approvalId}:${token}` },
-      { text: '❌ Deny',    callback_data: `deny:${approvalId}:${token}` },
-    ]],
-  };
-}
-
 /**
  * 4-button keyboard for the SDK canUseTool flow (rc.6 Phase 2 step 6).
  * "Always allow" / "Always deny" rows persist the decision into
@@ -126,7 +111,6 @@ function safeParse(s) {
 }
 
 module.exports = {
-  buildApprovalKeyboard,
   buildApprovalKeyboardWithAlways,
   formatToolInputForCard,
   approvalCardText,

package/lib/config.js

@@ -0,0 +1,121 @@
+/**
+ * Config loader / saver / sticker-map loader.
+ *
+ * Pure I/O functions extracted from polygram.js. The caller owns
+ * the module-level mutable `config` / `stickerMap` state and
+ * assigns the return values; this module never touches process
+ * globals.
+ *
+ * - `loadConfig(configPath)` — sync read + JSON.parse. Throws on
+ *   parse error so the caller fails fast at boot.
+ * - `saveConfig({ configPath, botName, config })` — atomic
+ *   read-merge-write. In-memory `config` is filtered (one bot's
+ *   scope only); to avoid clobbering OTHER bots on disk we read
+ *   the live file fresh, overlay our bot's section + chats, then
+ *   rename a temp file in place. Top-level non-bot-scoped fields
+ *   are NOT touched (ops-wide policy lives there).
+ * - `loadStickers(stickersPath)` — read sticker map. Returns
+ *   `{ stickerMap, emojiToSticker }`. Missing file is non-fatal:
+ *   returns empty maps and logs "No sticker map found".
+ * - `isWellFormedMessage(msg)` — pure predicate; quick shape
+ *   check before recordInbound runs hashing/DB-writes on
+ *   user-controlled Telegram updates.
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+function loadConfig(configPath) {
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+/**
+ * Atomic read-merge-write. We only ever write our bot's section +
+ * its chats; other bots in the same on-disk file are preserved.
+ * The temp file + rename is for atomicity (a crash mid-write
+ * leaves the .tmp.<pid> rather than a truncated config).
+ */
+function saveConfig({ configPath, botName, config }) {
+  const onDisk = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+  if (botName && config.bots?.[botName]) {
+    onDisk.bots = onDisk.bots || {};
+    onDisk.bots[botName] = config.bots[botName];
+  }
+  if (config.chats) {
+    onDisk.chats = onDisk.chats || {};
+    for (const [chatId, chat] of Object.entries(config.chats)) {
+      onDisk.chats[chatId] = chat;
+    }
+  }
+  // Top-level non-bot-scoped fields (defaults, maxWarmProcesses,
+  // etc.) are ops-wide policy — leave them as-is on disk.
+
+  const tmp = `${configPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(onDisk, null, 2));
+  fs.renameSync(tmp, configPath);
+}
+
+/**
+ * @returns {{ stickerMap: object, emojiToSticker: object }}
+ */
+function loadStickers(stickersPath, { logger = console } = {}) {
+  const stickerMap = {};
+  const emojiToSticker = {};
+  try {
+    const data = JSON.parse(fs.readFileSync(stickersPath, 'utf8'));
+    for (const [name, s] of Object.entries(data.stickers || {})) {
+      stickerMap[name] = s.file_id;
+      if (s.emoji) emojiToSticker[s.emoji] = s.file_id;
+    }
+    logger.log?.(`Stickers: ${Object.keys(stickerMap).join(', ')}`);
+  } catch {
+    logger.log?.('No sticker map found');
+  }
+  return { stickerMap, emojiToSticker };
+}
+
+/**
+ * Quick shape check before recordInbound runs. Telegram updates
+ * are user-controlled; a hostile or malformed payload without
+ * chat.id / message_id would throw deep in the writer.
+ */
+function isWellFormedMessage(msg) {
+  return !!(msg
+    && msg.chat
+    && (typeof msg.chat.id === 'number' || typeof msg.chat.id === 'bigint')
+    && typeof msg.message_id === 'number');
+}
+
+/**
+ * Quick shape check on `callback_query`. The handlers use optional
+ * chaining so they don't crash on malformed payloads, but skipping
+ * obviously-wrong shapes early keeps the events table cleaner and
+ * documents what we expect.
+ *
+ * Polygram only sends message-attached inline buttons — never
+ * INLINE-MODE keyboards. A callback with `inline_message_id` and
+ * no `message` is therefore either a leaked old keyboard from a
+ * deleted chat, an attacker-crafted update, or a Telegram API
+ * quirk; either way: skip.
+ */
+function isWellFormedCallbackQuery(cb) {
+  if (!cb) return false;
+  if (typeof cb.id !== 'string' && typeof cb.id !== 'number') return false;
+  if (!cb.from || typeof cb.from.id !== 'number') return false;
+  if (typeof cb.data !== 'string') return false;
+  // Inline-mode callbacks have inline_message_id in lieu of message;
+  // polygram never emits inline-mode keyboards, so reject.
+  if (!cb.message) return false;
+  if (!isWellFormedMessage(cb.message)) return false;
+  return true;
+}
+
+module.exports = {
+  loadConfig,
+  saveConfig,
+  loadStickers,
+  isWellFormedMessage,
+  isWellFormedCallbackQuery,
+};

package/lib/{error-classify.js → error/classify.js}

@@ -1,34 +1,26 @@
 /**
  * Error classifier — maps any error from any source to a stable shape.
  *
- * Sources today (0.7.7): stream-json `result` events with error
- * subtypes, child_process `'close'`/`'error'` event errors, idle
- * timer fires, polygram-internal Errors with `err.code` set.
+ * Sources covered: SDK iterator throws (`AbortError` named class plus
+ * plain `Error`s), `SDKResultMessage` with subtypes
+ * `error_during_execution` / `error_max_turns` / `error_max_budget_usd`
+ * / `error_max_structured_output_retries`, per-message
+ * `SDKAssistantMessage.error` subtypes (`authentication_failed` /
+ * `billing_error` / `rate_limit` / `invalid_request` / `server_error`
+ * / `unknown` / `max_output_tokens`), 5xx HTTP errors that bubble
+ * through the SDK transport, idle timer fires, polygram-internal
+ * Errors with `err.code` set (`INTERRUPTED`, `RESET_SESSION`, etc).
  *
- * Sources after 0.8.0 SDK migration: SDK iterator throws
- * (`AbortError` named class plus plain `Error`s), `SDKResultMessage`
- * with subtypes `error_during_execution` / `error_max_turns` /
- * `error_max_budget_usd` / `error_max_structured_output_retries`,
- * per-message `SDKAssistantMessage.error` subtypes
- * (`authentication_failed` / `billing_error` / `rate_limit` /
- * `invalid_request` / `server_error` / `unknown` / `max_output_tokens`),
- * 5xx HTTP errors that bubble through the SDK transport.
- *
- * Returning the same shape regardless of transport means
+ * Returning the same shape regardless of source means
  * `errorReplyText` in polygram.js doesn't grow N branches every time
  * a new error class shows up — we just add a row to PATTERNS or a
  * `code:` short-circuit at the top.
  *
- * Layered ship order (per v4 plan §6.5.1):
- *   - 0.7.7 (this file): transport-agnostic patterns and the public
- *     `classify()` API. Polygram.js's `errorReplyText` consults this
- *     module directly.
- *   - Phase 1 of 0.8.0 (later): adds typed-code branches for
- *     `INTERRUPTED`, plus SDK `error_max_structured_output_retries`,
- *     plus per-message SDK error subtypes.
- *   - Phase 2 of 0.8.0 (later): adds AUTO_RECOVER actions
- *     (`reset_session` etc) so pm can self-heal stuck sessions
- *     without waiting for the user to type /new.
+ * Returned shape:
+ *   { kind, userMessage, isTransient, autoRecover, shouldResetSession }
+ *
+ * AUTO_RECOVER actions ('reset_session' etc) let pm self-heal stuck
+ * sessions without waiting for the user to type /new.
  */
 
 'use strict';
@@ -104,8 +96,8 @@ const USER_MESSAGES = {
 };
 
 // Auto-recovery actions for kinds where the session is irrecoverable
-// without a reset. Phase 2 of 0.8.0 wires `pm.resetSession()` to
-// these; 0.7.7 just exports the table for forward-compat.
+// without a reset. polygram.js consults this when result.error fires
+// and dispatches `pm.resetSession()` accordingly.
 //
 // Values map to action names that pm understands:
 //   'reset_session' — close current Query, clear sessionId, fresh start
@@ -117,8 +109,8 @@ const AUTO_RECOVER = {
 };
 
 // Typed-code short-circuits — set on errors polygram throws itself
-// (see lib/process-manager.js), not pattern-matched. Keep these in
-// sync with the codes pm emits.
+// (see lib/process-manager-sdk.js), not pattern-matched. Keep these
+// in sync with the codes pm emits.
 const CODES = {
   // 0.7.6 (item H): queue cap drop. Pre-empts pattern matching so
   // the queue-overflow message is exact, not classified.
@@ -128,18 +120,17 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
-  // 0.8.0 Phase 1 will set this on pendings rejected via
-  // pm.interrupt(). Matched here so the abort-grace silence works
-  // before the SDK migration lands (pm could start setting it
-  // earlier as a no-op).
+  // Set on pendings rejected via pm.interrupt() (e.g. /stop). Matched
+  // here so the abort-grace silence works — user already saw the
+  // /stop ack, no need to surface another error.
   INTERRUPTED: {
     kind: 'interrupted',
-    userMessage: null, // suppressed; user already saw the /stop ack
+    userMessage: null,
     isTransient: false,
     autoRecover: null,
   },
-  // Phase 2 will set this when pm.resetSession() drains the queue
-  // for any reason (auto-recovery, /new, /reset, auth-expired).
+  // Set when pm.resetSession() drains the queue for any reason
+  // (auto-recovery, /new, /reset, auth-expired).
   RESET_SESSION: {
     kind: 'resetSession',
     userMessage: '✨ Started a fresh session.',

package/lib/handlers/abort.js

@@ -0,0 +1,89 @@
+/**
+ * Stop / abort handler.
+ *
+ * Detects natural-language stop cues ("stop" / "стоп" / "cancel" /
+ * "отмена") and explicit slash commands (/stop, /abort, /cancel) via
+ * the injected isAbortRequest predicate. On match:
+ *
+ *   1. Mark the session aborted BEFORE the SDK interrupt fires —
+ *      pm-sdk's close handler races; if we marked after, the
+ *      generic error-reply could slip through.
+ *   2. pm.interrupt() — non-destructive cancel of the in-flight
+ *      turn (preserves Query for the next user message).
+ *   3. pm.drainQueue() — rejects queued pendings with
+ *      err.code='INTERRUPTED' so the abort-grace classifier
+ *      suppresses error replies on the way out.
+ *   4. Clear ✍ reactions on already-autosteered messages from
+ *      this turn (now dead context).
+ *   5. Acknowledge in the language the user aborted in (en/ru).
+ *
+ * Returns true when the message was handled as an abort, false
+ * otherwise. Caller short-circuits on true.
+ */
+
+'use strict';
+
+function createHandleAbort({
+  pm,
+  bot,
+  tg,
+  logEvent,
+  isAbortRequest,
+  markSessionAborted,
+  clearAutosteeredReactions,
+  getSessionKey,
+  botName,
+  logger = console,
+} = {}) {
+
+  return async function handleAbortIfRequested(msg, chatId, chatConfig, cleanText) {
+    if (!isAbortRequest(cleanText)) return false;
+
+    const threadId = msg.message_thread_id?.toString();
+    const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+    const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
+
+    // Mark BEFORE killing: the 'close' event fires almost immediately
+    // after interrupt, and the surrounding handleMessage's catch
+    // needs to see the flag to skip the generic error-reply.
+    if (hadActive) markSessionAborted(sessionKey);
+
+    // SDK abort: interrupt() + drainQueue(). interrupt() cancels
+    // the in-flight turn at SDK level WITHOUT tearing down the
+    // Query (cheap to reuse for the user's next message);
+    // drainQueue() rejects every queued pending with
+    // err.code='INTERRUPTED' so the abort-grace classifier
+    // suppresses error replies.
+    await pm.interrupt(sessionKey).catch((err) =>
+      logger.error?.(`[${botName}] interrupt failed: ${err.message}`));
+    pm.drainQueue(sessionKey, 'INTERRUPTED');
+
+    clearAutosteeredReactions(sessionKey).catch(() => {});
+    logEvent('abort-requested', {
+      chat_id: chatId, user_id: msg.from?.id || null,
+      had_active: hadActive,
+      trigger: cleanText.slice(0, 40),
+    });
+
+    // Reply in the same language the user aborted in. Cyrillic-
+    // detection is crude but reliable for ru/en.
+    const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
+    const strs = {
+      en: { stopped: 'Stopped.',     nothing: 'Nothing to stop.' },
+      ru: { stopped: 'Остановлено.', nothing: 'Нечего останавливать.' },
+    }[lang];
+    const reply = hadActive ? strs.stopped : strs.nothing;
+    try {
+      await tg(bot, 'sendMessage', {
+        chat_id: chatId, text: reply,
+        reply_parameters: { message_id: msg.message_id, allow_sending_without_reply: true },
+        ...(threadId && { message_thread_id: threadId }),
+      }, { source: 'abort-ack', botName });
+    } catch (err) {
+      logger.error?.(`[${botName}] abort-ack send failed: ${err.message}`);
+    }
+    return true;
+  };
+}
+
+module.exports = { createHandleAbort };