@gguf/pigbot 0.0.1 → 0.0.3

package/extensions/bluebubbles/src/monitor.test.ts

@@ -2,8 +2,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { EventEmitter } from "node:events";
 
-import { removeAckReactionAfterReply, shouldAckReaction } from "pigbot/plugin-sdk";
-import type { PigbotConfig, PluginRuntime } from "pigbot/plugin-sdk";
+import { removeAckReactionAfterReply, shouldAckReaction } from "clawdbot/plugin-sdk";
+import type { MoltbotConfig, PluginRuntime } from "clawdbot/plugin-sdk";
 import {
   handleBlueBubblesWebhookRequest,
   registerBlueBubblesWebhookTarget,
@@ -146,8 +146,14 @@ function createMockRuntime(): PluginRuntime {
         resolveRequireMention: mockResolveRequireMention as unknown as PluginRuntime["channel"]["groups"]["resolveRequireMention"],
       },
       debounce: {
-        createInboundDebouncer: vi.fn() as unknown as PluginRuntime["channel"]["debounce"]["createInboundDebouncer"],
-        resolveInboundDebounceMs: vi.fn() as unknown as PluginRuntime["channel"]["debounce"]["resolveInboundDebounceMs"],
+        // Create a pass-through debouncer that immediately calls onFlush
+        createInboundDebouncer: vi.fn((params: { onFlush: (items: unknown[]) => Promise<void> }) => ({
+          enqueue: async (item: unknown) => {
+            await params.onFlush([item]);
+          },
+          flushKey: vi.fn(),
+        })) as unknown as PluginRuntime["channel"]["debounce"]["createInboundDebouncer"],
+        resolveInboundDebounceMs: vi.fn(() => 0) as unknown as PluginRuntime["channel"]["debounce"]["resolveInboundDebounceMs"],
       },
       commands: {
         resolveCommandAuthorizedFromAuthorizers: mockResolveCommandAuthorizedFromAuthorizers as unknown as PluginRuntime["channel"]["commands"]["resolveCommandAuthorizedFromAuthorizers"],
@@ -172,7 +178,7 @@ function createMockRuntime(): PluginRuntime {
       })) as unknown as PluginRuntime["logging"]["getChildLogger"],
     },
     state: {
-      resolveStateDir: vi.fn(() => "/tmp/pigbot") as unknown as PluginRuntime["state"]["resolveStateDir"],
+      resolveStateDir: vi.fn(() => "/tmp/moltbot") as unknown as PluginRuntime["state"]["resolveStateDir"],
     },
   };
 }
