polygram 0.1.0

package/lib/ipc-server.js

@@ -0,0 +1,149 @@
+/**
+ * Unix socket IPC server for the bridge daemon.
+ *
+ * One socket per bot process at `/tmp/polygram-<bot>.sock`. Clients
+ * (Claude Code approval hooks, future cron bridge) send newline-delimited
+ * JSON requests; the server invokes a registered handler and writes back a
+ * newline-delimited JSON response.
+ *
+ * Each TCP-equivalent connection is one request / one response — no pooling,
+ * no long-lived sessions. Simpler and matches the hook's one-shot lifecycle.
+ */
+
+const net = require('net');
+const fs = require('fs');
+const crypto = require('crypto');
+
+function socketPathFor(botName) {
+  return `/tmp/polygram-${botName}.sock`;
+}
+
+function secretPathFor(botName) {
+  return `/tmp/polygram-${botName}.secret`;
+}
+
+/**
+ * Generate and persist a fresh IPC secret. Written 0600 so only same-UID
+ * processes can read it; same-UID is already the trust boundary (they can
+ * also connect to the socket), but requiring knowledge of this secret gives
+ * us a cheap way to reject stray processes that stumbled onto the socket
+ * without intent — and makes the auth model explicit rather than implicit.
+ */
+function writeSecret(botName) {
+  const secret = crypto.randomBytes(32).toString('base64url');
+  const p = secretPathFor(botName);
+  fs.writeFileSync(p, secret, { mode: 0o600 });
+  // Re-chmod in case umask overrode our mode on create.
+  try { fs.chmodSync(p, 0o600); } catch {}
+  return secret;
+}
+
+function timingSafeEqual(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);
+}
+
+/**
+ * Start a unix-socket server. Returns a close() function.
+ *
+ * @param {Object} opts
+ * @param {string} opts.path       - socket path
+ * @param {Object} opts.handlers   - { op_name: async (req) => res }
+ * @param {Object} [opts.logger]   - console-like logger
+ * @param {number} [opts.mode]     - chmod on the socket (default 0o600)
+ */
+function start({ path, handlers, logger = console, mode = 0o600, secret = null }) {
+  // Stale socket cleanup — a crashed predecessor leaves the file.
+  try { fs.unlinkSync(path); } catch {}
+
+  const server = net.createServer((sock) => {
+    let buf = '';
+    sock.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      // Drain as many complete lines as the chunk contains. The earlier
+      // version handled only the first newline and silently dropped the
+      // rest — that was a correctness bug under cron storms.
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        handleLine(sock, line, handlers, logger, secret);
+      }
+    });
+    sock.on('error', (err) => {
+      if (err.code !== 'EPIPE' && err.code !== 'ECONNRESET') {
+        logger.error(`[ipc] socket error: ${err.message}`);
+      }
+    });
+  });
+
+  server.on('error', (err) => {
+    logger.error(`[ipc] server error: ${err.message}`);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.listen(path, () => {
+      try { fs.chmodSync(path, mode); } catch (err) {
+        logger.error(`[ipc] chmod ${path}: ${err.message}`);
+      }
+      logger.log(`[ipc] listening on ${path}`);
+      resolve({
+        close() {
+          return new Promise((res) => {
+            server.close(() => {
+              try { fs.unlinkSync(path); } catch {}
+              res();
+            });
+          });
+        },
+      });
+    });
+    server.once('error', reject);
+  });
+}
+
+async function handleLine(sock, line, handlers, logger, secret) {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch (err) {
+    writeReply(sock, { ok: false, error: `bad json: ${err.message}` });
+    return;
+  }
+  const op = req.op;
+  const id = req.id || null;
+  // Validate the shared secret (unless the server was started without one,
+  // in which case we're in a test or back-compat mode). The 'ping' op is
+  // exempt so liveness probes work without needing the secret.
+  if (secret && op !== 'ping') {
+    if (!timingSafeEqual(req.secret || '', secret)) {
+      logger.error(`[ipc] missing/bad secret on op=${op}`);
+      writeReply(sock, { id, ok: false, error: 'auth' });
+      return;
+    }
+  }
+  const handler = handlers[op];
+  if (!handler) {
+    writeReply(sock, { id, ok: false, error: `unknown op: ${op}` });
+    return;
+  }
+  try {
+    const res = await handler(req);
+    writeReply(sock, { id, ok: true, ...res });
+  } catch (err) {
+    logger.error(`[ipc] handler ${op} failed: ${err.message}`);
+    writeReply(sock, { id, ok: false, error: err.message });
+  }
+}
+
+function writeReply(sock, obj) {
+  try {
+    sock.write(JSON.stringify(obj) + '\n');
+    sock.end();
+  } catch {}
+}
+
+module.exports = { start, socketPathFor, secretPathFor, writeSecret };

