polygram 0.8.0-rc.16 → 0.8.0-rc.17

package/.claude-plugin/plugin.json

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

@@ -77,4 +77,55 @@ function createAutosteerBuffer() {
   return { append, drain, size, clear, formatForHook };
 }
 
-module.exports = { createAutosteerBuffer };
+/**
+ * Build the PostToolBatch hook callback that drains the buffer for
+ * a specific sessionKey on each tool boundary. The callback shape
+ * matches `@anthropic-ai/claude-agent-sdk`'s HookCallback contract
+ * (sdk.d.ts:726-728): returns a HookJSONOutput; never throws.
+ *
+ * @param {object} opts
+ * @param {object} opts.buffer        — the per-session buffer instance
+ * @param {string} opts.sessionKey    — closure-bound at Query spawn time
+ * @param {(kind: string, detail: object) => void} [opts.logEvent]
+ *   — optional events.table emitter; called when a drain produces
+ *     non-empty output, with kind='autosteer-hook-drained'.
+ * @param {string|null} [opts.chatId] — for the logEvent payload only.
+ * @param {object} [opts.logger]      — for error logging (must have .error).
+ *
+ * @returns {async () => Promise<HookJSONOutput>}
+ */
+function makePostToolBatchHook({ buffer, sessionKey, logEvent = null, chatId = null, logger = console } = {}) {
+  if (!buffer) throw new TypeError('buffer required');
+  if (!sessionKey) throw new TypeError('sessionKey required');
+  return async () => {
+    try {
+      const drained = buffer.drain(sessionKey);
+      if (drained.length === 0) return { continue: true };
+      const additionalContext = buffer.formatForHook(drained);
+      if (typeof logEvent === 'function') {
+        try {
+          logEvent('autosteer-hook-drained', {
+            chat_id: chatId,
+            session_key: sessionKey,
+            message_count: drained.length,
+          });
+        } catch { /* logger errors must not break the hook */ }
+      }
+      return {
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: 'PostToolBatch',
+          additionalContext,
+        },
+      };
+    } catch (err) {
+      logger?.error?.(`[${sessionKey}] PostToolBatch hook error: ${err?.message || err}`);
+      // Never throw out of a hook — the SDK may treat it as a hard
+      // fail (`stop_hook_prevented` result subtype). Drop the
+      // queued messages on the floor; the user can re-send.
+      return { continue: true };
+    }
+  };
+}
+
+module.exports = { createAutosteerBuffer, makePostToolBatchHook };

package/lib/pm-router.js

