fix(imessage): coalesce split-sends without delaying normal DMs

omarshahine · claude · omarshahine · commit feaa685710bf · 2026-06-05T17:45:26.000-07:00
`coalesceSameSenderDms` previously debounced every DM for the full window
(2500ms), so each reply waited out the debounce even when no follow-up was
coming. A `Dump &lt;URL&gt;` whose payload row arrived late (e.g. attachment
transfer lag) could also miss the window and dispatch as two turns, producing
a stray "send me the URL" bubble.

Classify each DM instead of holding all of them:
- lead-in: a short bare command-style fragment (`Dump`) that plausibly
  precedes a payload — briefly held.
- payload-join: a URL/attachment that completes a pending lead-in — merged
  into the held lead-in and flushed immediately.
- instant: everything else (prose, questions, lone URLs) — zero added latency.

Normal conversation now replies instantly; real split-sends still coalesce
and flush as soon as the payload row lands rather than waiting out the window.
The window now only bounds how long a lone lead-in waits for a follow-up.

Adds pure `isIMessageSplitLeadIn` / `iMessageTextHasUrl` helpers in coalesce.ts
with unit tests.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 Docs: https://docs.openclaw.ai
 
+## Unreleased
+
+### Fixes
+
+- iMessage: coalesce same-sender split-sends (`Dump <URL>`, caption + image) without adding latency to normal DMs. The monitor now classifies each DM — only short command-style lead-ins are briefly held, the payload row that follows merges in and flushes immediately, and everything else (prose, questions, lone URLs) dispatches instantly instead of waiting out the debounce window.
+
 ## 2026.6.2
 
 ### Highlights
diff --git a/extensions/imessage/src/monitor/coalesce.test.ts b/extensions/imessage/src/monitor/coalesce.test.ts
@@ -2,6 +2,8 @@
 import { describe, expect, it } from "vitest";
 import {
   combineIMessagePayloads,
+  iMessageTextHasUrl,
+  isIMessageSplitLeadIn,
   MAX_COALESCED_ATTACHMENTS,
   MAX_COALESCED_ENTRIES,
   MAX_COALESCED_TEXT_CHARS,
@@ -160,3 +162,52 @@ describe("combineIMessagePayloads", () => {
     expect(MAX_COALESCED_ENTRIES).toBeGreaterThan(1);
   });
 });
+
+describe("iMessageTextHasUrl", () => {
+  it("detects http and https URLs anywhere in the text", () => {
+    expect(iMessageTextHasUrl("https://stocks.apple.com/A16n5gO09T5y1YRM")).toBe(true);
+    expect(iMessageTextHasUrl("check this http://example.com out")).toBe(true);
+  });
+
+  it("returns false for plain text and empty input", () => {
+    expect(iMessageTextHasUrl("Dump")).toBe(false);
+    expect(iMessageTextHasUrl("look at this")).toBe(false);
+    expect(iMessageTextHasUrl("")).toBe(false);
+    expect(iMessageTextHasUrl(null)).toBe(false);
+    expect(iMessageTextHasUrl(undefined)).toBe(false);
+  });
+});
+
+describe("isIMessageSplitLeadIn", () => {
+  it("treats short bare command fragments as lead-ins", () => {
+    expect(isIMessageSplitLeadIn({ text: "Dump", hasMedia: false })).toBe(true);
+    expect(isIMessageSplitLeadIn({ text: "Save this", hasMedia: false })).toBe(true);
+    expect(isIMessageSplitLeadIn({ text: "look at", hasMedia: false })).toBe(true);
+  });
+
+  it("does not hold complete one-liners (terminal punctuation)", () => {
+    expect(isIMessageSplitLeadIn({ text: "what's for dinner?", hasMedia: false })).toBe(false);
+    expect(isIMessageSplitLeadIn({ text: "thanks.", hasMedia: false })).toBe(false);
+    expect(isIMessageSplitLeadIn({ text: "got it!", hasMedia: false })).toBe(false);
+  });
+
+  it("does not hold longer messages beyond the word cap", () => {
+    expect(isIMessageSplitLeadIn({ text: "can you look at this for me", hasMedia: false })).toBe(
+      false,
+    );
+  });
+
+  it("does not hold messages that already carry the payload", () => {
+    expect(isIMessageSplitLeadIn({ text: "Dump https://example.com", hasMedia: false })).toBe(
+      false,
+    );
+    expect(isIMessageSplitLeadIn({ text: "https://example.com", hasMedia: false })).toBe(false);
+    expect(isIMessageSplitLeadIn({ text: "Dump", hasMedia: true })).toBe(false);
+  });
+
+  it("does not hold empty or whitespace-only text", () => {
+    expect(isIMessageSplitLeadIn({ text: "", hasMedia: false })).toBe(false);
+    expect(isIMessageSplitLeadIn({ text: "   ", hasMedia: false })).toBe(false);
+    expect(isIMessageSplitLeadIn({ text: null, hasMedia: false })).toBe(false);
+  });
+});
diff --git a/extensions/imessage/src/monitor/coalesce.ts b/extensions/imessage/src/monitor/coalesce.ts
@@ -17,6 +17,56 @@ export const MAX_COALESCED_TEXT_CHARS = 4000;
 export const MAX_COALESCED_ATTACHMENTS = 20;
 export const MAX_COALESCED_ENTRIES = 10;
 
