polygram 0.8.0 → 0.9.0-rc.2

package/lib/handlers/dispatcher.js

@@ -0,0 +1,263 @@
+/**
+ * Per-message handler dispatcher.
+ *
+ * `dispatchHandleMessage(sessionKey, chatId, msg, bot)` is what
+ * grammy's `bot.on('message')` calls per inbound — it runs
+ * handleMessage in a fire-and-forget manner with centralised
+ * error handling, in-flight-counter telemetry, and auto-resume
+ * recovery on no-activity timeouts.
+ *
+ * Owned state:
+ *   - inFlightHandlers (Map<sessionKey, count>) — per-session
+ *     concurrent handler count. queue-depth-warning fires when
+ *     this crosses queueWarnThreshold.
+ *   - autoResumeTracker — per-session cooldown to prevent
+ *     infinite resume-loop on permanently wedged tools.
+ *
+ * Auto-resume contract: on a 300s no-activity timeout (Claude
+ * never emits a chunk), spawn a fresh Query resuming the same
+ * claude_session_id and inject a continuation nudge. Falls back
+ * to the standard error reply if the resume itself fails.
+ */
+
+'use strict';
+
+const CONCURRENT_WARN_THRESHOLD_DEFAULT = 20;
+
+function createDispatcher({
+  config,
+  db,
+  dbWrite,
+  tg,
+  botName,
+  logEvent,
+  // Closures that polygram.js owns; passed in:
+  handleMessage,                  // async (sessionKey, chatId, msg, bot)
+  sendToProcess,                  // async (sessionKey, prompt, ctx)
+  // Cross-cutting helpers:
+  classifyError,                  // (err) → { kind, userMessage, isTransient, autoRecover }
+  isAutoResumable,                // ({ error, aborted, replay, shuttingDown }) → boolean
+  abortGrace,                     // lib/abort-grace.js instance
+  autoResumeTracker,              // lib/db/auto-resume.js instance
+  chunkMarkdownText,              // lib/telegram/chunk.js
+  deliverReplies,                 // lib/telegram/deliver.js
+  TG_MAX_LEN = 4096,
+  // State accessors (need late binding because polygram.js mutates):
+  getIsShuttingDown,              // () → boolean
+  logger = console,
+} = {}) {
+  // Per-session in-flight handler count.
+  const inFlightHandlers = new Map();
+
+  function queueWarnThreshold() {
+    const v = Number(config.bot?.queueWarnThreshold);
+    return (Number.isInteger(v) && v > 0) ? v : CONCURRENT_WARN_THRESHOLD_DEFAULT;
+  }
+
+  function errorReplyText(err) {
+    const { userMessage } = classifyError(err);
+    return userMessage;  // may be null — "suppress reply" signal
+  }
+
+  // rc.54: spawn a fresh Query resuming the same session_id and ask
+  // Claude to continue the timed-out work. The killed pm Query has
+  // already torn down the wedged subprocess; getOrSpawnForChat creates
+  // a new entry that picks up the saved session_id and sets
+  // `--resume <id>` on the SDK Options.
+  async function attemptAutoResume(sessionKey, chatId, originalMsg, bot) {
+    const threadId = originalMsg.message_thread_id || null;
+
+    // 1. Tell the user we're auto-resuming so they don't think
+    //    nothing happened. Threaded under their original message.
+    await tg(bot, 'sendMessage', {
+      chat_id: chatId,
+      text: '🔁 Auto-resuming after timeout — continuing where the previous turn left off.',
+      reply_parameters: { message_id: originalMsg.message_id },
+      ...(threadId && { message_thread_id: threadId }),
+    }, { source: 'auto-resume-indicator', botName }).catch((sendErr) => {
+      logger.error?.(`[${sessionKey}] auto-resume indicator send failed: ${sendErr.message}`);
+    });
+
+    // 2. Continuation prompt. Plain text — the SDK Query resumes
+    //    the saved session_id, so Claude has full prior transcript
+    //    context including its own partially-streamed text and
+    //    tool calls. We just need to tell it WHAT happened.
+    const continuation = '[polygram] Your previous turn timed out at 300s with no Claude activity (likely a wedged tool call — long Bash, hanging MCP, or stuck subagent). Continue from where you left off; do not restart from scratch. If the same operation would just hang again, abort it and tell me.';
+
+    // 3. No-op streamer + reactor. We don't stream the resume
+    //    turn's response (we'll send it as one message at the
+    //    end). pm invokes streamer/reactor methods only when
+    //    present; minimal stubs keep pm happy.
+    const noopStreamer = {
+      onChunk: async () => {},
+      forceNewMessage: () => {},
+      finalize: async () => ({ streamed: false }),
+      flushDraft: async () => {},
+      discard: async () => {},
+    };
+    const noopReactor = {
+      setState: () => {},
+      heartbeat: () => {},
+      clear: async () => {},
+      stop: () => {},
+    };
+
+    const result = await sendToProcess(sessionKey, continuation, {
+      streamer: noopStreamer,
+      reactor: noopReactor,
+      sourceMsgId: originalMsg.message_id,
+      threadId,
+      onFirstStream: () => {},
+    });
+
+    if (result?.error) {
+      throw new Error(`auto-resume turn errored: ${String(result.error).slice(0, 200)}`);
+    }
+    if (!result?.text) {
+      throw new Error('auto-resume turn produced no text');
+    }
+
+    // 4. Send the continuation reply as regular Telegram messages,
+    //    threaded under the original user message.
+    const chunks = chunkMarkdownText(result.text, TG_MAX_LEN);
+    await deliverReplies({
+      bot,
+      send: (b, method, params, m) => tg(b, method, params, m),
+      chatId,
+      threadId,
+      chunks,
+      replyToMessageId: originalMsg.message_id,
+      meta: { source: 'auto-resume-reply', botName },
+      logger: { error: (m) => logger.error?.(`[${sessionKey}] auto-resume deliver: ${m}`) },
+    });
+
+    return result.text;
+  }
+
+  function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
+    const count = (inFlightHandlers.get(sessionKey) || 0) + 1;
+    inFlightHandlers.set(sessionKey, count);
+    const warnAt = queueWarnThreshold();
+    if (count === warnAt) {
+      logEvent('queue-depth-warning', {
+        chat_id: chatId, session_key: sessionKey,
+        in_flight: count, threshold: warnAt,
+      });
+    }
+    handleMessage(sessionKey, chatId, msg, bot).catch((err) => {
+      const wasAborted = abortGrace.isRecent(sessionKey);
+      const isReplay = msg._isReplay === true;
+      const isShuttingDown = getIsShuttingDown();
+      logger.error?.(`[${sessionKey}] Error: ${err.message}`);
+      // Mark the row terminal so the right thing happens on next
+      // boot:
+      //   aborted        — user explicitly stopped → not replayable
+      //   shutdown + new — 'replay-pending' so next boot re-dispatches
+      //   shutdown + replay — keep 'replay-attempted' (one-shot guard
+      //                       prevents infinite replay-on-replay)
+      //   else           — 'failed' (genuine claude crash / timeout)
+      const status = wasAborted
+        ? 'aborted'
+        : isShuttingDown
+          ? (isReplay ? 'replay-attempted' : 'replay-pending')
+          : 'failed';
+      dbWrite(() => db.setInboundHandlerStatus({
+        chat_id: chatId, msg_id: msg.message_id, status,
+      }), `set handler_status=${status}`);
+      logEvent('handler-error', {
+        chat_id: chatId, session_key: sessionKey,
+        msg_id: msg?.message_id,
+        error: err.message?.slice(0, 500),
+        stack: err.stack?.split('\n').slice(0, 5).join('\n'),
+        aborted: wasAborted || undefined,
+        replay: isReplay || undefined,
+      });
+      // rc.55: surface replay failures with a meaningful message.
+      // Pre-rc.55 any boot-replay turn that failed for ANY reason
+      // was silently dropped. The rc.51-onward boot-replay path is
+      // a recovery primitive, not stale-message handling — when it
+      // fails, the user IS still waiting.
+      if (isReplay && !wasAborted && !isShuttingDown) {
+        tg(bot, 'sendMessage', {
+          chat_id: chatId,
+          text: '⚠️ This turn was interrupted and didn\'t complete on retry — please rephrase or simplify, or split into smaller steps.',
+          reply_parameters: { message_id: msg.message_id },
+        }, { source: 'error-reply', botName }).catch((replyErr) => {
+          logger.error?.(`[${sessionKey}] failed to send replay-failure reply: ${replyErr.message}`);
+        });
+      }
+      // Suppress the user-facing error reply when:
+      //   - boot replay (handled above),
+      //   - shutting down ("Process killed" isn't a real error),
+      //   - user just /stop'd (already saw their abort ack).
+      if (!wasAborted && !isReplay && !isShuttingDown) {
+        // rc.54: auto-resume on 300s no-activity timeout. The
+        // resume turn itself runs through sendToProcess directly
+        // (not handleMessage), so its errors don't re-enter this
+        // catch block — autoResumeTracker.isInCooldown() is the
+        // only guard needed against runaway loops.
+        const resumable = isAutoResumable({
+          error: err, aborted: wasAborted, replay: isReplay, shuttingDown: isShuttingDown,
+        });
+        if (resumable && !autoResumeTracker.isInCooldown(sessionKey)) {
+          autoResumeTracker.markAttempt(sessionKey);
+          logEvent('auto-resume-attempted', {
+            chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
+            original_error: err.message?.slice(0, 200),
+          });
+          attemptAutoResume(sessionKey, chatId, msg, bot)
+            .then(() => {
+              logEvent('auto-resume-success', {
+                chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
+              });
+              autoResumeTracker.clear(sessionKey);
+            })
+            .catch((resumeErr) => {
+              logger.error?.(`[${sessionKey}] auto-resume failed: ${resumeErr?.message}`);
+              logEvent('auto-resume-failed', {
+                chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
+                error: resumeErr?.message?.slice(0, 200),
+              });
+              const fallbackText = errorReplyText(err);
+              if (fallbackText) {
+                tg(bot, 'sendMessage', {
+                  chat_id: chatId, text: fallbackText,
+                  reply_parameters: { message_id: msg.message_id },
+                }, { source: 'error-reply', botName }).catch(() => {});
+              }
+            });
+          return;
+        }
+        // 0.7.7: errorReplyText may return null (suppress reply
+        // signal — INTERRUPTED inside abort grace).
+        const replyText = errorReplyText(err);
+        if (replyText) {
+          tg(bot, 'sendMessage', {
+            chat_id: chatId,
+            text: replyText,
+            reply_parameters: { message_id: msg.message_id },
+          }, { source: 'error-reply', botName }).catch((replyErr) => {
+            logger.error?.(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
+          });
+        }
+      }
+    }).finally(() => {
+      const n = (inFlightHandlers.get(sessionKey) || 1) - 1;
+      if (n <= 0) inFlightHandlers.delete(sessionKey);
+      else inFlightHandlers.set(sessionKey, n);
+    });
+  }
+
+  return {
+    dispatchHandleMessage,
+    attemptAutoResume,
+    errorReplyText,
+    queueWarnThreshold,
+    inFlightHandlers,  // exposed so polygram.js can introspect for shutdown drain
+  };
+}
+
+module.exports = {
+  createDispatcher,
+  CONCURRENT_WARN_THRESHOLD_DEFAULT,
+};