@@ -0,0 +1,159 @@
+/**
+ * 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
+ */
+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.
+    async killChat(chatId) {
+      const tasks = [cliPm.killChat(chatId)];
+      if (sdkPm) tasks.push(sdkPm.killChat(chatId));
+      await Promise.all(tasks);
+    },
+    async shutdown() {
+      const tasks = [cliPm.shutdown()];
+      if (sdkPm) tasks.push(sdkPm.shutdown());
+      await Promise.all(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;
+    },
+    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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.8.0-rc.16",
+  "version": "0.8.0-rc.17",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc-client.js",
   "bin": {

package/polygram.js

@@ -31,7 +31,8 @@ const { ProcessManager } = require('./lib/process-manager');
 // pick-at-startup. Phase 4 deletes the CLI version after Phase 5
 // soak proves SDK stable. See docs/0.8.0-architecture-decisions.md.
 const { ProcessManagerSdk } = require('./lib/process-manager-sdk');
-const { createAutosteerBuffer } = require('./lib/autosteer-buffer');
+const { createAutosteerBuffer, makePostToolBatchHook } = require('./lib/autosteer-buffer');
+const { makeRouterPolicy, createPmRouter } = require('./lib/pm-router');
 const agentLoader = require('./lib/agent-loader');
 const USE_SDK = process.env.POLYGRAM_USE_SDK === '1';
 const { createSender } = require('./lib/telegram');
@@ -907,39 +908,19 @@ function buildSdkOptions(sessionKey, ctx) {
   const useCanUseTool = apprCfg && apprCfg.adminChatId
     && Array.isArray(apprCfg.gatedTools) && apprCfg.gatedTools.length > 0;
 
-  // 0.8.0-rc.9: PostToolBatch hook drains the autosteer buffer for
-  // this session and injects queued user follow-ups as
-  // `additionalContext` on each tool boundary. Framing matters:
-  // wrapping in `<channel source="user-followup">…</channel>` is
-  // what Claude is trained to trust as legitimate out-of-band user
-  // context (verified live via post-tool-batch-spike-v2.mjs); the
-  // earlier `<user_message_during_turn>` framing tripped the
-  // model's prompt-injection defense and got refused.
-  const postToolBatchHook = async () => {
-    try {
-      const drained = autosteerBuffer.drain(sessionKey);
-      if (drained.length === 0) return { continue: true };
-      const additionalContext = autosteerBuffer.formatForHook(drained);
-      logEvent('autosteer-hook-drained', {
-        chat_id: ctx?.chatId ?? null,
-        session_key: sessionKey,
-        message_count: drained.length,
-      });
-      return {
-        continue: true,
-        hookSpecificOutput: {
-          hookEventName: 'PostToolBatch',
-          additionalContext,
-        },
-      };
-    } catch (err) {
-      console.error(`[${sessionKey}] PostToolBatch hook error: ${err.message}`);
-      // Never throw out of a hook — the SDK may treat it as a hard
-      // fail (`stop_hook_prevented` result subtype). Drop the
-      // queued messages on the floor; the user can re-send.
-      return { continue: true };
-    }
-  };
+  // 0.8.0-rc.9 (factored to lib/autosteer-buffer.js in rc.17): the
+  // PostToolBatch hook drains the autosteer buffer for THIS session
+  // and injects queued user follow-ups as `additionalContext` on
+  // each tool boundary, wrapped in `<channel source="user-followup">`
+  // which Claude is trained to trust as legitimate out-of-band user
+  // context.
+  const postToolBatchHook = makePostToolBatchHook({
+    buffer: autosteerBuffer,
+    sessionKey,
+    chatId: ctx?.chatId ?? null,
+    logEvent,
+    logger: console,
+  });
 
   const baseOpts = {
     model: chatConfig.model || config.defaults.model,
@@ -3559,20 +3540,15 @@ async function main() {
   // battle-tested CLI path. When both pms run, killChat /shutdown
   // broadcast to both; everything else routes per-sessionKey via
   // pickPmFor() based on the chat's set membership.
-  const sdkChatIdSet = new Set(
-    String(process.env.POLYGRAM_SDK_CHATS || '')
-      .split(',').map((s) => s.trim()).filter(Boolean)
-  );
-  const sdkAllChats = USE_SDK && 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';
-  }
+  // rc.17: router policy + proxy live in lib/pm-router.js for
+  // testability. Policy parses env config and produces
+  // pickPmKindFor; createPmRouter wraps the cli/sdk pms with the
+  // routed surface.
+  const { sdkActive, sdkAllChats, sdkSomeChats, sdkChatIdSet, pickPmKindFor } = makeRouterPolicy({
+    useSdkAll: USE_SDK,
+    sdkChats: String(process.env.POLYGRAM_SDK_CHATS || '').split(','),
+    getChatIdFromKey,
+  });
 
   // Shared callbacks: identical instance passed to both pms so a
   // chat's lifecycle events look the same regardless of which pm
@@ -3715,85 +3691,9 @@ async function main() {
     : null;
 
   // Routing pm: same surface as a single pm, but per-method routing
-  // through pickPmKindFor(sessionKey). Methods that don't take a
-  // sessionKey (killChat by chatId, shutdown) broadcast to both.
-  // For optional methods (steer / setModel / applyFlagSettings /
-  // requestRespawn / drainQueue / interrupt / resetSession) we
-  // forward when the routed pm has the method and return a
-  // sentinel otherwise — so feature-detection at the call site
-  // still works via `typeof pm.pickFor(sessionKey).X === 'function'`.
-  pm = (() => {
-    function routedPm(sessionKey) {
-      return pickPmKindFor(sessionKey) === 'sdk' && sdkPm ? sdkPm : cliPm;
-    }
-    const router = {
-      pickFor: routedPm,
-      isSdkFor(sessionKey) {
-        return pickPmKindFor(sessionKey) === 'sdk' && !!sdkPm;
-      },
-      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); },
-      async killChat(chatId) {
-        const tasks = [cliPm.killChat(chatId)];
-        if (sdkPm) tasks.push(sdkPm.killChat(chatId));
-        await Promise.all(tasks);
-      },
-      async shutdown() {
-        const tasks = [cliPm.shutdown()];
-        if (sdkPm) tasks.push(sdkPm.shutdown());
-        await Promise.all(tasks);
-      },
-      // Optional methods. The router returns a function — but the
-      // function returns a sentinel if the routed pm doesn't have
-      // the method. Sites that want feature-detection should use
-      // `pm.pickFor(sessionKey)` and check `typeof X === 'function'`
-      // there instead of probing `pm.X` directly.
-      steer(sessionKey, ...args) {
-        const target = routedPm(sessionKey);
-        return typeof target.steer === 'function' ? target.steer(sessionKey, ...args) : 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();
-      },
-    };
-    return router;
-  })();
+  // through pickPmKindFor(sessionKey). Per-method semantics
+  // documented in lib/pm-router.js.
+  pm = createPmRouter({ cliPm, sdkPm, pickPmKindFor });
 
   if (sdkAllChats) {
     console.log('[polygram] using SDK ProcessManager (all chats)');