package/lib/pairings.js

@@ -0,0 +1,215 @@
+/**
+ * Pairing codes - live onboarding without bridge restarts.
+ *
+ * Admin: /pair-code issues a single-use code. Short TTL (default 10 min).
+ * Guest: /pair <CODE> claims it, gets an ACL row in `pairings`.
+ *
+ * Trust model: a code is bound to one bot and optionally one chat. Claiming
+ * creates a pairing row the address-detector consults. Revocation is a soft
+ * delete so audit trails survive.
+ */
+
+const crypto = require('crypto');
+
+// Crockford-ish base32: no 0/O/1/I/L to avoid hand-entry confusion.
+const ALPHA = '23456789ABCDEFGHJKMNPQRSTVWXYZ';
+const CODE_LEN = 8;
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const MAX_TTL_MS = 7 * 24 * 3600 * 1000;
+const MIN_TTL_MS = 60 * 1000;
+
+const ISSUE_RATE_PER_OPERATOR_PER_HOUR = 10;
+const CLAIM_RATE_PER_USER_PER_HOUR = 5;
+
+function generateCode(len = CODE_LEN) {
+  const buf = crypto.randomBytes(len);
+  let out = '';
+  for (let i = 0; i < len; i++) out += ALPHA[buf[i] % ALPHA.length];
+  return out;
+}
+
+function normalizeCode(input) {
+  return String(input || '')
+    .toUpperCase()
+    .replace(/[\s-]/g, '');
+}
+
+function parseTtl(input) {
+  if (input == null) return DEFAULT_TTL_MS;
+  if (typeof input === 'number') return Math.max(MIN_TTL_MS, Math.min(MAX_TTL_MS, input));
+  // `s` was historically accepted but always rejected by MIN_TTL_MS; dropped.
+  const m = String(input).trim().match(/^(\d+)(m|h|d)$/);
+  if (!m) throw new Error(`invalid ttl: ${input} (use 10m, 1h, 1d)`);
+  const n = parseInt(m[1], 10);
+  const mult = { m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+  const ms = n * mult;
+  if (ms < MIN_TTL_MS) throw new Error(`ttl too short: ${input} (min 1m)`);
+  if (ms > MAX_TTL_MS) throw new Error(`ttl too long: ${input} (max 7d)`);
+  return ms;
+}
+
+function createStore(rawDb, now = () => Date.now()) {
+  const issueStmt = rawDb.prepare(`
+    INSERT INTO pair_codes
+      (code, bot_name, chat_id, scope, issued_by_user_id, issued_ts, expires_ts, note)
+    VALUES
+      (@code, @bot_name, @chat_id, @scope, @issued_by_user_id, @issued_ts, @expires_ts, @note)
+  `);
+  const findCodeStmt = rawDb.prepare(`SELECT * FROM pair_codes WHERE code = ?`);
+  const markCodeUsedStmt = rawDb.prepare(`
+    UPDATE pair_codes
+       SET used_by_user_id = @user_id, used_ts = @ts
+     WHERE code = @code AND used_ts IS NULL
+  `);
+  const insertPairingStmt = rawDb.prepare(`
+    INSERT INTO pairings
+      (bot_name, user_id, chat_id, granted_ts, granted_by_user_id, note)
+    VALUES
+      (@bot_name, @user_id, @chat_id, @granted_ts, @granted_by_user_id, @note)
+    ON CONFLICT(bot_name, user_id, chat_id) DO UPDATE SET
+      revoked_ts = NULL,
+      granted_ts = excluded.granted_ts,
+      granted_by_user_id = excluded.granted_by_user_id,
+      note = excluded.note
+  `);
+  const livePairingAnyChatStmt = rawDb.prepare(`
+    SELECT 1 FROM pairings
+     WHERE bot_name = ? AND user_id = ? AND chat_id IS NULL
+       AND revoked_ts IS NULL
+     LIMIT 1
+  `);
+  const livePairingChatStmt = rawDb.prepare(`
+    SELECT 1 FROM pairings
+     WHERE bot_name = ? AND user_id = ?
+       AND (chat_id IS NULL OR chat_id = ?)
+       AND revoked_ts IS NULL
+     LIMIT 1
+  `);
+  const revokeByUserStmt = rawDb.prepare(`
+    UPDATE pairings SET revoked_ts = ?
+     WHERE bot_name = ? AND user_id = ? AND revoked_ts IS NULL
+  `);
+  const listActiveStmt = rawDb.prepare(`
+    SELECT id, bot_name, user_id, chat_id, granted_ts, granted_by_user_id, note
+      FROM pairings
+     WHERE bot_name = ? AND revoked_ts IS NULL
+     ORDER BY granted_ts DESC
+  `);
+  const recentIssuesByOperatorStmt = rawDb.prepare(`
+    SELECT COUNT(*) AS n FROM pair_codes
+     WHERE bot_name = ? AND issued_by_user_id = ? AND issued_ts > ?
+  `);
+  const recentClaimsByUserStmt = rawDb.prepare(`
+    SELECT COUNT(*) AS n FROM pair_codes
+     WHERE used_by_user_id = ? AND used_ts > ?
+  `);
+
+  return {
+    issueCode({
+      bot_name, chat_id = null, scope = 'user',
+      issued_by_user_id, ttlMs, note = null,
+    }) {
+      if (!bot_name) throw new Error('bot_name required');
+      if (!Number.isFinite(issued_by_user_id)) throw new Error('issued_by_user_id required');
+      if (!['user', 'chat'].includes(scope)) throw new Error(`bad scope: ${scope}`);
+
+      const recent = recentIssuesByOperatorStmt.get(
+        bot_name, issued_by_user_id, now() - 3_600_000,
+      ).n;
+      if (recent >= ISSUE_RATE_PER_OPERATOR_PER_HOUR) {
+        throw new Error(`rate limit: ${recent} codes issued in last hour (max ${ISSUE_RATE_PER_OPERATOR_PER_HOUR})`);
+      }
+
+      const issued_ts = now();
+      const expires_ts = issued_ts + (ttlMs || DEFAULT_TTL_MS);
+      // Single attempt: the Crockford alphabet × 8 chars gives ~6.5×10¹¹
+      // codes. Combined with 10/hr/operator rate-limit, collision is
+      // astronomically unlikely. A retry loop would only swallow real DB
+      // errors (disk full, schema mismatch) as "just collided, try again".
+      const code = generateCode();
+      issueStmt.run({
+        code,
+        bot_name,
+        chat_id: chat_id ? String(chat_id) : null,
+        scope,
+        issued_by_user_id,
+        issued_ts,
+        expires_ts,
+        note,
+      });
+      return { code, issued_ts, expires_ts, bot_name, chat_id, scope, note };
+    },
+
+    claimCode({ code, claimer_user_id, chat_id, bot_name }) {
+      const norm = normalizeCode(code);
+
+      const recent = recentClaimsByUserStmt.get(claimer_user_id, now() - 3_600_000).n;
+      if (recent >= CLAIM_RATE_PER_USER_PER_HOUR) {
+        return { ok: false, reason: 'rate-limited' };
+      }
+
+      const row = findCodeStmt.get(norm);
+      if (!row) return { ok: false, reason: 'not-found' };
+      if (row.used_ts) return { ok: false, reason: 'already-used' };
+      if (row.expires_ts < now()) return { ok: false, reason: 'expired' };
+      if (row.bot_name !== bot_name) return { ok: false, reason: 'wrong-bot' };
+      if (row.chat_id && String(row.chat_id) !== String(chat_id)) {
+        return { ok: false, reason: 'wrong-chat' };
+      }
+
+      const tx = rawDb.transaction(() => {
+        const upd = markCodeUsedStmt.run({ code: norm, user_id: claimer_user_id, ts: now() });
+        if (upd.changes === 0) throw new Error('race: code claimed by another user');
+        insertPairingStmt.run({
+          bot_name: row.bot_name,
+          user_id: claimer_user_id,
+          chat_id: row.chat_id || null,
+          granted_ts: now(),
+          granted_by_user_id: row.issued_by_user_id,
+          note: row.note,
+        });
+      });
+      try {
+        tx();
+      } catch (err) {
+        if (/race: code claimed/.test(err.message)) return { ok: false, reason: 'race' };
+        throw err;
+      }
+      return {
+        ok: true,
+        bot_name: row.bot_name,
+        chat_id: row.chat_id,
+        scope: row.scope,
+        note: row.note,
+      };
+    },
+
+    hasLivePairing({ bot_name, user_id, chat_id }) {
+      if (chat_id == null) {
+        return !!livePairingAnyChatStmt.get(bot_name, user_id);
+      }
+      return !!livePairingChatStmt.get(bot_name, user_id, String(chat_id));
+    },
+
+    revokeByUser({ bot_name, user_id }) {
+      return revokeByUserStmt.run(now(), bot_name, user_id).changes;
+    },
+
+    listActive(bot_name) {
+      return listActiveStmt.all(bot_name);
+    },
+  };
+}
+
+module.exports = {
+  createStore,
+  generateCode,
+  normalizeCode,
+  parseTtl,
+  DEFAULT_TTL_MS,
+  MAX_TTL_MS,
+  MIN_TTL_MS,
+  ISSUE_RATE_PER_OPERATOR_PER_HOUR,
+  CLAIM_RATE_PER_USER_PER_HOUR,
+};

package/lib/process-manager.js

@@ -0,0 +1,287 @@
+/**
+ * LRU-bounded warm process pool.
+ *
+ * - No idle timeout: processes die only via eviction or graceful kill.
+ * - Never evict an in-flight process.
+ * - Graceful SIGTERM, then SIGKILL after 3 s fallback.
+ * - If `--resume <id>` fails on spawn, clear the session_id so the next
+ *   message spawns fresh.
+ *
+ * All I/O (spawn, db) is injected for testability.
+ */
+
+const { createInterface } = require('readline');
+
+const DEFAULT_CAP = 10;
+const DEFAULT_KILL_TIMEOUT_MS = 3000;
+
+/**
+ * Pull text from a stream-json `assistant` event.
+ * Claude Code emits one event per assistant step; each carries a
+ * `message.content[]` of blocks. Text blocks have `{type:'text', text:'…'}`;
+ * tool_use blocks we summarise inline so the user sees what Claude is doing.
+ */
+function extractAssistantText(event) {
+  const blocks = event?.message?.content;
+  if (!Array.isArray(blocks)) return '';
+  const parts = [];
+  for (const b of blocks) {
+    if (!b) continue;
+    if (b.type === 'text' && typeof b.text === 'string') {
+      parts.push(b.text);
+    } else if (b.type === 'tool_use' && b.name) {
+      parts.push(`_Calling \`${b.name}\`…_`);
+    }
+  }
+  return parts.join('\n\n').trim();
+}
+
+class ProcessManager {
+  constructor({
+    cap = DEFAULT_CAP,
+    spawnFn,
+    db = null,
+    logger = console,
+    killTimeoutMs = DEFAULT_KILL_TIMEOUT_MS,
+    onInit = null,       // (sessionKey, event) → void (system init)
+    onResult = null,     // (sessionKey, event) → void (turn result)
+    onClose = null,      // (sessionKey, code) → void
+    onStreamChunk = null,// (sessionKey, partialText, entry) → void (per assistant event)
+  } = {}) {
+    if (!spawnFn) throw new Error('spawnFn required');
+    this.cap = cap;
+    this.spawnFn = spawnFn;
+    this.db = db;
+    this.logger = logger;
+    this.killTimeoutMs = killTimeoutMs;
+    this.onInit = onInit;
+    this.onResult = onResult;
+    this.onClose = onClose;
+    this.onStreamChunk = onStreamChunk;
+    this.procs = new Map();
+  }
+
+  has(sessionKey) {
+    return this.procs.has(sessionKey);
+  }
+
+  get(sessionKey) {
+    return this.procs.get(sessionKey);
+  }
+
+  size() {
+    return this.procs.size;
+  }
+
+  keys() {
+    return Array.from(this.procs.keys());
+  }
+
+  /**
+   * Return existing entry or spawn a new one. Evicts LRU if at capacity.
+   * Throws if at capacity and all entries are in-flight.
+   */
+  async getOrSpawn(sessionKey, spawnContext) {
+    const existing = this.procs.get(sessionKey);
+    if (existing && !existing.closed) {
+      existing.lastUsedTs = Date.now();
+      return existing;
+    }
+    if (this.procs.size >= this.cap) {
+      const evicted = await this.evictLRU();
+      if (!evicted) throw new Error('LRU full: all processes in-flight');
+    }
+    return this._spawn(sessionKey, spawnContext);
+  }
+
+  async evictLRU() {
+    let victim = null;
+    for (const [k, v] of this.procs) {
+      if (v.inFlight) continue;
+      if (!victim || v.lastUsedTs < victim.entry.lastUsedTs) {
+        victim = { key: k, entry: v };
+      }
+    }
+    if (!victim) {
+      this._logEvent('lru-full', { cap: this.cap });
+      return false;
+    }
+    this._logEvent('evict', { session_key: victim.key, chat_id: victim.entry.chatId });
+    await this.kill(victim.key);
+    return true;
+  }
+
+  async kill(sessionKey) {
+    const entry = this.procs.get(sessionKey);
+    if (!entry) return;
+    this.procs.delete(sessionKey);
+    try { entry.proc.kill('SIGTERM'); } catch {}
+    await new Promise((resolve) => {
+      if (entry.closed) return resolve();
+      const timer = setTimeout(() => {
+        try { entry.proc.kill('SIGKILL'); } catch {}
+        resolve();
+      }, this.killTimeoutMs);
+      entry.proc.once('close', () => { clearTimeout(timer); resolve(); });
+    });
+    if (entry.pending) {
+      const { reject } = entry.pending;
+      entry.pending = null;
+      reject(new Error('Process killed'));
+    }
+  }
+
+  async killChat(chatId) {
+    const prefix = String(chatId);
+    const targets = [];
+    for (const key of this.procs.keys()) {
+      if (key === prefix || key.startsWith(prefix + ':')) targets.push(key);
+    }
+    for (const key of targets) await this.kill(key);
+  }
+
+  async shutdown() {
+    const keys = Array.from(this.procs.keys());
+    for (const key of keys) await this.kill(key);
+  }
+
+  _spawn(sessionKey, ctx = {}) {
+    const proc = this.spawnFn(sessionKey, ctx);
+    const rl = createInterface({ input: proc.stdout });
+    const entry = {
+      sessionKey,
+      proc,
+      rl,
+      pending: null,
+      lastUsedTs: Date.now(),
+      inFlight: false,
+      closed: false,
+      sessionId: ctx.existingSessionId || null,
+      chatId: ctx.chatId || null,
+      threadId: ctx.threadId || null,
+      label: ctx.label || sessionKey,
+      // Stream accumulator — cleared at each turn start (on send()).
+      streamText: '',
+    };
+
+    rl.on('line', (line) => {
+      let event;
+      try { event = JSON.parse(line); }
+      catch { this.logger.error(`[${entry.label}] non-JSON: ${line.slice(0, 200)}`); return; }
+
+      if (event.type === 'system' && event.subtype === 'init') {
+        entry.sessionId = event.session_id;
+        if (this.onInit) this.onInit(sessionKey, event, entry);
+      }
+      if (event.type === 'assistant' && this.onStreamChunk && entry.pending) {
+        const added = extractAssistantText(event);
+        if (added) {
+          entry.streamText = entry.streamText
+            ? `${entry.streamText}\n\n${added}`
+            : added;
+          try { this.onStreamChunk(sessionKey, entry.streamText, entry); }
+          catch (err) { this.logger.error(`[${entry.label}] onStreamChunk: ${err.message}`); }
+        }
+      }
+      if (event.type === 'result' && entry.pending) {
+        const { resolve } = entry.pending;
+        entry.pending = null;
+        entry.inFlight = false;
+        if (this.onResult) this.onResult(sessionKey, event, entry);
+        resolve({
+          text: event.result || '',
+          sessionId: event.session_id,
+          cost: event.total_cost_usd,
+          duration: event.duration_ms,
+          error: event.subtype === 'success' ? null : (event.error || event.subtype),
+        });
+      }
+    });
+
+    proc.on('close', (code) => {
+      entry.closed = true;
+      if (entry.pending) {
+        const { reject } = entry.pending;
+        entry.pending = null;
+        entry.inFlight = false;
+        reject(new Error(`Process exited (code ${code})`));
+      }
+      this.procs.delete(sessionKey);
+      if (code !== 0 && ctx.existingSessionId && this.db?.clearSessionId) {
+        this._logEvent('resume-fail', { session_key: sessionKey, session_id: ctx.existingSessionId, code });
+        try { this.db.clearSessionId(sessionKey); } catch (err) {
+          this.logger.error(`[${entry.label}] clearSessionId failed: ${err.message}`);
+        }
+      }
+      if (this.onClose) this.onClose(sessionKey, code, entry);
+    });
+
+    proc.on('error', (err) => {
+      this.logger.error(`[${entry.label}] proc error: ${err.message}`);
+      entry.closed = true;
+      if (entry.pending) {
+        const { reject } = entry.pending;
+        entry.pending = null;
+        entry.inFlight = false;
+        reject(err);
+      }
+      this.procs.delete(sessionKey);
+    });
+
+    this.procs.set(sessionKey, entry);
+    return entry;
+  }
+
+  send(sessionKey, prompt, { timeoutMs = 600_000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const entry = this.procs.get(sessionKey);
+      if (!entry || entry.closed) return reject(new Error('No process for session'));
+      if (entry.pending) return reject(new Error('Process busy'));
+      // Race: proc may have emitted 'close' between getOrSpawn and send, in
+      // which case entry.closed is true but handlers could still be draining.
+      // Also guard against a destroyed/ended stdin pipe explicitly — writing
+      // to a closed pipe would either throw EPIPE or silently buffer.
+      if (!entry.proc.stdin || entry.proc.stdin.destroyed || !entry.proc.stdin.writable) {
+        return reject(new Error('Process stdin not writable'));
+      }
+
+      entry.inFlight = true;
+      entry.lastUsedTs = Date.now();
+      entry.pending = { resolve, reject };
+      entry.streamText = '';
+
+      const timer = setTimeout(() => {
+        if (entry.pending) {
+          entry.pending = null;
+          entry.inFlight = false;
+          reject(new Error(`Timeout after ${timeoutMs / 1000}s`));
+        }
+      }, timeoutMs);
+
+      const wrappedResolve = entry.pending.resolve;
+      const wrappedReject = entry.pending.reject;
+      entry.pending.resolve = (r) => { clearTimeout(timer); wrappedResolve(r); };
+      entry.pending.reject = (e) => { clearTimeout(timer); wrappedReject(e); };
+
+      try {
+        entry.proc.stdin.write(JSON.stringify({
+          type: 'user',
+          message: { role: 'user', content: prompt },
+        }) + '\n');
+      } catch (err) {
+        entry.pending = null;
+        entry.inFlight = false;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  }
+
+  _logEvent(kind, detail) {
+    if (!this.db?.logEvent) return;
+    try { this.db.logEvent(kind, detail); }
+    catch (err) { this.logger.error(`[pm] logEvent ${kind} failed: ${err.message}`); }
+  }
+}
+
+module.exports = { ProcessManager, DEFAULT_CAP, extractAssistantText };