polygram 0.8.0-rc.41 → 0.8.0-rc.43

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.41",
+  "version": "0.8.0-rc.43",
   "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/pm-interface.js

@@ -67,7 +67,11 @@
  *
  *   Optional (only one of the two pms implements these — feature-detect):
  * @property {((sessionKey: string, text: string, opts?: object) => boolean)=} steer
- *   — SDK pm only (rc.9 PostToolBatch hook drains buffer).
+ *   — SDK pm only (rc.9 priority='now' direct push, opt-in shouldQuery).
+ * @property {((sessionKey: string, opts: {content: string, priority?: 'now'|'next'|'later', shouldQuery?: boolean, parent_tool_use_id?: string|null}) => boolean)=} injectUserMessage
+ *   — SDK pm only (rc.42 native autosteer / queue via SDKUserMessage
+ *     priority hint). Returns false on CLI pm (no inputController
+ *     surface) or when sessionKey not found.
  * @property {((sessionKey: string, model: string) => Promise<boolean>)=} setModel
  *   — SDK pm only (Query.setModel live).
  * @property {((sessionKey: string, settings: {effortLevel?: string}) => Promise<boolean>)=} applyFlagSettings

package/lib/pm-router.js

@@ -149,6 +149,16 @@ function createPmRouter({ cliPm, sdkPm = null, pickPmKindFor } = {}) {
       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'

package/lib/process-manager-sdk.js

@@ -840,6 +840,61 @@ class ProcessManagerSdk {
     }
   }
 