package/lib/handlers/download.js

@@ -0,0 +1,182 @@
+/**
+ * Telegram attachment downloader with bounded concurrency.
+ *
+ * Per inbound message with attachments, this fans out parallel
+ * fetches against Telegram's CDN, writes each to disk atomically
+ * (temp file + rename), and updates the attachments DB row with
+ * download_status / local_path / error. The per-file 10MB cap is
+ * enforced THREE ways: content-length header (cheap), streaming
+ * accumulator (DOS protection), final post-buffer check (defense
+ * in depth).
+ *
+ * Reuse path: if a row already says downloaded AND the file is on
+ * disk with non-zero size, the fetch is skipped (idempotent on
+ * boot-replay).
+ *
+ * Token redaction: the fetch URL embeds bot${TOKEN}; some undici
+ * error variants stringify the URL into err.message. We pipe every
+ * persisted error through redactBotToken so the bot token never
+ * lands in attachments.download_error or stderr.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { redactBotToken } = require('../error/net');
+const { MAX_FILE_BYTES } = require('../attachments');
+
+const ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT = 6;
+
+function sanitizeFilename(name) {
+  if (!name) return 'file';
+  return name.replace(/[\/\\:\0]/g, '_').slice(0, 120);
+}
+
+function createDownloadAttachments({
+  config,
+  db,
+  dbWrite,
+  inboxDir,
+  logger = console,
+  fetchImpl = (typeof fetch === 'function' ? fetch : null),
+} = {}) {
+
+  function attachmentConcurrency() {
+    const v = Number(config.bot?.attachmentConcurrency);
+    return (Number.isInteger(v) && v > 0) ? v : ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT;
+  }
+
+  // Per-attachment download. Pure function over (att, deps) → result.
+  // Pulled out of the loop so downloadAttachments can run several in
+  // parallel.
+  async function downloadOneAttachment(bot, token, chatId, msg, chatDir, att) {
+    // Reuse path: row already says downloaded AND the file is on disk.
+    if (att.download_status === 'downloaded' && att.local_path) {
+      try {
+        if (fs.statSync(att.local_path).size > 0) {
+          return { ...att, path: att.local_path, size: att.size_bytes || 0, error: null };
+        }
+      } catch { /* fall through to refetch */ }
+    }
+    try {
+      const fileInfo = await bot.api.getFile(att.file_id);
+      if (!fileInfo?.file_path) throw new Error('no file_path from getFile');
+      const url = `https://api.telegram.org/file/bot${token}/${fileInfo.file_path}`;
+      const res = await fetchImpl(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      // Three-layer size enforcement, in order of cheapness:
+      //   1. Content-Length header — fail-fast before reading body.
+      //   2. Streaming accumulator — abort the moment cumulative byte
+      //      count crosses the cap. Defends against attackers omitting
+      //      Content-Length: pre-cap the whole body could pin RSS.
+      //   3. Final post-buffer check — defense in depth.
+      const cl = parseInt(res.headers.get('content-length') || '0', 10);
+      if (cl > MAX_FILE_BYTES) {
+        throw new Error(`content-length ${cl} exceeds per-file cap ${MAX_FILE_BYTES}`);
+      }
+      let total = 0;
+      const chunks = [];
+      if (res.body && typeof res.body.getReader === 'function') {
+        const reader = res.body.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          total += value.byteLength;
+          if (total > MAX_FILE_BYTES) {
+            try { await reader.cancel(); } catch {}
+            throw new Error(`stream ${total}+ bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
+          }
+          chunks.push(value);
+        }
+      } else {
+        // Fallback for runtimes without WHATWG streams (shouldn't fire
+        // on Node 22+).
+        const ab = await res.arrayBuffer();
+        if (ab.byteLength > MAX_FILE_BYTES) {
+          throw new Error(`body ${ab.byteLength} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
+        }
+        chunks.push(new Uint8Array(ab));
+        total = ab.byteLength;
+      }
+      const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
+      if (buf.length > MAX_FILE_BYTES) {
+        throw new Error(`body ${buf.length} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
+      }
+      const safeName = sanitizeFilename(att.name);
+      // Embed file_unique_id so two attachments with the same msg_id+name
+      // (album, resend) can't silently overwrite each other.
+      const uniq = att.file_unique_id ? `-${att.file_unique_id}` : '';
+      const localName = `${msg.message_id}${uniq}-${safeName}`;
+      const localPath = path.join(chatDir, localName);
+      // Atomic write: temp file + rename. A crash mid-write leaves a
+      // .tmp.* file (swept later) rather than a truncated canonical
+      // file the EEXIST dedup branch would happily serve next time.
+      if (fs.existsSync(localPath)) {
+        logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (already on disk, reusing)`);
+      } else {
+        const tmpPath = `${localPath}.tmp.${process.pid}.${Date.now()}`;
+        try {
+          fs.writeFileSync(tmpPath, buf, { flag: 'wx' });
+          fs.renameSync(tmpPath, localPath);
+        } catch (e) {
+          try { fs.unlinkSync(tmpPath); } catch {}
+          if (e.code !== 'EEXIST') throw e;
+          logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (race: already on disk)`);
+        }
+      }
+      logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (${buf.length} bytes) → ${localPath}`);
+      dbWrite(() => db.markAttachmentDownloaded(att.id, {
+        local_path: localPath, size_bytes: att.size_bytes || buf.length,
+      }), `markAttachmentDownloaded ${att.id}`);
+      return { ...att, path: localPath, size: att.size_bytes || buf.length, error: null };
+    } catch (err) {
+      // Don't drop the attachment silently — push it through with the
+      // failure noted. buildAttachmentTags renders this as
+      // <attachment-failed reason="..." /> so claude tells the user
+      // "I couldn't see your <kind>" instead of pretending it received
+      // text only. Token redaction is mandatory: the fetch URL embeds
+      // bot${TOKEN} and some undici variants stringify it into err.message.
+      const raw = (err.message || 'unknown').slice(0, 200);
+      const reason = redactBotToken(raw);
+      logger.error?.(`[attach] download failed for ${att.name}: ${reason}`);
+      dbWrite(() => db.markAttachmentFailed(att.id, reason),
+        `markAttachmentFailed ${att.id}`);
+      return { ...att, path: null, error: reason };
+    }
+  }
+
+  // 0.6.7: parallel fetches with bounded concurrency. Inner work is
+  // stateless per-attachment (writes keyed on file_unique_id so two
+  // parallel downloads can't collide). Order of results is preserved
+  // by writing into a fixed-size array at the original index —
+  // important so the prompt sees attachments in album order.
+  async function downloadAttachments(bot, token, chatId, msg, rows) {
+    if (!rows.length) return [];
+    const chatDir = path.join(inboxDir, String(chatId));
+    fs.mkdirSync(chatDir, { recursive: true });
+
+    const results = new Array(rows.length);
+    let cursor = 0;
+    const workers = Array.from(
+      { length: Math.min(attachmentConcurrency(), rows.length) },
+      async () => {
+        while (true) {
+          const idx = cursor++;
+          if (idx >= rows.length) return;
+          results[idx] = await downloadOneAttachment(bot, token, chatId, msg, chatDir, rows[idx]);
+        }
+      },
+    );
+    await Promise.all(workers);
+    return results;
+  }
+
+  return downloadAttachments;
+}
+
+module.exports = {
+  createDownloadAttachments,
+  sanitizeFilename,
+  ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT,
+};

package/lib/handlers/extract-attachments.js

@@ -0,0 +1,97 @@
+/**
+ * Extract attachment metadata from a Telegram message.
+ *
+ * Returns the canonical row shape that the rest of polygram's
+ * pipeline (recordInbound → filterAttachments → downloadAttachments
+ * → buildAttachmentTags) consumes. Pure function: no DB, no fs,
+ * no network.
+ *
+ * Media-group bundling: when polygram pre-merges several
+ * siblings sharing a `media_group_id` into a single message, the
+ * merged attachment list lives at `msg._mergedAttachments`; we
+ * return it verbatim. Otherwise the per-field extractors run.
+ *
+ * Auto-generated names use `shortFileTag(file_unique_id)` —
+ * file_unique_id is stable per file across sessions, so a 6-char
+ * prefix gives stable names that survive media-group reassignment.
+ * Falls back to msg.message_id when file_unique_id is missing.
+ */
+
+'use strict';
+
+/**
+ * 8-char filesystem-safe handle from a Telegram file_unique_id.
+ * Falls back to fallback (typically msg.message_id) when no
+ * unique id is available.
+ */
+function shortFileTag(fileUniqueId, fallback) {
+  if (fileUniqueId) {
+    return String(fileUniqueId).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 8)
+      || String(fallback);
+  }
+  return String(fallback);
+}
+
+function extractAttachments(msg) {
+  // Media-group bundling: pre-merged list takes precedence.
+  if (Array.isArray(msg._mergedAttachments)) return msg._mergedAttachments;
+
+  const items = [];
+  if (msg.document) {
+    const d = msg.document;
+    items.push({
+      file_id: d.file_id,
+      file_unique_id: d.file_unique_id,
+      name: d.file_name || `document-${shortFileTag(d.file_unique_id, msg.message_id)}`,
+      mime_type: d.mime_type || 'application/octet-stream',
+      size: d.file_size || 0,
+      kind: 'document',
+    });
+  }
+  if (msg.photo && msg.photo.length > 0) {
+    const largest = msg.photo[msg.photo.length - 1];
+    items.push({
+      file_id: largest.file_id,
+      file_unique_id: largest.file_unique_id,
+      name: `photo-${shortFileTag(largest.file_unique_id, msg.message_id)}.jpg`,
+      mime_type: 'image/jpeg',
+      size: largest.file_size || 0,
+      kind: 'photo',
+    });
+  }
+  if (msg.voice) {
+    items.push({
+      file_id: msg.voice.file_id,
+      file_unique_id: msg.voice.file_unique_id,
+      name: `voice-${shortFileTag(msg.voice.file_unique_id, msg.message_id)}.ogg`,
+      mime_type: msg.voice.mime_type || 'audio/ogg',
+      size: msg.voice.file_size || 0,
+      kind: 'voice',
+    });
+  }
+  if (msg.audio) {
+    const a = msg.audio;
+    items.push({
+      file_id: a.file_id,
+      file_unique_id: a.file_unique_id,
+      name: a.file_name || `audio-${shortFileTag(a.file_unique_id, msg.message_id)}.mp3`,
+      mime_type: a.mime_type || 'audio/mpeg',
+      size: a.file_size || 0,
+      kind: 'audio',
+    });
+  }
+  if (msg.video) {
+    const v = msg.video;
+    items.push({
+      file_id: v.file_id,
+      file_unique_id: v.file_unique_id,
+      name: v.file_name || `video-${shortFileTag(v.file_unique_id, msg.message_id)}.mp4`,
+      mime_type: v.mime_type || 'video/mp4',
+      size: v.file_size || 0,
+      kind: 'video',
+    });
+  }
+  return items;
+}
+
+module.exports = { extractAttachments, shortFileTag };

