refactor(src): split oversized modules

src/web/auto-reply/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_WEB_MEDIA_BYTES = 5 * 1024 * 1024;

src/web/auto-reply/deliver-reply.ts

@@ -0,0 +1,209 @@
+import { chunkMarkdownText } from "../../auto-reply/chunk.js";
+import type { ReplyPayload } from "../../auto-reply/types.js";
+import { logVerbose, shouldLogVerbose } from "../../globals.js";
+import { loadWebMedia } from "../media.js";
+import { newConnectionId } from "../reconnect.js";
+import { formatError } from "../session.js";
+import { whatsappOutboundLog } from "./loggers.js";
+import type { WebInboundMsg } from "./types.js";
+import { elide } from "./util.js";
+
+export async function deliverWebReply(params: {
+  replyResult: ReplyPayload;
+  msg: WebInboundMsg;
+  maxMediaBytes: number;
+  textLimit: number;
+  replyLogger: {
+    info: (obj: unknown, msg: string) => void;
+    warn: (obj: unknown, msg: string) => void;
+  };
+  connectionId?: string;
+  skipLog?: boolean;
+}) {
+  const {
+    replyResult,
+    msg,
+    maxMediaBytes,
+    textLimit,
+    replyLogger,
+    connectionId,
+    skipLog,
+  } = params;
+  const replyStarted = Date.now();
+  const textChunks = chunkMarkdownText(replyResult.text || "", textLimit);
+  const mediaList = replyResult.mediaUrls?.length
+    ? replyResult.mediaUrls
+    : replyResult.mediaUrl
+      ? [replyResult.mediaUrl]
+      : [];
+
+  const sleep = (ms: number) =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+  const sendWithRetry = async (
+    fn: () => Promise<unknown>,
+    label: string,
+    maxAttempts = 3,
+  ) => {
+    let lastErr: unknown;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastErr = err;
+        const errText = formatError(err);
+        const isLast = attempt === maxAttempts;
+        const shouldRetry = /closed|reset|timed\\s*out|disconnect/i.test(
+          errText,
+        );
+        if (!shouldRetry || isLast) {
+          throw err;
+        }
+        const backoffMs = 500 * attempt;
+        logVerbose(
+          `Retrying ${label} to ${msg.from} after failure (${attempt}/${maxAttempts - 1}) in ${backoffMs}ms: ${errText}`,
+        );
+        await sleep(backoffMs);
+      }
+    }
+    throw lastErr;
+  };
+
+  // Text-only replies
+  if (mediaList.length === 0 && textChunks.length) {
+    const totalChunks = textChunks.length;
+    for (const [index, chunk] of textChunks.entries()) {
+      const chunkStarted = Date.now();
+      await sendWithRetry(() => msg.reply(chunk), "text");
+      if (!skipLog) {
+        const durationMs = Date.now() - chunkStarted;
+        whatsappOutboundLog.debug(
+          `Sent chunk ${index + 1}/${totalChunks} to ${msg.from} (${durationMs.toFixed(0)}ms)`,
+        );
+      }
+    }
+    replyLogger.info(
+      {
+        correlationId: msg.id ?? newConnectionId(),
+        connectionId: connectionId ?? null,
+        to: msg.from,
+        from: msg.to,
+        text: elide(replyResult.text, 240),
+        mediaUrl: null,
+        mediaSizeBytes: null,
+        mediaKind: null,
+        durationMs: Date.now() - replyStarted,
+      },
+      "auto-reply sent (text)",
+    );
+    return;
+  }
+
+  const remainingText = [...textChunks];
+
+  // Media (with optional caption on first item)
+  for (const [index, mediaUrl] of mediaList.entries()) {
+    const caption =
+      index === 0 ? remainingText.shift() || undefined : undefined;
+    try {
+      const media = await loadWebMedia(mediaUrl, maxMediaBytes);
+      if (shouldLogVerbose()) {
+        logVerbose(
+          `Web auto-reply media size: ${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB`,
+        );
+        logVerbose(
+          `Web auto-reply media source: ${mediaUrl} (kind ${media.kind})`,
+        );
+      }
+      if (media.kind === "image") {
+        await sendWithRetry(
+          () =>
+            msg.sendMedia({
+              image: media.buffer,
+              caption,
+              mimetype: media.contentType,
+            }),
+          "media:image",
+        );
+      } else if (media.kind === "audio") {
+        await sendWithRetry(
+          () =>
+            msg.sendMedia({
+              audio: media.buffer,
+              ptt: true,
+              mimetype: media.contentType,
+              caption,
+            }),
+          "media:audio",
+        );
+      } else if (media.kind === "video") {
+        await sendWithRetry(
+          () =>
+            msg.sendMedia({
+              video: media.buffer,
+              caption,
+              mimetype: media.contentType,
+            }),
+          "media:video",
+        );
+      } else {
+        const fileName = media.fileName ?? mediaUrl.split("/").pop() ?? "file";
+        const mimetype = media.contentType ?? "application/octet-stream";
+        await sendWithRetry(
+          () =>
+            msg.sendMedia({
+              document: media.buffer,
+              fileName,
+              caption,
+              mimetype,
+            }),
+          "media:document",
+        );
+      }
+      whatsappOutboundLog.info(
+        `Sent media reply to ${msg.from} (${(media.buffer.length / (1024 * 1024)).toFixed(2)}MB)`,
+      );
+      replyLogger.info(
+        {
+          correlationId: msg.id ?? newConnectionId(),
+          connectionId: connectionId ?? null,
+          to: msg.from,
+          from: msg.to,
+          text: caption ?? null,
+          mediaUrl,
+          mediaSizeBytes: media.buffer.length,
+          mediaKind: media.kind,
+          durationMs: Date.now() - replyStarted,
+        },
+        "auto-reply sent (media)",
+      );
+    } catch (err) {
+      whatsappOutboundLog.error(
+        `Failed sending web media to ${msg.from}: ${formatError(err)}`,
+      );
+      replyLogger.warn({ err, mediaUrl }, "failed to send web media reply");
+      if (index === 0) {
+        const warning =
+          err instanceof Error
+            ? `⚠️ Media failed: ${err.message}`
+            : "⚠️ Media failed.";
+        const fallbackTextParts = [
+          remainingText.shift() ?? caption ?? "",
+          warning,
+        ].filter(Boolean);
+        const fallbackText = fallbackTextParts.join("\n");
+        if (fallbackText) {
+          whatsappOutboundLog.warn(
+            `Media skipped; sent text-only to ${msg.from}`,
+          );
+          await msg.reply(fallbackText);
+        }
+      }
+    }
+  }
+
+  // Remaining text chunks after media
+  for (const chunk of remainingText) {
+    await msg.reply(chunk);
+  }
+}

src/web/auto-reply/heartbeat-runner.ts

