polygram 0.7.9 → 0.8.0-rc.1

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,169 @@
+/**
+ * Per-chat agent loader for the SDK migration (Phase 1 step 14 /
+ * v4 plan §6.5.5).
+ *
+ * Background: today's CLI pm passes `--agent <name>` on spawn; the
+ * Claude CLI then loads that agent's directory under
+ * `~/.claude/agents/<name>/` (system prompt from `CLAUDE.md`,
+ * skills, mcpServers from settings.json). Phase 0 gate 15 is DEFER —
+ * the SDK's `Options.agents` is for in-memory subagent definitions
+ * (the Task tool), NOT a "run THIS query AS this agent" mechanism.
+ *
+ * This module provides a polygram-side loader so buildSdkOptions
+ * can compose the per-chat agent's settings into the chat's
+ * SdkOptions: read the agent's CLAUDE.md (system prompt), enumerate
+ * its skills, pick up its mcpServers from settings.json. Then merge
+ * into the per-chat SdkOptions with chat-level overrides taking
+ * precedence (chatConfig wins over agent wins over defaults).
+ *
+ * Used by `polygram.js` `buildSdkOptions(sessionKey, ctx)` —
+ * Phase 1 step 14.
+ *
+ * Cache: agentName → resolved AgentBundle. Invalidated on SIGHUP
+ * (callable via `clearCache()`). Phase 5 acceptance includes "agent
+ * config edits don't require daemon restart" — but for 0.8.0
+ * initial release, restart-on-edit is acceptable; clearCache hook
+ * is forward-compat.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const cache = new Map();                       // agentName → AgentBundle
+
+/**
+ * Load an agent bundle from disk.
+ *
+ * @param {string} agentName — e.g. 'shumabit-finance'
+ * @param {object} opts
+ * @param {string} [opts.homeDir] — defaults to process.env.HOME.
+ *   Resolves agent at `${homeDir}/.claude/agents/${agentName}/`.
+ * @param {object} [opts.logger] — error logger.
+ *
+ * @returns {AgentBundle}
+ *   { agentName, agentDir, systemPrompt, skills: string[],
+ *     mcpServers: object, raw: settingsJson }
+ *
+ * Throws `{ code: 'AGENT_NOT_FOUND' }` if the agent dir doesn't
+ * exist. Does NOT throw on partial agents (missing CLAUDE.md or
+ * skills/ etc — fields just default to null/empty).
+ */
+function loadAgent(agentName, { homeDir = process.env.HOME, logger = console } = {}) {
+  if (cache.has(agentName)) return cache.get(agentName);
+
+  const agentDir = path.join(homeDir, '.claude', 'agents', agentName);
+  if (!fs.existsSync(agentDir)) {
+    throw Object.assign(
+      new Error(`agent not found: ${agentName} (looked in ${agentDir})`),
+      { code: 'AGENT_NOT_FOUND', agentDir },
+    );
+  }
+
+  // System prompt: prefer CLAUDE.md (the standard polygram convention),
+  // fall back to AGENTS.md (OpenClaw legacy), then to a single-line
+  // file `system-prompt.txt` if either of the markdown files is
+  // absent. Whichever is present, read as UTF-8 string.
+  let systemPrompt = null;
+  for (const fname of ['CLAUDE.md', 'AGENTS.md', 'system-prompt.txt']) {
+    const p = path.join(agentDir, fname);
+    if (fs.existsSync(p)) {
+      try {
+        systemPrompt = fs.readFileSync(p, 'utf8');
+        break;
+      } catch (err) {
+        logger.error?.(`[agent-loader] reading ${p}: ${err.message}`);
+      }
+    }
+  }
+
+  // Settings: optional `settings.json` for per-agent overrides
+  // (mcpServers, model, effort defaults, etc.).
+  let settings = {};
+  const settingsPath = path.join(agentDir, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (err) {
+      logger.error?.(`[agent-loader] parsing ${settingsPath}: ${err.message}`);
+    }
+  }
+
+  // Skills: enumerate `${agentDir}/skills/*` directories. SDK's
+  // `Options.skills` accepts a string[] of skill names.
+  const skillsDir = path.join(agentDir, 'skills');
+  let skills = [];
+  if (fs.existsSync(skillsDir)) {
+    try {
+      skills = fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    } catch (err) {
+      logger.error?.(`[agent-loader] enumerating ${skillsDir}: ${err.message}`);
+    }
+  }
+
+  const mcpServers = settings.mcpServers ?? {};
+
+  const bundle = {
+    agentName,
+    agentDir,
+    systemPrompt,
+    skills,
+    mcpServers,
+    // Pass through extra settings for callers that want them
+    // (e.g. agent-level model/effort defaults).
+    raw: settings,
+  };
+  cache.set(agentName, bundle);
+  return bundle;
+}
+
+/**
+ * Compose a chat's final SdkOptions from defaults + agent + per-chat
+ * overrides. Precedence: chatConfig > agent > defaults.
+ *
+ * @param {object} chatConfig — config.chats[chatId].
+ * @param {AgentBundle|null} agentBundle — null if chat has no agent.
+ * @param {object} defaults — config.defaults.
+ *
+ * @returns {object} SdkOptions for `query({ options: ... })`.
+ */
+function composeSdkOptions(chatConfig = {}, agentBundle = null, defaults = {}) {
+  // Start with defaults — these are the lowest-priority.
+  const opts = { ...defaults };
+
+  // Layer agent on top.
+  if (agentBundle) {
+    if (agentBundle.systemPrompt) opts.systemPrompt = agentBundle.systemPrompt;
+    if (agentBundle.skills?.length) opts.skills = agentBundle.skills;
+    if (agentBundle.mcpServers && Object.keys(agentBundle.mcpServers).length) {
+      opts.mcpServers = { ...(opts.mcpServers || {}), ...agentBundle.mcpServers };
+    }
+    // Agent-level model/effort/etc — only if chatConfig doesn't
+    // override.
+    for (const key of ['model', 'effort', 'thinking', 'permissionMode']) {
+      if (agentBundle.raw?.[key] != null && chatConfig[key] == null) {
+        opts[key] = agentBundle.raw[key];
+      }
+    }
+  }
+
+  // Chat-level overrides (highest priority).
+  for (const [k, v] of Object.entries(chatConfig)) {
+    if (v == null) continue;
+    // Don't override the spread system-prompt with `agent` config
+    // string — that's a polygram concept, not an SdkOptions field.
+    if (k === 'agent') continue;
+    opts[k] = v;
+  }
+
+  return opts;
+}
+
+function clearCache() {
+  cache.clear();
+}
+
+module.exports = { loadAgent, composeSdkOptions, clearCache, _cache: cache };