package/lib/handlers/ipc-send.js

@@ -0,0 +1,80 @@
+/**
+ * Cron / IPC `send` handler — wraps tg() for external callers
+ * (cron jobs, CLI scripts) that talk to polygram via the Unix
+ * socket IPC.
+ *
+ * Allowlist: only non-destructive Telegram Bot API methods. cron
+ * has no business calling deleteMessage / banChatMember etc.
+ *
+ * Cross-bot guard: chat_id MUST belong to this bot (after
+ * filterConfigToBot, config.chats only contains our chats — so
+ * lookup-by-chat-id naturally enforces ownership).
+ *
+ * File-param validation: validateIpcFileParam catches the most
+ * common upload-shape mistakes before Telegram rejects with a
+ * confusing error.
+ */
+
+'use strict';
+
+const { validateIpcFileParam } = require('../ipc/file-validator');
+
+// Allowed Telegram Bot API methods. Broader than sendMessage to
+// cover receipts, error reports, quick replies. Deliberately
+// excludes destructive ops.
+const IPC_SEND_ALLOWED_METHODS = new Set([
+  'sendMessage',
+  'sendPhoto',
+  'sendDocument',
+  'sendSticker',
+  'sendChatAction',
+  'editMessageText',
+  'setMessageReaction',
+]);
+
+function createHandleSendOverIpc({ config, bot, tg, botName } = {}) {
+  return async function handleSendOverIpc(req) {
+    const { method, params = {}, source } = req || {};
+    if (!method) throw new Error('method required');
+    if (!IPC_SEND_ALLOWED_METHODS.has(method)) {
+      throw new Error(`method not allowed: ${method}`);
+    }
+    if (!bot) throw new Error('bot process not ready');
+
+    // Enforce: chat_id must belong to this bot (no cross-bot sends).
+    const chatId = params.chat_id != null ? String(params.chat_id) : null;
+    if (chatId && !config.chats[chatId]) {
+      throw new Error(`chat not owned by ${botName}: ${chatId}`);
+    }
+
+    // editMessageText accepts (chat_id+message_id) OR
+    // inline_message_id as the addressing mode. The chat_id branch
+    // above gates the first; inline_message_id has no owner field
+    // a cron caller can be checked against, so a malicious or buggy
+    // caller could edit any inline message system-wide. Polygram
+    // never sends inline-mode messages (we have no inline-bot
+    // handlers), so reject inline_message_id outright.
+    if (params.inline_message_id != null) {
+      throw new Error('inline_message_id editing not supported by polygram IPC');
+    }
+    // editMessageText with neither chat_id nor inline_message_id
+    // would silently succeed-with-error from Telegram; fail fast.
+    if (method === 'editMessageText' && !chatId) {
+      throw new Error('editMessageText requires chat_id');
+    }
+
+    const fileParamErr = validateIpcFileParam(method, params);
+    if (fileParamErr) throw new Error(fileParamErr);
+
+    const sendRes = await tg(bot, method, params, {
+      source: source || 'ipc',
+      botName,
+    });
+    return { result: sendRes };
+  };
+}
+
+module.exports = {
+  createHandleSendOverIpc,
+  IPC_SEND_ALLOWED_METHODS,
+};