@@ -0,0 +1,245 @@
+import {
+  DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+  resolveHeartbeatPrompt,
+  stripHeartbeatToken,
+} from "../../auto-reply/heartbeat.js";
+import { getReplyFromConfig } from "../../auto-reply/reply.js";
+import type { ReplyPayload } from "../../auto-reply/types.js";
+import { resolveWhatsAppHeartbeatRecipients } from "../../channels/plugins/whatsapp-heartbeat.js";
+import { loadConfig } from "../../config/config.js";
+import {
+  loadSessionStore,
+  resolveSessionKey,
+  resolveStorePath,
+  saveSessionStore,
+} from "../../config/sessions.js";
+import { emitHeartbeatEvent } from "../../infra/heartbeat-events.js";
+import { getChildLogger } from "../../logging.js";
+import { normalizeMainKey } from "../../routing/session-key.js";
+import { sendMessageWhatsApp } from "../outbound.js";
+import { newConnectionId } from "../reconnect.js";
+import { formatError } from "../session.js";
+import { whatsappHeartbeatLog } from "./loggers.js";
+import { getSessionSnapshot } from "./session-snapshot.js";
+import { elide } from "./util.js";
+
+function resolveHeartbeatReplyPayload(
+  replyResult: ReplyPayload | ReplyPayload[] | undefined,
+): ReplyPayload | undefined {
+  if (!replyResult) return undefined;
+  if (!Array.isArray(replyResult)) return replyResult;
+  for (let idx = replyResult.length - 1; idx >= 0; idx -= 1) {
+    const payload = replyResult[idx];
+    if (!payload) continue;
+    if (
+      payload.text ||
+      payload.mediaUrl ||
+      (payload.mediaUrls && payload.mediaUrls.length > 0)
+    ) {
+      return payload;
+    }
+  }
+  return undefined;
+}
+
+export async function runWebHeartbeatOnce(opts: {
+  cfg?: ReturnType<typeof loadConfig>;
+  to: string;
+  verbose?: boolean;
+  replyResolver?: typeof getReplyFromConfig;
+  sender?: typeof sendMessageWhatsApp;
+  sessionId?: string;
+  overrideBody?: string;
+  dryRun?: boolean;
+}) {
+  const {
+    cfg: cfgOverride,
+    to,
+    verbose = false,
+    sessionId,
+    overrideBody,
+    dryRun = false,
+  } = opts;
+  const replyResolver = opts.replyResolver ?? getReplyFromConfig;
+  const sender = opts.sender ?? sendMessageWhatsApp;
+  const runId = newConnectionId();
+  const heartbeatLogger = getChildLogger({
+    module: "web-heartbeat",
+    runId,
+    to,
+  });
+
+  const cfg = cfgOverride ?? loadConfig();
+  const sessionCfg = cfg.session;
+  const sessionScope = sessionCfg?.scope ?? "per-sender";
+  const mainKey = normalizeMainKey(sessionCfg?.mainKey);
+  const sessionKey = resolveSessionKey(sessionScope, { From: to }, mainKey);
+  if (sessionId) {
+    const storePath = resolveStorePath(cfg.session?.store);
+    const store = loadSessionStore(storePath);
+    const current = store[sessionKey] ?? {};
+    store[sessionKey] = {
+      ...current,
+      sessionId,
+      updatedAt: Date.now(),
+    };
+    await saveSessionStore(storePath, store);
+  }
+  const sessionSnapshot = getSessionSnapshot(cfg, to, true);
+  if (verbose) {
+    heartbeatLogger.info(
+      {
+        to,
+        sessionKey: sessionSnapshot.key,
+        sessionId: sessionId ?? sessionSnapshot.entry?.sessionId ?? null,
+        sessionFresh: sessionSnapshot.fresh,
+        idleMinutes: sessionSnapshot.idleMinutes,
+      },
+      "heartbeat session snapshot",
+    );
+  }
+
+  if (overrideBody && overrideBody.trim().length === 0) {
+    throw new Error("Override body must be non-empty when provided.");
+  }
+
+  try {
+    if (overrideBody) {
+      if (dryRun) {
+        whatsappHeartbeatLog.info(
+          `[dry-run] web send -> ${to}: ${elide(overrideBody.trim(), 200)} (manual message)`,
+        );
+        return;
+      }
+      const sendResult = await sender(to, overrideBody, { verbose });
+      emitHeartbeatEvent({
+        status: "sent",
+        to,
+        preview: overrideBody.slice(0, 160),
+        hasMedia: false,
+      });
+      heartbeatLogger.info(
+        {
+          to,
+          messageId: sendResult.messageId,
+          chars: overrideBody.length,
+          reason: "manual-message",
+        },
+        "manual heartbeat message sent",
+      );
+      whatsappHeartbeatLog.info(
+        `manual heartbeat sent to ${to} (id ${sendResult.messageId})`,
+      );
+      return;
+    }
+
+    const replyResult = await replyResolver(
+      {
+        Body: resolveHeartbeatPrompt(cfg.agents?.defaults?.heartbeat?.prompt),
+        From: to,
+        To: to,
+        MessageSid: sessionId ?? sessionSnapshot.entry?.sessionId,
+      },
+      { isHeartbeat: true },
+      cfg,
+    );
+    const replyPayload = resolveHeartbeatReplyPayload(replyResult);
+
+    if (
+      !replyPayload ||
+      (!replyPayload.text &&
+        !replyPayload.mediaUrl &&
+        !replyPayload.mediaUrls?.length)
+    ) {
+      heartbeatLogger.info(
+        {
+          to,
+          reason: "empty-reply",
+          sessionId: sessionSnapshot.entry?.sessionId ?? null,
+        },
+        "heartbeat skipped",
+      );
+      emitHeartbeatEvent({ status: "ok-empty", to });
+      return;
+    }
+
+    const hasMedia = Boolean(
+      replyPayload.mediaUrl || (replyPayload.mediaUrls?.length ?? 0) > 0,
+    );
+    const ackMaxChars = Math.max(
+      0,
+      cfg.agents?.defaults?.heartbeat?.ackMaxChars ??
+        DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
+    );
+    const stripped = stripHeartbeatToken(replyPayload.text, {
+      mode: "heartbeat",
+      maxAckChars: ackMaxChars,
+    });
+    if (stripped.shouldSkip && !hasMedia) {
+      // Don't let heartbeats keep sessions alive: restore previous updatedAt so idle expiry still works.
+      const storePath = resolveStorePath(cfg.session?.store);
+      const store = loadSessionStore(storePath);
+      if (sessionSnapshot.entry && store[sessionSnapshot.key]) {
+        store[sessionSnapshot.key].updatedAt = sessionSnapshot.entry.updatedAt;
+        await saveSessionStore(storePath, store);
+      }
+
+      heartbeatLogger.info(
+        { to, reason: "heartbeat-token", rawLength: replyPayload.text?.length },
+        "heartbeat skipped",
+      );
+      emitHeartbeatEvent({ status: "ok-token", to });
+      return;
+    }
+
+    if (hasMedia) {
+      heartbeatLogger.warn(
+        { to },
+        "heartbeat reply contained media; sending text only",
+      );
+    }
+
+    const finalText = stripped.text || replyPayload.text || "";
+    if (dryRun) {
+      heartbeatLogger.info(
+        { to, reason: "dry-run", chars: finalText.length },
+        "heartbeat dry-run",
+      );
+      whatsappHeartbeatLog.info(
+        `[dry-run] heartbeat -> ${to}: ${elide(finalText, 200)}`,
+      );
+      return;
+    }
+
+    const sendResult = await sender(to, finalText, { verbose });
+    emitHeartbeatEvent({
+      status: "sent",
+      to,
+      preview: finalText.slice(0, 160),
+      hasMedia,
+    });
+    heartbeatLogger.info(
+      {
+        to,
+        messageId: sendResult.messageId,
+        chars: finalText.length,
+        preview: elide(finalText, 140),
+      },
+      "heartbeat sent",
+    );
+    whatsappHeartbeatLog.info(`heartbeat alert sent to ${to}`);
+  } catch (err) {
+    const reason = formatError(err);
+    heartbeatLogger.warn({ to, error: reason }, "heartbeat failed");
+    whatsappHeartbeatLog.warn(`heartbeat failed (${reason})`);
+    emitHeartbeatEvent({ status: "failed", to, reason });
+    throw err;
+  }
+}
+
+export function resolveHeartbeatRecipients(
+  cfg: ReturnType<typeof loadConfig>,
+  opts: { to?: string; all?: boolean } = {},
+) {
+  return resolveWhatsAppHeartbeatRecipients(cfg, opts);
+}

src/web/auto-reply/loggers.ts

@@ -0,0 +1,6 @@
+import { createSubsystemLogger } from "../../logging.js";
+
+export const whatsappLog = createSubsystemLogger("gateway/channels/whatsapp");
+export const whatsappInboundLog = whatsappLog.child("inbound");
+export const whatsappOutboundLog = whatsappLog.child("outbound");
+export const whatsappHeartbeatLog = whatsappLog.child("heartbeat");

src/web/auto-reply/mentions.ts

@@ -0,0 +1,124 @@
+import {
+  buildMentionRegexes,
+  normalizeMentionText,
+} from "../../auto-reply/reply/mentions.js";
+import type { loadConfig } from "../../config/config.js";
+import { isSelfChatMode, jidToE164, normalizeE164 } from "../../utils.js";
+import type { WebInboundMsg } from "./types.js";
+
+export type MentionConfig = {
+  mentionRegexes: RegExp[];
+  allowFrom?: Array<string | number>;
+};
+
+export type MentionTargets = {
+  normalizedMentions: string[];
+  selfE164: string | null;
+  selfJid: string | null;
+};
+
+export function buildMentionConfig(
+  cfg: ReturnType<typeof loadConfig>,
+  agentId?: string,
+): MentionConfig {
+  const mentionRegexes = buildMentionRegexes(cfg, agentId);
+  return { mentionRegexes, allowFrom: cfg.channels?.whatsapp?.allowFrom };
+}
+
+export function resolveMentionTargets(
+  msg: WebInboundMsg,
+  authDir?: string,
+): MentionTargets {
+  const jidOptions = authDir ? { authDir } : undefined;
+  const normalizedMentions = msg.mentionedJids?.length
+    ? msg.mentionedJids
+        .map((jid) => jidToE164(jid, jidOptions) ?? jid)
+        .filter(Boolean)
+    : [];
+  const selfE164 =
+    msg.selfE164 ?? (msg.selfJid ? jidToE164(msg.selfJid, jidOptions) : null);
+  const selfJid = msg.selfJid ? msg.selfJid.replace(/:\\d+/, "") : null;
+  return { normalizedMentions, selfE164, selfJid };
+}
+
+export function isBotMentionedFromTargets(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  targets: MentionTargets,
+): boolean {
+  const clean = (text: string) =>
+    // Remove zero-width and directionality markers WhatsApp injects around display names
+    normalizeMentionText(text);
+
+  const isSelfChat = isSelfChatMode(targets.selfE164, mentionCfg.allowFrom);
+
+  if (msg.mentionedJids?.length && !isSelfChat) {
+    if (
+      targets.selfE164 &&
+      targets.normalizedMentions.includes(targets.selfE164)
+    )
+      return true;
+    if (targets.selfJid && targets.selfE164) {
+      // Some mentions use the bare JID; match on E.164 to be safe.
+      if (targets.normalizedMentions.includes(targets.selfJid)) return true;
+    }
+  } else if (msg.mentionedJids?.length && isSelfChat) {
+    // Self-chat mode: ignore WhatsApp @mention JIDs, otherwise @mentioning the owner in group chats triggers the bot.
+  }
+  const bodyClean = clean(msg.body);
+  if (mentionCfg.mentionRegexes.some((re) => re.test(bodyClean))) return true;
+
+  // Fallback: detect body containing our own number (with or without +, spacing)
+  if (targets.selfE164) {
+    const selfDigits = targets.selfE164.replace(/\D/g, "");
+    if (selfDigits) {
+      const bodyDigits = bodyClean.replace(/[^\d]/g, "");
+      if (bodyDigits.includes(selfDigits)) return true;
+      const bodyNoSpace = msg.body.replace(/[\s-]/g, "");
+      const pattern = new RegExp(`\\+?${selfDigits}`, "i");
+      if (pattern.test(bodyNoSpace)) return true;
+    }
+  }
+
+  return false;
+}
+
+export function debugMention(
+  msg: WebInboundMsg,
+  mentionCfg: MentionConfig,
+  authDir?: string,
+): { wasMentioned: boolean; details: Record<string, unknown> } {
+  const mentionTargets = resolveMentionTargets(msg, authDir);
+  const result = isBotMentionedFromTargets(msg, mentionCfg, mentionTargets);
+  const details = {
+    from: msg.from,
+    body: msg.body,
+    bodyClean: normalizeMentionText(msg.body),
+    mentionedJids: msg.mentionedJids ?? null,
+    normalizedMentionedJids: mentionTargets.normalizedMentions.length
+      ? mentionTargets.normalizedMentions
+      : null,
+    selfJid: msg.selfJid ?? null,
+    selfJidBare: mentionTargets.selfJid,
+    selfE164: msg.selfE164 ?? null,
+    resolvedSelfE164: mentionTargets.selfE164,
+  };
+  return { wasMentioned: result, details };
+}
+
+export function resolveOwnerList(
+  mentionCfg: MentionConfig,
+  selfE164?: string | null,
+) {
+  const allowFrom = mentionCfg.allowFrom;
+  const raw =
+    Array.isArray(allowFrom) && allowFrom.length > 0
+      ? allowFrom
+      : selfE164
+        ? [selfE164]
+        : [];
+  return raw
+    .filter((entry): entry is string => Boolean(entry && entry !== "*"))
+    .map((entry) => normalizeE164(entry))
+    .filter((entry): entry is string => Boolean(entry));
+}

