feat(whatsapp): add debounceMs for batching rapid messages (#971)

* feat(whatsapp): add debounceMs for batching rapid messages

Add a `debounceMs` configuration option to WhatsApp channel settings
that batches rapid consecutive messages from the same sender into a
single response. This prevents triggering separate agent runs for
each message when a user sends multiple short messages in quick
succession (e.g., "Hey!", "how are you?", "I was wondering...").

Changes:
- Add `debounceMs` config to WhatsAppConfig and WhatsAppAccountConfig
- Implement message buffering in `monitorWebInbox` with:
  - Map-based buffer keyed by sender (DM) or chat ID (groups)
  - Debounce timer that resets on each new message
  - Message combination with newline separator
  - Single message optimization (no modification if only one message)
- Wire `debounceMs` through account resolution and monitor tuning
- Add UI hints and schema documentation

Usage example:
{
  "channels": {
    "whatsapp": {
      "debounceMs": 5000  // 5 second window
    }
  }
}

Default behavior: `debounceMs: 0` (disabled by default)

Verified: All existing tests pass (3204 tests), TypeScript compilation
succeeds with no errors.

Implemented with assistance from AI coding tools.

Closes #967

* chore: wip inbound debounce

* fix: debounce inbound messages across channels (#971) (thanks @juanpablodlc)

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>

src/auto-reply/inbound-debounce.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createInboundDebouncer } from "./inbound-debounce.js";
+
+describe("createInboundDebouncer", () => {
+  it("debounces and combines items", async () => {
+    vi.useFakeTimers();
+    const calls: Array<string[]> = [];
+
+    const debouncer = createInboundDebouncer<{ key: string; id: string }>({
+      debounceMs: 10,
+      buildKey: (item) => item.key,
+      onFlush: async (items) => {
+        calls.push(items.map((entry) => entry.id));
+      },
+    });
+
+    await debouncer.enqueue({ key: "a", id: "1" });
+    await debouncer.enqueue({ key: "a", id: "2" });
+
+    expect(calls).toEqual([]);
+    await vi.advanceTimersByTimeAsync(10);
+    expect(calls).toEqual([["1", "2"]]);
+
+    vi.useRealTimers();
+  });
+
+  it("flushes buffered items before non-debounced item", async () => {
+    vi.useFakeTimers();
+    const calls: Array<string[]> = [];
+
+    const debouncer = createInboundDebouncer<{ key: string; id: string; debounce: boolean }>({
+      debounceMs: 50,
+      buildKey: (item) => item.key,
+      shouldDebounce: (item) => item.debounce,
+      onFlush: async (items) => {
+        calls.push(items.map((entry) => entry.id));
+      },
+    });
+
+    await debouncer.enqueue({ key: "a", id: "1", debounce: true });
+    await debouncer.enqueue({ key: "a", id: "2", debounce: false });
+
+    expect(calls).toEqual([["1"], ["2"]]);
+
+    vi.useRealTimers();
+  });
+});

src/auto-reply/inbound-debounce.ts

@@ -0,0 +1,101 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import type { InboundDebounceByProvider } from "../config/types.messages.js";
+
+const resolveMs = (value: unknown): number | undefined => {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.max(0, Math.trunc(value));
+};
+
+const resolveChannelOverride = (params: {
+  byChannel?: InboundDebounceByProvider;
+  channel: string;
+}): number | undefined => {
+  if (!params.byChannel) return undefined;
+  const channelKey = params.channel as keyof InboundDebounceByProvider;
+  return resolveMs(params.byChannel[channelKey]);
+};
+
+export function resolveInboundDebounceMs(params: {
+  cfg: ClawdbotConfig;
+  channel: string;
+  overrideMs?: number;
+}): number {
+  const inbound = params.cfg.messages?.inbound;
+  const override = resolveMs(params.overrideMs);
+  const byChannel = resolveChannelOverride({
+    byChannel: inbound?.byChannel,
+    channel: params.channel,
+  });
+  const base = resolveMs(inbound?.debounceMs);
+  return override ?? byChannel ?? base ?? 0;
+}
+
+type DebounceBuffer<T> = {
+  items: T[];
+  timeout: ReturnType<typeof setTimeout> | null;
+};
+
+export function createInboundDebouncer<T>(params: {
+  debounceMs: number;
+  buildKey: (item: T) => string | null | undefined;
+  shouldDebounce?: (item: T) => boolean;
+  onFlush: (items: T[]) => Promise<void>;
+  onError?: (err: unknown, items: T[]) => void;
+}) {
+  const buffers = new Map<string, DebounceBuffer<T>>();
+  const debounceMs = Math.max(0, Math.trunc(params.debounceMs));
+
+  const flushBuffer = async (key: string, buffer: DebounceBuffer<T>) => {
+    buffers.delete(key);
+    if (buffer.timeout) {
+      clearTimeout(buffer.timeout);
+      buffer.timeout = null;
+    }
+    if (buffer.items.length === 0) return;
+    try {
+      await params.onFlush(buffer.items);
+    } catch (err) {
+      params.onError?.(err, buffer.items);
+    }
+  };
+
+  const flushKey = async (key: string) => {
+    const buffer = buffers.get(key);
+    if (!buffer) return;
+    await flushBuffer(key, buffer);
+  };
+
+  const scheduleFlush = (key: string, buffer: DebounceBuffer<T>) => {
+    if (buffer.timeout) clearTimeout(buffer.timeout);
+    buffer.timeout = setTimeout(() => {
+      void flushBuffer(key, buffer);
+    }, debounceMs);
+    buffer.timeout.unref?.();
+  };
+
+  const enqueue = async (item: T) => {
+    const key = params.buildKey(item);
+    const canDebounce = debounceMs > 0 && (params.shouldDebounce?.(item) ?? true);
+
+    if (!canDebounce || !key) {
+      if (key && buffers.has(key)) {
+        await flushKey(key);
+      }
+      await params.onFlush([item]);
+      return;
+    }
+
+    const existing = buffers.get(key);
+    if (existing) {
+      existing.items.push(item);
+      scheduleFlush(key, existing);
+      return;
+    }
+
+    const buffer: DebounceBuffer<T> = { items: [item], timeout: null };
+    buffers.set(key, buffer);
+    scheduleFlush(key, buffer);
+  };
+
+  return { enqueue, flushKey };
+}

src/auto-reply/reply.triggers.trigger-handling.shows-quick-model-picker-grouped-by-model.test.ts

@@ -263,9 +263,7 @@ describe("trigger handling", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       // Selecting the default model shows "reset to default" instead of "set to"
-      expect(normalizeTestText(text ?? "")).toContain(
-        "anthropic/claude-opus-4-5",
-      );
+      expect(normalizeTestText(text ?? "")).toContain("anthropic/claude-opus-4-5");
 
       const store = loadSessionStore(cfg.session.store);
       // When selecting the default, overrides are cleared

src/auto-reply/templating.ts

@@ -24,6 +24,9 @@ export type MsgContext = {
   AccountId?: string;
   ParentSessionKey?: string;
   MessageSid?: string;
+  MessageSids?: string[];
+  MessageSidFirst?: string;
+  MessageSidLast?: string;
   ReplyToId?: string;
   ReplyToBody?: string;
   ReplyToSender?: string;