package/lib/approval-waiters.js

@@ -0,0 +1,194 @@
+/**
+ * Parked-Promise Map for canUseTool's async user-approval flow.
+ *
+ * Per v4 plan §6.5.3 / Phase 1 step 8.
+ *
+ * Background: under SDK migration, canUseTool is an in-process
+ * callback (replaces today's `bin/approval-hook.js` IPC). When a
+ * gated tool fires, polygram posts a Telegram inline-keyboard card
+ * to the admin chat and PARKS a Promise that resolves on user click.
+ * The SDK awaits that Promise — so the in-flight tool sleeps until
+ * the user decides.
+ *
+ * This module owns the waiter Map. Five cleanup paths are wired:
+ *   1. resolveByClick(toolUseId, decision) — user pressed a button
+ *   2. signal abort — SDK called Query.interrupt() / Query.close();
+ *      AbortSignal fires → Promise rejects with code:'ABORTED'
+ *   3. timeout — periodic sweeper rejects waiters parked > timeoutMs
+ *   4. rejectAllForSession(sessionKey) — pm.resetSession or kill
+ *   5. shutdown — daemon SIGTERM; reject all
+ *
+ * Memory bound: MAX_WAITERS (200). Park beyond cap throws a typed
+ * error so the caller can return `{behavior:'deny'}` to the SDK
+ * instead of accumulating garbage.
+ */
+
+'use strict';
+
+const DEFAULT_MAX_WAITERS = 200;
+const DEFAULT_TIMEOUT_MS = 60_000;             // 60s; matches OpenClaw cancel window
+const DEFAULT_SWEEP_INTERVAL_MS = 5_000;
+
+function createApprovalWaiters({
+  logger = console,
+  maxWaiters = DEFAULT_MAX_WAITERS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  sweepIntervalMs = DEFAULT_SWEEP_INTERVAL_MS,
+} = {}) {
+  // toolUseId → entry { resolve, reject, signal, sigCleanup,
+  //                     parkedAt, sessionKey }
+  const waiters = new Map();
+  let sweepTimer = null;
+
+  /**
+   * Park the canUseTool Promise; return a Promise that resolves on
+   * user click / rejects on signal-abort / timeout / shutdown.
+   *
+   * @param {object} args
+   * @param {string} args.toolUseId — SDK opts.toolUseID. Required.
+   * @param {string} args.sessionKey — for rejectAllForSession routing.
+   * @param {AbortSignal} [args.signal] — opts.signal from canUseTool.
+   *
+   * @returns {Promise<PermissionResult>}
+   * @throws {Error{code:'WAITER_CAP'}} if cap exceeded.
+   */
+  function park({ toolUseId, sessionKey, signal }) {
+    if (!toolUseId) {
+      throw Object.assign(new Error('toolUseId required'),
+                          { code: 'NO_TOOL_USE_ID' });
+    }
+    if (waiters.size >= maxWaiters) {
+      logger.error?.(`[approval-waiters] cap reached (${maxWaiters}); rejecting`);
+      throw Object.assign(
+        new Error(`approval waiter cap exceeded (${maxWaiters})`),
+        { code: 'WAITER_CAP' },
+      );
+    }
+    if (waiters.has(toolUseId)) {
+      // Concurrent canUseTool with same toolUseID — SDK doesn't
+      // typically retry the same call, but handle defensively by
+      // resolving the old one with a deny first.
+      logger.error?.(`[approval-waiters] duplicate toolUseId ${toolUseId}; abandoning prior waiter`);
+      const prior = waiters.get(toolUseId);
+      prior.reject(Object.assign(new Error('superseded'), { code: 'SUPERSEDED' }));
+    }
+
+    return new Promise((resolve, reject) => {
+      // signal-abort cleanup wired here so signal-fires always
+      // unparks the waiter, even if user click never arrives.
+      const sigCleanup = signal
+        ? () => {
+            const e = waiters.get(toolUseId);
+            if (e) {
+              waiters.delete(toolUseId);
+              e.reject(Object.assign(new Error('aborted'), { code: 'ABORTED' }));
+            }
+          }
+        : null;
+      if (signal && sigCleanup) {
+        signal.addEventListener('abort', sigCleanup, { once: true });
+      }
+
+      waiters.set(toolUseId, {
+        resolve: (decision) => {
+          if (signal && sigCleanup) {
+            try { signal.removeEventListener('abort', sigCleanup); }
+            catch { /* swallow */ }
+          }
+          waiters.delete(toolUseId);
+          resolve(decision);
+        },
+        reject: (err) => {
+          if (signal && sigCleanup) {
+            try { signal.removeEventListener('abort', sigCleanup); }
+            catch { /* swallow */ }
+          }
+          waiters.delete(toolUseId);
+          reject(err);
+        },
+        signal,
+        parkedAt: Date.now(),
+        sessionKey,
+      });
+    });
+  }
+
+  /**
+   * Path 1: user clicked a button. `decision` is the
+   * SDK-shape PermissionResult.
+   */
+  function resolveByClick(toolUseId, decision) {
+    const e = waiters.get(toolUseId);
+    if (!e) return false;
+    e.resolve(decision);
+    return true;
+  }
+
+  /**
+   * Path 4: pm.resetSession or kill. Reject every waiter whose
+   * sessionKey matches.
+   */
+  function rejectAllForSession(sessionKey, code = 'RESET_SESSION') {
+    let count = 0;
+    for (const [id, e] of [...waiters.entries()]) {
+      if (e.sessionKey === sessionKey) {
+        e.reject(Object.assign(new Error('session reset'), { code }));
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Path 5: daemon shutdown. Reject every waiter.
+   */
+  function rejectAll(code = 'DAEMON_SHUTDOWN') {
+    let count = 0;
+    for (const [id, e] of [...waiters.entries()]) {
+      e.reject(Object.assign(new Error('daemon shutdown'), { code }));
+      count++;
+    }
+    return count;
+  }
+
+  /**
+   * Path 3: timeout sweeper. Periodically reject waiters parked
+   * longer than timeoutMs.
+   */
+  function startTimeoutSweeper() {
+    if (sweepTimer) return;
+    const sweep = () => {
+      const cutoff = Date.now() - timeoutMs;
+      for (const [id, e] of [...waiters.entries()]) {
+        if (e.parkedAt < cutoff) {
+          e.reject(Object.assign(new Error('approval timeout'),
+                                  { code: 'TIMEOUT' }));
+        }
+      }
+    };
+    sweepTimer = setInterval(sweep, sweepIntervalMs);
+    sweepTimer.unref?.();
+  }
+
+  function stopTimeoutSweeper() {
+    if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+  }
+
+  return {
+    park,
+    resolveByClick,
+    rejectAllForSession,
+    rejectAll,
+    startTimeoutSweeper,
+    stopTimeoutSweeper,
+    get size() { return waiters.size; },
+    // Test introspection only:
+    _waiters: waiters,
+  };
+}
+
+module.exports = {
+  createApprovalWaiters,
+  DEFAULT_MAX_WAITERS,
+  DEFAULT_TIMEOUT_MS,
+};

package/lib/db.js

@@ -8,13 +8,18 @@ const fs = require('fs');
 const path = require('path');
 const Database = require('better-sqlite3');
 
-// 0.7.8: bumped from 8 → 9. 0.7.6 added migration 009-turn-metrics.sql
-// but failed to bump SCHEMA_VERSION; the early-return on line ~36
-// skipped the migration loop on any DB already at user_version=8 (any
-// upgraded install) → turn_metrics table never created → INSERT prepare
-// at startup crashed polygram. Both 0.7.6 and 0.7.7 shipped with the
-// bug. Fixed by bumping the constant.
-const SCHEMA_VERSION = 9;
+// 0.8.0 Phase 1: bumped from 9 → 10. Adds migration
+// 010-tool-use-id.sql (pending_approvals.tool_use_id column for the
+// SDK canUseTool stable per-call ID + chat_tool_decisions table for
+// "always allow / always deny" persistence under the new in-process
+// approval flow).
+//
+// 0.7.8 (history): bumped from 8 → 9 to fix a regression where 0.7.6
+// added migration 009-turn-metrics.sql but forgot to bump
+// SCHEMA_VERSION; the early-return on line ~42 then skipped the
+// migration loop on any DB already at user_version=8 → turn_metrics
+// table never created → INSERT prepare at startup crashed polygram.
+const SCHEMA_VERSION = 10;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo
@@ -188,6 +193,35 @@ function wrap(db) {
     )
   `);
 
+  // 0.8.0 Phase 1 step 8 — chat_tool_decisions persistence for the
+  // SDK canUseTool flow. Queried at the START of canUseTool to
+  // short-circuit "always allow / always deny" decisions before
+  // posting a Telegram inline-keyboard card. Migration 010 created
+  // the table; queries here. See v4 plan §6.5.4.
+  const lookupChatToolDecisionsStmt = db.prepare(`
+    SELECT match_type, input_pattern, decision, expires_ts
+      FROM chat_tool_decisions
+     WHERE bot_name = @bot_name
+       AND chat_id  = @chat_id
+       AND tool_name = @tool_name
+       AND (expires_ts IS NULL OR expires_ts > @now)
+  `);
+  const insertChatToolDecisionStmt = db.prepare(`
+    INSERT INTO chat_tool_decisions (
+      bot_name, chat_id, tool_name, match_type,
+      input_pattern, decision,
+      issued_ts, issued_by_user_id, expires_ts
+    ) VALUES (
+      @bot_name, @chat_id, @tool_name, @match_type,
+      @input_pattern, @decision,
+      @issued_ts, @issued_by_user_id, @expires_ts
+    )
+  `);
+  const deleteChatToolDecisionStmt = db.prepare(`
+    DELETE FROM chat_tool_decisions
+     WHERE bot_name = ? AND chat_id = ? AND id = ?
+  `);
+
   const markStalePendingStmt = db.prepare(`
     UPDATE messages SET status = 'failed', error = '${CRASHED_MID_SEND}'
     WHERE status = 'pending' AND ts < ?
@@ -326,6 +360,58 @@ function wrap(db) {
       });
     },
 
+    /**
+     * 0.8.0 Phase 1 step 8 — chat_tool_decisions persistence.
+     *
+     * Look up "always allow / always deny" decisions for a tool
+     * call. Returns the FIRST matching decision (by id ASC) whose
+     * match_type accepts the canonical input. Pattern matching is
+     * done in-process here so the SQL query stays simple.
+     *
+     * Canonical input: keys sorted alphabetically, no whitespace.
+     * Done by the caller (canUseTool wrapper) — we accept the
+     * pre-canonicalised string as `canonical_input`.
+     */
+    lookupChatToolDecision({ bot_name, chat_id, tool_name, canonical_input, now }) {
+      const rows = lookupChatToolDecisionsStmt.all({
+        bot_name: String(bot_name),
+        chat_id: String(chat_id),
+        tool_name: String(tool_name),
+        now: now || Date.now(),
+      });
+      for (const r of rows) {
+        if (r.match_type === 'exact') {
+          if (r.input_pattern === canonical_input) return r;
+        } else if (r.match_type === 'prefix') {
+          if (canonical_input?.startsWith?.(r.input_pattern)) return r;
+        } else if (r.match_type === 'regex') {
+          try {
+            if (new RegExp(r.input_pattern).test(canonical_input || '')) return r;
+          } catch { /* malformed regex — ignore */ }
+        }
+      }
+      return null;
+    },
+
+    insertChatToolDecision(row) {
+      return insertChatToolDecisionStmt.run({
+        bot_name: String(row.bot_name),
+        chat_id: String(row.chat_id),
+        tool_name: String(row.tool_name),
+        match_type: row.match_type,
+        input_pattern: row.input_pattern,
+        decision: row.decision,
+        issued_ts: row.issued_ts || Date.now(),
+        issued_by_user_id: row.issued_by_user_id != null
+          ? String(row.issued_by_user_id) : null,
+        expires_ts: row.expires_ts ?? null,
+      });
+    },
+
+    deleteChatToolDecision({ bot_name, chat_id, id }) {
+      return deleteChatToolDecisionStmt.run(String(bot_name), String(chat_id), id);
+    },
+
     logConfigChange(row) {
       return logConfigChangeStmt.run({
         chat_id: String(row.chat_id),