src/web/auto-reply/monitor.ts

@@ -0,0 +1,441 @@
+import { DEFAULT_GROUP_HISTORY_LIMIT } from "../../auto-reply/reply/history.js";
+import { getReplyFromConfig } from "../../auto-reply/reply.js";
+import { waitForever } from "../../cli/wait.js";
+import { loadConfig } from "../../config/config.js";
+import { logVerbose } from "../../globals.js";
+import { formatDurationMs } from "../../infra/format-duration.js";
+import { enqueueSystemEvent } from "../../infra/system-events.js";
+import { registerUnhandledRejectionHandler } from "../../infra/unhandled-rejections.js";
+import { getChildLogger } from "../../logging.js";
+import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { defaultRuntime, type RuntimeEnv } from "../../runtime.js";
+import { resolveWhatsAppAccount } from "../accounts.js";
+import { setActiveWebListener } from "../active-listener.js";
+import { monitorWebInbox } from "../inbound.js";
+import {
+  computeBackoff,
+  newConnectionId,
+  resolveHeartbeatSeconds,
+  resolveReconnectPolicy,
+  sleepWithAbort,
+} from "../reconnect.js";
+import { formatError, getWebAuthAgeMs, readWebSelfId } from "../session.js";
+import { DEFAULT_WEB_MEDIA_BYTES } from "./constants.js";
+import { whatsappHeartbeatLog, whatsappLog } from "./loggers.js";
+import { buildMentionConfig } from "./mentions.js";
+import { createEchoTracker } from "./monitor/echo.js";
+import { createWebOnMessageHandler } from "./monitor/on-message.js";
+import type {
+  WebChannelStatus,
+  WebInboundMsg,
+  WebMonitorTuning,
+} from "./types.js";
+import { isLikelyWhatsAppCryptoError } from "./util.js";
+
+export async function monitorWebChannel(
+  verbose: boolean,
+  listenerFactory: typeof monitorWebInbox | undefined = monitorWebInbox,
+  keepAlive = true,
+  replyResolver: typeof getReplyFromConfig | undefined = getReplyFromConfig,
+  runtime: RuntimeEnv = defaultRuntime,
+  abortSignal?: AbortSignal,
+  tuning: WebMonitorTuning = {},
+) {
+  const runId = newConnectionId();
+  const replyLogger = getChildLogger({ module: "web-auto-reply", runId });
+  const heartbeatLogger = getChildLogger({ module: "web-heartbeat", runId });
+  const reconnectLogger = getChildLogger({ module: "web-reconnect", runId });
+  const status: WebChannelStatus = {
+    running: true,
+    connected: false,
+    reconnectAttempts: 0,
+    lastConnectedAt: null,
+    lastDisconnect: null,
+    lastMessageAt: null,
+    lastEventAt: null,
+    lastError: null,
+  };
+  const emitStatus = () => {
+    tuning.statusSink?.({
+      ...status,
+      lastDisconnect: status.lastDisconnect
+        ? { ...status.lastDisconnect }
+        : null,
+    });
+  };
+  emitStatus();
+
+  const baseCfg = loadConfig();
+  const account = resolveWhatsAppAccount({
+    cfg: baseCfg,
+    accountId: tuning.accountId,
+  });
+  const cfg = {
+    ...baseCfg,
+    channels: {
+      ...baseCfg.channels,
+      whatsapp: {
+        ...baseCfg.channels?.whatsapp,
+        ackReaction: account.ackReaction,
+        messagePrefix: account.messagePrefix,
+        allowFrom: account.allowFrom,
+        groupAllowFrom: account.groupAllowFrom,
+        groupPolicy: account.groupPolicy,
+        textChunkLimit: account.textChunkLimit,
+        mediaMaxMb: account.mediaMaxMb,
+        blockStreaming: account.blockStreaming,
+        groups: account.groups,
+      },
+    },
+  } satisfies ReturnType<typeof loadConfig>;
+
+  const configuredMaxMb = cfg.agents?.defaults?.mediaMaxMb;
+  const maxMediaBytes =
+    typeof configuredMaxMb === "number" && configuredMaxMb > 0
+      ? configuredMaxMb * 1024 * 1024
+      : DEFAULT_WEB_MEDIA_BYTES;
+  const heartbeatSeconds = resolveHeartbeatSeconds(
+    cfg,
+    tuning.heartbeatSeconds,
+  );
+  const reconnectPolicy = resolveReconnectPolicy(cfg, tuning.reconnect);
+  const baseMentionConfig = buildMentionConfig(cfg);
+  const groupHistoryLimit =
+    cfg.channels?.whatsapp?.accounts?.[tuning.accountId ?? ""]?.historyLimit ??
+    cfg.channels?.whatsapp?.historyLimit ??
+    cfg.messages?.groupChat?.historyLimit ??
+    DEFAULT_GROUP_HISTORY_LIMIT;
+  const groupHistories = new Map<
+    string,
+    Array<{
+      sender: string;
+      body: string;
+      timestamp?: number;
+      id?: string;
+      senderJid?: string;
+    }>
+  >();
+  const groupMemberNames = new Map<string, Map<string, string>>();
+  const echoTracker = createEchoTracker({ maxItems: 100, logVerbose });
+
+  const sleep =
+    tuning.sleep ??
+    ((ms: number, signal?: AbortSignal) =>
+      sleepWithAbort(ms, signal ?? abortSignal));
+  const stopRequested = () => abortSignal?.aborted === true;
+  const abortPromise =
+    abortSignal &&
+    new Promise<"aborted">((resolve) =>
+      abortSignal.addEventListener("abort", () => resolve("aborted"), {
+        once: true,
+      }),
+    );
+
+  // Avoid noisy MaxListenersExceeded warnings in test environments where
+  // multiple gateway instances may be constructed.
+  const currentMaxListeners = process.getMaxListeners?.() ?? 10;
+  if (process.setMaxListeners && currentMaxListeners < 50) {
+    process.setMaxListeners(50);
+  }
+
+  let sigintStop = false;
+  const handleSigint = () => {
+    sigintStop = true;
+  };
+  process.once("SIGINT", handleSigint);
+
+  let reconnectAttempts = 0;
+
+  while (true) {
+    if (stopRequested()) break;
+
+    const connectionId = newConnectionId();
+    const startedAt = Date.now();
+    let heartbeat: NodeJS.Timeout | null = null;
+    let watchdogTimer: NodeJS.Timeout | null = null;
+    let lastMessageAt: number | null = null;
+    let handledMessages = 0;
+    let _lastInboundMsg: WebInboundMsg | null = null;
+    let unregisterUnhandled: (() => void) | null = null;
+
+    // Watchdog to detect stuck message processing (e.g., event emitter died)
+    const MESSAGE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes without any messages
+    const WATCHDOG_CHECK_MS = 60 * 1000; // Check every minute
+
+    const backgroundTasks = new Set<Promise<unknown>>();
+    const onMessage = createWebOnMessageHandler({
+      cfg,
+      verbose,
+      connectionId,
+      maxMediaBytes,
+      groupHistoryLimit,
+      groupHistories,
+      groupMemberNames,
+      echoTracker,
+      backgroundTasks,
+      replyResolver: replyResolver ?? getReplyFromConfig,
+      replyLogger,
+      baseMentionConfig,
+      account,
+    });
+
+    const listener = await (listenerFactory ?? monitorWebInbox)({
+      verbose,
+      accountId: account.accountId,
+      authDir: account.authDir,
+      mediaMaxMb: account.mediaMaxMb,
+      onMessage: async (msg: WebInboundMsg) => {
+        handledMessages += 1;
+        lastMessageAt = Date.now();
+        status.lastMessageAt = lastMessageAt;
+        status.lastEventAt = lastMessageAt;
+        emitStatus();
+        _lastInboundMsg = msg;
+        await onMessage(msg);
+      },
+    });
+
+    status.connected = true;
+    status.lastConnectedAt = Date.now();
+    status.lastEventAt = status.lastConnectedAt;
+    status.lastError = null;
+    emitStatus();
+
+    // Surface a concise connection event for the next main-session turn/heartbeat.
+    const { e164: selfE164 } = readWebSelfId(account.authDir);
+    const connectRoute = resolveAgentRoute({
+      cfg,
+      channel: "whatsapp",
+      accountId: account.accountId,
+    });
+    enqueueSystemEvent(
+      `WhatsApp gateway connected${selfE164 ? ` as ${selfE164}` : ""}.`,
+      { sessionKey: connectRoute.sessionKey },
+    );
+
+    setActiveWebListener(account.accountId, listener);
+    unregisterUnhandled = registerUnhandledRejectionHandler((reason) => {
+      if (!isLikelyWhatsAppCryptoError(reason)) return false;
+      const errorStr = formatError(reason);
+      reconnectLogger.warn(
+        { connectionId, error: errorStr },
+        "web reconnect: unhandled rejection from WhatsApp socket; forcing reconnect",
+      );
+      listener.signalClose?.({
+        status: 499,
+        isLoggedOut: false,
+        error: reason,
+      });
+      return true;
+    });
+
+    const closeListener = async () => {
+      setActiveWebListener(account.accountId, null);
+      if (unregisterUnhandled) {
+        unregisterUnhandled();
+        unregisterUnhandled = null;
+      }
+      if (heartbeat) clearInterval(heartbeat);
+      if (watchdogTimer) clearInterval(watchdogTimer);
+      if (backgroundTasks.size > 0) {
+        await Promise.allSettled(backgroundTasks);
+        backgroundTasks.clear();
+      }
+      try {
+        await listener.close();
+      } catch (err) {
+        logVerbose(`Socket close failed: ${formatError(err)}`);
+      }
+    };
+
+    if (keepAlive) {
+      heartbeat = setInterval(() => {
+        const authAgeMs = getWebAuthAgeMs(account.authDir);
+        const minutesSinceLastMessage = lastMessageAt
+          ? Math.floor((Date.now() - lastMessageAt) / 60000)
+          : null;
+
+        const logData = {
+          connectionId,
+          reconnectAttempts,
+          messagesHandled: handledMessages,
+          lastMessageAt,
+          authAgeMs,
+          uptimeMs: Date.now() - startedAt,
+          ...(minutesSinceLastMessage !== null && minutesSinceLastMessage > 30
+            ? { minutesSinceLastMessage }
+            : {}),
+        };
+
+        if (minutesSinceLastMessage && minutesSinceLastMessage > 30) {
+          heartbeatLogger.warn(
+            logData,
+            "⚠️ web gateway heartbeat - no messages in 30+ minutes",
+          );
+        } else {
+          heartbeatLogger.info(logData, "web gateway heartbeat");
+        }
+      }, heartbeatSeconds * 1000);
+
+      watchdogTimer = setInterval(() => {
+        if (!lastMessageAt) return;
+        const timeSinceLastMessage = Date.now() - lastMessageAt;
+        if (timeSinceLastMessage <= MESSAGE_TIMEOUT_MS) return;
+        const minutesSinceLastMessage = Math.floor(
+          timeSinceLastMessage / 60000,
+        );
+        heartbeatLogger.warn(
+          {
+            connectionId,
+            minutesSinceLastMessage,
+            lastMessageAt: new Date(lastMessageAt),
+            messagesHandled: handledMessages,
+          },
+          "Message timeout detected - forcing reconnect",
+        );
+        whatsappHeartbeatLog.warn(
+          `No messages received in ${minutesSinceLastMessage}m - restarting connection`,
+        );
+        void closeListener().catch((err) => {
+          logVerbose(`Close listener failed: ${formatError(err)}`);
+        });
+        listener.signalClose?.({
+          status: 499,
+          isLoggedOut: false,
+          error: "watchdog-timeout",
+        });
+      }, WATCHDOG_CHECK_MS);
+    }
+
+    whatsappLog.info("Listening for personal WhatsApp inbound messages.");
+    if (process.stdout.isTTY || process.stderr.isTTY) {
+      whatsappLog.raw("Ctrl+C to stop.");
+    }
+
+    if (!keepAlive) {
+      await closeListener();
+      return;
+    }
+
+    const reason = await Promise.race([
+      listener.onClose?.catch((err) => {
+        reconnectLogger.error(
+          { error: formatError(err) },
+          "listener.onClose rejected",
+        );
+        return { status: 500, isLoggedOut: false, error: err };
+      }) ?? waitForever(),
+      abortPromise ?? waitForever(),
+    ]);
+
+    const uptimeMs = Date.now() - startedAt;
+    if (uptimeMs > heartbeatSeconds * 1000) {
+      reconnectAttempts = 0; // Healthy stretch; reset the backoff.
+    }
+    status.reconnectAttempts = reconnectAttempts;
+    emitStatus();
+
+    if (stopRequested() || sigintStop || reason === "aborted") {
+      await closeListener();
+      break;
+    }
+
+    const statusCode =
+      (typeof reason === "object" && reason && "status" in reason
+        ? (reason as { status?: number }).status
+        : undefined) ?? "unknown";
+    const loggedOut =
+      typeof reason === "object" &&
+      reason &&
+      "isLoggedOut" in reason &&
+      (reason as { isLoggedOut?: boolean }).isLoggedOut;
+
+    const errorStr = formatError(reason);
+    status.connected = false;
+    status.lastEventAt = Date.now();
+    status.lastDisconnect = {
+      at: status.lastEventAt,
+      status: typeof statusCode === "number" ? statusCode : undefined,
+      error: errorStr,
+      loggedOut: Boolean(loggedOut),
+    };
+    status.lastError = errorStr;
+    status.reconnectAttempts = reconnectAttempts;
+    emitStatus();
+
+    reconnectLogger.info(
+      {
+        connectionId,
+        status: statusCode,
+        loggedOut,
+        reconnectAttempts,
+        error: errorStr,
+      },
+      "web reconnect: connection closed",
+    );
+
+    enqueueSystemEvent(
+      `WhatsApp gateway disconnected (status ${statusCode ?? "unknown"})`,
+      { sessionKey: connectRoute.sessionKey },
+    );
+
+    if (loggedOut) {
+      runtime.error(
+        "WhatsApp session logged out. Run `clawdbot channels login --channel web` to relink.",
+      );
+      await closeListener();
+      break;
+    }
+
+    reconnectAttempts += 1;
+    status.reconnectAttempts = reconnectAttempts;
+    emitStatus();
+    if (
+      reconnectPolicy.maxAttempts > 0 &&
+      reconnectAttempts >= reconnectPolicy.maxAttempts
+    ) {
+      reconnectLogger.warn(
+        {
+          connectionId,
+          status: statusCode,
+          reconnectAttempts,
+          maxAttempts: reconnectPolicy.maxAttempts,
+        },
+        "web reconnect: max attempts reached; continuing in degraded mode",
+      );
+      runtime.error(
+        `WhatsApp Web reconnect: max attempts reached (${reconnectAttempts}/${reconnectPolicy.maxAttempts}). Stopping web monitoring.`,
+      );
+      await closeListener();
+      break;
+    }
+
+    const delay = computeBackoff(reconnectPolicy, reconnectAttempts);
+    reconnectLogger.info(
+      {
+        connectionId,
+        status: statusCode,
+        reconnectAttempts,
+        maxAttempts: reconnectPolicy.maxAttempts || "unlimited",
+        delayMs: delay,
+      },
+      "web reconnect: scheduling retry",
+    );
+    runtime.error(
+      `WhatsApp Web connection closed (status ${statusCode}). Retry ${reconnectAttempts}/${reconnectPolicy.maxAttempts || "∞"} in ${formatDurationMs(delay)}… (${errorStr})`,
+    );
+    await closeListener();
+    try {
+      await sleep(delay, abortSignal);
+    } catch {
+      break;
+    }
+  }
+
+  status.running = false;
+  status.connected = false;
+  status.lastEventAt = Date.now();
+  emitStatus();
+
+  process.removeListener("SIGINT", handleSigint);
+}

