polygram 0.8.0 → 0.9.0-rc.1

package/lib/handlers/approvals.js

@@ -0,0 +1,361 @@
+/**
+ * Approval flow — SDK canUseTool callback + Telegram callback_query
+ * handler + timeout sweeper.
+ *
+ * This factory owns the approvalWaiters Map (approval_id → array of
+ * Promise-resolver fns) and exposes:
+ *
+ *   - makeCanUseTool(sessionKey) — closure that returns the SDK
+ *     canUseTool callback. Per-call: lookup chat_tool_decisions,
+ *     match against gatedTools patterns, issue pending row, post
+ *     4-button card to admin chat, park resolver, race against
+ *     opts.signal + timeout, return PermissionResult.
+ *
+ *   - handleApprovalCallback(ctx) — grammy callback_query handler
+ *     for the approve / deny / approve-always / deny-always buttons.
+ *     Validates token + status, atomically resolves the row,
+ *     persists chat_tool_decisions for always-* clicks, edits the
+ *     card to show the decision, resolves the parked waiter.
+ *
+ *   - startApprovalSweeper(intervalMs?) — periodic timeout sweeper.
+ *     Sweeps pending rows past timeout_ts, marks them 'timeout',
+ *     edits the card to ⏰ Timed out, resolves the waiter.
+ *
+ *   - resolveApprovalWaiter(id, decision, reason?, extra?) +
+ *     dropWaiter(id, fn) — internal-but-exported for adjacent code
+ *     that needs to feed back from the callback flow.
+ *
+ * No more dual-pm IPC: the deleted bin/approval-hook.js used to
+ * connect to polygram via Unix-socket IPC; SDK pm wires canUseTool
+ * in-process.
+ */
+
+'use strict';
+
+const { canonicalizeToolInput } = require('../canonical-json');
+const {
+  matchesAnyPattern: matchesApprovalPattern,
+  tokensEqual: approvalTokensEqual,
+  DEFAULT_TIMEOUT_MS: APPROVAL_DEFAULT_TIMEOUT_MS,
+} = require('../approvals/store');
+const {
+  buildApprovalKeyboardWithAlways,
+  approvalCardText,
+} = require('../approvals/ui');
+
+function createApprovals({
+  config,
+  db,
+  bot,
+  botName,
+  tg,
+  logEvent,
+  approvals,           // approvals store instance
+  getChatIdFromKey,
+  logger = console,
+} = {}) {
+  // approval_id → array of resolver fns
+  const approvalWaiters = new Map();
+
+  function dropWaiter(id, fn) {
+    const list = approvalWaiters.get(id);
+    if (!list) return;
+    const i = list.indexOf(fn);
+    if (i !== -1) list.splice(i, 1);
+    if (list.length === 0) approvalWaiters.delete(id);
+  }
+
+  function resolveApprovalWaiter(id, decision, reason, extra) {
+    // `extra` carries SDK-shape updatedPermissions for always-* clicks.
+    // canUseTool waiters use it to populate
+    // PermissionResult.updatedPermissions so the in-flight Query
+    // picks up the new rule for the rest of the turn.
+    const list = approvalWaiters.get(id);
+    if (!list) return;
+    approvalWaiters.delete(id);
+    for (const fn of list) {
+      try { fn(decision, reason, extra); } catch {}
+    }
+  }
+
+  function makeCanUseTool(sessionKey) {
+    const chatId = getChatIdFromKey(sessionKey);
+    return async function canUseTool(toolName, input, opts) {
+      const apprCfg = config.bot?.approvals;
+      if (!apprCfg || !apprCfg.adminChatId) {
+        // Not configured for this bot → allow everything.
+        return { behavior: 'allow' };
+      }
+
+      const canonicalInput = canonicalizeToolInput(input);
+
+      // chat_tool_decisions short-circuit.
+      try {
+        const persisted = db.lookupChatToolDecision({
+          bot_name: botName, chat_id: chatId, tool_name: toolName,
+          canonical_input: canonicalInput, now: Date.now(),
+        });
+        if (persisted) {
+          logEvent('canusetool-shortcircuit', {
+            chat_id: chatId, tool_name: toolName,
+            decision: persisted.decision, match_type: persisted.match_type,
+            tool_use_id: opts?.toolUseID || null,
+          });
+          if (persisted.decision === 'allow') return { behavior: 'allow' };
+          return { behavior: 'deny', message: 'matched persisted always-deny rule' };
+        }
+      } catch (err) {
+        logger.error?.(`[${sessionKey}] chat_tool_decisions lookup: ${err.message}`);
+      }
+
+      const gated = matchesApprovalPattern(toolName, input, apprCfg.gatedTools || []);
+      if (!gated.matched) return { behavior: 'allow' };
+
+      // Issue + post + park. tool_use_id is the dedup key when
+      // the SDK supplies it; falls back to the legacy
+      // (turn_id, tool_input_digest) tuple for cron / IPC callers.
+      const row = approvals.issue({
+        bot_name: botName,
+        turn_id: opts?.toolUseID || null,
+        tool_use_id: opts?.toolUseID || null,
+        requester_chat_id: chatId,
+        approver_chat_id: String(apprCfg.adminChatId),
+        tool_name: toolName, tool_input: input,
+        timeoutMs: apprCfg.timeoutMs || APPROVAL_DEFAULT_TIMEOUT_MS,
+      });
+      if (!bot) {
+        approvals.resolve({ id: row.id, status: 'cancelled', reason: 'bot not ready' });
+        return { behavior: 'deny', message: 'bot not ready' };
+      }
+      if (!row.reused || !row.approver_msg_id) {
+        try {
+          const sent = await tg(bot, 'sendMessage', {
+            chat_id: apprCfg.adminChatId,
+            text: approvalCardText(row),
+            reply_markup: buildApprovalKeyboardWithAlways(row.id, row.callback_token),
+          }, { source: 'canusetool-card', botName, plainText: true });
+          if (sent?.message_id) approvals.setApproverMsgId(row.id, sent.message_id);
+        } catch (err) {
+          logger.error?.(`[${sessionKey}] failed to post canUseTool card: ${err.message}`);
+          approvals.resolve({ id: row.id, status: 'cancelled', reason: `post failed: ${err.message}` });
+          return { behavior: 'deny', message: `post failed: ${err.message}` };
+        }
+      }
+
+      // Race signal + timeout + click.
+      return await new Promise((resolve) => {
+        let settled = false;
+        const settle = (decision) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          if (opts?.signal && sigCleanup) {
+            try { opts.signal.removeEventListener('abort', sigCleanup); }
+            catch {}
+          }
+          dropWaiter(row.id, wrappedResolve);
+          resolve(decision);
+        };
+        const timer = setTimeout(() => {
+          approvals.resolve({ id: row.id, status: 'timeout' }).catch?.(() => {});
+          settle({ behavior: 'deny', message: 'approval timed out' });
+        }, Math.max(1000, row.timeout_ts - Date.now()));
+        const sigCleanup = opts?.signal
+          ? () => settle({ behavior: 'deny', message: 'aborted' })
+          : null;
+        if (opts?.signal && sigCleanup) {
+          opts.signal.addEventListener('abort', sigCleanup, { once: true });
+        }
+        const wrappedResolve = (decision, reason, extra) => {
+          // decision: 'approved' | 'denied' | 'approved-always' | 'denied-always'
+          if (decision === 'approved' || decision === 'approved-always') {
+            settle({
+              behavior: 'allow',
+              ...(decision === 'approved-always' && extra?.updatedPermissions
+                ? { updatedPermissions: extra.updatedPermissions }
+                : {}),
+            });
+          } else {
+            settle({
+              behavior: 'deny',
+              message: reason || decision || 'denied',
+            });
+          }
+        };
+        const list = approvalWaiters.get(row.id) || [];
+        list.push(wrappedResolve);
+        approvalWaiters.set(row.id, list);
+      });
+    };
+  }
+
+  async function handleApprovalCallback(ctx) {
+    const data = ctx.callbackQuery?.data || '';
+    const m = String(data).match(/^(approve|deny|approve-always|deny-always):(\d+):(\S+)$/);
+    if (!m) return;
+    const decision = m[1];
+    const id = parseInt(m[2], 10);
+    const token = m[3];
+
+    const row = approvals.getById(id);
+    if (!row) {
+      await ctx.answerCallbackQuery({ text: 'Unknown approval.', show_alert: true }).catch(() => {});
+      return;
+    }
+    if (!approvalTokensEqual(row.callback_token, token)) {
+      logEvent('approval-token-mismatch', { id, from_user: ctx.from?.id });
+      await ctx.answerCallbackQuery({ text: 'Bad token.', show_alert: true }).catch(() => {});
+      return;
+    }
+    if (row.status !== 'pending') {
+      await ctx.answerCallbackQuery({ text: `Already ${row.status}.`, show_alert: true }).catch(() => {});
+      return;
+    }
+
+    // Only the configured approver chat is authoritative.
+    const apprCfg = config.bot?.approvals;
+    const expectedChat = String(apprCfg?.adminChatId || '');
+    if (String(ctx.chat?.id) !== expectedChat) {
+      logEvent('approval-foreign-chat', {
+        id, from_chat: ctx.chat?.id, expected: expectedChat,
+      });
+      await ctx.answerCallbackQuery({ text: 'Not authorised here.', show_alert: true }).catch(() => {});
+      return;
+    }
+
+    const isApprove = decision === 'approve' || decision === 'approve-always';
+    const isAlways = decision === 'approve-always' || decision === 'deny-always';
+    const status = isApprove ? 'approved' : 'denied';
+    const user = ctx.from?.first_name || ctx.from?.username || null;
+    const userId = ctx.from?.id || null;
+    // Atomic SQL UPDATE ... WHERE status='pending' — double-click
+    // race: only one writer wins; the second sees changes=0.
+    const changes = approvals.resolve({
+      id, status,
+      decided_by_user_id: userId, decided_by_user: user,
+    });
+    if (changes === 0) {
+      const fresh = approvals.getById(id);
+      await ctx.answerCallbackQuery({
+        text: `Already ${fresh?.status || 'resolved'}.`,
+        show_alert: true,
+      }).catch(() => {});
+      return;
+    }
+    logEvent('approval-resolved', {
+      id, status, by: userId, user, bot: botName,
+    });
+
+    // Edit the card to show the decision.
+    try {
+      const fresh = approvals.getById(id);
+      await tg(bot, 'editMessageText', {
+        chat_id: row.approver_chat_id,
+        message_id: row.approver_msg_id,
+        text: approvalCardText(fresh, {
+          resolvedBy: `${status === 'approved' ? '✅ Approved' : '❌ Denied'} by ${user || userId}`,
+        }),
+      }, { source: 'approval-card-decision', botName, plainText: true });
+    } catch (err) {
+      logger.error?.(`[${botName}] edit approval card failed: ${err.message}`);
+    }
+    // Persist always-* clicks to chat_tool_decisions.
+    let updatedPermissions = null;
+    if (isAlways) {
+      try {
+        const canonical = canonicalizeToolInput(row.tool_input);
+        db.insertChatToolDecision({
+          bot_name: botName,
+          chat_id: row.requester_chat_id,
+          tool_name: row.tool_name,
+          match_type: 'prefix',
+          input_pattern: canonical,
+          decision: status === 'approved' ? 'allow' : 'deny',
+          issued_by_user_id: userId ? String(userId) : null,
+          expires_ts: null,
+        });
+        logEvent('chat-tool-decision-persisted', {
+          chat_id: row.requester_chat_id,
+          tool_name: row.tool_name,
+          decision: status === 'approved' ? 'allow' : 'deny',
+          match_type: 'prefix',
+        });
+        updatedPermissions = [{
+          type: 'addRules',
+          rules: [{
+            toolName: row.tool_name,
+            decision: status === 'approved' ? 'allow' : 'deny',
+          }],
+        }];
+      } catch (err) {
+        logger.error?.(`[${botName}] chat_tool_decisions persist failed: ${err.message}`);
+      }
+    }
+
+    await ctx.answerCallbackQuery({ text: status }).catch(() => {});
+
+    // Pass the original decision back to the waiter so it can
+    // distinguish 'approved-always' (SDK gets updatedPermissions)
+    // from plain 'approved'.
+    resolveApprovalWaiter(id, decision === 'approve-always' ? 'approved-always'
+      : decision === 'deny-always' ? 'denied-always'
+      : status, undefined, { updatedPermissions });
+  }
+
+  function startApprovalSweeper(intervalMs = 30_000) {
+    return setInterval(() => {
+      let rows;
+      try {
+        rows = approvals.sweepTimedOut();
+      } catch (err) {
+        logger.error?.(`[approvals] sweeper DB error: ${err.message}`);
+        logEvent('approval-sweep-failed', { error: err.message?.slice(0, 300) });
+        return;
+      }
+      for (const row of rows) {
+        approvals.resolve({ id: row.id, status: 'timeout' });
+        logEvent('approval-timeout', { id: row.id, bot: botName, tool: row.tool_name });
+        resolveApprovalWaiter(row.id, 'timeout', 'swept');
+        if (bot && row.approver_msg_id) {
+          tg(bot, 'editMessageText', {
+            chat_id: row.approver_chat_id,
+            message_id: row.approver_msg_id,
+            text: approvalCardText(approvals.getById(row.id), { resolvedBy: '⏰ Timed out' }),
+          }, { source: 'approval-card-timeout', botName, plainText: true })
+            .catch((err) => logger.error?.(`[${botName}] approval-card-timeout edit: ${err.message}`));
+        }
+      }
+    }, intervalMs);
+  }
+
+  /**
+   * Reject every parked waiter with the supplied decision (default
+   * 'denied'). Called from polygram.js's shutdown handler so any
+   * in-flight canUseTool Promises don't dangle with the daemon
+   * gone — the SDK Query gets a deny and the tool call fails
+   * cleanly instead of timing out into the void.
+   */
+  function cancelAllWaiters(decision = 'denied', reason = 'shutdown') {
+    let count = 0;
+    for (const list of approvalWaiters.values()) {
+      for (const fn of list) {
+        try { fn(decision, reason); count++; } catch {}
+      }
+    }
+    approvalWaiters.clear();
+    return count;
+  }
+
+  return {
+    makeCanUseTool,
+    handleApprovalCallback,
+    resolveApprovalWaiter,
+    dropWaiter,
+    startApprovalSweeper,
+    cancelAllWaiters,
+    // Test introspection
+    _approvalWaiters: approvalWaiters,
+  };
+}
+
+module.exports = { createApprovals };

