polygram 0.8.0-rc.9 → 0.8.0

package/lib/agent-loader.js

@@ -3,18 +3,26 @@
  * 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.
+ * 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`.
  *
- * 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).
+ * Search order (rc.13+ — supports BOTH Claude Code's standard
+ * single-file convention AND polygram's pre-0.8.0 directory layout):
+ *
+ *   1. `<cwd>/.claude/agents/<name>.md`          — Claude Code project-level
+ *   2. `<homeDir>/.claude/agents/<name>.md`      — Claude Code user-level
+ *   3. `<cwd>/.claude/agents/<name>/CLAUDE.md`   — polygram convention
+ *      (also `AGENTS.md`, `system-prompt.txt`)
+ *   4. `<homeDir>/.claude/agents/<name>/CLAUDE.md` — polygram legacy
+ *      (also `AGENTS.md`, `system-prompt.txt`)
+ *
+ * Single-file Claude Code agents may have YAML frontmatter; we strip
+ * it before using the body as systemPrompt. Frontmatter `model` /
+ * `effort` are merged into the bundle.raw so composeSdkOptions can
+ * use them as agent-level defaults.
  *
  * Used by `polygram.js` `buildSdkOptions(sessionKey, ctx)` —
  * Phase 1 step 14.
@@ -31,106 +39,330 @@
 const fs = require('fs');
 const path = require('path');
 
-const cache = new Map();                       // agentName → AgentBundle
+const cache = new Map();                       // cacheKey → AgentBundle
+
+// Resolve agent file by checking each search path in order.
+// Returns { kind: 'file'|'dir', path, dir | null } or null.
+// Restrict agent names to a conservative charset so they can't
+// path-traverse out of the `.claude/agents/` directory. Pre-fix, an
+// agent name like `../../etc/passwd` silently resolved to whatever
+// existed at that path, loading arbitrary file content as the
+// system prompt. Chat configs are operator-controlled (not user
+// input), so the practical threat is operator typos — but pinning
+// the contract removes the foot-gun.
+//
+// Allowed: alphanumerics, hyphen, underscore, single dots inside
+// (e.g. "shumabit-finance.v2"). Forbidden: leading/trailing dot,
+// consecutive dots, slashes, NUL.
+const AGENT_NAME_RE = /^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$/;
+
+// rc.49: parse `<plugin>:<agent>` qualified names. Each side must
+// independently satisfy AGENT_NAME_RE. Returns { plugin, agent } or
+// null if not qualified or malformed.
+function parseQualifiedName(name) {
+  if (typeof name !== 'string' || !name.includes(':')) return null;
+  const parts = name.split(':');
+  if (parts.length !== 2) return null;
+  const [plugin, agent] = parts;
+  if (!AGENT_NAME_RE.test(plugin) || !AGENT_NAME_RE.test(agent)) return null;
+  return { plugin, agent };
+}
+
+// rc.49: look up a plugin's installPath in
+// ~/.claude/plugins/installed_plugins.json. Keys are
+// `<name>@<marketplace>` — match by the bare `<name>` prefix and
+// return the first installed entry's `installPath`. Returns null if
+// not enrolled or registry unreadable.
+function lookupInstalledPlugin(pluginName, homeDir) {
+  const registryPath = path.join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+  if (!fs.existsSync(registryPath)) return null;
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  const plugins = registry?.plugins || {};
+  const prefix = pluginName + '@';
+  for (const key of Object.keys(plugins)) {
+    if (key.startsWith(prefix)) {
+      const entries = plugins[key];
+      if (Array.isArray(entries) && entries[0]?.installPath) {
+        return entries[0].installPath;
+      }
+    }
+  }
+  return null;
+}
+
+function resolveAgentLocation(agentName, homeDir, cwd) {
+  if (typeof agentName !== 'string') return null;
+
+  // rc.49: plugin-qualified `<plugin>:<agent>` names look up the plugin
+  // from the installed registry (with fallback to ~/.claude-plugins-local/).
+  // Resolution is intentionally NARROW — only the qualified form
+  // searches plugin directories. Plain unqualified names keep the
+  // pre-rc.49 ~/.claude/agents/ + <cwd>/.claude/agents/ behaviour.
+  const qualified = parseQualifiedName(agentName);
+  if (qualified) {
+    const { plugin, agent } = qualified;
+    const installPath = lookupInstalledPlugin(plugin, homeDir);
+    if (installPath) {
+      const p = path.join(installPath, 'agents', agent + '.md');
+      if (fs.existsSync(p)) return { kind: 'file', path: p, dir: null };
+    }
+    // Fallback: ~/.claude-plugins-local/<plugin>/agents/<agent>.md
+    const localPath = path.join(homeDir, '.claude-plugins-local', plugin, 'agents', agent + '.md');
+    if (fs.existsSync(localPath)) return { kind: 'file', path: localPath, dir: null };
+    return null;
+  }
+
+  if (!AGENT_NAME_RE.test(agentName)) return null;
+
+  const fileCandidates = [];
+  if (cwd) fileCandidates.push(path.join(cwd, '.claude', 'agents', agentName + '.md'));
+  fileCandidates.push(path.join(homeDir, '.claude', 'agents', agentName + '.md'));
+  for (const p of fileCandidates) {
+    if (fs.existsSync(p)) return { kind: 'file', path: p, dir: null };
+  }
+  const dirCandidates = [];
+  if (cwd) dirCandidates.push(path.join(cwd, '.claude', 'agents', agentName));
+  dirCandidates.push(path.join(homeDir, '.claude', 'agents', agentName));
+  for (const d of dirCandidates) {
+    if (fs.existsSync(d) && fs.statSync(d).isDirectory()) {
+      return { kind: 'dir', path: d, dir: d };
+    }
+  }
+  return null;
+}
+
+// Strip leading YAML frontmatter (---\n...\n---\n) from markdown.
+function stripFrontmatter(content) {
+  if (typeof content !== 'string' || !content.startsWith('---\n')) return content;
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) return content;
+  return content.slice(end + 5);
+}
+
+// Recursively expand Claude Code @<file> import directives. A line
+// starting with `@<path>` is replaced with the file's contents
+// (frontmatter stripped, imports recursively expanded). Paths
+// resolve relative to the importing file's directory FIRST, then
+// fall back to cwd. Cycle detection via visited Set.
+//
+// rc.15: pre-rc.15 the literal "@_shumabit-base.md" reached the
+// model verbatim because polygram's loader didn't process imports.
+// Symptom: agent appeared loaded but the system prompt was
+// effectively empty (just an unresolved import directive).
+function expandImports(content, importingFile, cwd, visited, logger) {
+  if (typeof content !== 'string' || !content) return content;
+  const lines = content.split('\n');
+  const out = [];
+  for (const line of lines) {
+    const m = /^@(\S+)\s*$/.exec(line);
+    if (!m) {
+      out.push(line);
+      continue;
+    }
+    const ref = m[1];
+    const importingDir = path.dirname(importingFile);
+    // Resolution order: relative to importing file's dir; relative
+    // to cwd; absolute path as-is.
+    const candidates = [];
+    if (path.isAbsolute(ref)) {
+      candidates.push(ref);
+    } else {
+      candidates.push(path.join(importingDir, ref));
+      if (cwd) candidates.push(path.join(cwd, ref));
+    }
+    let resolved = null;
+    for (const c of candidates) {
+      if (fs.existsSync(c)) { resolved = c; break; }
+    }
+    if (!resolved) {
+      logger?.warn?.(`[agent-loader] @-import not found: ${ref} (in ${importingFile})`);
+      out.push(line);
+      continue;
+    }
+    if (visited.has(resolved)) {
+      logger?.warn?.(`[agent-loader] @-import cycle: ${resolved}`);
+      continue;
+    }
+    visited.add(resolved);
+    let imported = '';
+    try {
+      imported = fs.readFileSync(resolved, 'utf8');
+    } catch (err) {
+      logger?.error?.(`[agent-loader] reading @-import ${resolved}: ${err.message}`);
+      out.push(line);
+      continue;
+    }
+    // Strip frontmatter from imported file (same convention as
+    // top-level agent file) and recursively expand its imports.
+    imported = stripFrontmatter(imported);
+    imported = expandImports(imported, resolved, cwd, visited, logger);
+    out.push(imported);
+  }
+  return out.join('\n');
+}
+
+// Parse a tiny subset of YAML frontmatter (key: value lines).
+function parseFrontmatter(content) {
+  if (typeof content !== 'string' || !content.startsWith('---\n')) return {};
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+  const block = content.slice(4, end);
+  const out = {};
+  for (const line of block.split('\n')) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    out[m[1]] = v;
+  }
+  return out;
+}
 
 /**
  * Load an agent bundle from disk.
  *
- * @param {string} agentName — e.g. 'shumabit-finance'
+ * @param {string} agentName
  * @param {object} opts
  * @param {string} [opts.homeDir] — defaults to process.env.HOME.
- *   Resolves agent at `${homeDir}/.claude/agents/${agentName}/`.
+ * @param {string} [opts.cwd] — chat's working directory; checked
+ *   FIRST for Claude Code project-level agent discovery.
  * @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);
+function loadAgent(agentName, { homeDir = process.env.HOME, cwd = null, logger = console } = {}) {
+  // Cache key includes cwd because the same agentName can resolve
+  // to different files when called from different chats with
+  // different cwds (e.g. shumabit-claude vs shumabit-partners).
+  const cacheKey = agentName + '\x00' + (cwd || '');
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
 
-  const agentDir = path.join(homeDir, '.claude', 'agents', agentName);
-  if (!fs.existsSync(agentDir)) {
+  const loc = resolveAgentLocation(agentName, homeDir, cwd);
+  if (!loc) {
+    const looked = [
+      cwd ? cwd + '/.claude/agents/' + agentName + '.md' : null,
+      homeDir + '/.claude/agents/' + agentName + '.md',
+      cwd ? cwd + '/.claude/agents/' + agentName + '/' : null,
+      homeDir + '/.claude/agents/' + agentName + '/',
+    ].filter(Boolean).join(', ');
     throw Object.assign(
-      new Error(`agent not found: ${agentName} (looked in ${agentDir})`),
-      { code: 'AGENT_NOT_FOUND', agentDir },
+      new Error('agent not found: ' + agentName + ' (looked in ' + looked + ')'),
+      { code: 'AGENT_NOT_FOUND', searchPaths: looked },
     );
   }
 
-  // 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}`);
+  let frontmatter = {};
+  let agentPath = loc.path;
+
+  if (loc.kind === 'file') {
+    // Claude Code single-file format. Read whole file, parse and
+    // strip frontmatter, body becomes systemPrompt. Then expand
+    // any @<file> import directives recursively (rc.15).
+    try {
+      const raw = fs.readFileSync(loc.path, 'utf8');
+      frontmatter = parseFrontmatter(raw);
+      const stripped = stripFrontmatter(raw);
+      const visited = new Set([loc.path]);
+      systemPrompt = expandImports(stripped, loc.path, cwd, visited, logger);
+    } catch (err) {
+      logger.error?.('[agent-loader] reading ' + loc.path + ': ' + err.message);
+    }
+  } else {
+    // polygram directory layout. CLAUDE.md > AGENTS.md > system-prompt.txt.
+    for (const fname of ['CLAUDE.md', 'AGENTS.md', 'system-prompt.txt']) {
+      const p = path.join(loc.dir, fname);
+      if (fs.existsSync(p)) {
+        try {
+          const raw = fs.readFileSync(p, 'utf8');
+          // Expand @-imports for directory-layout agents too —
+          // their content might also reference shared base files.
+          const visited = new Set([p]);
+          systemPrompt = expandImports(raw, p, cwd, visited, logger);
+          agentPath = p;
+          break;
+        } catch (err) {
+          logger.error?.('[agent-loader] reading ' + p + ': ' + err.message);
+        }
       }
     }
   }
 