src/web/auto-reply/monitor/ack-reaction.ts

@@ -0,0 +1,76 @@
+import type { loadConfig } from "../../../config/config.js";
+import { logVerbose } from "../../../globals.js";
+import { sendReactionWhatsApp } from "../../outbound.js";
+import { formatError } from "../../session.js";
+import type { WebInboundMsg } from "../types.js";
+import { resolveGroupActivationFor } from "./group-activation.js";
+
+export function maybeSendAckReaction(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  msg: WebInboundMsg;
+  agentId: string;
+  sessionKey: string;
+  conversationId: string;
+  verbose: boolean;
+  accountId?: string;
+  info: (obj: unknown, msg: string) => void;
+  warn: (obj: unknown, msg: string) => void;
+}) {
+  if (!params.msg.id) return;
+
+  const ackConfig = params.cfg.channels?.whatsapp?.ackReaction;
+  const emoji = (ackConfig?.emoji ?? "").trim();
+  const directEnabled = ackConfig?.direct ?? true;
+  const groupMode = ackConfig?.group ?? "mentions";
+  const conversationIdForCheck = params.msg.conversationId ?? params.msg.from;
+
+  const shouldSendReaction = () => {
+    if (!emoji) return false;
+
+    if (params.msg.chatType === "direct") {
+      return directEnabled;
+    }
+
+    if (params.msg.chatType === "group") {
+      if (groupMode === "never") return false;
+      if (groupMode === "always") return true;
+      if (groupMode === "mentions") {
+        const activation = resolveGroupActivationFor({
+          cfg: params.cfg,
+          agentId: params.agentId,
+          sessionKey: params.sessionKey,
+          conversationId: conversationIdForCheck,
+        });
+        if (activation === "always") return true;
+        return params.msg.wasMentioned === true;
+      }
+    }
+
+    return false;
+  };
+
+  if (!shouldSendReaction()) return;
+
+  params.info(
+    { chatId: params.msg.chatId, messageId: params.msg.id, emoji },
+    "sending ack reaction",
+  );
+  sendReactionWhatsApp(params.msg.chatId, params.msg.id, emoji, {
+    verbose: params.verbose,
+    fromMe: false,
+    participant: params.msg.senderJid,
+    accountId: params.accountId,
+  }).catch((err) => {
+    params.warn(
+      {
+        error: formatError(err),
+        chatId: params.msg.chatId,
+        messageId: params.msg.id,
+      },
+      "failed to send ack reaction",
+    );
+    logVerbose(
+      `WhatsApp ack reaction failed for chat ${params.msg.chatId}: ${formatError(err)}`,
+    );
+  });
+}

src/web/auto-reply/monitor/broadcast.ts