package/lib/handlers/autosteer.js

@@ -0,0 +1,94 @@
+/**
+ * Autosteer detection + dispatch.
+ *
+ * When a user types a follow-up message while the bot is mid-reply,
+ * absorb it into the current turn instead of queueing a separate
+ * response (OpenClaw-style "merge into active"). Saves a turn,
+ * saves tokens, feels conversational.
+ *
+ * Two halves:
+ *   - shouldAutosteer(sessionKey, chatConfig) — boolean predicate,
+ *     used pre-THINKING to skip the 🤔 → ✍ flash.
+ *   - tryAutosteer(...) — full dispatch: pm.injectUserMessage with
+ *     priority hint ('next' for merge, 'later' for queue), records
+ *     ✍ reaction ref, logs telemetry, sets reactor to AUTOSTEERED
+ *     and returns true so caller short-circuits.
+ *
+ * Opt-out: chatConfig.autosteer === false (per-chat) or
+ * config.bot.autosteer === false. Mode: chatConfig.autosteerMode
+ * (or config.bot.autosteerMode) of 'merge' (default → priority='next')
+ * or 'queue' (→ priority='later'); spike findings in
+ * scripts/spikes/native-queue.mjs explain the difference.
+ */
+
+'use strict';
+
+function isAutosteerEnabledFor(chatConfig, config) {
+  return chatConfig.autosteer != null
+    ? chatConfig.autosteer !== false
+    : config.bot?.autosteer !== false;
+}
+
+function priorityFor(chatConfig, config) {
+  const mode = chatConfig.autosteerMode != null
+    ? chatConfig.autosteerMode
+    : config.bot?.autosteerMode;
+  return mode === 'queue' ? 'later' : 'next';
+}
+
+function createAutosteerHandlers({
+  config,
+  pm,
+  autosteeredRefs,
+  logEvent,
+} = {}) {
+
+  /**
+   * Pre-THINKING predicate. Returns true when the upcoming message
+   * will be autosteered (so the caller skips reactor.setState('THINKING')
+   * to avoid the 🤔 → ✍ flash).
+   */
+  function willAutosteer(sessionKey, chatConfig) {
+    if (!pm.has(sessionKey)) return false;
+    if (!pm.get(sessionKey)?.inFlight) return false;
+    return isAutosteerEnabledFor(chatConfig, config);
+  }
+
+  /**
+   * Attempt to inject the user message into the in-flight turn.
+   * Returns:
+   *   - { autosteered: true, priority }  — caller marks reactor
+   *     AUTOSTEERED + records ✍ ref + returns from handleMessage.
+   *   - { autosteered: false }  — caller falls through to normal
+   *     pm.send queue path.
+   */
+  function tryAutosteer({ sessionKey, chatConfig, chatId, msg, prompt }) {
+    if (!isAutosteerEnabledFor(chatConfig, config)) return { autosteered: false };
+    if (!pm.has(sessionKey)) return { autosteered: false };
+    const entry = pm.get(sessionKey);
+    if (!entry?.inFlight) return { autosteered: false };
+
+    const priority = priorityFor(chatConfig, config);
+    const ok = pm.injectUserMessage(sessionKey, {
+      content: prompt,
+      priority,
+    });
+    if (!ok) return { autosteered: false };
+
+    autosteeredRefs.add(sessionKey, { chatId, msgId: msg.message_id });
+    logEvent('autosteer', {
+      chat_id: chatId, msg_id: msg.message_id,
+      text_len: prompt?.length ?? 0,
+      priority,
+    });
+    return { autosteered: true, priority };
+  }
+
+  return { willAutosteer, tryAutosteer };
+}
+
+module.exports = {
+  createAutosteerHandlers,
+  isAutosteerEnabledFor,
+  priorityFor,
+};