+/**
+ * Longest text (in whitespace-delimited words) still treated as a split
+ * lead-in. Apple peels short command fragments — `Dump`, `Save this`,
+ * `look at` — off the front of a `<command> <payload>` send; anything longer
+ * reads as a self-contained message and dispatches instantly.
+ */
+export const LEAD_IN_MAX_WORDS = 3;
+
+const URL_PATTERN = /\bhttps?:\/\/\S+/i;
+
+/** True when the text carries an http(s) URL — the typical split-send payload. */
+export function iMessageTextHasUrl(text: string | null | undefined): boolean {
+  return URL_PATTERN.test(text ?? "");
+}
+
+/**
+ * A "split lead-in" is the short text fragment Apple delivers as its own
+ * `chat.db` row just before the payload row of a `<command> <URL/attachment>`
+ * send (e.g. `Dump` ahead of `https://…`, or a bare caption typed just before
+ * an image). It is the ONLY DM shape the monitor holds back to wait for a
+ * follow-up; every other shape dispatches instantly so normal conversation
+ * carries zero added latency.
+ *
+ * Heuristic: non-empty short text (≤ {@link LEAD_IN_MAX_WORDS} words), no URL,
+ * no media, and no terminal sentence punctuation. The dangling, unpunctuated
+ * shape is what separates a lead-in (`Dump`) from a complete one-liner
+ * (`what's for dinner?`). The cost of a false positive is bounded: a lone
+ * short fragment with no follow-up still flushes after the coalesce window.
+ */
+export function isIMessageSplitLeadIn(params: {
+  text: string | null | undefined;
+  hasMedia: boolean;
+}): boolean {
+  if (params.hasMedia) {
+    return false;
+  }
+  const text = (params.text ?? "").trim();
+  if (!text) {
+    return false;
+  }
+  if (iMessageTextHasUrl(text)) {
+    return false;
+  }
+  if (/[.?!…]$/.test(text)) {
+    return false;
+  }
+  const words = text.split(/\s+/).filter(Boolean);
+  return words.length >= 1 && words.length <= LEAD_IN_MAX_WORDS;
+}
+
 export type CoalescedIMessagePayload = IMessagePayload & {
   /**
    * Source GUIDs folded into this merged payload, in arrival order. Includes
diff --git a/extensions/imessage/src/monitor/monitor-provider.ts b/extensions/imessage/src/monitor/monitor-provider.ts
@@ -66,7 +66,7 @@ import { normalizeIMessageHandle } from "../targets.js";
 import { attachIMessageMonitorAbortHandler } from "./abort-handler.js";
 import { runIMessageCatchup } from "./catchup-bridge.js";
 import { advanceIMessageCatchupCursor, resolveCatchupConfig } from "./catchup.js";
-import { combineIMessagePayloads } from "./coalesce.js";
+import { combineIMessagePayloads, iMessageTextHasUrl, isIMessageSplitLeadIn } from "./coalesce.js";
 import { repairIMessageConversationAnchor } from "./conversation-repair.js";
 import { createIMessageEchoCachingSend, deliverReplies } from "./deliver.js";
 import { resolveIMessageDmHistoryContext, resolveIMessageDmHistoryLimit } from "./dm-history.js";
@@ -346,11 +346,21 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     ? await resolveIMessageStartupRowidWatermark(watchSourceDbPath)
     : null;
 
-  // When `coalesceSameSenderDms` is enabled and the user has not set an
-  // explicit inbound debounce for this channel, widen the window to 2500 ms.
-  // Apple's split-send for `<command> <URL>` arrives ~0.8-2.0 s apart on most
-  // setups, so the legacy 0 ms default would flush the command alone before
-  // the URL row reaches the debouncer.
+  // `coalesceSameSenderDms` merges Apple's split-send — a `<command> <URL>` or
+  // `<caption> <image>` send that arrives as two `chat.db` rows ~0.8-2.0 s
+  // apart — into one agent turn, WITHOUT taxing normal conversation. Rather
+  // than debounce every DM (which delayed every reply by the full window), the
+  // monitor classifies each DM:
+  //   - "lead-in"      — a short bare fragment (`Dump`) that plausibly precedes
+  //                      a payload. Held until the payload arrives or the window
+  //                      elapses.
+  //   - "payload-join" — a URL/attachment that completes a pending lead-in.
+  //                      Merged into the held lead-in and flushed immediately.
+  //   - "instant"      — everything else (prose, questions, lone URLs). Zero
+  //                      added latency.
+  // The window only bounds how long a lead-in waits for a follow-up, so it must
+  // still exceed Apple's max split gap; real split-sends flush as soon as the
+  // payload row lands.
   const coalesceSameSenderDms = imessageCfg.coalesceSameSenderDms === true;
   const inboundCfg = cfg.messages?.inbound;
   const hasExplicitInboundDebounce =
@@ -359,8 +369,59 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
   const debounceMsOverride =
     coalesceSameSenderDms && !hasExplicitInboundDebounce ? 2500 : undefined;
 
+  // Keys of DM lead-ins currently buffered, awaiting a payload follow-up. A
+  // payload that matches a pending key merges into the held lead-in instead of
+  // dispatching on its own.
+  const pendingLeadInKeys = new Set<string>();
+
+  const buildDmCoalesceKey = (msg: IMessagePayload): string | null => {
+    const sender = msg.sender?.trim();
+    if (!sender) {
+      return null;
+    }
+    const conversationId =
+      msg.chat_id != null
+        ? `chat:${msg.chat_id}`
+        : (msg.chat_guid ?? msg.chat_identifier ?? "unknown");
+    return `imessage:${accountInfo.accountId}:dm:${conversationId}:${sender}`;
+  };
+
+  type DmCoalesceMode = "lead-in" | "payload-join" | "instant";
+  type DmCoalesceDecision = { mode: DmCoalesceMode; key: string };
+
+  // Classify a DM for split-send coalescing. Returns null when coalescing does
+  // not apply (disabled, group chat, reaction, or a from-me echo), so the
+  // legacy/group path handles the message.
+  const classifyDmCoalesce = (msg: IMessagePayload): DmCoalesceDecision | null => {
+    if (!coalesceSameSenderDms || msg.is_group === true) {
+      return null;
+    }
+    if (msg.is_from_me === true) {
+      return null;
+    }
+    if (resolveIMessageReactionContext(msg, (msg.text ?? "").trim())) {
+      return null;
+    }
+    const key = buildDmCoalesceKey(msg);
+    if (!key) {
+      return null;
+    }
+    const hasMedia = Boolean(
+      msg.attachments?.some((attachment) => !isIMessagePluginPayloadAttachment(attachment)),
+    );
+    const isPayload = hasMedia || iMessageTextHasUrl(msg.text);
+    if (isPayload && pendingLeadInKeys.has(key)) {
+      return { mode: "payload-join", key };
+    }
+    if (isIMessageSplitLeadIn({ text: msg.text, hasMedia })) {
+      return { mode: "lead-in", key };
+    }
+    return { mode: "instant", key };
+  };
+
   const { debouncer: inboundDebouncer } = createChannelInboundDebouncer<{
     message: IMessagePayload;
+    dm?: DmCoalesceDecision;
   }>({
     cfg,
     channel: "imessage",
@@ -371,21 +432,17 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
       if (!sender) {
         return null;
       }
+      // DM coalesce path: key on chat:sender so a lead-in and its payload
+      // follow-up fall into the same bucket and merge into one agent turn.
+      if (entry.dm) {
+        return entry.dm.key;
+      }
+      // Group chats / coalesce-disabled use the legacy key so multi-user turn
+      // structure is preserved.
       const conversationId =
         msg.chat_id != null
           ? `chat:${msg.chat_id}`
           : (msg.chat_guid ?? msg.chat_identifier ?? "unknown");
-
-      // With coalesceSameSenderDms enabled, DMs key on chat:sender so two
-      // distinct user sends — `Dump` followed by a pasted URL that Apple
-      // delivers as a separate row — fall into the same bucket and merge
-      // into one agent turn. Group chats fall through to the legacy key so
-      // shouldDebounce can route them to the instant-dispatch path and
-      // preserve multi-user turn structure.
-      if (coalesceSameSenderDms && msg.is_group !== true) {
-        return `imessage:${accountInfo.accountId}:dm:${conversationId}:${sender}`;
-      }
-
       return `imessage:${accountInfo.accountId}:${conversationId}:${sender}`;
     },
     shouldDebounce: (entry) => {
@@ -397,16 +454,16 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
       if (msg.is_from_me === true) {
         return false;
       }
-
-      // With coalesceSameSenderDms enabled, debounce DM messages aggressively
-      // (text, media, control commands) so split-sends — `Dump <URL>`,
-      // `Save 📎image caption`, and rapid floods — merge into one agent
-      // turn. Group chats keep instant dispatch so the bot stays responsive
-      // when multiple people are typing.
+      // DM coalesce path: only hold lead-ins and the payloads that join them;
+      // everything else dispatches instantly.
+      if (entry.dm) {
+        return entry.dm.mode !== "instant";
+      }
+      // Group chats keep instant dispatch when coalescing is enabled so the bot
+      // stays responsive when multiple people are typing.
       if (coalesceSameSenderDms) {
-        return msg.is_group !== true;
+        return false;
       }
-
       // Legacy gate: text-only, no control commands, no media.
       return shouldDebounceTextInbound({
         text: msg.text,
@@ -420,6 +477,13 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
       if (entries.length === 0) {
         return;
       }
+      // A flushing bucket is no longer pending — clear any lead-in keys it held
+      // so a later payload is classified fresh.
+      for (const entry of entries) {
+        if (entry.dm) {
+          pendingLeadInKeys.delete(entry.dm.key);
+        }
+      }
       if (entries.length === 1) {
         await handleMessageNow(entries[0].message);
         return;
@@ -434,6 +498,13 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
       }
       await handleMessageNow(combined);
     },
+    onCancel: (entries) => {
+      for (const entry of entries) {
+        if (entry.dm) {
+          pendingLeadInKeys.delete(entry.dm.key);
+        }
+      }
+    },
     onError: (err) => {
       runtime.error?.(`imessage debounce flush failed: ${String(err)}`);
     },
@@ -1053,7 +1124,18 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     if (!repairedMessage) {
       return;
     }
-    await inboundDebouncer.enqueue({ message: repairedMessage });
+    const dm = classifyDmCoalesce(repairedMessage) ?? undefined;
+    if (dm?.mode === "lead-in") {
+      // Remember this lead-in so the payload row that follows merges into it
+      // instead of dispatching on its own.
+      pendingLeadInKeys.add(dm.key);
+    }
+    await inboundDebouncer.enqueue({ message: repairedMessage, dm });
+    if (dm?.mode === "payload-join") {
+      // The payload has merged into the buffered lead-in; flush now so the
+      // combined turn dispatches immediately rather than waiting out the window.
+      await inboundDebouncer.flushKey(dm.key);
+    }
   };
 
   await waitForTransportReady({