@@ -258,7 +264,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("webhook parsing + auth handling", () => {
     it("rejects non-POST requests", async () => {
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -281,7 +287,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("accepts POST requests with valid JSON payload", async () => {
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -317,7 +323,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("rejects requests with invalid JSON", async () => {
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -340,7 +346,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("authenticates via password query parameter", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -374,7 +380,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("authenticates via x-password header", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -412,7 +418,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("rejects unauthorized requests with wrong password", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -445,7 +451,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("allows localhost requests without authentication", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -491,7 +497,7 @@ describe("BlueBubbles webhook monitor", () => {
       vi.mocked(resolveChatGuidForTarget).mockClear();
 
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -539,7 +545,7 @@ describe("BlueBubbles webhook monitor", () => {
       });
 
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -585,7 +591,7 @@ describe("BlueBubbles webhook monitor", () => {
         dmPolicy: "allowlist",
         allowFrom: ["+15551234567"],
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -626,7 +632,7 @@ describe("BlueBubbles webhook monitor", () => {
         dmPolicy: "allowlist",
         allowFrom: ["+15559999999"], // Different number
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -667,7 +673,7 @@ describe("BlueBubbles webhook monitor", () => {
         dmPolicy: "pairing",
         allowFrom: ["+15559999999"], // Different number than sender
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -710,7 +716,7 @@ describe("BlueBubbles webhook monitor", () => {
         dmPolicy: "pairing",
         allowFrom: ["+15559999999"], // Different number than sender
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -751,7 +757,7 @@ describe("BlueBubbles webhook monitor", () => {
         dmPolicy: "open",
         allowFrom: [],
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -788,7 +794,7 @@ describe("BlueBubbles webhook monitor", () => {
       const account = createMockAccount({
         dmPolicy: "disabled",
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -827,7 +833,7 @@ describe("BlueBubbles webhook monitor", () => {
       const account = createMockAccount({
         groupPolicy: "open",
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -865,7 +871,7 @@ describe("BlueBubbles webhook monitor", () => {
       const account = createMockAccount({
         groupPolicy: "disabled",
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -904,7 +910,7 @@ describe("BlueBubbles webhook monitor", () => {
         groupPolicy: "allowlist",
         dmPolicy: "open",
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -943,7 +949,7 @@ describe("BlueBubbles webhook monitor", () => {
         groupPolicy: "allowlist",
         groupAllowFrom: ["chat_guid:iMessage;+;chat123456"],
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -984,7 +990,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockMatchesMentionPatterns.mockReturnValue(true);
 
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1025,7 +1031,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockMatchesMentionPatterns.mockReturnValue(false);
 
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1063,7 +1069,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockResolveRequireMention.mockReturnValue(false);
 
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1101,7 +1107,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("group metadata", () => {
     it("includes group subject + members in ctx", async () => {
       const account = createMockAccount({ groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1147,7 +1153,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("reply metadata", () => {
     it("surfaces reply fields in ctx when provided", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1195,7 +1201,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("preserves part index prefixes in reply tags when short IDs are unavailable", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1240,7 +1246,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("hydrates missing reply sender/body from the recent-message cache", async () => {
       const account = createMockAccount({ dmPolicy: "open", groupPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1310,7 +1316,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("falls back to threadOriginatorGuid when reply metadata is absent", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1351,7 +1357,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("tapback text parsing", () => {
     it("does not rewrite tapback-like text without metadata", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1391,7 +1397,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("parses tapback text with custom emoji when metadata is present", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1436,7 +1442,7 @@ describe("BlueBubbles webhook monitor", () => {
       vi.mocked(sendBlueBubblesReaction).mockClear();
 
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {
+      const config: MoltbotConfig = {
         messages: {
           ackReaction: "❤️",
           ackReactionScope: "direct",
@@ -1494,7 +1500,7 @@ describe("BlueBubbles webhook monitor", () => {
         groupPolicy: "open",
         allowFrom: ["+15551234567"],
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1537,7 +1543,7 @@ describe("BlueBubbles webhook monitor", () => {
         groupPolicy: "open",
         allowFrom: [], // No one authorized
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1580,7 +1586,7 @@ describe("BlueBubbles webhook monitor", () => {
       const account = createMockAccount({
         sendReadReceipts: true,
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1621,7 +1627,7 @@ describe("BlueBubbles webhook monitor", () => {
       const account = createMockAccount({
         sendReadReceipts: false,
       });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1660,7 +1666,7 @@ describe("BlueBubbles webhook monitor", () => {
       vi.mocked(sendBlueBubblesTyping).mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1708,7 +1714,7 @@ describe("BlueBubbles webhook monitor", () => {
       vi.mocked(sendBlueBubblesTyping).mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1757,7 +1763,7 @@ describe("BlueBubbles webhook monitor", () => {
       vi.mocked(sendBlueBubblesTyping).mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1807,7 +1813,7 @@ describe("BlueBubbles webhook monitor", () => {
       });
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1853,7 +1859,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockEnqueueSystemEvent.mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1893,7 +1899,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockEnqueueSystemEvent.mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1933,7 +1939,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockEnqueueSystemEvent.mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -1970,7 +1976,7 @@ describe("BlueBubbles webhook monitor", () => {
       mockEnqueueSystemEvent.mockClear();
 
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -2011,7 +2017,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("short message ID mapping", () => {
     it("assigns sequential short IDs to messages", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -2051,7 +2057,7 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("resolves short ID back to UUID", async () => {
       const account = createMockAccount({ dmPolicy: "open" });
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
@@ -2104,7 +2110,7 @@ describe("BlueBubbles webhook monitor", () => {
   describe("fromMe messages", () => {
     it("ignores messages from self (fromMe=true)", async () => {
       const account = createMockAccount();
-      const config: PigbotConfig = {};
+      const config: MoltbotConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 

package/extensions/bluebubbles/src/monitor.ts

@@ -1,13 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 
-import type { PigbotConfig } from "pigbot/plugin-sdk";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
 import {
   logAckFailure,
   logInboundDrop,
   logTypingFailure,
   resolveAckReaction,
   resolveControlCommandGate,
-} from "pigbot/plugin-sdk";
+} from "clawdbot/plugin-sdk";
 import { markBlueBubblesChatRead, sendBlueBubblesTyping } from "./chat.js";
 import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import { downloadBlueBubblesAttachment } from "./attachments.js";
@@ -26,7 +26,7 @@ export type BlueBubblesRuntimeEnv = {
 
 export type BlueBubblesMonitorOptions = {
   account: ResolvedBlueBubblesAccount;
-  config: PigbotConfig;
+  config: MoltbotConfig;
   runtime: BlueBubblesRuntimeEnv;
   abortSignal: AbortSignal;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
@@ -243,15 +243,185 @@ function logGroupAllowlistHint(params: {
 
 type WebhookTarget = {
   account: ResolvedBlueBubblesAccount;
-  config: PigbotConfig;
+  config: MoltbotConfig;
   runtime: BlueBubblesRuntimeEnv;
   core: BlueBubblesCoreRuntime;
   path: string;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
 };
 
+/**
+ * Entry type for debouncing inbound messages.
+ * Captures the normalized message and its target for later combined processing.
+ */
+type BlueBubblesDebounceEntry = {
+  message: NormalizedWebhookMessage;
+  target: WebhookTarget;
+};
+
+/**
+ * Default debounce window for inbound message coalescing (ms).
+ * This helps combine URL text + link preview balloon messages that BlueBubbles
+ * sends as separate webhook events when no explicit inbound debounce config exists.
+ */
+const DEFAULT_INBOUND_DEBOUNCE_MS = 350;
+
+/**
+ * Combines multiple debounced messages into a single message for processing.
+ * Used when multiple webhook events arrive within the debounce window.
+ */
+function combineDebounceEntries(entries: BlueBubblesDebounceEntry[]): NormalizedWebhookMessage {
+  if (entries.length === 0) {
+    throw new Error("Cannot combine empty entries");
+  }
+  if (entries.length === 1) {
+    return entries[0].message;
+  }
+
+  // Use the first message as the base (typically the text message)
+  const first = entries[0].message;
+
+  // Combine text from all entries, filtering out duplicates and empty strings
+  const seenTexts = new Set<string>();
+  const textParts: string[] = [];
+  
+  for (const entry of entries) {
+    const text = entry.message.text.trim();
+    if (!text) continue;
+    // Skip duplicate text (URL might be in both text message and balloon)
+    const normalizedText = text.toLowerCase();
+    if (seenTexts.has(normalizedText)) continue;
+    seenTexts.add(normalizedText);
+    textParts.push(text);
+  }
+
+  // Merge attachments from all entries
+  const allAttachments = entries.flatMap((e) => e.message.attachments ?? []);
+
+  // Use the latest timestamp
+  const timestamps = entries
+    .map((e) => e.message.timestamp)
+    .filter((t): t is number => typeof t === "number");
+  const latestTimestamp = timestamps.length > 0 ? Math.max(...timestamps) : first.timestamp;
+
+  // Collect all message IDs for reference
+  const messageIds = entries
+    .map((e) => e.message.messageId)
+    .filter((id): id is string => Boolean(id));
+
+  // Prefer reply context from any entry that has it
+  const entryWithReply = entries.find((e) => e.message.replyToId);
+
+  return {
+    ...first,
+    text: textParts.join(" "),
+    attachments: allAttachments.length > 0 ? allAttachments : first.attachments,
+    timestamp: latestTimestamp,
+    // Use first message's ID as primary (for reply reference), but we've coalesced others
+    messageId: messageIds[0] ?? first.messageId,
+    // Preserve reply context if present
+    replyToId: entryWithReply?.message.replyToId ?? first.replyToId,
+    replyToBody: entryWithReply?.message.replyToBody ?? first.replyToBody,
+    replyToSender: entryWithReply?.message.replyToSender ?? first.replyToSender,
+    // Clear balloonBundleId since we've combined (the combined message is no longer just a balloon)
+    balloonBundleId: undefined,
+  };
+}
+
 const webhookTargets = new Map<string, WebhookTarget[]>();
 
+/**
+ * Maps webhook targets to their inbound debouncers.
+ * Each target gets its own debouncer keyed by a unique identifier.
+ */
+const targetDebouncers = new Map<
+  WebhookTarget,
+  ReturnType<BlueBubblesCoreRuntime["channel"]["debounce"]["createInboundDebouncer"]>
+>();
+
+function resolveBlueBubblesDebounceMs(
+  config: MoltbotConfig,
+  core: BlueBubblesCoreRuntime,
+): number {
+  const inbound = config.messages?.inbound;
+  const hasExplicitDebounce =
+    typeof inbound?.debounceMs === "number" || typeof inbound?.byChannel?.bluebubbles === "number";
+  if (!hasExplicitDebounce) return DEFAULT_INBOUND_DEBOUNCE_MS;
+  return core.channel.debounce.resolveInboundDebounceMs({ cfg: config, channel: "bluebubbles" });
+}
+
+/**
+ * Creates or retrieves a debouncer for a webhook target.
+ */
+function getOrCreateDebouncer(target: WebhookTarget) {
+  const existing = targetDebouncers.get(target);
+  if (existing) return existing;
+
+  const { account, config, runtime, core } = target;
+
+  const debouncer = core.channel.debounce.createInboundDebouncer<BlueBubblesDebounceEntry>({
+    debounceMs: resolveBlueBubblesDebounceMs(config, core),
+    buildKey: (entry) => {
+      const msg = entry.message;
+      // Build key from account + chat + sender to coalesce messages from same source
+      const chatKey =
+        msg.chatGuid?.trim() ??
+        msg.chatIdentifier?.trim() ??
+        (msg.chatId ? String(msg.chatId) : "dm");
+      return `bluebubbles:${account.accountId}:${chatKey}:${msg.senderId}`;
+    },
+    shouldDebounce: (entry) => {
+      const msg = entry.message;
+      // Skip debouncing for messages with attachments - process immediately
+      if (msg.attachments && msg.attachments.length > 0) return false;
+      // Skip debouncing for from-me messages (they're just cached, not processed)
+      if (msg.fromMe) return false;
+      // Skip debouncing for control commands - process immediately
+      if (core.channel.text.hasControlCommand(msg.text, config)) return false;
+      // Debounce normal text messages and URL balloon messages
+      return true;
+    },
+    onFlush: async (entries) => {
+      if (entries.length === 0) return;
+      
+      // Use target from first entry (all entries have same target due to key structure)
+      const flushTarget = entries[0].target;
+      
+      if (entries.length === 1) {
+        // Single message - process normally
+        await processMessage(entries[0].message, flushTarget);
+        return;
+      }
+
+      // Multiple messages - combine and process
+      const combined = combineDebounceEntries(entries);
+      
+      if (core.logging.shouldLogVerbose()) {
+        const count = entries.length;
+        const preview = combined.text.slice(0, 50);
+        runtime.log?.(
+          `[bluebubbles] coalesced ${count} messages: "${preview}${combined.text.length > 50 ? "..." : ""}"`,
+        );
+      }
+      
+      await processMessage(combined, flushTarget);
+    },
+    onError: (err) => {
+      runtime.error?.(`[${account.accountId}] [bluebubbles] debounce flush failed: ${String(err)}`);
+    },
+  });
+
+  targetDebouncers.set(target, debouncer);
+  return debouncer;
+}
+
+/**
+ * Removes a debouncer for a target (called during unregistration).
+ */
+function removeDebouncer(target: WebhookTarget): void {
+  targetDebouncers.delete(target);
+}
+
 function normalizeWebhookPath(raw: string): string {
   const trimmed = raw.trim();
   if (!trimmed) return "/";
@@ -275,6 +445,8 @@ export function registerBlueBubblesWebhookTarget(target: WebhookTarget): () => v
     } else {
       webhookTargets.delete(key);
     }
+    // Clean up debouncer when target is unregistered
+    removeDebouncer(normalizedTarget);
   };
 }
 
@@ -768,7 +940,7 @@ function maskSecret(value: string): string {
 }
 
 function resolveBlueBubblesAckReaction(params: {
-  cfg: PigbotConfig;
+  cfg: MoltbotConfig;
   agentId: string;
   core: BlueBubblesCoreRuntime;
   runtime: BlueBubblesRuntimeEnv;
@@ -1205,7 +1377,10 @@ export async function handleBlueBubblesWebhookRequest(
         );
       });
     } else if (message) {
-      processMessage(message, target).catch((err) => {
+      // Route messages through debouncer to coalesce rapid-fire events
+      // (e.g., text message + URL balloon arriving as separate webhooks)
+      const debouncer = getOrCreateDebouncer(target);
+      debouncer.enqueue({ message, target }).catch((err) => {
         target.runtime.error?.(
           `[${target.account.accountId}] BlueBubbles webhook failed: ${String(err)}`,
         );