polygram 0.1.0

package/config.example.json

@@ -0,0 +1,118 @@
+{
+  "_comment": "Copy to config.json and fill in real values. Two bots shown: one admin, one partner-facing with approvals + voice.",
+
+  "bots": {
+    "admin-bot": {
+      "token": "REPLACE_WITH_BOT_TOKEN_FROM_BOTFATHER",
+      "allowConfigCommands": true,
+      "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
+      "adminChatId": "123456789",
+      "needsToken": false,
+      "streamReplies": true,
+      "streamMinChars": 30,
+      "streamThrottleMs": 500,
+      "voice": {
+        "enabled": true,
+        "provider": "openai",
+        "openai": {
+          "apiKeyEnv": "OPENAI_API_KEY",
+          "model": "whisper-1"
+        },
+        "language": "auto",
+        "maxDurationSec": 600,
+        "ackReaction": "👂"
+      }
+    },
+
+    "partner-bot": {
+      "token": "REPLACE_WITH_PARTNER_BOT_TOKEN",
+      "needsToken": false,
+      "approvals": {
+        "adminChatId": "123456789",
+        "timeoutMs": 300000,
+        "gatedTools": [
+          "Bash(rm *)",
+          "Bash(git push *)",
+          "mcp__*__invoice_create",
+          "mcp__*__order_write"
+        ]
+      },
+      "voice": {
+        "enabled": true,
+        "provider": "local",
+        "local": {
+          "binary": "/opt/homebrew/bin/whisper-cpp",
+          "model": "/Users/you/models/ggml-base.en.bin"
+        }
+      }
+    }
+  },
+
+  "chats": {
+    "123456789": {
+      "name": "Admin DM",
+      "bot": "admin-bot",
+      "agent": "admin",
+      "model": "opus",
+      "effort": "medium",
+      "cwd": "/Users/you/admin-agent",
+      "timeout": 600
+    },
+
+    "-1000000000001": {
+      "name": "Ops Group",
+      "bot": "admin-bot",
+      "agent": "admin",
+      "model": "sonnet",
+      "effort": "low",
+      "cwd": "/Users/you/admin-agent",
+      "requireMention": true,
+      "_comment_isolateTopics": "Default false: all topics share one Claude context (intuitive for organisational topics). Set true for OpenClaw-style per-topic isolation when each topic is a genuinely separate project.",
+      "topics": {
+        "100": "Orders",
+        "200": "Billing",
+        "300": "Planning"
+      }
+    },
+
+    "-1000000000003": {
+      "name": "Projects Group (per-topic isolation)",
+      "bot": "admin-bot",
+      "agent": "admin",
+      "model": "sonnet",
+      "effort": "low",
+      "cwd": "/Users/you/admin-agent",
+      "requireMention": true,
+      "isolateTopics": true,
+      "topics": {
+        "100": "Customer A",
+        "200": "Customer B"
+      }
+    },
+
+    "-1000000000002": {
+      "name": "Partner Group",
+      "bot": "partner-bot",
+      "agent": "partner",
+      "model": "sonnet",
+      "effort": "low",
+      "cwd": "/Users/you/partner-agent",
+      "requireMention": true
+    }
+  },
+
+  "defaults": {
+    "model": "sonnet",
+    "effort": "low",
+    "timeout": 300,
+    "inboxRetentionDays": 30
+  },
+
+  "maxWarmProcesses": 10,
+
+  "attachmentLimits": {
+    "maxCount": 5,
+    "maxTotalMb": 20,
+    "maxFileMb": 10
+  }
+}

package/lib/approvals.js