@@ -0,0 +1,111 @@
+import type { loadConfig } from "../../../config/config.js";
+import type { resolveAgentRoute } from "../../../routing/resolve-route.js";
+import { buildAgentSessionKey } from "../../../routing/resolve-route.js";
+import {
+  buildAgentMainSessionKey,
+  DEFAULT_MAIN_KEY,
+  normalizeAgentId,
+} from "../../../routing/session-key.js";
+import { formatError } from "../../session.js";
+import { whatsappInboundLog } from "../loggers.js";
+import type { WebInboundMsg } from "../types.js";
+import type { GroupHistoryEntry } from "./process-message.js";
+
+export async function maybeBroadcastMessage(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  msg: WebInboundMsg;
+  peerId: string;
+  route: ReturnType<typeof resolveAgentRoute>;
+  groupHistoryKey: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  processMessage: (
+    msg: WebInboundMsg,
+    route: ReturnType<typeof resolveAgentRoute>,
+    groupHistoryKey: string,
+    opts?: {
+      groupHistory?: GroupHistoryEntry[];
+      suppressGroupHistoryClear?: boolean;
+    },
+  ) => Promise<boolean>;
+}) {
+  const broadcastAgents = params.cfg.broadcast?.[params.peerId];
+  if (!broadcastAgents || !Array.isArray(broadcastAgents)) return false;
+  if (broadcastAgents.length === 0) return false;
+
+  const strategy = params.cfg.broadcast?.strategy || "parallel";
+  whatsappInboundLog.info(
+    `Broadcasting message to ${broadcastAgents.length} agents (${strategy})`,
+  );
+
+  const agentIds = params.cfg.agents?.list?.map((agent) =>
+    normalizeAgentId(agent.id),
+  );
+  const hasKnownAgents = (agentIds?.length ?? 0) > 0;
+  const groupHistorySnapshot =
+    params.msg.chatType === "group"
+      ? (params.groupHistories.get(params.groupHistoryKey) ?? [])
+      : undefined;
+
+  const processForAgent = async (agentId: string): Promise<boolean> => {
+    const normalizedAgentId = normalizeAgentId(agentId);
+    if (hasKnownAgents && !agentIds?.includes(normalizedAgentId)) {
+      whatsappInboundLog.warn(
+        `Broadcast agent ${agentId} not found in agents.list; skipping`,
+      );
+      return false;
+    }
+    const agentRoute = {
+      ...params.route,
+      agentId: normalizedAgentId,
+      sessionKey: buildAgentSessionKey({
+        agentId: normalizedAgentId,
+        channel: "whatsapp",
+        peer: {
+          kind: params.msg.chatType === "group" ? "group" : "dm",
+          id: params.peerId,
+        },
+      }),
+      mainSessionKey: buildAgentMainSessionKey({
+        agentId: normalizedAgentId,
+        mainKey: DEFAULT_MAIN_KEY,
+      }),
+    };
+
+    try {
+      return await params.processMessage(
+        params.msg,
+        agentRoute,
+        params.groupHistoryKey,
+        {
+          groupHistory: groupHistorySnapshot,
+          suppressGroupHistoryClear: true,
+        },
+      );
+    } catch (err) {
+      whatsappInboundLog.error(
+        `Broadcast agent ${agentId} failed: ${formatError(err)}`,
+      );
+      return false;
+    }
+  };
+
+  let didSendReply = false;
+  if (strategy === "sequential") {
+    for (const agentId of broadcastAgents) {
+      if (await processForAgent(agentId)) didSendReply = true;
+    }
+  } else {
+    const results = await Promise.allSettled(
+      broadcastAgents.map(processForAgent),
+    );
+    didSendReply = results.some(
+      (result) => result.status === "fulfilled" && result.value,
+    );
+  }
+
+  if (params.msg.chatType === "group" && didSendReply) {
+    params.groupHistories.set(params.groupHistoryKey, []);
+  }
+
+  return true;
+}

src/web/auto-reply/monitor/commands.ts

@@ -0,0 +1,29 @@
+export function isStatusCommand(body: string) {
+  const trimmed = body.trim().toLowerCase();
+  if (!trimmed) return false;
+  return (
+    trimmed === "/status" ||
+    trimmed === "status" ||
+    trimmed.startsWith("/status ")
+  );
+}
+
+export function stripMentionsForCommand(
+  text: string,
+  mentionRegexes: RegExp[],
+  selfE164?: string | null,
+) {
+  let result = text;
+  for (const re of mentionRegexes) {
+    result = result.replace(re, " ");
+  }
+  if (selfE164) {
+    // `selfE164` is usually like "+1234"; strip down to digits so we can match "+?1234" safely.
+    const digits = selfE164.replace(/\D/g, "");
+    if (digits) {
+      const pattern = new RegExp(`\\+?${digits}`, "g");
+      result = result.replace(pattern, " ");
+    }
+  }
+  return result.replace(/\s+/g, " ").trim();
+}

src/web/auto-reply/monitor/echo.ts

@@ -0,0 +1,63 @@
+export type EchoTracker = {
+  rememberText: (
+    text: string | undefined,
+    opts: {
+      combinedBody?: string;
+      combinedBodySessionKey?: string;
+      logVerboseMessage?: boolean;
+    },
+  ) => void;
+  has: (key: string) => boolean;
+  forget: (key: string) => void;
+  buildCombinedKey: (params: {
+    sessionKey: string;
+    combinedBody: string;
+  }) => string;
+};
+
+export function createEchoTracker(params: {
+  maxItems?: number;
+  logVerbose?: (msg: string) => void;
+}): EchoTracker {
+  const recentlySent = new Set<string>();
+  const maxItems = Math.max(1, params.maxItems ?? 100);
+
+  const buildCombinedKey = (p: { sessionKey: string; combinedBody: string }) =>
+    `combined:${p.sessionKey}:${p.combinedBody}`;
+
+  const trim = () => {
+    while (recentlySent.size > maxItems) {
+      const firstKey = recentlySent.values().next().value as string | undefined;
+      if (!firstKey) break;
+      recentlySent.delete(firstKey);
+    }
+  };
+
+  const rememberText: EchoTracker["rememberText"] = (text, opts) => {
+    if (!text) return;
+    recentlySent.add(text);
+    if (opts.combinedBody && opts.combinedBodySessionKey) {
+      recentlySent.add(
+        buildCombinedKey({
+          sessionKey: opts.combinedBodySessionKey,
+          combinedBody: opts.combinedBody,
+        }),
+      );
+    }
+    if (opts.logVerboseMessage) {
+      params.logVerbose?.(
+        `Added to echo detection set (size now: ${recentlySent.size}): ${text.substring(0, 50)}...`,
+      );
+    }
+    trim();
+  };
+
+  return {
+    rememberText,
+    has: (key) => recentlySent.has(key),
+    forget: (key) => {
+      recentlySent.delete(key);
+    },
+    buildCombinedKey,
+  };
+}

src/web/auto-reply/monitor/group-activation.ts

@@ -0,0 +1,62 @@
+import { normalizeGroupActivation } from "../../../auto-reply/group-activation.js";
+import type { loadConfig } from "../../../config/config.js";
+import {
+  resolveChannelGroupPolicy,
+  resolveChannelGroupRequireMention,
+} from "../../../config/group-policy.js";
+import {
+  loadSessionStore,
+  resolveGroupSessionKey,
+  resolveStorePath,
+} from "../../../config/sessions.js";
+
+export function resolveGroupPolicyFor(
+  cfg: ReturnType<typeof loadConfig>,
+  conversationId: string,
+) {
+  const groupId = resolveGroupSessionKey({
+    From: conversationId,
+    ChatType: "group",
+    Provider: "whatsapp",
+  })?.id;
+  return resolveChannelGroupPolicy({
+    cfg,
+    channel: "whatsapp",
+    groupId: groupId ?? conversationId,
+  });
+}
+
+export function resolveGroupRequireMentionFor(
+  cfg: ReturnType<typeof loadConfig>,
+  conversationId: string,
+) {
+  const groupId = resolveGroupSessionKey({
+    From: conversationId,
+    ChatType: "group",
+    Provider: "whatsapp",
+  })?.id;
+  return resolveChannelGroupRequireMention({
+    cfg,
+    channel: "whatsapp",
+    groupId: groupId ?? conversationId,
+  });
+}
+
+export function resolveGroupActivationFor(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  agentId: string;
+  sessionKey: string;
+  conversationId: string;
+}) {
+  const storePath = resolveStorePath(params.cfg.session?.store, {
+    agentId: params.agentId,
+  });
+  const store = loadSessionStore(storePath);
+  const entry = store[params.sessionKey];
+  const requireMention = resolveGroupRequireMentionFor(
+    params.cfg,
+    params.conversationId,
+  );
+  const defaultActivation = requireMention === false ? "always" : "mention";
+  return normalizeGroupActivation(entry?.groupActivation) ?? defaultActivation;
+}

src/web/auto-reply/monitor/group-gating.ts

