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/imessage/monitor/monitor-provider.ts

@@ -10,6 +10,10 @@ import {
 import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
 import { formatAgentEnvelope } from "../../auto-reply/envelope.js";
+import {
+  createInboundDebouncer,
+  resolveInboundDebounceMs,
+} from "../../auto-reply/inbound-debounce.js";
 import { dispatchReplyFromConfig } from "../../auto-reply/reply/dispatch-from-config.js";
 import {
   buildHistoryContextFromMap,
@@ -73,11 +77,48 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
   const includeAttachments = opts.includeAttachments ?? imessageCfg.includeAttachments ?? false;
   const mediaMaxBytes = (opts.mediaMaxMb ?? imessageCfg.mediaMaxMb ?? 16) * 1024 * 1024;
 
-  const handleMessage = async (raw: unknown) => {
-    const params = raw as { message?: IMessagePayload | null };
-    const message = params?.message ?? null;
-    if (!message) return;
+  const inboundDebounceMs = resolveInboundDebounceMs({ cfg, channel: "imessage" });
+  const inboundDebouncer = createInboundDebouncer<{ message: IMessagePayload }>({
+    debounceMs: inboundDebounceMs,
+    buildKey: (entry) => {
+      const sender = entry.message.sender?.trim();
+      if (!sender) return null;
+      const conversationId =
+        entry.message.chat_id != null
+          ? `chat:${entry.message.chat_id}`
+          : (entry.message.chat_guid ?? entry.message.chat_identifier ?? "unknown");
+      return `imessage:${accountInfo.accountId}:${conversationId}:${sender}`;
+    },
+    shouldDebounce: (entry) => {
+      const text = entry.message.text?.trim() ?? "";
+      if (!text) return false;
+      if (entry.message.attachments && entry.message.attachments.length > 0) return false;
+      return !hasControlCommand(text, cfg);
+    },
+    onFlush: async (entries) => {
+      const last = entries.at(-1);
+      if (!last) return;
+      if (entries.length === 1) {
+        await handleMessageNow(last.message);
+        return;
+      }
+      const combinedText = entries
+        .map((entry) => entry.message.text ?? "")
+        .filter(Boolean)
+        .join("\n");
+      const syntheticMessage: IMessagePayload = {
+        ...last.message,
+        text: combinedText,
+        attachments: null,
+      };
+      await handleMessageNow(syntheticMessage);
+    },
+    onError: (err) => {
+      runtime.error?.(`imessage debounce flush failed: ${String(err)}`);
+    },
+  });
 
+  async function handleMessageNow(message: IMessagePayload) {
     const senderRaw = message.sender ?? "";
     const sender = senderRaw.trim();
     if (!sender) return;
@@ -403,6 +444,13 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     if (isGroup && historyKey && historyLimit > 0 && didSendReply) {
       clearHistoryEntries({ historyMap: groupHistories, historyKey });
     }
+  }
+
+  const handleMessage = async (raw: unknown) => {
+    const params = raw as { message?: IMessagePayload | null };
+    const message = params?.message ?? null;
+    if (!message) return;
+    await inboundDebouncer.enqueue({ message });
   };
 
   const client = await createIMessageRpcClient({