fix(imessage): native poll vote-cue, echo suppression, and same-sender comment fold

omarshahine · web-flow · commit 8c7ac9b9b9df · 2026-07-01T21:30:29.000-07:00
Makes native iMessage polls behave correctly end to end. What changed: - Inbound polls render with a numbered-options vote cue so the agent casts a native vote instead of answering the poll in prose. - poll-vote resolves the poll reference from pollId/pollGuid/messageId and now defaults to the current inbound poll message when the model omits it; still errors when no reference exists. - poll-vote echo suppression is session-scoped, so the redundant spoken answer is dropped across the separate poll and comment runs. - A poll's inline-reply caption is folded (not delivered as a standalone question) only when the poll creator and reply sender are both known and equal; unknown/mismatched sender falls through to the normal inbound decision gate, so no inbound reply is silently dropped. Evidence: - 64 passing tests in the poll suites (poll-comment, poll-render, actions), incl. sender fail-closed regressions; pnpm build clean. - Two Codex autoreviews clean (patch is correct); ClawSweeper re-review rated it platinum hermit. - Live-verified on macOS 26.4.1 on the deployed gateway: poll "What color pill?" -> native vote delivered with a 7333-byte payload, caption folded, zero echo. Note: vote delivery also depends on the imsg vote-stamp fix (openclaw/imsg#150); OpenClaw ships ahead of imsg per owner decision.
diff --git a/extensions/imessage/src/actions.test.ts b/extensions/imessage/src/actions.test.ts
@@ -373,6 +373,51 @@ describe("imessage message actions", () => {
     });
   });
 