@@ -0,0 +1,125 @@
+import { parseActivationCommand } from "../../../auto-reply/group-activation.js";
+import type { loadConfig } from "../../../config/config.js";
+import { normalizeE164 } from "../../../utils.js";
+import type { MentionConfig } from "../mentions.js";
+import {
+  buildMentionConfig,
+  debugMention,
+  resolveOwnerList,
+} from "../mentions.js";
+import type { WebInboundMsg } from "../types.js";
+import { isStatusCommand, stripMentionsForCommand } from "./commands.js";
+import {
+  resolveGroupActivationFor,
+  resolveGroupPolicyFor,
+} from "./group-activation.js";
+import { noteGroupMember } from "./group-members.js";
+
+export type GroupHistoryEntry = {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  id?: string;
+  senderJid?: string;
+};
+
+function isOwnerSender(baseMentionConfig: MentionConfig, msg: WebInboundMsg) {
+  const sender = normalizeE164(msg.senderE164 ?? "");
+  if (!sender) return false;
+  const owners = resolveOwnerList(baseMentionConfig, msg.selfE164 ?? undefined);
+  return owners.includes(sender);
+}
+
+export function applyGroupGating(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  msg: WebInboundMsg;
+  conversationId: string;
+  groupHistoryKey: string;
+  agentId: string;
+  sessionKey: string;
+  baseMentionConfig: MentionConfig;
+  authDir?: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  groupHistoryLimit: number;
+  groupMemberNames: Map<string, Map<string, string>>;
+  logVerbose: (msg: string) => void;
+  replyLogger: { debug: (obj: unknown, msg: string) => void };
+}) {
+  const groupPolicy = resolveGroupPolicyFor(params.cfg, params.conversationId);
+  if (groupPolicy.allowlistEnabled && !groupPolicy.allowed) {
+    params.logVerbose(
+      `Skipping group message ${params.conversationId} (not in allowlist)`,
+    );
+    return { shouldProcess: false };
+  }
+
+  noteGroupMember(
+    params.groupMemberNames,
+    params.groupHistoryKey,
+    params.msg.senderE164,
+    params.msg.senderName,
+  );
+
+  const mentionConfig = buildMentionConfig(params.cfg, params.agentId);
+  const commandBody = stripMentionsForCommand(
+    params.msg.body,
+    mentionConfig.mentionRegexes,
+    params.msg.selfE164,
+  );
+  const activationCommand = parseActivationCommand(commandBody);
+  const owner = isOwnerSender(params.baseMentionConfig, params.msg);
+  const statusCommand = isStatusCommand(commandBody);
+  const shouldBypassMention =
+    owner && (activationCommand.hasCommand || statusCommand);
+
+  if (activationCommand.hasCommand && !owner) {
+    params.logVerbose(
+      `Ignoring /activation from non-owner in group ${params.conversationId}`,
+    );
+    return { shouldProcess: false };
+  }
+
+  if (!shouldBypassMention) {
+    const history = params.groupHistories.get(params.groupHistoryKey) ?? [];
+    const sender =
+      params.msg.senderName && params.msg.senderE164
+        ? `${params.msg.senderName} (${params.msg.senderE164})`
+        : (params.msg.senderName ?? params.msg.senderE164 ?? "Unknown");
+    history.push({
+      sender,
+      body: params.msg.body,
+      timestamp: params.msg.timestamp,
+      id: params.msg.id,
+      senderJid: params.msg.senderJid,
+    });
+    while (history.length > params.groupHistoryLimit) history.shift();
+    params.groupHistories.set(params.groupHistoryKey, history);
+  }
+
+  const mentionDebug = debugMention(params.msg, mentionConfig, params.authDir);
+  params.replyLogger.debug(
+    {
+      conversationId: params.conversationId,
+      wasMentioned: mentionDebug.wasMentioned,
+      ...mentionDebug.details,
+    },
+    "group mention debug",
+  );
+  const wasMentioned = mentionDebug.wasMentioned;
+  params.msg.wasMentioned = wasMentioned;
+  const activation = resolveGroupActivationFor({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    sessionKey: params.sessionKey,
+    conversationId: params.conversationId,
+  });
+  const requireMention = activation !== "always";
+  if (!shouldBypassMention && requireMention && !wasMentioned) {
+    params.logVerbose(
+      `Group message stored for context (no mention detected) in ${params.conversationId}: ${params.msg.body}`,
+    );
+    return { shouldProcess: false };
+  }
+
+  return { shouldProcess: true };
+}

src/web/auto-reply/monitor/group-members.ts

@@ -0,0 +1,57 @@
+import { normalizeE164 } from "../../../utils.js";
+
+export function noteGroupMember(
+  groupMemberNames: Map<string, Map<string, string>>,
+  conversationId: string,
+  e164?: string,
+  name?: string,
+) {
+  if (!e164 || !name) return;
+  const normalized = normalizeE164(e164);
+  const key = normalized ?? e164;
+  if (!key) return;
+  let roster = groupMemberNames.get(conversationId);
+  if (!roster) {
+    roster = new Map();
+    groupMemberNames.set(conversationId, roster);
+  }
+  roster.set(key, name);
+}
+
+export function formatGroupMembers(params: {
+  participants: string[] | undefined;
+  roster: Map<string, string> | undefined;
+  fallbackE164?: string;
+}) {
+  const { participants, roster, fallbackE164 } = params;
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  if (participants?.length) {
+    for (const entry of participants) {
+      if (!entry) continue;
+      const normalized = normalizeE164(entry) ?? entry;
+      if (!normalized || seen.has(normalized)) continue;
+      seen.add(normalized);
+      ordered.push(normalized);
+    }
+  }
+  if (roster) {
+    for (const entry of roster.keys()) {
+      const normalized = normalizeE164(entry) ?? entry;
+      if (!normalized || seen.has(normalized)) continue;
+      seen.add(normalized);
+      ordered.push(normalized);
+    }
+  }
+  if (ordered.length === 0 && fallbackE164) {
+    const normalized = normalizeE164(fallbackE164) ?? fallbackE164;
+    if (normalized) ordered.push(normalized);
+  }
+  if (ordered.length === 0) return undefined;
+  return ordered
+    .map((entry) => {
+      const name = roster?.get(entry);
+      return name ? `${name} (${entry})` : entry;
+    })
+    .join(", ");
+}

src/web/auto-reply/monitor/last-route.ts

@@ -0,0 +1,53 @@
+import type { loadConfig } from "../../../config/config.js";
+import { resolveStorePath, updateLastRoute } from "../../../config/sessions.js";
+import { formatError } from "../../session.js";
+
+export function trackBackgroundTask(
+  backgroundTasks: Set<Promise<unknown>>,
+  task: Promise<unknown>,
+) {
+  backgroundTasks.add(task);
+  void task.finally(() => {
+    backgroundTasks.delete(task);
+  });
+}
+
+export function updateLastRouteInBackground(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  backgroundTasks: Set<Promise<unknown>>;
+  storeAgentId: string;
+  sessionKey: string;
+  channel: "whatsapp";
+  to: string;
+  accountId?: string;
+  warn: (obj: unknown, msg: string) => void;
+}) {
+  const storePath = resolveStorePath(params.cfg.session?.store, {
+    agentId: params.storeAgentId,
+  });
+  const task = updateLastRoute({
+    storePath,
+    sessionKey: params.sessionKey,
+    channel: params.channel,
+    to: params.to,
+    accountId: params.accountId,
+  }).catch((err) => {
+    params.warn(
+      {
+        error: formatError(err),
+        storePath,
+        sessionKey: params.sessionKey,
+        to: params.to,
+      },
+      "failed updating last route",
+    );
+  });
+  trackBackgroundTask(params.backgroundTasks, task);
+}
+
+export function awaitBackgroundTasks(backgroundTasks: Set<Promise<unknown>>) {
+  if (backgroundTasks.size === 0) return Promise.resolve();
+  return Promise.allSettled(backgroundTasks).then(() => {
+    backgroundTasks.clear();
+  });
+}

src/web/auto-reply/monitor/message-line.ts

@@ -0,0 +1,42 @@
+import { resolveMessagePrefix } from "../../../agents/identity.js";
+import { formatAgentEnvelope } from "../../../auto-reply/envelope.js";
+import type { loadConfig } from "../../../config/config.js";
+import type { WebInboundMsg } from "../types.js";
+
+export function formatReplyContext(msg: WebInboundMsg) {
+  if (!msg.replyToBody) return null;
+  const sender = msg.replyToSender ?? "unknown sender";
+  const idPart = msg.replyToId ? ` id:${msg.replyToId}` : "";
+  return `[Replying to ${sender}${idPart}]\n${msg.replyToBody}\n[/Replying]`;
+}
+
+export function buildInboundLine(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  msg: WebInboundMsg;
+  agentId: string;
+}) {
+  const { cfg, msg, agentId } = params;
+  // WhatsApp inbound prefix: channels.whatsapp.messagePrefix > legacy messages.messagePrefix > identity/defaults
+  const messagePrefix = resolveMessagePrefix(cfg, agentId, {
+    configured: cfg.channels?.whatsapp?.messagePrefix,
+    hasAllowFrom: (cfg.channels?.whatsapp?.allowFrom?.length ?? 0) > 0,
+  });
+  const prefixStr = messagePrefix ? `${messagePrefix} ` : "";
+  const senderLabel =
+    msg.chatType === "group"
+      ? `${msg.senderName ?? msg.senderE164 ?? "Someone"}: `
+      : "";
+  const replyContext = formatReplyContext(msg);
+  const baseLine = `${prefixStr}${senderLabel}${msg.body}${
+    replyContext ? `\n\n${replyContext}` : ""
+  }`;
+
+  // Wrap with standardized envelope for the agent.
+  return formatAgentEnvelope({
+    channel: "WhatsApp",
+    from:
+      msg.chatType === "group" ? msg.from : msg.from?.replace(/^whatsapp:/, ""),
+    timestamp: msg.timestamp,
+    body: baseLine,
+  });
+}

src/web/auto-reply/monitor/on-message.ts