-  // Settings: optional `settings.json` for per-agent overrides
-  // (mcpServers, model, effort defaults, etc.).
+  // Settings.json — only meaningful for directory-layout agents.
   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}`);
+  if (loc.dir) {
+    const settingsPath = path.join(loc.dir, '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');
+  // Skills (only for directory layout).
   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}`);
+  if (loc.dir) {
+    const skillsDir = path.join(loc.dir, '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 ?? {};
 
+  // Frontmatter merged with settings — composeSdkOptions can pick up
+  // model/effort overrides from either source.
+  const raw = { ...frontmatter, ...settings };
+
   const bundle = {
     agentName,
-    agentDir,
+    agentPath,
+    agentDir: loc.dir,
     systemPrompt,
     skills,
     mcpServers,
-    // Pass through extra settings for callers that want them
-    // (e.g. agent-level model/effort defaults).
-    raw: settings,
+    raw,
   };
-  cache.set(agentName, bundle);
+  cache.set(cacheKey, bundle);
   return bundle;
 }
 
 /**
  * Compose a chat's final SdkOptions from defaults + agent + per-chat
- * overrides. Precedence: chatConfig > agent > defaults.
+ * overrides + per-topic overrides. Precedence (highest to lowest):
+ *   topicConfig > chatConfig > agent.raw > defaults
+ *
+ * rc.48 added the per-topic layer (`topicConfig` arg). Per-topic
+ * overrides are the principal rc.48 use case — typically loosening
+ * an agent's `bypassPermissions` default to `default` for a sensitive
+ * topic (so canUseTool prompts fire there) while keeping the rest of
+ * the chat in bypass mode. Per-topic permissionMode MUST override the
+ * chat-level one for this to work.
  *
  * @param {object} chatConfig — config.chats[chatId].
  * @param {AgentBundle|null} agentBundle — null if chat has no agent.
  * @param {object} defaults — config.defaults.
+ * @param {object} [topicConfig] — per-topic overrides from
+ *   getTopicConfig(chatConfig, threadId). Empty object when there's
+ *   no active topic, no override config, or topic uses legacy string
+ *   form. Highest precedence — overrides chatConfig.
  *
  * @returns {object} SdkOptions for `query({ options: ... })`.
  */
-function composeSdkOptions(chatConfig = {}, agentBundle = null, defaults = {}) {
+function composeSdkOptions(chatConfig = {}, agentBundle = null, defaults = {}, topicConfig = {}) {
   // Start with defaults — these are the lowest-priority.
   const opts = { ...defaults };
 
@@ -141,16 +373,18 @@ function composeSdkOptions(chatConfig = {}, agentBundle = null, defaults = {}) {
     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.
+    // Agent-level model/effort/etc — only if chatConfig AND
+    // topicConfig don't override.
     for (const key of ['model', 'effort', 'thinking', 'permissionMode']) {
-      if (agentBundle.raw?.[key] != null && chatConfig[key] == null) {
+      if (agentBundle.raw?.[key] != null
+          && chatConfig[key] == null
+          && topicConfig?.[key] == null) {
         opts[key] = agentBundle.raw[key];
       }
     }
   }
 
-  // Chat-level overrides (highest priority).
+  // Chat-level overrides.
   for (const [k, v] of Object.entries(chatConfig)) {
     if (v == null) continue;
     // Don't override the spread system-prompt with `agent` config
@@ -159,6 +393,18 @@ function composeSdkOptions(chatConfig = {}, agentBundle = null, defaults = {}) {
     opts[k] = v;
   }
 
+  // rc.48: per-topic overrides (highest priority). Same `agent` exclusion
+  // — `agent` here is a polygram name reference, NOT an SdkOptions
+  // field. polygram's spawn flow resolves topicConfig.agent into the
+  // correct agentBundle BEFORE calling composeSdkOptions, so by the
+  // time we get here, agentBundle already reflects the topic's agent
+  // choice and the `agent` string itself shouldn't leak into opts.
+  for (const [k, v] of Object.entries(topicConfig || {})) {
+    if (v == null) continue;
+    if (k === 'agent') continue;
+    opts[k] = v;
+  }
+
   return opts;
 }
 
@@ -166,4 +412,14 @@ function clearCache() {
   cache.clear();
 }
 
-module.exports = { loadAgent, composeSdkOptions, clearCache, _cache: cache };
+module.exports = {
+  loadAgent,
+  composeSdkOptions,
+  clearCache,
+  // Internals for tests.
+  _resolveAgentLocation: resolveAgentLocation,
+  _stripFrontmatter: stripFrontmatter,
+  _parseFrontmatter: parseFrontmatter,
+  _expandImports: expandImports,
+  _cache: cache,
+};

package/lib/approval-ui.js

@@ -0,0 +1,135 @@
+/**
+ * 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
+ *     "Always allow / Always deny" via chat_tool_decisions)
+ *   - Card text with friendly heading + clipped tool_input body
+ *
+ * No runtime dependencies — these are pure transforms suitable for
+ * unit-testing in isolation. The polygram.js side wires them to
+ * `tg(bot, 'sendMessage', ...)` / `editMessageText`.
+ */
+
+'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
+ * `chat_tool_decisions` so subsequent invocations of the same tool
+ * with the same input short-circuit.
+ *
+ * Callback_data conventions:
+ *   approve:<id>:<token>          — one-time allow
+ *   deny:<id>:<token>             — one-time deny
+ *   approve-always:<id>:<token>   — allow + persist
+ *   deny-always:<id>:<token>      — deny + persist
+ *
+ * @param {number|string} approvalId
+ * @param {string} token
+ */
+function buildApprovalKeyboardWithAlways(approvalId, token) {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Approve', callback_data: `approve:${approvalId}:${token}` },
+        { text: '❌ Deny',    callback_data: `deny:${approvalId}:${token}` },
+      ],
+      [
+        { text: '🔁 Always allow', callback_data: `approve-always:${approvalId}:${token}` },
+        { text: '🚫 Always deny',  callback_data: `deny-always:${approvalId}:${token}` },
+      ],
+    ],
+  };
+}
+
+/**
+ * Format a tool_input value for the inline-keyboard card body.
+ * Clips aggressively so the whole card stays under Telegram's
+ * 4096-char limit (approval card has surrounding metadata too).
+ *
+ * @param {unknown} input — string OR any JSON-able object
+ * @returns {string}
+ */
+function formatToolInputForCard(input) {
+  let s;
+  try {
+    s = typeof input === 'string' ? input : JSON.stringify(input, null, 2);
+  } catch {
+    s = String(input);
+  }
+  // JSON.stringify(undefined) returns undefined, and objects with
+  // a circular toJSON could surface odd values too. Fall back to
+  // String() so we always operate on a real string.
+  if (typeof s !== 'string') s = String(input);
+  if (s.length <= 1200) return s;
+  return s.slice(0, 900) + '\n…[clipped]…\n' + s.slice(-200);
+}
+
+/**
+ * Approval card text. Plain-text only (NO parse_mode) — tool_input
+ * originates from Claude and could contain Markdown specials or
+ * tg:// links crafted for phishing.
+ *
+ * @param {object} row             — approval row from the approvals store
+ * @param {string} row.tool_name
+ * @param {number|string|null} row.turn_id
+ * @param {string} row.requester_chat_id
+ * @param {object|string|null} [row.tool_input_json]
+ * @param {object|string|null} [row.tool_input]    — alias for tool_input_json
+ * @param {number} row.timeout_ts  — unix ms when the row expires
+ * @param {object} [opts]
+ * @param {string} [opts.resolvedBy] — heading override for resolved cards
+ *                                     (e.g. "✓ Approved by ivan").
+ *                                     When set, footer is dropped.
+ *                                     When unset, heading is "Approval needed — <tool>"
+ *                                     and footer shows seconds-to-expire.
+ * @param {() => number} [opts.now]  — clock injection for tests
+ *
+ * @returns {string}
+ */
+function approvalCardText(row, opts = {}) {
+  const now = (typeof opts.now === 'function' ? opts.now : Date.now)();
+  const heading = opts.resolvedBy
+    ? opts.resolvedBy
+    : `Approval needed — ${row.tool_name}`;
+  // tool_input may arrive as a parsed object OR a JSON string under
+  // either key name depending on the call site.
+  const inputSource = row.tool_input_json !== undefined
+    ? row.tool_input_json
+    : row.tool_input;
+  const parsed = typeof inputSource === 'string'
+    ? safeParse(inputSource)
+    : inputSource;
+  const body = formatToolInputForCard(parsed);
+  const ttl = Math.max(0, Math.round((row.timeout_ts - now) / 1000));
+  const footer = opts.resolvedBy ? '' : `\n\n⏱ expires in ${ttl}s`;
+  return `${heading}\nChat: ${row.requester_chat_id}\nTurn: ${row.turn_id || '-'}\n\n${body}${footer}`;
+}
+
+function safeParse(s) {
+  try { return JSON.parse(s); } catch { return s; }
+}
+
+module.exports = {
+  buildApprovalKeyboard,
+  buildApprovalKeyboardWithAlways,
+  formatToolInputForCard,
+  approvalCardText,
+  // Internals exposed for tests
+  _safeParse: safeParse,
+};

package/lib/approval-waiters.js

@@ -110,6 +110,13 @@ function createApprovalWaiters({
         parkedAt: Date.now(),
         sessionKey,
       });
+
+      // If the signal was ALREADY aborted before we attached the
+      // listener, addEventListener never fires — the waiter would
+      // sit in the map until timeout-sweep / shutdown picked it up.
+      // Trigger the cleanup manually so the parked promise rejects
+      // immediately (matches "abort fired during park" semantics).
+      if (signal && signal.aborted) sigCleanup();
     });
   }
 

package/lib/approvals.js

@@ -11,6 +11,7 @@
  */
 
 const crypto = require('crypto');
+const { canonicalizeToolInput } = require('./canonical-json');
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 // 16 random bytes → 22 base64url chars ≈ 128 bits of entropy. Prevents
@@ -19,7 +20,14 @@ const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 const TOKEN_BYTES = 16;
 
 function digestInput(input) {
-  const json = typeof input === 'string' ? input : JSON.stringify(input);
+  // Canonicalise object inputs so key-order doesn't change the digest.
+  // Pre-fix `JSON.stringify({a:1,b:2})` and `JSON.stringify({b:2,a:1})`
+  // produced different hashes — the dedup contract assumed logical
+  // equivalence but the impl was order-sensitive, so an SDK that
+  // re-serialised the input between turns would dedup-miss.
+  const json = typeof input === 'string'
+    ? input
+    : JSON.stringify(canonicalizeToolInput(input));
   return crypto.createHash('sha256').update(json).digest('hex').slice(0, 16);
 }