+  /**
+   * 0.8.0-rc.42 — native autosteer / queue. Push a user message
+   * directly onto the SDK's input controller. The SDK manages
+   * absorption / queueing per the `priority` hint:
+   *   - 'now':   abort current turn (terminal_reason='aborted_streaming')
+   *              and start a fresh turn for this message (verified U7
+   *              spike 2026-05-01).
+   *   - 'next':  absorb into current turn at next natural pause
+   *              (between tool calls / after subagent return / etc.)
+   *              — same UX as the deleted autosteer-buffer + PostToolBatch
+   *              flow, but the SDK manages the queue. ONE result event
+   *              for the whole chain.
+   *   - 'later': queue for after current turn ends. SEPARATE result
+   *              event per absorbed message. Clean per-msg lifecycle.
+   *   - undefined: same as 'next'.
+   *
+   * Returns true on push success, false if no entry / closed.
+   *
+   * NOTE: this does NOT push a polygram pending into pendingQueue.
+   * The message bypasses pm's per-pending bookkeeping (cost-row,
+   * idle-timer, wall-clock cap) — those still attach to the
+   * trigger pending of the in-flight turn. For 'later' priority,
+   * the SDK will fire its own SDKResultMessage for the followup;
+   * polygram's onResult only sees one of these per active pending.
+   * Callers wanting per-msg accounting must use pm.send() instead.
+   */
+  injectUserMessage(sessionKey, { content, priority = 'next', shouldQuery, parent_tool_use_id = null } = {}) {
+    const entry = this.procs.get(sessionKey);
+    if (!entry || entry.closed) return false;
+    if (typeof content !== 'string' || !content) {
+      throw new TypeError('injectUserMessage: content (string) required');
+    }
+    try {
+      const msg = {
+        type: 'user',
+        message: { role: 'user', content },
+        parent_tool_use_id,
+      };
+      if (priority !== undefined) msg.priority = priority;
+      if (shouldQuery !== undefined) msg.shouldQuery = shouldQuery;
+      entry.inputController.push(msg);
+      this._logEvent('inject-user-message', {
+        session_key: sessionKey,
+        chat_id: entry.chatId,
+        priority: priority ?? null,
+        should_query: shouldQuery ?? null,
+        text_len: content.length,
+      });
+      return true;
+    } catch (err) {
+      this.logger.error?.(`[${entry.label}] injectUserMessage: ${err.message}`);
+      return false;
+    }
+  }
+
   /**
    * Forcibly reset a session: drain pendings, close Query, clear
    * sessionId in DB. Per v4 plan §6.5.2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.8.0-rc.41",
+  "version": "0.8.0-rc.43",
   "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, makePostToolBatchHook } = require('./lib/autosteer-buffer');
+// rc.42: autosteer-buffer module deleted. Native SDK priority push
+// (pm.injectUserMessage) replaces the buffer + PostToolBatch detour.
 const { createAutosteeredRefs } = require('./lib/autosteered-refs');
 const { makeRouterPolicy, createPmRouter } = require('./lib/pm-router');
 const { canonicalizeToolInput } = require('./lib/canonical-json');
@@ -712,21 +713,24 @@ function formatPrompt(msg, sessionCtx, attachments = []) {
 
 let pm = null; // ProcessManager, created in main()
 
-// 0.8.0-rc.9: per-session autosteer buffer. Holds user follow-ups
-// that arrive mid-turn so the SDK pm's PostToolBatch hook can drain
-// them into `additionalContext` on each tool boundary. Replaces the
-// rc.6/rc.7 approach of pushing priority:'now' SDKUserMessages
-// directly (which violated the SDK's m87 transcript-shape gate when
-// the assistant was mid-tool-use).
-const autosteerBuffer = createAutosteerBuffer();
-
-// 0.8.0-rc.14: track msg_ids that received the AUTOSTEERED ✍ ack, per
-// session, so we can clear those reactions when the in-flight turn
-// finishes. Pre-rc.14 the ✍ persisted forever because each autosteer
-// invocation runs in its OWN handleMessage scope (own reactor), and
-// the TRIGGER message's reactor.clear() at turn-end couldn't reach
-// across to other messages. Without this map, users see ✍ stuck on
-// every follow-up and don't know whether the bot incorporated them.
+// 0.8.0-rc.42: autosteer buffer + stale-drain DELETED. Replaced by
+// pm.injectUserMessage() with native SDK priority hints. The U7 spike
+// (scripts/spikes/native-queue.mjs, 2026-05-01) verified all three
+// SDK priorities ('now' / 'next' / 'later') work cleanly without
+// m87 rejection. The buffer/hook detour was a workaround for a
+// problem the SDK no longer has.
+//
+// What used to live here: createAutosteerBuffer + makePostToolBatchHook
+// + drainStaleAutosteerBuffer. The buffer kept user follow-ups that
+// arrived mid-turn; the PostToolBatch hook drained them into
+// `additionalContext` (with the <channel source="user-followup"> Channels-
+// MCP framing) on each tool boundary; the stale-drain handled the
+// edge case where a turn ended with zero tool calls (no hook fire,
+// followups would otherwise be lost). All three are obsolete with
+// native priority push.
+//
+// Kept: autosteeredRefs — still tracks msg_ids that received the ✍
+// AUTOSTEERED ack so the trigger turn's success path can clear them.
 const autosteeredRefs = createAutosteeredRefs({
   applyClear: async ({ chatId, msgId }) => {
     if (!bot) return;
@@ -741,57 +745,6 @@ async function clearAutosteeredReactions(sessionKey) {
   return autosteeredRefs.clear(sessionKey);
 }
 
-// 0.8.0-rc.14: tool-less-turn drain. PostToolBatch hook only fires
-// on tool boundaries — when a Query produces a turn that uses ZERO
-// tools (just a text answer), the autosteerBuffer never gets
-// drained and any user follow-ups buffered during that turn
-// disappear silently into the next tool-using turn (or never, if
-// the chat is purely conversational).
-//
-// Workaround: at every success exit in handleMessage, check if
-// the buffer still has items and dispatch them as a synthetic
-// next turn via pm.send. The bot replies to the drained content
-// in a fresh turn — UX-wise the user sees TWO replies (one to
-// the trigger message, one to "B + C") which is the same as if
-// they'd sent the messages without autosteer. Better than losing.
-async function drainStaleAutosteerBuffer(sessionKey, chatId, threadId) {
-  const stale = autosteerBuffer.drain(sessionKey);
-  if (stale.length === 0) return;
-  const followUpPrompt = stale.join('\n\n');
-  logEvent('autosteer-stale-drain', {
-    chat_id: chatId,
-    session_key: sessionKey,
-    message_count: stale.length,
-    text_len: followUpPrompt.length,
-  });
-  // Dispatch as a fresh pm.send via setImmediate so we don't
-  // block the current handleMessage's success-path return. No
-  // streamer / reactor — the synthetic turn gets a plain bubble
-  // reply (no streaming preview, no progress reactions). User
-  // already saw their ✍ ack on the original follow-up; this
-  // turn's existence is the substantive response.
-  setImmediate(async () => {
-    try {
-      const chatConfig = config.chats[chatId];
-      if (!chatConfig) return;
-      const result = await sendToProcess(sessionKey, followUpPrompt, {
-        streamer: null, reactor: null, sourceMsgId: null,
-      });
-      if (result?.text && bot) {
-        await tg(bot, 'sendMessage', {
-          chat_id: chatId,
-          text: result.text,
-          ...(threadId ? { message_thread_id: threadId } : {}),
-        }, { source: 'autosteer-stale-reply', botName: BOT_NAME }).catch((err) => {
-          console.error(`[${BOT_NAME}] autosteer-stale-reply send: ${err.message}`);
-        });
-      }
-    } catch (err) {
-      console.error(`[${BOT_NAME}] autosteer-stale-drain dispatch: ${err.message}`);
-    }
-  });
-}
-
 function spawnClaude(sessionKey, ctx) {
   const { chatConfig, existingSessionId, label, chatId } = ctx;
   // 0.7.3: Claude Code's Chrome-extension integration (browser
@@ -919,31 +872,11 @@ function buildSdkOptions(sessionKey, ctx) {
   const useCanUseTool = apprCfg && apprCfg.adminChatId
     && Array.isArray(apprCfg.gatedTools) && apprCfg.gatedTools.length > 0;
 
-  // 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,
-    // rc.37: clear ✍ reactions when the hook ABSORBS follow-ups, not
-    // at SDK turn-end. Under autosteer one SDK "turn" can stretch
-    // tens of minutes — every drain feeds more user text via
-    // additionalContext, the agent keeps reasoning, no `result` event
-    // fires, inFlight stays true, ✍ stays stuck on every drained
-    // follow-up. Clearing at drain time matches user perception
-    // ("the bot got my message → ✍ goes away").
-    onDrained: (key) => {
-      clearAutosteeredReactions(key).catch((err) => {
-        console.error(`[${BOT_NAME}] autosteer-hook clearReactions: ${err.message}`);
-      });
-    },
-  });
+  // rc.42: PostToolBatch hook removed. Native SDK priority push
+  // (pm.injectUserMessage) replaces the absorb-via-additionalContext
+  // detour. The autosteered ✍ reaction now clears via the regular
+  // turn-end path (handleMessage finally + success branches —
+  // existing rc.38 cleanup).
 
   // 0.8.0-rc.21: SessionStart hook preloads recent polygram-DB
   // history into a fresh Query (no resume). Without this, every
@@ -972,7 +905,6 @@ function buildSdkOptions(sessionKey, ctx) {
     allowDangerouslySkipPermissions: !useCanUseTool,
     ...(useCanUseTool && { canUseTool: makeCanUseTool(sessionKey) }),
     hooks: {
-      PostToolBatch: [{ hooks: [postToolBatchHook] }],
       ...(sessionStartHook && {
         SessionStart: [{ hooks: [sessionStartHook] }],
       }),
@@ -2513,52 +2445,57 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   const chatAutosteer = chatConfig.autosteer != null
     ? chatConfig.autosteer
     : config.bot?.autosteer;
-  // 0.8.0-rc.9: autosteer now drives through autosteerBuffer +
-  // PostToolBatch hook (in buildSdkOptions), not pm.steer's direct
-  // inputController push. The hook fires on every tool boundary
-  // and injects queued follow-ups as <channel source="user-followup">
-  // additionalContext — the SDK-trusted framing that survives the
-  // m87 transcript-shape gate.
+  // 0.8.0-rc.42: autosteer is now native — push the user message
+  // directly onto the SDK's input controller with a priority hint.
+  // The SDK manages absorption / queueing per the U7 spike findings
+  // (scripts/spikes/native-queue.mjs, 2026-05-01):
+  //
+  //   priority='next' (default): absorb into current turn at the next
+  //     natural pause (between tool calls / after subagent return).
+  //     ONE result event for the whole chain — same UX as the
+  //     deleted autosteer-buffer + PostToolBatch flow.
+  //   priority='later': queue for after current turn ends. SEPARATE
+  //     result event per absorbed message. Cleaner per-msg lifecycle
+  //     for chats that prefer accurate cost-row attribution.
   //
-  // We still gate on the SDK pm path: under CLI pm there's no
-  // PostToolBatch hook surface, so autosteer falls through to the
-  // regular FIFO send (same UX as 0.7.x).
+  // Per-chat opt-in via `chatConfig.autosteerMode: 'merge' | 'queue'`.
+  // 'merge' → priority='next' (default). 'queue' → priority='later'.
+  //
+  // Pre-rc.42 this used a custom autosteerBuffer + PostToolBatch hook
+  // returning <channel source="user-followup"> additionalContext. The
+  // SDK at the time rejected priority='now' mid-tool-use (m87 gate);
+  // 'next'/'later' were never tested. The U7 spike confirmed all
+  // three priorities now work cleanly — so the buffer/hook detour is
+  // gone. ~250 LOC + 2 test files deleted.
+  //
+  // CLI pm has no inputController push primitive, so it falls
+  // through to FIFO pm.send (same UX as 0.7.x — queued behind active).
   const autosteerEnabled = chatAutosteer !== false
     && pm.isSdkFor(sessionKey);
   if (autosteerEnabled && pm.has(sessionKey)) {
     const entry = pm.get(sessionKey);
     if (entry?.inFlight) {
-      const ok = autosteerBuffer.append(sessionKey, prompt);
+      const autosteerMode = chatConfig.autosteerMode != null
+        ? chatConfig.autosteerMode
+        : config.bot?.autosteerMode;
+      const priority = autosteerMode === 'queue' ? 'later' : 'next';
+      const ok = pm.injectUserMessage(sessionKey, {
+        content: prompt,
+        priority,
+      });
       if (ok) {
-        // Track this msg_id so the in-flight turn's success / abort
-        // / error path can clear the ✍ reaction at turn-end.
         autosteeredRefs.add(sessionKey, { chatId, msgId: msg.message_id });
         logEvent('autosteer', {
           chat_id: chatId, msg_id: msg.message_id,
           text_len: prompt?.length ?? 0,
+          priority,
         });
         stopTyping();
-        // 0.8.0-rc.11: route the ✍ ack through the reactor's
-        // serialized apply chain. Pre-rc.11 we used a direct
-        // setMessageReaction(✍) racing with the reactor's
-        // QUEUED→👀 apply AND a follow-up reactor.clear() — three
-        // concurrent network calls, final state was whichever
-        // landed last at Telegram. Symptom: 👀 sometimes stuck,
-        // ✍ sometimes vanished, reactions disappeared "almost
-        // immediately" or got stuck arbitrarily.
-        //
-        // setState('AUTOSTEERED') is terminal so it bypasses the
-        // 800ms throttle and flushes synchronously through
-        // applyChain — so it serializes after any in-flight
-        // QUEUED apply and lands as the final visible reaction.
+        // setState('AUTOSTEERED') is terminal — bypasses the throttle,
+        // serializes after any in-flight QUEUED apply via applyChain.
         await reactor.setState('AUTOSTEERED');
-        // rc.38: stop the reactor's STALL/TIMEOUT timers. Pre-rc.38
-        // the timers stayed armed, holding setTimeout handles for
-        // up to 30s and pinning the closure (and the bot/chatId
-        // captures) until they fired. AUTOSTEERED is terminal — no
-        // further state changes — so the timers serve no purpose
-        // and just delay GC. One-line patch; small steady-state
-        // heap relief in busy chats.
+        // rc.38: AUTOSTEERED is terminal; stop the reactor's STALL /
+        // TIMEOUT timers so they don't pin the closure for up to 30s.
         reactor.stop();
         markReplied();
         return;
@@ -2648,12 +2585,11 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // message that was autosteered into THIS turn — they live in
       // separate handleMessage scopes whose reactors are already GC'd.
       clearAutosteeredReactions(sessionKey).catch(() => {});
-      // rc.14: tool-less-turn drain. PostToolBatch hook fires only
-      // on tool boundaries; if this turn produced ZERO tools, the
-      // hook never fired and the autosteer buffer still has the
-      // user's follow-ups. Dispatch them as a synthetic next turn
-      // so the bot at least addresses them (better than losing).
-      drainStaleAutosteerBuffer(sessionKey, chatId, threadId).catch(() => {});
+      // rc.42: tool-less-turn stale-drain DELETED. With native priority
+      // push, the SDK's input controller has the followups directly —
+      // there's no buffer for us to drain. Tool-less turns just emit
+      // result, the followup messages (if any) get their own SDK
+      // pause to absorb at, no special handling needed.
 
       // 0.8.0 Phase 2 step 4: 85%-context-full live hint. After a
       // successful turn, peek at SDK's getContextUsage(); if past
@@ -2707,10 +2643,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       if (toolOnlyTurn) {
         await reactor.clear().catch(() => {});
         clearAutosteeredReactions(sessionKey).catch(() => {});
-        // Tool-only turns DID fire PostToolBatch — buffer was drained
-        // — but autosteers received AFTER the last tool-result still
-        // wouldn't be merged. Defensive drain here too.
-        drainStaleAutosteerBuffer(sessionKey, chatId, threadId).catch(() => {});
+        // rc.42: stale-drain removed. SDK manages absorption directly.
         logEvent('tool-only-completion', {
           chat_id: chatId, msg_id: msg.message_id, bot: BOT_NAME,
           num_tool_uses: result.metrics?.numToolUses,
@@ -3129,13 +3062,12 @@ function createBot(token) {
         await stopTarget.kill(sessionKey).catch((err) =>
           console.error(`[${BOT_NAME}] abort kill failed: ${err.message}`));
       }
-      // 0.8.0-rc.13: drop any buffered autosteer follow-ups for this
-      // session — otherwise they'd be injected into the NEXT turn
-      // (stale steer leak across abort boundary, which is what the
-      // user just asked us not to do).
-      autosteerBuffer.clear(sessionKey);
-      // rc.14: also clear ✍ reactions on already-autosteered
-      // messages from this aborted turn — they're now dead context.
+      // rc.42: autosteer buffer is gone (native SDK priority push).
+      // Followups already pushed onto the SDK's input controller will
+      // be drained by drainQueue() / kill() on the entry — no separate
+      // buffer to clear.
+      // Clear ✍ reactions on already-autosteered messages from this
+      // aborted turn — they're now dead context.
       clearAutosteeredReactions(sessionKey).catch(() => {});
       logEvent('abort-requested', {
         chat_id: chatId, user_id: msg.from?.id || null,

package/lib/autosteer-buffer.js

@@ -1,155 +0,0 @@
-/**
- * Per-session buffer for mid-turn user follow-ups (autosteer + /steer).
- *
- * 0.8.0-rc.9: lands the steer mechanism that survived production. Earlier
- * rcs pushed `priority:'now'` SDKUserMessages onto the SDK input
- * iterable mid-tool-use; the CLI binary's `m87` gate rejected them with
- * `result.subtype = error_during_execution` because the transcript shape
- * (assistant ending with tool_use → next user message NOT being a
- * tool_result) is malformed per Anthropic's API contract.
- *
- * The mechanism we landed on: append the follow-up to a per-session
- * buffer; on every PostToolBatch hook fire, drain the buffer into the
- * hook's `additionalContext` field wrapped in a `<channel
- * source="user-followup">…</channel>` tag — the same framing Channels
- * MCP uses, which Claude is trained to trust as legitimate
- * out-of-band user context (vs. prompt-injection inside tool output,
- * which the model defends against by refusing to follow).
- *
- * Spike result (post-tool-batch-spike-v2.mjs): with this framing, the
- * marker "spike-marker-9d3e" injected via additionalContext was
- * incorporated verbatim into the assistant's final answer. With the
- * earlier `<user_message_during_turn>` framing, the model recognised
- * it as prompt-injection-shaped and refused.
- *
- * Why a buffer module instead of inlining: per-sessionKey state lives
- * outside the pm and outside polygram.js's handleMessage so both
- * autosteer (handleMessage line ~2418) and /steer (line ~1975) can
- * share it. pm-sdk binds a hook callback per spawn that closes over
- * its sessionKey and drains this buffer.
- *
- * Edge: tool-less turns (Claude answers without firing a tool). The
- * hook never fires, so a queued message would be lost. pm-sdk's
- * onResult handler MUST drain the buffer at turn-end and push the
- * remainder via `inputController.push(..., { shouldQuery: false })`
- * for next-turn injection — no m87 risk because the previous turn
- * ended cleanly with text/end_turn before the push lands.
- */
-
-'use strict';
-
-function createAutosteerBuffer() {
-  // sessionKey → array of strings (in order of arrival)
-  const queues = new Map();
-
-  function append(sessionKey, text) {
-    if (!sessionKey || typeof text !== 'string' || text.length === 0) return false;
-    let q = queues.get(sessionKey);
-    if (!q) { q = []; queues.set(sessionKey, q); }
-    q.push(text);
-    return true;
-  }
-
-  function drain(sessionKey) {
-    const q = queues.get(sessionKey);
-    if (!q || q.length === 0) return [];
-    queues.delete(sessionKey);
-    return q;
-  }
-
-  function size(sessionKey) {
-    return queues.get(sessionKey)?.length ?? 0;
-  }
-
-  function clear(sessionKey) {
-    queues.delete(sessionKey);
-  }
-
-  // Format the drained messages as the additionalContext payload that
-  // Claude trusts. Multiple messages are joined with a blank line so
-  // the model sees them as a sequence within a single channel tag.
-  function formatForHook(messages) {
-    if (!messages || messages.length === 0) return null;
-    const body = messages.join('\n\n');
-    return `<channel source="user-followup">\n${body}\n</channel>`;
-  }
-
-  return { append, drain, size, clear, formatForHook };
-}
-
-/**
- * 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).
- * @param {(sessionKey: string, drainedCount: number) => void} [opts.onDrained]
- *   — fired AFTER the hook successfully injects additionalContext.
- *     rc.37 wires this to clearAutosteeredReactions so the ✍ reaction
- *     fades the moment the agent absorbs the follow-up — not at SDK
- *     turn-end, which under autosteer can stretch tens of minutes
- *     (one SDK turn keeps absorbing follow-ups via additionalContext
- *     and never emits result, so the old turn-end-only cleanup left
- *     ✍ stuck across many user messages).
- *
- * @returns {async () => Promise<HookJSONOutput>}
- */
-function makePostToolBatchHook({ buffer, sessionKey, logEvent = null, chatId = null, logger = console, onDrained = null } = {}) {
-  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 */ }
-      }
-      if (typeof onDrained === 'function') {
-        // rc.38: async-safe. onDrained may return a Promise (it does
-        // today — clearAutosteeredReactions is async). A bare
-        // synchronous try/catch only catches throws, not rejections;
-        // an unhandled rejection escaping the hook would land on the
-        // process-level handler as misleading noise. Detect a
-        // thenable and attach .catch so async failures are logged at
-        // the same site, not as out-of-band unhandledRejection.
-        try {
-          const r = onDrained(sessionKey, drained.length);
-          if (r && typeof r.then === 'function') {
-            r.catch((err) => logger?.error?.(`[${sessionKey}] onDrained async: ${err?.message || err}`));
-          }
-        }
-        catch (err) { logger?.error?.(`[${sessionKey}] onDrained: ${err?.message || err}`); }
-      }
-      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 };