@@ -0,0 +1,219 @@
+/**
+ * Approvals - inline keyboard gating for destructive tool calls.
+ *
+ * Claude Code fires a PreToolUse hook. The hook RPCs to the bridge daemon.
+ * The daemon inserts a pending row, posts [Approve]/[Deny] to the admin
+ * chat, and blocks on the operator's click (or a timeout).
+ *
+ * Persistence: `pending_approvals` row captures the whole lifecycle so we
+ * keep an audit trail even if the bridge restarts. Rows never get deleted;
+ * 'pending' rows at boot are swept into 'timeout'.
+ */
+
+const crypto = require('crypto');
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+// 16 random bytes → 22 base64url chars ≈ 128 bits of entropy. Prevents
+// brute-force guessing of approval callback tokens by anyone in the admin
+// chat (old 6-char value was ~36 bits, within chat-storm reach).
+const TOKEN_BYTES = 16;
+
+function digestInput(input) {
+  const json = typeof input === 'string' ? input : JSON.stringify(input);
+  return crypto.createHash('sha256').update(json).digest('hex').slice(0, 16);
+}
+
+function newToken() {
+  return crypto.randomBytes(TOKEN_BYTES).toString('base64url');
+}
+
+/**
+ * Constant-time compare. Different lengths → false without timing leak
+ * (timingSafeEqual itself throws on length mismatch).
+ */
+function tokensEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+/**
+ * Translate a Claude-Code-style permission pattern into a RegExp.
+ * Supported forms:
+ *   "Bash"                       - any Bash tool call
+ *   "Bash(rm *)"                 - Bash whose first-argument string matches glob
+ *   "mcp__shopify__order_cancel" - exact MCP tool name
+ *   "mcp__*__invoice_create"     - glob on segment
+ *   "WebFetch"                   - any WebFetch
+ * `*` matches anything non-greedily within a segment, including spaces.
+ */
+function patternToRegex(pattern) {
+  const trimmed = String(pattern).trim();
+  const parenIdx = trimmed.indexOf('(');
+  const toolPart = parenIdx === -1 ? trimmed : trimmed.slice(0, parenIdx);
+  const argPart = parenIdx === -1
+    ? null
+    : trimmed.slice(parenIdx + 1, trimmed.lastIndexOf(')'));
+
+  const escape = (s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  const globToRe = (s) => escape(s).replace(/\*/g, '.*');
+
+  const toolRe = new RegExp(`^${globToRe(toolPart)}$`);
+  const argRe = argPart == null ? null : new RegExp(`^${globToRe(argPart)}$`);
+  return { toolRe, argRe, raw: trimmed };
+}
+
+/**
+ * Check whether a tool call matches any of the configured patterns.
+ * `toolInput` is the original params object. We match on:
+ *   - Bash: first positional command (`command` param, space-split first token
+ *           or whole string for arg globs that include spaces)
+ *   - WebFetch: `url`
+ *   - others: the JSON stringification (coarse but safe default)
+ */
+function matchesAnyPattern(toolName, toolInput, patterns = []) {
+  const input = toolInput || {};
+  for (const raw of patterns) {
+    const p = patternToRegex(raw);
+    if (!p.toolRe.test(toolName)) continue;
+    if (!p.argRe) return { matched: true, pattern: p.raw };
+    let candidate = '';
+    if (toolName === 'Bash') {
+      candidate = input.command || '';
+    } else if (toolName === 'WebFetch') {
+      candidate = input.url || '';
+    } else {
+      candidate = typeof input === 'string' ? input : JSON.stringify(input);
+    }
+    if (p.argRe.test(candidate)) return { matched: true, pattern: p.raw };
+  }
+  return { matched: false };
+}
+
+function createStore(rawDb, now = () => Date.now()) {
+  const insertStmt = rawDb.prepare(`
+    INSERT INTO pending_approvals (
+      bot_name, turn_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,
+      @tool_name, @tool_input_json, @tool_input_digest,
+      @callback_token, @requested_ts, @timeout_ts
+    )
+  `);
+  const findDedupStmt = rawDb.prepare(`
+    SELECT * FROM pending_approvals
+     WHERE bot_name = ? AND turn_id IS ? AND tool_input_digest = ?
+       AND status = 'pending'
+     LIMIT 1
+  `);
+  const setApproverMsgStmt = rawDb.prepare(`
+    UPDATE pending_approvals SET approver_msg_id = ? WHERE id = ?
+  `);
+  const resolveStmt = rawDb.prepare(`
+    UPDATE pending_approvals
+       SET status = @status,
+           decided_ts = @decided_ts,
+           decided_by_user_id = @decided_by_user_id,
+           decided_by_user = @decided_by_user,
+           reason = @reason
+     WHERE id = @id AND status = 'pending'
+  `);
+  const getByIdStmt = rawDb.prepare(`SELECT * FROM pending_approvals WHERE id = ?`);
+  const listTimedOutStmt = rawDb.prepare(`
+    SELECT * FROM pending_approvals
+     WHERE status = 'pending' AND timeout_ts < ?
+  `);
+  const listPendingStmt = rawDb.prepare(`
+    SELECT * FROM pending_approvals
+     WHERE bot_name = ? AND status = 'pending'
+     ORDER BY requested_ts DESC
+  `);
+
+  return {
+    issue({
+      bot_name, turn_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');
+      if (!requester_chat_id) throw new Error('requester_chat_id required');
+      if (!approver_chat_id) throw new Error('approver_chat_id required');
+      if (!tool_name) throw new Error('tool_name required');
+
+      const tool_input_json = typeof tool_input === 'string'
+        ? tool_input
+        : JSON.stringify(tool_input || {});
+      const tool_input_digest = digestInput(tool_input_json);
+      const requested_ts = now();
+      const timeout_ts = requested_ts + timeoutMs;
+      const callback_token = newToken();
+
+      // Dedup: wrap find + insert in a single BEGIN IMMEDIATE transaction so
+      // two concurrent hook calls (same turn, same input) can't both miss
+      // 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.
+      let row, reused = false;
+      const tx = rawDb.transaction(() => {
+        const existing = findDedupStmt.get(bot_name, turn_id, tool_input_digest);
+        if (existing) { row = existing; reused = true; return; }
+        const res = insertStmt.run({
+          bot_name,
+          turn_id,
+          requester_chat_id: String(requester_chat_id),
+          approver_chat_id: String(approver_chat_id),
+          tool_name,
+          tool_input_json,
+          tool_input_digest,
+          callback_token,
+          requested_ts,
+          timeout_ts,
+        });
+        row = getByIdStmt.get(res.lastInsertRowid);
+      });
+      tx.immediate();  // BEGIN IMMEDIATE → write lock before the SELECT
+      if (reused) return { ...row, reused: true };
+      return row;
+    },
+
+    setApproverMsgId(id, msg_id) {
+      return setApproverMsgStmt.run(msg_id, id).changes;
+    },
+
+    resolve({ id, status, decided_by_user_id = null, decided_by_user = null, reason = null }) {
+      if (!['approved', 'denied', 'timeout', 'cancelled'].includes(status)) {
+        throw new Error(`bad status: ${status}`);
+      }
+      const res = resolveStmt.run({
+        id,
+        status,
+        decided_ts: now(),
+        decided_by_user_id,
+        decided_by_user,
+        reason,
+      });
+      return res.changes;
+    },
+
+    getById(id) { return getByIdStmt.get(id); },
+
+    listPending(bot_name) { return listPendingStmt.all(bot_name); },
+
+    sweepTimedOut() {
+      return listTimedOutStmt.all(now());
+    },
+  };
+}
+
+module.exports = {
+  createStore,
+  digestInput,
+  newToken,
+  tokensEqual,
+  patternToRegex,
+  matchesAnyPattern,
+  DEFAULT_TIMEOUT_MS,
+};

package/lib/attachments.js

@@ -0,0 +1,56 @@
+/**
+ * Attachment filter — caps count + total size + MIME allowlist.
+ * Rejected items return a human-readable reason that we surface to the
+ * user and log to the events table.
+ */
+
+const MAX_COUNT = 5;
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+const MIME_ALLOW = [
+  /^image\//, /^audio\//, /^video\//,
+  /^application\/pdf$/, /^text\/plain$/,
+  /^application\/msword$/, /^application\/vnd\.openxmlformats-/,
+  /^application\/vnd\.ms-excel$/, /^application\/json$/,
+  /^text\/csv$/,
+];
+
+function filterAttachments(attachments, opts = {}) {
+  const maxCount = opts.maxCount ?? MAX_COUNT;
+  const maxFileBytes = opts.maxFileBytes ?? MAX_FILE_BYTES;
+  const maxTotalBytes = opts.maxTotalBytes ?? MAX_TOTAL_BYTES;
+  const mimeAllow = opts.mimeAllow ?? MIME_ALLOW;
+
+  const accepted = [];
+  const rejected = [];
+  let totalBytes = 0;
+
+  for (const a of attachments || []) {
+    if (accepted.length >= maxCount) {
+      rejected.push({ att: a, reason: `exceeds max count (${maxCount})` });
+      continue;
+    }
+    const mime = a.mime_type || '';
+    if (!mimeAllow.some((re) => re.test(mime))) {
+      rejected.push({ att: a, reason: `mime not allowed (${mime || 'unknown'})` });
+      continue;
+    }
+    const size = a.size || 0;
+    // Telegram sometimes reports file_size=0 or omits it. Those bypass the
+    // cap here but the download step MUST re-check Content-Length and actual
+    // bytes — see downloadAttachments in bridge.js.
+    if (size > maxFileBytes) {
+      rejected.push({ att: a, reason: `exceeds per-file cap (${maxFileBytes} bytes, got ${size})` });
+      continue;
+    }
+    if (totalBytes + size > maxTotalBytes) {
+      rejected.push({ att: a, reason: `exceeds total size cap (${maxTotalBytes} bytes)` });
+      continue;
+    }
+    totalBytes += size;
+    accepted.push(a);
+  }
+  return { accepted, rejected, totalBytes };
+}
+
+module.exports = { filterAttachments, MAX_COUNT, MAX_FILE_BYTES, MAX_TOTAL_BYTES, MIME_ALLOW };

package/lib/config-scope.js

@@ -0,0 +1,49 @@
+/**
+ * Per-bot config scoping.
+ *
+ * `filterConfigToBot(config, botName)` narrows a full-bridge config down to
+ * the subset owned by one bot. Enables Phase 7 (per-bot process isolation):
+ * each bot runs in its own Node process, sees only its own chats, and can't
+ * accidentally touch another bot's queue or Claude pool.
+ */
+
+function parseBotArg(argv) {
+  return parseFlag(argv, '--bot', 'a bot name (e.g. --bot shumabit)');
+}
+
+function parseDbArg(argv) {
+  return parseFlag(argv, '--db', 'a path (e.g. --db /path/to/shumabit.db)');
+}
+
+function parseFlag(argv, flag, hint) {
+  const i = argv.indexOf(flag);
+  if (i === -1) return null;
+  const v = argv[i + 1];
+  if (!v || v.startsWith('--')) {
+    throw new Error(`${flag} requires ${hint}`);
+  }
+  return v;
+}
+
+function filterConfigToBot(config, botName) {
+  if (!config || !config.bots || !config.chats) {
+    throw new Error('config must have bots and chats');
+  }
+  if (!config.bots[botName]) {
+    throw new Error(`bot "${botName}" not in config.bots`);
+  }
+  const chats = {};
+  for (const [chatId, chat] of Object.entries(config.chats)) {
+    if (chat.bot === botName) chats[chatId] = chat;
+  }
+  if (Object.keys(chats).length === 0) {
+    throw new Error(`bot "${botName}" owns no chats in config.chats`);
+  }
+  return {
+    ...config,
+    bots: { [botName]: config.bots[botName] },
+    chats,
+  };
+}
+
+module.exports = { parseBotArg, parseDbArg, filterConfigToBot };