package/lib/handlers/config-callback.js

@@ -0,0 +1,118 @@
+/**
+ * Inline-keyboard callback handler for the /model and /effort cards.
+ *
+ * When a user taps a button on the config card, this routes:
+ *   1. validate the new value;
+ *   2. mutate chatConfig in-place + persist via db.logConfigChange;
+ *   3. apply the change live to the running SDK Query via
+ *      pm.applyFlagSettings (effort) or pm.setModel (model);
+ *   4. re-render the card with the new ✓ marker;
+ *   5. acknowledge the button press with a context-aware toast.
+ *
+ * SDK pm applies the change live — no kill, no respawn. Pre-cleanup
+ * the CLI pm path used requestRespawn (drain queue + kill subprocess)
+ * for /model + /effort; that's gone with the CLI pm.
+ */
+
+'use strict';
+
+const { toTelegramHtml } = require('../telegram/format');
+
+const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
+const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+function createHandleConfigCallback({
+  config,
+  db,
+  dbWrite,
+  pm,
+  getSessionKey,
+  formatConfigInfoText,
+  buildConfigKeyboard,
+  botName,
+  logger = console,
+} = {}) {
+
+  return async function handleConfigCallback(ctx) {
+    const data = ctx.callbackQuery?.data || '';
+    const m = String(data).match(/^cfg:(model|effort):(\S+)$/);
+    if (!m) return;
+    const setting = m[1];
+    const value = m[2];
+
+    const chatId = String(ctx.callbackQuery.message?.chat?.id || '');
+    const chatConfig = config.chats[chatId];
+    if (!chatConfig) {
+      await ctx.answerCallbackQuery({ text: 'Chat not configured', show_alert: true }).catch(() => {});
+      return;
+    }
+    if (!config.bot?.allowConfigCommands) {
+      await ctx.answerCallbackQuery({ text: 'Config commands disabled', show_alert: true }).catch(() => {});
+      return;
+    }
+
+    const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
+    if (!validValues.includes(value)) {
+      await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
+      return;
+    }
+
+    const oldValue = chatConfig[setting];
+    if (oldValue === value) {
+      await ctx.answerCallbackQuery({ text: `Already ${value}` }).catch(() => {});
+      return;
+    }
+
+    chatConfig[setting] = value;
+    const cmdUserId = ctx.callbackQuery.from?.id || null;
+    const cmdUser = ctx.callbackQuery.from?.first_name || ctx.callbackQuery.from?.username || null;
+    dbWrite(() => db.logConfigChange({
+      chat_id: chatId, thread_id: null, field: setting,
+      old_value: oldValue, new_value: value,
+      user: cmdUser, user_id: cmdUserId, source: 'inline-button',
+    }), `log ${setting} change`);
+
+    // Graceful application to the topic's session. SDK pm applies live
+    // via setModel / applyFlagSettings; chatConfig is already updated
+    // on disk above so a missing live session still picks up the new
+    // value on its next cold spawn.
+    const callbackThreadId = ctx.callbackQuery.message?.message_thread_id?.toString() || null;
+    const callbackSessionKey = getSessionKey(chatId, callbackThreadId, chatConfig);
+    let applied = false;
+    if (setting === 'effort') {
+      applied = await pm.applyFlagSettings(callbackSessionKey, { effortLevel: value });
+    } else if (setting === 'model') {
+      applied = await pm.setModel(callbackSessionKey, value);
+    }
+    const anyActive = !applied;
+
+    // Re-render the card with the new ✓ marker. Detect original card
+    // type (model-only / effort-only / both) by counting rows in the
+    // existing reply_markup so the user sees the same layout they
+    // tapped into.
+    const existingRows = ctx.callbackQuery.message?.reply_markup?.inline_keyboard?.length || 0;
+    const showRow = existingRows >= 2 ? 'all' : setting;
+    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId);
+    const newKeyboard = buildConfigKeyboard(chatConfig, showRow);
+    try {
+      const { text: html, parseMode } = toTelegramHtml(newInfo);
+      await ctx.editMessageText(html, {
+        reply_markup: newKeyboard,
+        ...(parseMode && { parse_mode: parseMode }),
+      });
+    } catch (err) {
+      logger.error?.(`[${botName}] config-card edit failed: ${err.message}`);
+    }
+
+    const ackText = anyActive
+      ? `${setting} → ${value} — switching when finished`
+      : `${setting} → ${value}`;
+    await ctx.answerCallbackQuery({ text: ackText }).catch(() => {});
+  };
+}
+
+module.exports = {
+  createHandleConfigCallback,
+  MODEL_OPTIONS,
+  EFFORT_OPTIONS,
+};

