polygram 0.8.0 → 0.9.0-rc.2

package/scripts/doctor.js

@@ -28,7 +28,7 @@ const Database = require('better-sqlite3');
 
 const {
   call, tell, socketPathFor, readSecret,
-} = require('../lib/ipc-client');
+} = require('../lib/ipc/client');
 
 // ─── Arg parsing ─────────────────────────────────────────────────────
 

package/scripts/ipc-smoke.js

@@ -4,7 +4,7 @@
  * Usage: node scripts/ipc-smoke.js <bot-name>
  */
 
-const { call, socketPathFor } = require('../lib/ipc-client');
+const { call, socketPathFor } = require('../lib/ipc/client');
 
 (async () => {
   const bot = process.argv[2] || 'shumabit';
@@ -12,15 +12,6 @@ const { call, socketPathFor } = require('../lib/ipc-client');
 
   console.log('path:', path);
   console.log('ping:', JSON.stringify(await call({ path, op: 'ping' })));
-
-  console.log('ungated:', JSON.stringify(await call({
-    path, op: 'approval_request',
-    payload: {
-      bot_name: bot, chat_id: '111111111',
-      tool_name: 'Read', tool_input: { path: '/etc/hosts' },
-    },
-  })));
-
   console.log('DONE');
 })().catch((err) => {
   console.error('ERR:', err.message);

package/bin/approval-hook.js

@@ -1,113 +0,0 @@
-#!/usr/bin/env node
-/**
- * Claude Code PreToolUse hook -> polygram daemon approval round-trip.
- *
- * Installed into an agent's settings.json:
- *   { "hooks": { "PreToolUse": [
- *     { "matcher": "Bash|WebFetch|mcp__*", "hooks": [
- *       { "type": "command",
- *         "command": "/Users/YOURNAME/polygram/bin/approval-hook.js" }
- *     ]}
- *   ]}}
- *
- * Environment (set by polygram when spawning Claude):
- *   POLYGRAM_BOT       - bot name owning this session (socket suffix)
- *   POLYGRAM_CHAT_ID   - chat whose message triggered this turn (for the card)
- *   POLYGRAM_TURN_ID   - optional; helps dedupe re-fires on Claude retries
- *
- * Contract (Claude Code):
- *   stdin  JSON: { session_id, hook_event_name: "PreToolUse",
- *                  tool_name, tool_input, ... }
- *   stdout JSON reply for PreToolUse: either pass-through (exit 0 empty stdout),
- *          or a block decision:
- *     {"hookSpecificOutput": {"hookEventName":"PreToolUse",
- *                             "permissionDecision":"allow"|"deny"|"ask",
- *                             "permissionDecisionReason":"..."}}
- *   Exit codes:
- *     0 - allow (empty stdout) or structured decision in stdout
- *     2 - block (deny)
- *
- * Failure policy: on IPC error (polygram down, socket missing, timeout) we
- * deny by default. Better to block a legitimate tool call than to let a
- * destructive one through when the approver is unreachable.
- */
-
-const fs = require('fs');
-
-(async () => {
-  const botName = process.env.POLYGRAM_BOT;
-  const chatId  = process.env.POLYGRAM_CHAT_ID;
-  const turnId  = process.env.POLYGRAM_TURN_ID || null;
-
-  if (!botName || !chatId) {
-    deny('polygram-approval-hook: POLYGRAM_BOT and POLYGRAM_CHAT_ID env vars required');
-    return;
-  }
-
-  let req;
-  try {
-    req = JSON.parse(fs.readFileSync(0, 'utf8'));
-  } catch (err) {
-    deny(`bad hook input: ${err.message}`);
-    return;
-  }
-  if (req.hook_event_name !== 'PreToolUse') {
-    // Not our event; pass through silently.
-    process.exit(0);
-  }
-
-  // Resolve relative to this hook's own location rather than a hardcoded
-  // absolute path — an absolute-path require is a symlink-swap RCE vector
-  // (anyone who can write to that path gets code execution in-polygram).
-  const path = require('path');
-  const { call, socketPathFor, readSecret } = require(path.join(__dirname, '..', 'lib', 'ipc-client'));
-  let res;
-  try {
-    res = await call({
-      path: socketPathFor(botName),
-      op: 'approval_request',
-      secret: readSecret(botName),
-      payload: {
-        bot_name: botName,
-        chat_id: chatId,
-        turn_id: turnId,
-        tool_name: req.tool_name,
-        tool_input: req.tool_input,
-      },
-    });
-  } catch (err) {
-    deny(`polygram unreachable: ${err.message}`);
-    return;
-  }
-
-  if (!res || !res.ok) {
-    deny(`polygram error: ${res?.error || 'unknown'}`);
-    return;
-  }
-
-  // Bridge signals one of: 'not-gated' | 'approved' | 'denied' | 'timeout' | 'auto-approved'
-  if (res.decision === 'not-gated' || res.decision === 'approved' || res.decision === 'auto-approved') {
-    // Pass through — let the default permission flow decide. An empty
-    // stdout + exit 0 means "no opinion" from this hook.
-    process.exit(0);
-  }
-
-  const reason = res.reason || `approval ${res.decision}`;
-  deny(reason, res.decision);
-})().catch((err) => {
-  deny(`hook crashed: ${err.message}`);
-});
-
-function deny(reason, decision = 'denied') {
-  const out = {
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: `[${decision}] ${reason}`,
-    },
-  };
-  try {
-    process.stdout.write(JSON.stringify(out));
-  } catch {}
-  process.exit(2);
-}

package/lib/approval-waiters.js

@@ -1,201 +0,0 @@
-/**
- * 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,
-      });
-
-      // 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();
-    });
-  }
-
-  /**
-   * 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/pm-router.js

@@ -1,201 +0,0 @@
-/**
- * Per-chat ProcessManager router (rc.6+).
- *
- * Daemon hosts up to TWO pm instances simultaneously — the
- * stream-json-CLI ProcessManager and the @anthropic-ai/claude-agent-sdk
- * ProcessManagerSdk. Each chat is assigned to one of them based on
- * env config:
- *
- *   POLYGRAM_USE_SDK=1                 → all chats SDK pm
- *   POLYGRAM_SDK_CHATS=id1,id2,...     → those chats SDK; others CLI
- *   neither set                        → all chats CLI
- *
- * The router exposes the same surface a single pm did, plus two
- * introspection methods:
- *
- *   pm.pickFor(sessionKey)   → underlying pm instance (for feature
- *                              detection at call sites)
- *   pm.isSdkFor(sessionKey)  → boolean shortcut
- *
- * Lifecycle methods (`killChat`, `shutdown`) broadcast to BOTH pms
- * when both are alive — a chat could have a session on either side
- * (e.g. mid-config-change), so we don't risk leaking one.
- *
- * Optional methods (steer / setModel / applyFlagSettings /
- * requestRespawn / drainQueue / interrupt / resetSession) forward
- * when the routed pm has the method and return a sentinel otherwise.
- * Sites that need to feature-detect should `pm.pickFor(sessionKey)`
- * and check `typeof X === 'function'` directly.
- *
- * Used by `polygram.js` main() — Phase 5 + rc.6.
- */
-
-'use strict';
-
-/**
- * Parse the SDK-chats env config into a router policy.
- *
- * @param {object} opts
- * @param {boolean} opts.useSdkAll  — POLYGRAM_USE_SDK=1
- * @param {Iterable<string>} [opts.sdkChats]  — POLYGRAM_SDK_CHATS list
- * @param {(sessionKey: string) => string|null} opts.getChatIdFromKey
- *
- * @returns {object} { sdkAllChats, sdkSomeChats, sdkActive,
- *                     sdkChatIdSet, pickPmKindFor }
- */
-function makeRouterPolicy({ useSdkAll = false, sdkChats = [], getChatIdFromKey } = {}) {
-  if (typeof getChatIdFromKey !== 'function') {
-    throw new TypeError('getChatIdFromKey function required');
-  }
-  const sdkChatIdSet = new Set(
-    [...sdkChats].map((s) => String(s).trim()).filter(Boolean),
-  );
-  const sdkAllChats = !!useSdkAll && sdkChatIdSet.size === 0;
-  const sdkSomeChats = sdkChatIdSet.size > 0;
-  const sdkActive = sdkAllChats || sdkSomeChats;
-
-  function pickPmKindFor(sessionKey) {
-    if (sdkAllChats) return 'sdk';
-    if (!sdkSomeChats) return 'cli';
-    const chatId = String(getChatIdFromKey(sessionKey) ?? '');
-    return sdkChatIdSet.has(chatId) ? 'sdk' : 'cli';
-  }
-
-  return { sdkAllChats, sdkSomeChats, sdkActive, sdkChatIdSet, pickPmKindFor };
-}
-
-/**
- * Build a routing pm proxy. cliPm is required; sdkPm is optional
- * (null when SDK isn't enabled for any chat).
- *
- * @param {object} opts
- * @param {object} opts.cliPm
- * @param {object|null} opts.sdkPm
- * @param {(sessionKey: string) => 'sdk'|'cli'} opts.pickPmKindFor
- */
-/**
- * Broadcast helper for killChat / shutdown. Awaits every task to
- * settlement (success OR rejection), then throws an aggregate error
- * if any task rejected. Single rejections re-throw the original
- * error untouched (no AggregateError noise); multiple rejections
- * surface as `AggregateError` with all causes preserved.
- *
- * Each task entry is `[label, () => Promise]`; the label appears in
- * AggregateError messages so a debugger can tell which pm failed.
- */
-async function broadcastSettle(method, tasks) {
-  const results = await Promise.allSettled(tasks.map(([, fn]) => fn()));
-  const errors = [];
-  results.forEach((r, i) => {
-    if (r.status === 'rejected') {
-      const tag = tasks[i][0];
-      const err = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
-      err.pmTag = tag;
-      errors.push(err);
-    }
-  });
-  if (errors.length === 1) throw errors[0];
-  if (errors.length > 1) {
-    throw new AggregateError(errors, `${method} failed in ${errors.length} pms`);
-  }
-}
-
-function createPmRouter({ cliPm, sdkPm = null, pickPmKindFor } = {}) {
-  if (!cliPm) throw new TypeError('cliPm required');
-  if (typeof pickPmKindFor !== 'function') {
-    throw new TypeError('pickPmKindFor function required');
-  }
-
-  function routedPm(sessionKey) {
-    return pickPmKindFor(sessionKey) === 'sdk' && sdkPm ? sdkPm : cliPm;
-  }
-
-  return {
-    pickFor: routedPm,
-    isSdkFor(sessionKey) {
-      return pickPmKindFor(sessionKey) === 'sdk' && !!sdkPm;
-    },
-
-    // Methods that exist on every pm instance — direct routing.
-    has(sessionKey) { return routedPm(sessionKey).has(sessionKey); },
-    get(sessionKey) { return routedPm(sessionKey).get(sessionKey); },
-    getOrSpawn(sessionKey, ctx) { return routedPm(sessionKey).getOrSpawn(sessionKey, ctx); },
-    send(sessionKey, prompt, opts) { return routedPm(sessionKey).send(sessionKey, prompt, opts); },
-    kill(sessionKey) { return routedPm(sessionKey).kill(sessionKey); },
-
-    // Lifecycle methods broadcast to both pms because a chat may
-    // have spawned sessions on either side at different times.
-    // Promise.allSettled (NOT Promise.all) so a rejection from one
-    // pm doesn't abandon the other mid-tear-down. Both must always
-    // complete; we then surface aggregated errors. Pre-fix, a cliPm
-    // rejection let sdkPm's Query.close() get GC'd with handles
-    // still open.
-    killChat(chatId) {
-      const tasks = [['cli', () => cliPm.killChat(chatId)]];
-      if (sdkPm) tasks.push(['sdk', () => sdkPm.killChat(chatId)]);
-      return broadcastSettle('killChat', tasks);
-    },
-    shutdown() {
-      const tasks = [['cli', () => cliPm.shutdown()]];
-      if (sdkPm) tasks.push(['sdk', () => sdkPm.shutdown()]);
-      return broadcastSettle('shutdown', tasks);
-    },
-
-    // Optional methods — forward when the routed pm implements
-    // them, return a documented sentinel otherwise. Use
-    // `pm.pickFor(sessionKey)` for proper feature detection at
-    // call sites that need to branch on capability.
-    steer(sessionKey, ...args) {
-      const target = routedPm(sessionKey);
-      return typeof target.steer === 'function' ? target.steer(sessionKey, ...args) : false;
-    },
-    // rc.42: native autosteer / queue. CLI pm doesn't have an
-    // input-controller push primitive (the binary's stream-json
-    // input is one-shot per pm.send), so it returns false. SDK pm
-    // forwards to its inject implementation.
-    injectUserMessage(sessionKey, opts) {
-      const target = routedPm(sessionKey);
-      return typeof target.injectUserMessage === 'function'
-        ? target.injectUserMessage(sessionKey, opts)
-        : false;
-    },
-    resetSession(sessionKey, opts) {
-      const target = routedPm(sessionKey);
-      return typeof target.resetSession === 'function'
-        ? target.resetSession(sessionKey, opts)
-        : Promise.resolve({ closed: false, drainedPendings: 0 });
-    },
-    applyFlagSettings(sessionKey, settings) {
-      const target = routedPm(sessionKey);
-      return typeof target.applyFlagSettings === 'function'
-        ? target.applyFlagSettings(sessionKey, settings)
-        : Promise.resolve(false);
-    },
-    setModel(sessionKey, model) {
-      const target = routedPm(sessionKey);
-      return typeof target.setModel === 'function'
-        ? target.setModel(sessionKey, model)
-        : Promise.resolve(false);
-    },
-    requestRespawn(sessionKey, reason) {
-      const target = routedPm(sessionKey);
-      return typeof target.requestRespawn === 'function'
-        ? target.requestRespawn(sessionKey, reason)
-        : { killed: false, queued: 0 };
-    },
-    drainQueue(sessionKey, errCode) {
-      const target = routedPm(sessionKey);
-      return typeof target.drainQueue === 'function'
-        ? target.drainQueue(sessionKey, errCode)
-        : 0;
-    },
-    interrupt(sessionKey) {
-      const target = routedPm(sessionKey);
-      return typeof target.interrupt === 'function'
-        ? target.interrupt(sessionKey)
-        : Promise.resolve();
-    },
-  };
-}
-
-module.exports = { makeRouterPolicy, createPmRouter };