+  it("defaults the poll reference to the current inbound message id", async () => {
+    probeMock.getCachedIMessagePrivateApiStatus.mockReturnValue({
+      available: true,
+      v2Ready: true,
+      selectors: { pollVoteMessage: true },
+      rpcMethods: ["send", "poll.send", "poll.vote"],
+    });
+    runtimeMock.resolveIMessageMessageId.mockReturnValueOnce("poll-full-guid");
+    runtimeMock.sendPollVote.mockResolvedValue({ messageId: "vote-guid", optionText: "Blue" });
+
+    // No explicit pollId/pollGuid/messageId — the poll is the current inbound
+    // message, so the reference defaults from toolContext.currentMessageId.
+    await imessageMessageActions.handleAction?.({
+      action: "poll-vote",
+      cfg: cfg(),
+      params: { chatGuid: "iMessage;+;chat0000", pollOptionIndex: 2 },
+      toolContext: { currentMessageId: 3 },
+    } as never);
+
+    expect(runtimeMock.resolveIMessageMessageId).toHaveBeenCalledWith(
+      "3",
+      expect.objectContaining({ requireKnownShortId: true }),
+    );
+    expect(runtimeMock.sendPollVote).toHaveBeenCalledWith(
+      expect.objectContaining({ pollGuid: "poll-full-guid", optionIndex: 2 }),
+    );
+  });
+
+  it("rejects a poll vote with no reference and no current inbound message", async () => {
+    probeMock.getCachedIMessagePrivateApiStatus.mockReturnValue({
+      available: true,
+      v2Ready: true,
+      selectors: { pollVoteMessage: true },
+      rpcMethods: ["send", "poll.send", "poll.vote"],
+    });
+    await expect(
+      imessageMessageActions.handleAction?.({
+        action: "poll-vote",
+        cfg: cfg(),
+        params: { chatGuid: "iMessage;+;chat0000", pollOptionIndex: 2 },
+      } as never),
+    ).rejects.toThrow("requires the poll message id");
+    expect(runtimeMock.sendPollVote).not.toHaveBeenCalled();
+  });
+
   it("rejects a poll vote with conflicting selectors", async () => {
     probeMock.getCachedIMessagePrivateApiStatus.mockReturnValue({
       available: true,
diff --git a/extensions/imessage/src/actions.ts b/extensions/imessage/src/actions.ts
@@ -829,11 +829,17 @@ export const imessageMessageActions: ChannelMessageActionAdapter = {
       }
       // The poll being voted on is an inbound message; the agent references it
       // by the shared `pollId` param or a message id, which we resolve to the
-      // poll's full GUID through the same reply cache the react path uses.
+      // poll's full GUID through the same reply cache the react path uses. When
+      // the model omits an explicit reference, default to the current inbound
+      // message id — the poll it is replying to — mirroring how reaction-like
+      // actions default their target (resolveReactionMessageId). Without this a
+      // vote that names only the option index fails the required-reference
+      // check below even though the intended poll is unambiguous.
       const pollRef =
         readStringParam(params, "pollId") ??
         readStringParam(params, "pollGuid") ??
-        readStringParam(params, "messageId");
+        readStringParam(params, "messageId") ??
+        (toolContext?.currentMessageId != null ? String(toolContext.currentMessageId) : undefined);
       if (!pollRef) {
         throw new Error("iMessage poll-vote requires the poll message id (pollId or messageId).");
       }
diff --git a/extensions/imessage/src/monitor/monitor-provider.ts b/extensions/imessage/src/monitor/monitor-provider.ts
@@ -103,6 +103,7 @@ import {
 import { createLoopRateLimiter } from "./loop-rate-limiter.js";
 import { stageIMessageAttachments } from "./media-staging.js";
 import { parseIMessageNotification } from "./parse-notification.js";
+import { createPollCommentFolder } from "./poll-comment.js";
 import { renderIMessagePollBody } from "./poll-render.js";
 import { enqueueIMessageReactionSystemEvent } from "./reaction-system-event.js";
 import { advanceIMessageRecoveryCursor, loadIMessageRecoveryCursor } from "./recovery-cursor.js";
@@ -832,6 +833,11 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     }
   }
 
+  // iMessage delivers a poll's comment as a separate inline reply to the poll
+  // balloon; fold it into the poll so the agent votes once instead of also
+  // replying to the caption in prose (a redundant restatement of the vote).
+  const pollCommentFolder = createPollCommentFolder();
+
   function resolveIMessageInboundBodyText(message: IMessagePayload) {
     // Native poll balloons carry only a 0xFFFD placeholder in `text`; render the
     // decoded poll (question/options/votes) so the agent sees the actual poll.
@@ -885,6 +891,25 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
       return;
     }
 
+    // Remember native polls so a caption reply that lands WITH the poll is
+    // recognized and folded. The poll balloon (rendered with options + a vote
+    // cue) is still delivered; only the near-simultaneous comment is dropped so
+    // the agent votes without also answering it as a standalone question. A
+    // deliberate later inline reply to the poll falls outside the window and is
+    // delivered normally.
+    const pollFoldAtMs = message.created_at ? Date.parse(message.created_at) : Number.NaN;
+    if (message.poll) {
+      pollCommentFolder.rememberPoll(message.guid, pollFoldAtMs, message.sender);
+    } else if (
+      message.reply_to_guid != null &&
+      pollCommentFolder.isPollComment(message.reply_to_guid, pollFoldAtMs, message.sender)
+    ) {
+      logVerbose(
+        "imessage: folding poll comment (inline reply sent with a poll) into the poll; not delivering standalone",
+      );
+      return;
+    }
+
     const {
       messageText,
       bodyText,
diff --git a/extensions/imessage/src/monitor/parse-notification.ts b/extensions/imessage/src/monitor/parse-notification.ts
@@ -70,6 +70,7 @@ export function parseIMessageNotification(raw: unknown): IMessagePayload | null
     !isOptionalBoolean(message.is_from_me) ||
     !isOptionalString(message.text) ||
     !isOptionalStringOrNumber(message.reply_to_id) ||
+    !isOptionalString(message.reply_to_guid) ||
     !isOptionalString(message.reply_to_text) ||
     !isOptionalString(message.reply_to_sender) ||
     !isOptionalString(message.created_at) ||
diff --git a/extensions/imessage/src/monitor/poll-comment.test.ts b/extensions/imessage/src/monitor/poll-comment.test.ts
@@ -0,0 +1,76 @@
+// Covers the poll-comment folder: a native poll's caption is an inline reply to
+// the poll balloon (its reply_to_guid == the poll's guid) that lands WITH the
+// poll, and must be folded (dropped) rather than delivered as a standalone
+// message the agent answers in prose. A deliberate later reply, or a different
+// sender's reply, must NOT be folded.
+import { describe, expect, it } from "vitest";
+import { createPollCommentFolder } from "./poll-comment.js";
+
+const POLL_GUID = "75A8F623-947D-4611-A23D-4DDD6D17BC0F";
+const T0 = 1_000_000; // arbitrary base timestamp (ms)
+
+describe("createPollCommentFolder", () => {
+  it("folds a caption whose reply_to_guid targets a poll that lands with it", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    // Caption ships with the poll — same instant, same sender.
+    expect(folder.isPollComment(POLL_GUID, T0 + 500, "+15551110000")).toBe(true);
+  });
+
+  it("does NOT fold a deliberate later inline reply to the poll", () => {
+    const folder = createPollCommentFolder({ windowMs: 15_000 });
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    // A real "I can't make it" reply a minute later must be delivered.
+    expect(folder.isPollComment(POLL_GUID, T0 + 60_000, "+15551110000")).toBe(false);
+  });
+
+  it("does NOT fold an in-window reply from a different sender (group member)", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    expect(folder.isPollComment(POLL_GUID, T0 + 500, "+15559998888")).toBe(false);
+  });
+
+  it("does NOT fold when the reply sender is known but the poll sender is unknown", () => {
+    // Fail closed: an unknown-sender poll row must not turn a real in-window
+    // reply from an identified participant into a dropped message. This fold
+    // runs before the normal missing-sender/allowlist gate.
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, undefined);
+    expect(folder.isPollComment(POLL_GUID, T0 + 500, "+15551110000")).toBe(false);
+  });
+
+  it("does NOT fold when the reply sender is unknown", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    expect(folder.isPollComment(POLL_GUID, T0 + 500, undefined)).toBe(false);
+  });
+
+  it("does not fold a reply to an unrelated message", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    expect(folder.isPollComment("SOME-OTHER-GUID", T0, "+15551110000")).toBe(false);
+  });
+
+  it("does not fold a non-reply or a reply with no usable timestamp", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    expect(folder.isPollComment(null, T0)).toBe(false);
+    expect(folder.isPollComment("", T0)).toBe(false);
+    expect(folder.isPollComment(POLL_GUID, Number.NaN)).toBe(false);
+  });
+
+  it("does not track a poll without a usable timestamp or guid", () => {
+    const folder = createPollCommentFolder();
+    folder.rememberPoll(POLL_GUID, Number.NaN, "+15551110000");
+    expect(folder.isPollComment(POLL_GUID, T0)).toBe(false);
+    folder.rememberPoll(null, T0, "+15551110000");
+    expect(folder.isPollComment("", T0)).toBe(false);
+  });
+
+  it("does not fold before the poll has been seen (ordering safety)", () => {
+    const folder = createPollCommentFolder();
+    expect(folder.isPollComment(POLL_GUID, T0, "+15551110000")).toBe(false);
+    folder.rememberPoll(POLL_GUID, T0, "+15551110000");
+    expect(folder.isPollComment(POLL_GUID, T0, "+15551110000")).toBe(true);
+  });
+});
diff --git a/extensions/imessage/src/monitor/poll-comment.ts b/extensions/imessage/src/monitor/poll-comment.ts
@@ -0,0 +1,92 @@
+// A native iMessage poll's comment/caption is delivered as a separate inbound
+// message that is an INLINE REPLY to the poll balloon (its `reply_to_guid` is
+// the poll's guid). Modern imsg emits balloon metadata, so the same-sender coalesce
+// path deliberately flushes the poll and the reply separately — which means the
+// caption reaches the agent as its own message. The agent then votes on the
+// poll AND answers the caption in prose, a redundant restatement of the vote.
+//
+// This tracker lets the monitor fold the caption into the poll: the poll message
+// already renders the options + vote cue, so a reply that arrives WITH the poll
+// is dropped instead of delivered standalone.
+//
+// The caption is sent as part of composing the poll, so its timestamp is
+// essentially the poll's. We only fold a reply whose own timestamp lands within
+// a short window of the poll; a deliberate later inline reply to the poll (e.g.
+// "I can't make it") falls outside the window and is delivered normally.
+
+// The caption ships with the poll, so it lands within a couple seconds; a short
+// window keeps genuine later replies out. Generous enough to absorb clock/queue
+// skew, tight enough that a human's read-then-type reply falls outside.
+const DEFAULT_COMMENT_WINDOW_MS = 15_000;
+
+function normalizeGuid(guid?: string | null): string {
+  return guid?.trim() ?? "";
+}
+
+function normalizeSender(sender?: string | null): string {
+  return sender?.trim().toLowerCase() ?? "";
+}
+
+type SeenPoll = { atMs: number; sender: string };
+
+export function createPollCommentFolder(options?: { windowMs?: number }) {
+  const windowMs = options?.windowMs ?? DEFAULT_COMMENT_WINDOW_MS;
+  // poll guid -> the poll's send time + creator. Bounded: pruned on every write
+  // against the newest poll time, so at most the polls seen within `windowMs`
+  // are kept.
+  const seenPolls = new Map<string, SeenPoll>();
+
+  function prune(referenceMs: number): void {
+    for (const [key, seen] of seenPolls) {
+      if (referenceMs - seen.atMs > windowMs) {
+        seenPolls.delete(key);
+      }
+    }
+  }
+
+  return {
+    // Remember a native poll balloon (its guid + send time + creator) so a
+    // caption reply that lands within the window from the same sender can be
+    // folded. `atMs` is the poll's created_at; without a usable timestamp or
+    // guid the poll is not tracked (fold stays disabled — messages deliver).
+    rememberPoll(guid: string | null | undefined, atMs: number, sender?: string | null): void {
+      const key = normalizeGuid(guid);
+      if (!key || !Number.isFinite(atMs)) {
+        return;
+      }
+      prune(atMs);
+      seenPolls.set(key, { atMs, sender: normalizeSender(sender) });
+    },
+    // True only for the poll's caption: a reply whose `reply_to_guid` targets a
+    // remembered poll, lands within the window after it, AND comes from the
+    // poll's creator. A deliberate later reply, or any reply from someone else
+    // (e.g. a group member), falls through and is delivered normally.
+    isPollComment(
+      replyToGuid: string | null | undefined,
+      atMs: number,
+      sender?: string | null,
+    ): boolean {
+      const key = normalizeGuid(replyToGuid);
+      if (!key || !Number.isFinite(atMs)) {
+        return false;
+      }
+      const seen = seenPolls.get(key);
+      if (!seen || atMs < seen.atMs || atMs - seen.atMs > windowMs) {
+        return false;
+      }
+      const replySender = normalizeSender(sender);
+      // Fail CLOSED on identity: fold only when the poll creator and the reply
+      // sender are both known and identical. This fold runs before the normal
+      // missing-sender/from-me/allowlist gate (monitor-provider handleMessageNowInner),
+      // so folding on an unknown sender could drop a real in-window reply from a
+      // different participant to the same poll guid. Unknown/mismatched sender
+      // therefore falls through and is delivered (the poll_vote_echo guard still
+      // catches a redundant spoken answer). Verified against chat.db: an inbound
+      // poll and its caption both carry the sender handle, so the 1:1 caption
+      // still folds as the same known sender.
+      return seen.sender.length > 0 && replySender.length > 0 && seen.sender === replySender;
+    },
+  };
+}
+
+export type PollCommentFolder = ReturnType<typeof createPollCommentFolder>;
diff --git a/extensions/imessage/src/monitor/poll-render.test.ts b/extensions/imessage/src/monitor/poll-render.test.ts
@@ -14,6 +14,10 @@ describe("renderIMessagePollBody", () => {
     expect(out).toContain("Favorite color?");
     expect(out).toContain("1) Red");
     expect(out).toContain("2) Blue");
+    // Must cue the vote action so the agent votes instead of replying in prose;
+    // the 📊 Poll prefix matches agents' vote-instruction trigger.
+    expect(out).toContain("poll-vote");
+    expect(out).toContain("\u{1F4CA} Poll");
   });
 
   it("folds in vote tallies", () => {
diff --git a/extensions/imessage/src/monitor/poll-render.ts b/extensions/imessage/src/monitor/poll-render.ts
@@ -33,17 +33,20 @@ export function renderIMessagePollBody(poll: IMessagePoll): string | null {
     tally.set(vote.option_id, (tally.get(vote.option_id) ?? 0) + 1);
   }
 
-  // Present the poll as a flat notification, not a question header with a
-  // call-to-action. Rendering it as "Poll: <question>?" + "to vote, use…" made
-  // the model treat it as a question to answer AND vote on (redundant echo).
-  // A notification-style line lets it vote (options + indices retained) without
-  // being nudged to also verbalize an answer.
+  // Cue the vote action explicitly. The agent has the poll-vote tool, but given
+  // a flat notification it tends to answer the poll with a prose text reply
+  // instead of casting a vote. Naming the action + index makes voting the
+  // obvious path. An earlier version dropped the call-to-action to stop the
+  // model from also verbalizing its pick, but that suppressed voting entirely;
+  // the poll_vote_echo guard now drops any redundant spoken answer, so the
+  // call-to-action is safe. The `📊 Poll:` prefix also matches the trigger
+  // phrasing agents key their vote instructions on.
   const optionList = options
     .map((option, index) => {
       const count = tally.get(option.id) ?? 0;
       return `${index + 1}) ${option.text}${count > 0 ? ` [${count}]` : ""}`;
     })
     .join("  ");
   const question = poll.question?.trim();
-  return `[poll shared]${question ? ` ${question}` : ""} — options: ${optionList}`;
+  return `\u{1F4CA} Poll${question ? `: ${question}` : ""} — options: ${optionList}. Cast your vote on this poll with the poll-vote action (pollOptionIndex = the option number); do not answer in a text reply.`;
 }
diff --git a/extensions/imessage/src/monitor/types.ts b/extensions/imessage/src/monitor/types.ts
@@ -45,6 +45,10 @@ export type IMessagePayload = {
   is_from_me?: boolean | null;
   text?: string | null;
   reply_to_id?: number | string | null;
+  // imsg emits the replied-to message's GUID here (its inbound events carry
+  // `reply_to_guid`, not a numeric `reply_to_id`); the poll-comment fold matches
+  // a caption's `reply_to_guid` against the poll balloon's guid.
+  reply_to_guid?: string | null;
   reply_to_text?: string | null;
   reply_to_sender?: string | null;
   created_at?: string | null;
diff --git a/src/agents/tools/message-tool.test.ts b/src/agents/tools/message-tool.test.ts
diff --git a/src/agents/tools/message-tool.ts b/src/agents/tools/message-tool.ts