package/lib/handlers/config-ui.js

@@ -0,0 +1,104 @@
+/**
+ * Config card UI builders — inline keyboard + descriptive body
+ * shown above it. Used by polygram's /config slash command and
+ * the /model + /effort callback re-render path
+ * (lib/handlers/config-callback.js).
+ *
+ * Pure functions (no DB / fs) but `formatConfigInfoText` needs
+ * runtime context (pm to check warm/cold, db + getClaudeSessionId
+ * to fetch session id) → factory wraps it. Keyboard builder is a
+ * top-level export.
+ *
+ * MODEL_VERSIONS_DESC bumps with each Claude release — see polygram's
+ * release notes for the verification step (`claude --model <alias>`
+ * + check the system:init event's `model` field).
+ */
+
+'use strict';
+
+const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
+const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+// Mirrors what `claude --model <alias>` resolves to. Display only —
+// polygram passes the alias (opus / sonnet / haiku) and lets claude
+// resolve. Bump on Claude release.
+const MODEL_VERSIONS_DESC = {
+  opus: 'claude-opus-4-7',
+  sonnet: 'claude-sonnet-4-6',
+  haiku: 'claude-haiku-4-5',
+};
+
+/**
+ * Build the inline keyboard for /model + /effort.
+ *   show = 'model' | 'effort' | 'all'
+ * The current value gets a ✓ prefix.
+ */
+function buildConfigKeyboard(chatConfig, show = 'all') {
+  const rows = [];
+  if (show === 'model' || show === 'all') {
+    rows.push(MODEL_OPTIONS.map((m) => ({
+      text: m === chatConfig.model ? `✓ ${m}` : m,
+      callback_data: `cfg:model:${m}`,
+    })));
+  }
+  if (show === 'effort' || show === 'all') {
+    rows.push(EFFORT_OPTIONS.map((e) => ({
+      text: e === chatConfig.effort ? `✓ ${e}` : e,
+      callback_data: `cfg:effort:${e}`,
+    })));
+  }
+  return { inline_keyboard: rows };
+}
+
+/**
+ * Factory for the card-body formatter. Needs runtime pm + db + a
+ * getClaudeSessionId fetcher.
+ *
+ * @param {object} deps
+ * @param {object} deps.pm
+ * @param {object} deps.db
+ * @param {(db, sessionKey) => string|null} deps.getClaudeSessionId
+ */
+function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
+  return function formatConfigInfoText(chatConfig, show, sessionKey) {
+    const alive = pm.has(sessionKey) && !pm.get(sessionKey).closed;
+    const ver = MODEL_VERSIONS_DESC[chatConfig.model] || chatConfig.model;
+    const sess = getClaudeSessionId(db, sessionKey)?.slice(0, 8) || 'new';
+    const head =
+      `Model: ${chatConfig.model} (${ver})\n` +
+      `Effort: ${chatConfig.effort}\n` +
+      `Agent: ${chatConfig.agent}\n` +
+      `Process: ${alive ? 'warm' : 'cold'}\n` +
+      `Session: ${sess}`;
+
+    const modelHelp = [
+      '',
+      '**Models**',
+      '🧠 **opus** — deep analysis, code refactor, multi-source reconciliation. ~5× sonnet cost.',
+      '🤖 **sonnet** — default. Most ops, code review, document summary.',
+      '⚡ **haiku** — quick simple tasks, classification, lookup.',
+    ].join('\n');
+
+    const effortHelp = [
+      '',
+      '**Effort** — ceiling on how much Claude can think. Simple questions get fast replies; hard ones spend more tokens. Safe to set higher — Claude scales down automatically when it doesn\'t need to think.',
+      '• **low** — fast replies, minimum reasoning. Casual chat, simple lookups.',
+      '• **medium** — balanced default. Fits most use cases.',
+      '• **high** — multi-step tasks. Audit, debug, multi-source analysis.',
+      '• **xhigh** / **max** — heaviest. Hard reasoning, edge cases.',
+    ].join('\n');
+
+    let body = head;
+    if (show === 'model' || show === 'all') body += '\n' + modelHelp;
+    if (show === 'effort' || show === 'all') body += '\n' + effortHelp;
+    return body;
+  };
+}
+
+module.exports = {
+  buildConfigKeyboard,
+  createFormatConfigInfoText,
+  MODEL_OPTIONS,
+  EFFORT_OPTIONS,
+  MODEL_VERSIONS_DESC,
+};