@@ -0,0 +1,153 @@
+import type { getReplyFromConfig } from "../../../auto-reply/reply.js";
+import type { loadConfig } from "../../../config/config.js";
+import { logVerbose } from "../../../globals.js";
+import { resolveAgentRoute } from "../../../routing/resolve-route.js";
+import { buildGroupHistoryKey } from "../../../routing/session-key.js";
+import { normalizeE164 } from "../../../utils.js";
+import type { MentionConfig } from "../mentions.js";
+import type { WebInboundMsg } from "../types.js";
+import { maybeBroadcastMessage } from "./broadcast.js";
+import type { EchoTracker } from "./echo.js";
+import type { GroupHistoryEntry } from "./group-gating.js";
+import { applyGroupGating } from "./group-gating.js";
+import { updateLastRouteInBackground } from "./last-route.js";
+import { resolvePeerId } from "./peer.js";
+import { processMessage } from "./process-message.js";
+
+export function createWebOnMessageHandler(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  verbose: boolean;
+  connectionId: string;
+  maxMediaBytes: number;
+  groupHistoryLimit: number;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  groupMemberNames: Map<string, Map<string, string>>;
+  echoTracker: EchoTracker;
+  backgroundTasks: Set<Promise<unknown>>;
+  replyResolver: typeof getReplyFromConfig;
+  replyLogger: ReturnType<
+    typeof import("../../../logging.js")["getChildLogger"]
+  >;
+  baseMentionConfig: MentionConfig;
+  account: { authDir?: string; accountId?: string };
+}) {
+  const processForRoute = async (
+    msg: WebInboundMsg,
+    route: ReturnType<typeof resolveAgentRoute>,
+    groupHistoryKey: string,
+    opts?: {
+      groupHistory?: GroupHistoryEntry[];
+      suppressGroupHistoryClear?: boolean;
+    },
+  ) =>
+    processMessage({
+      cfg: params.cfg,
+      msg,
+      route,
+      groupHistoryKey,
+      groupHistories: params.groupHistories,
+      groupMemberNames: params.groupMemberNames,
+      connectionId: params.connectionId,
+      verbose: params.verbose,
+      maxMediaBytes: params.maxMediaBytes,
+      replyResolver: params.replyResolver,
+      replyLogger: params.replyLogger,
+      backgroundTasks: params.backgroundTasks,
+      rememberSentText: params.echoTracker.rememberText,
+      echoHas: params.echoTracker.has,
+      echoForget: params.echoTracker.forget,
+      buildCombinedEchoKey: params.echoTracker.buildCombinedKey,
+      groupHistory: opts?.groupHistory,
+      suppressGroupHistoryClear: opts?.suppressGroupHistoryClear,
+    });
+
+  return async (msg: WebInboundMsg) => {
+    const conversationId = msg.conversationId ?? msg.from;
+    const peerId = resolvePeerId(msg);
+    const route = resolveAgentRoute({
+      cfg: params.cfg,
+      channel: "whatsapp",
+      accountId: msg.accountId,
+      peer: {
+        kind: msg.chatType === "group" ? "group" : "dm",
+        id: peerId,
+      },
+    });
+    const groupHistoryKey =
+      msg.chatType === "group"
+        ? buildGroupHistoryKey({
+            channel: "whatsapp",
+            accountId: route.accountId,
+            peerKind: "group",
+            peerId,
+          })
+        : route.sessionKey;
+
+    // Same-phone mode logging retained
+    if (msg.from === msg.to) {
+      logVerbose(`📱 Same-phone mode detected (from === to: ${msg.from})`);
+    }
+
+    // Skip if this is a message we just sent (echo detection)
+    if (params.echoTracker.has(msg.body)) {
+      logVerbose(
+        "Skipping auto-reply: detected echo (message matches recently sent text)",
+      );
+      params.echoTracker.forget(msg.body);
+      return;
+    }
+
+    if (msg.chatType === "group") {
+      updateLastRouteInBackground({
+        cfg: params.cfg,
+        backgroundTasks: params.backgroundTasks,
+        storeAgentId: route.agentId,
+        sessionKey: route.sessionKey,
+        channel: "whatsapp",
+        to: conversationId,
+        accountId: route.accountId,
+        warn: params.replyLogger.warn.bind(params.replyLogger),
+      });
+
+      const gating = applyGroupGating({
+        cfg: params.cfg,
+        msg,
+        conversationId,
+        groupHistoryKey,
+        agentId: route.agentId,
+        sessionKey: route.sessionKey,
+        baseMentionConfig: params.baseMentionConfig,
+        authDir: params.account.authDir,
+        groupHistories: params.groupHistories,
+        groupHistoryLimit: params.groupHistoryLimit,
+        groupMemberNames: params.groupMemberNames,
+        logVerbose,
+        replyLogger: params.replyLogger,
+      });
+      if (!gating.shouldProcess) return;
+    } else {
+      // Ensure `peerId` for DMs is stable and stored as E.164 when possible.
+      if (!msg.senderE164 && peerId && peerId.startsWith("+")) {
+        msg.senderE164 = normalizeE164(peerId) ?? msg.senderE164;
+      }
+    }
+
+    // Broadcast groups: when we'd reply anyway, run multiple agents.
+    // Does not bypass group mention/activation gating above.
+    if (
+      await maybeBroadcastMessage({
+        cfg: params.cfg,
+        msg,
+        peerId,
+        route,
+        groupHistoryKey,
+        groupHistories: params.groupHistories,
+        processMessage: processForRoute,
+      })
+    ) {
+      return;
+    }
+
+    await processForRoute(msg, route, groupHistoryKey);
+  };
+}

src/web/auto-reply/monitor/peer.ts

@@ -0,0 +1,9 @@
+import { jidToE164, normalizeE164 } from "../../../utils.js";
+import type { WebInboundMsg } from "../types.js";
+
+export function resolvePeerId(msg: WebInboundMsg) {
+  if (msg.chatType === "group") return msg.conversationId ?? msg.from;
+  if (msg.senderE164) return normalizeE164(msg.senderE164) ?? msg.senderE164;
+  if (msg.from.includes("@")) return jidToE164(msg.from) ?? msg.from;
+  return normalizeE164(msg.from) ?? msg.from;
+}

src/web/auto-reply/monitor/process-message.ts

@@ -0,0 +1,308 @@
+import { resolveEffectiveMessagesConfig } from "../../../agents/identity.js";
+import { resolveTextChunkLimit } from "../../../auto-reply/chunk.js";
+import { formatAgentEnvelope } from "../../../auto-reply/envelope.js";
+import { buildHistoryContext } from "../../../auto-reply/reply/history.js";
+import { dispatchReplyWithBufferedBlockDispatcher } from "../../../auto-reply/reply/provider-dispatcher.js";
+import type { getReplyFromConfig } from "../../../auto-reply/reply.js";
+import type { ReplyPayload } from "../../../auto-reply/types.js";
+import { toLocationContext } from "../../../channels/location.js";
+import type { loadConfig } from "../../../config/config.js";
+import { logVerbose, shouldLogVerbose } from "../../../globals.js";
+import type { getChildLogger } from "../../../logging.js";
+import type { resolveAgentRoute } from "../../../routing/resolve-route.js";
+import { jidToE164, normalizeE164 } from "../../../utils.js";
+import { newConnectionId } from "../../reconnect.js";
+import { formatError } from "../../session.js";
+import { deliverWebReply } from "../deliver-reply.js";
+import { whatsappInboundLog, whatsappOutboundLog } from "../loggers.js";
+import type { WebInboundMsg } from "../types.js";
+import { elide } from "../util.js";
+import { maybeSendAckReaction } from "./ack-reaction.js";
+import { formatGroupMembers } from "./group-members.js";
+import { updateLastRouteInBackground } from "./last-route.js";
+import { buildInboundLine } from "./message-line.js";
+
+export type GroupHistoryEntry = {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  id?: string;
+  senderJid?: string;
+};
+
+export async function processMessage(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  msg: WebInboundMsg;
+  route: ReturnType<typeof resolveAgentRoute>;
+  groupHistoryKey: string;
+  groupHistories: Map<string, GroupHistoryEntry[]>;
+  groupMemberNames: Map<string, Map<string, string>>;
+  connectionId: string;
+  verbose: boolean;
+  maxMediaBytes: number;
+  replyResolver: typeof getReplyFromConfig;
+  replyLogger: ReturnType<typeof getChildLogger>;
+  backgroundTasks: Set<Promise<unknown>>;
+  rememberSentText: (
+    text: string | undefined,
+    opts: {
+      combinedBody?: string;
+      combinedBodySessionKey?: string;
+      logVerboseMessage?: boolean;
+    },
+  ) => void;
+  echoHas: (key: string) => boolean;
+  echoForget: (key: string) => void;
+  buildCombinedEchoKey: (p: {
+    sessionKey: string;
+    combinedBody: string;
+  }) => string;
+  maxMediaTextChunkLimit?: number;
+  groupHistory?: GroupHistoryEntry[];
+  suppressGroupHistoryClear?: boolean;
+}) {
+  const conversationId = params.msg.conversationId ?? params.msg.from;
+  let combinedBody = buildInboundLine({
+    cfg: params.cfg,
+    msg: params.msg,
+    agentId: params.route.agentId,
+  });
+  let shouldClearGroupHistory = false;
+
+  if (params.msg.chatType === "group") {
+    const history =
+      params.groupHistory ??
+      params.groupHistories.get(params.groupHistoryKey) ??
+      [];
+    const historyWithoutCurrent =
+      history.length > 0 ? history.slice(0, -1) : [];
+    if (historyWithoutCurrent.length > 0) {
+      const lineBreak = "\\n";
+      const historyText = historyWithoutCurrent
+        .map((m) => {
+          const bodyWithId = m.id ? `${m.body}\n[message_id: ${m.id}]` : m.body;
+          return formatAgentEnvelope({
+            channel: "WhatsApp",
+            from: conversationId,
+            timestamp: m.timestamp,
+            body: `${m.sender}: ${bodyWithId}`,
+          });
+        })
+        .join(lineBreak);
+      combinedBody = buildHistoryContext({
+        historyText,
+        currentMessage: combinedBody,
+        lineBreak,
+      });
+    }
+    // Always surface who sent the triggering message so the agent can address them.
+    const senderLabel =
+      params.msg.senderName && params.msg.senderE164
+        ? `${params.msg.senderName} (${params.msg.senderE164})`
+        : (params.msg.senderName ?? params.msg.senderE164 ?? "Unknown");
+    combinedBody = `${combinedBody}\\n[from: ${senderLabel}]`;
+    shouldClearGroupHistory = !(params.suppressGroupHistoryClear ?? false);
+  }
+
+  // Echo detection uses combined body so we don't respond twice.
+  const combinedEchoKey = params.buildCombinedEchoKey({
+    sessionKey: params.route.sessionKey,
+    combinedBody,
+  });
+  if (params.echoHas(combinedEchoKey)) {
+    logVerbose("Skipping auto-reply: detected echo for combined message");
+    params.echoForget(combinedEchoKey);
+    return false;
+  }
+
+  // Send ack reaction immediately upon message receipt (post-gating)
+  maybeSendAckReaction({
+    cfg: params.cfg,
+    msg: params.msg,
+    agentId: params.route.agentId,
+    sessionKey: params.route.sessionKey,
+    conversationId,
+    verbose: params.verbose,
+    accountId: params.route.accountId,
+    info: params.replyLogger.info.bind(params.replyLogger),
+    warn: params.replyLogger.warn.bind(params.replyLogger),
+  });
+
+  const correlationId = params.msg.id ?? newConnectionId();
+  params.replyLogger.info(
+    {
+      connectionId: params.connectionId,
+      correlationId,
+      from: params.msg.chatType === "group" ? conversationId : params.msg.from,
+      to: params.msg.to,
+      body: elide(combinedBody, 240),
+      mediaType: params.msg.mediaType ?? null,
+      mediaPath: params.msg.mediaPath ?? null,
+    },
+    "inbound web message",
+  );
+
+  const fromDisplay =
+    params.msg.chatType === "group" ? conversationId : params.msg.from;
+  const kindLabel = params.msg.mediaType ? `, ${params.msg.mediaType}` : "";
+  whatsappInboundLog.info(
+    `Inbound message ${fromDisplay} -> ${params.msg.to} (${params.msg.chatType}${kindLabel}, ${combinedBody.length} chars)`,
+  );
+  if (shouldLogVerbose()) {
+    whatsappInboundLog.debug(`Inbound body: ${elide(combinedBody, 400)}`);
+  }
+
+  if (params.msg.chatType !== "group") {
+    const to = (() => {
+      if (params.msg.senderE164) return normalizeE164(params.msg.senderE164);
+      // In direct chats, `msg.from` is already the canonical conversation id.
+      if (params.msg.from.includes("@")) return jidToE164(params.msg.from);
+      return normalizeE164(params.msg.from);
+    })();
+    if (to) {
+      updateLastRouteInBackground({
+        cfg: params.cfg,
+        backgroundTasks: params.backgroundTasks,
+        storeAgentId: params.route.agentId,
+        sessionKey: params.route.mainSessionKey,
+        channel: "whatsapp",
+        to,
+        accountId: params.route.accountId,
+        warn: params.replyLogger.warn.bind(params.replyLogger),
+      });
+    }
+  }
+
+  const textLimit =
+    params.maxMediaTextChunkLimit ??
+    resolveTextChunkLimit(params.cfg, "whatsapp");
+  let didLogHeartbeatStrip = false;
+  let didSendReply = false;
+  const responsePrefix = resolveEffectiveMessagesConfig(
+    params.cfg,
+    params.route.agentId,
+  ).responsePrefix;
+
+  const { queuedFinal } = await dispatchReplyWithBufferedBlockDispatcher({
+    ctx: {
+      Body: combinedBody,
+      RawBody: params.msg.body,
+      CommandBody: params.msg.body,
+      From: params.msg.from,
+      To: params.msg.to,
+      SessionKey: params.route.sessionKey,
+      AccountId: params.route.accountId,
+      MessageSid: params.msg.id,
+      ReplyToId: params.msg.replyToId,
+      ReplyToBody: params.msg.replyToBody,
+      ReplyToSender: params.msg.replyToSender,
+      MediaPath: params.msg.mediaPath,
+      MediaUrl: params.msg.mediaUrl,
+      MediaType: params.msg.mediaType,
+      ChatType: params.msg.chatType,
+      GroupSubject: params.msg.groupSubject,
+      GroupMembers: formatGroupMembers({
+        participants: params.msg.groupParticipants,
+        roster: params.groupMemberNames.get(params.groupHistoryKey),
+        fallbackE164: params.msg.senderE164,
+      }),
+      SenderName: params.msg.senderName,
+      SenderId: params.msg.senderJid?.trim() || params.msg.senderE164,
+      SenderE164: params.msg.senderE164,
+      WasMentioned: params.msg.wasMentioned,
+      ...(params.msg.location ? toLocationContext(params.msg.location) : {}),
+      Provider: "whatsapp",
+      Surface: "whatsapp",
+      OriginatingChannel: "whatsapp",
+      OriginatingTo: params.msg.from,
+    },
+    cfg: params.cfg,
+    replyResolver: params.replyResolver,
+    dispatcherOptions: {
+      responsePrefix,
+      onHeartbeatStrip: () => {
+        if (!didLogHeartbeatStrip) {
+          didLogHeartbeatStrip = true;
+          logVerbose("Stripped stray HEARTBEAT_OK token from web reply");
+        }
+      },
+      deliver: async (payload: ReplyPayload, info) => {
+        await deliverWebReply({
+          replyResult: payload,
+          msg: params.msg,
+          maxMediaBytes: params.maxMediaBytes,
+          textLimit,
+          replyLogger: params.replyLogger,
+          connectionId: params.connectionId,
+          // Tool + block updates are noisy; skip their log lines.
+          skipLog: info.kind !== "final",
+        });
+        didSendReply = true;
+        if (info.kind === "tool") {
+          params.rememberSentText(payload.text, {});
+          return;
+        }
+        const shouldLog =
+          info.kind === "final" && payload.text ? true : undefined;
+        params.rememberSentText(payload.text, {
+          combinedBody,
+          combinedBodySessionKey: params.route.sessionKey,
+          logVerboseMessage: shouldLog,
+        });
+        if (info.kind === "final") {
+          const fromDisplay =
+            params.msg.chatType === "group"
+              ? conversationId
+              : (params.msg.from ?? "unknown");
+          const hasMedia = Boolean(
+            payload.mediaUrl || payload.mediaUrls?.length,
+          );
+          whatsappOutboundLog.info(
+            `Auto-replied to ${fromDisplay}${hasMedia ? " (media)" : ""}`,
+          );
+          if (shouldLogVerbose()) {
+            const preview =
+              payload.text != null ? elide(payload.text, 400) : "<media>";
+            whatsappOutboundLog.debug(
+              `Reply body: ${preview}${hasMedia ? " (media)" : ""}`,
+            );
+          }
+        }
+      },
+      onError: (err, info) => {
+        const label =
+          info.kind === "tool"
+            ? "tool update"
+            : info.kind === "block"
+              ? "block update"
+              : "auto-reply";
+        whatsappOutboundLog.error(
+          `Failed sending web ${label} to ${params.msg.from ?? conversationId}: ${formatError(err)}`,
+        );
+      },
+      onReplyStart: params.msg.sendComposing,
+    },
+    replyOptions: {
+      disableBlockStreaming:
+        typeof params.cfg.channels?.whatsapp?.blockStreaming === "boolean"
+          ? !params.cfg.channels.whatsapp.blockStreaming
+          : undefined,
+    },
+  });
+
+  if (!queuedFinal) {
+    if (shouldClearGroupHistory && didSendReply) {
+      params.groupHistories.set(params.groupHistoryKey, []);
+    }
+    logVerbose(
+      "Skipping auto-reply: silent token or no text/media returned from resolver",
+    );
+    return false;
+  }
+
+  if (shouldClearGroupHistory && didSendReply) {
+    params.groupHistories.set(params.groupHistoryKey, []);
+  }
+
+  return didSendReply;
+}

src/web/auto-reply/session-snapshot.ts

@@ -0,0 +1,34 @@
+import type { loadConfig } from "../../config/config.js";
+import {
+  DEFAULT_IDLE_MINUTES,
+  loadSessionStore,
+  resolveSessionKey,
+  resolveStorePath,
+} from "../../config/sessions.js";
+import { normalizeMainKey } from "../../routing/session-key.js";
+
+export function getSessionSnapshot(
+  cfg: ReturnType<typeof loadConfig>,
+  from: string,
+  isHeartbeat = false,
+) {
+  const sessionCfg = cfg.session;
+  const scope = sessionCfg?.scope ?? "per-sender";
+  const key = resolveSessionKey(
+    scope,
+    { From: from, To: "", Body: "" },
+    normalizeMainKey(sessionCfg?.mainKey),
+  );
+  const store = loadSessionStore(resolveStorePath(sessionCfg?.store));
+  const entry = store[key];
+  const idleMinutes = Math.max(
+    (isHeartbeat
+      ? (sessionCfg?.heartbeatIdleMinutes ?? sessionCfg?.idleMinutes)
+      : sessionCfg?.idleMinutes) ?? DEFAULT_IDLE_MINUTES,
+    1,
+  );
+  const fresh = !!(
+    entry && Date.now() - entry.updatedAt <= idleMinutes * 60_000
+  );
+  return { key, entry, fresh, idleMinutes };
+}

src/web/auto-reply/types.ts

@@ -0,0 +1,33 @@
+import type { monitorWebInbox } from "../inbound.js";
+import type { ReconnectPolicy } from "../reconnect.js";
+
+export type WebInboundMsg = Parameters<
+  typeof monitorWebInbox
+>[0]["onMessage"] extends (msg: infer M) => unknown
+  ? M
+  : never;
+
+export type WebChannelStatus = {
+  running: boolean;
+  connected: boolean;
+  reconnectAttempts: number;
+  lastConnectedAt?: number | null;
+  lastDisconnect?: {
+    at: number;
+    status?: number;
+    error?: string;
+    loggedOut?: boolean;
+  } | null;
+  lastMessageAt?: number | null;
+  lastEventAt?: number | null;
+  lastError?: string | null;
+};
+
+export type WebMonitorTuning = {
+  reconnect?: Partial<ReconnectPolicy>;
+  heartbeatSeconds?: number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  statusSink?: (status: WebChannelStatus) => void;
+  /** WhatsApp account id. Default: "default". */
+  accountId?: string;
+};

src/web/auto-reply/util.ts

@@ -0,0 +1,44 @@
+export function elide(text?: string, limit = 400) {
+  if (!text) return text;
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit)}… (truncated ${text.length - limit} chars)`;
+}
+
+export function isLikelyWhatsAppCryptoError(reason: unknown) {
+  const formatReason = (value: unknown): string => {
+    if (value == null) return "";
+    if (typeof value === "string") return value;
+    if (value instanceof Error) {
+      return `${value.message}\n${value.stack ?? ""}`;
+    }
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return Object.prototype.toString.call(value);
+      }
+    }
+    if (typeof value === "number") return String(value);
+    if (typeof value === "boolean") return String(value);
+    if (typeof value === "bigint") return String(value);
+    if (typeof value === "symbol") return value.description ?? value.toString();
+    if (typeof value === "function")
+      return value.name ? `[function ${value.name}]` : "[function]";
+    return Object.prototype.toString.call(value);
+  };
+  const raw =
+    reason instanceof Error
+      ? `${reason.message}\n${reason.stack ?? ""}`
+      : formatReason(reason);
+  const haystack = raw.toLowerCase();
+  const hasAuthError =
+    haystack.includes("unsupported state or unable to authenticate data") ||
+    haystack.includes("bad mac");
+  if (!hasAuthError) return false;
+  return (
+    haystack.includes("@whiskeysockets/baileys") ||
+    haystack.includes("baileys") ||
+    haystack.includes("noise-handler") ||
+    haystack.includes("aesdecryptgcm")
+  );
+}