@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/imessage/monitor/monitor-provider.js

@@ -2,34 +2,29 @@ import fs from "node:fs/promises";
 import { resolveHumanDelayConfig } from "../../agents/identity.js";
 import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
-import { formatInboundEnvelope, formatInboundFromLabel, resolveEnvelopeFormatOptions, } from "../../auto-reply/envelope.js";
-import { createInboundDebouncer, resolveInboundDebounceMs, } from "../../auto-reply/inbound-debounce.js";
 import { dispatchInboundMessage } from "../../auto-reply/dispatch.js";
-import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
-import { buildPendingHistoryContextFromMap, clearHistoryEntriesIfEnabled, DEFAULT_GROUP_HISTORY_LIMIT, recordPendingHistoryEntryIfEnabled, } from "../../auto-reply/reply/history.js";
-import { buildMentionRegexes, matchesMentionPatterns } from "../../auto-reply/reply/mentions.js";
+import { createInboundDebouncer, resolveInboundDebounceMs, } from "../../auto-reply/inbound-debounce.js";
+import { clearHistoryEntriesIfEnabled, DEFAULT_GROUP_HISTORY_LIMIT, } from "../../auto-reply/reply/history.js";
 import { createReplyDispatcher } from "../../auto-reply/reply/reply-dispatcher.js";
-import { logInboundDrop } from "../../channels/logging.js";
-import { createReplyPrefixContext } from "../../channels/reply-prefix.js";
+import { createReplyPrefixOptions } from "../../channels/reply-prefix.js";
 import { recordInboundSession } from "../../channels/session.js";
 import { loadConfig } from "../../config/config.js";
-import { resolveChannelGroupPolicy, resolveChannelGroupRequireMention, } from "../../config/group-policy.js";
 import { readSessionUpdatedAt, resolveStorePath } from "../../config/sessions.js";
 import { danger, logVerbose, shouldLogVerbose } from "../../globals.js";
 import { waitForTransportReady } from "../../infra/transport-ready.js";
 import { mediaKindFromMime } from "../../media/constants.js";
 import { buildPairingReply } from "../../pairing/pairing-messages.js";
 import { readChannelAllowFromStore, upsertChannelPairingRequest, } from "../../pairing/pairing-store.js";
-import { resolveAgentRoute } from "../../routing/resolve-route.js";
 import { truncateUtf16Safe } from "../../utils.js";
-import { resolveControlCommandGate } from "../../channels/command-gating.js";
 import { resolveIMessageAccount } from "../accounts.js";
 import { createIMessageRpcClient } from "../client.js";
 import { DEFAULT_IMESSAGE_PROBE_TIMEOUT_MS } from "../constants.js";
 import { probeIMessage } from "../probe.js";
 import { sendMessageIMessage } from "../send.js";
-import { formatIMessageChatTarget, isAllowedIMessageSender, normalizeIMessageHandle, } from "../targets.js";
+import { attachIMessageMonitorAbortHandler } from "./abort-handler.js";
 import { deliverReplies } from "./deliver.js";
+import { buildIMessageInboundContext, resolveIMessageInboundDecision, } from "./inbound-processing.js";
+import { parseIMessageNotification } from "./parse-notification.js";
 import { normalizeAllowList, resolveRuntime } from "./runtime.js";
 /**
  * Try to detect remote host from an SSH wrapper script like:
@@ -46,8 +41,9 @@ async function detectRemoteHostFromCliPath(cliPath) {
         const content = await fs.readFile(expanded, "utf8");
         // Match user@host pattern first (e.g., poolbot@192.168.64.3)
         const userHostMatch = content.match(/\bssh\b[^\n]*?\s+([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+)/);
-        if (userHostMatch)
+        if (userHostMatch) {
             return userHostMatch[1];
+        }
         // Fallback: match host-only before imsg command (e.g., ssh -T mac-mini imsg)
         const hostOnlyMatch = content.match(/\bssh\b[^\n]*?\s+([a-zA-Z][a-zA-Z0-9._-]*)\s+\S*\bimsg\b/);
         return hostOnlyMatch?.[1];
@@ -56,40 +52,31 @@ async function detectRemoteHostFromCliPath(cliPath) {
         return undefined;
     }
 }
-function normalizeReplyField(value) {
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        return trimmed ? trimmed : undefined;
-    }
-    if (typeof value === "number")
-        return String(value);
-    return undefined;
-}
-function describeReplyContext(message) {
-    const body = normalizeReplyField(message.reply_to_text);
-    if (!body)
-        return null;
-    const id = normalizeReplyField(message.reply_to_id);
-    const sender = normalizeReplyField(message.reply_to_sender);
-    return { body, id, sender };
-}
+/**
+ * Cache for recently sent messages, used for echo detection.
+ * Keys are scoped by conversation (accountId:target) so the same text in different chats is not conflated.
+ * Entries expire after 5 seconds; we do not forget on match so multiple echo deliveries are all filtered.
+ */
 class SentMessageCache {
     cache = new Map();
-    ttlMs = 5000;
+    ttlMs = 5000; // 5 seconds
     remember(scope, text) {
-        if (!text?.trim())
+        if (!text?.trim()) {
             return;
+        }
         const key = `${scope}:${text.trim()}`;
         this.cache.set(key, Date.now());
         this.cleanup();
     }
     has(scope, text) {
-        if (!text?.trim())
+        if (!text?.trim()) {
             return false;
+        }
         const key = `${scope}:${text.trim()}`;
         const timestamp = this.cache.get(key);
-        if (!timestamp)
+        if (!timestamp) {
             return false;
+        }
         const age = Date.now() - timestamp;
         if (age > this.ttlMs) {
             this.cache.delete(key);
@@ -100,8 +87,9 @@ class SentMessageCache {
     cleanup() {
         const now = Date.now();
         for (const [text, timestamp] of this.cache.entries()) {
-            if (now - timestamp > this.ttlMs)
+            if (now - timestamp > this.ttlMs) {
                 this.cache.delete(text);
+            }
         }
     }
 }
@@ -143,18 +131,10 @@ export async function monitorIMessageProvider(opts = {}) {
     const inboundDebouncer = createInboundDebouncer({
         debounceMs: inboundDebounceMs,
         buildKey: (entry) => {
-            // Use message-specific key to preserve attachments
-            // This prevents different messages from being merged incorrectly
             const sender = entry.message.sender?.trim();
-            if (!sender)
+            if (!sender) {
                 return null;
-            // Prefer message id for unique identification (prevents cross-message contamination)
-            // If id is not available, fall back to conversation-based key
-            const messageId = entry.message.id;
-            if (messageId != null) {
-                return `imessage:${accountInfo.accountId}:msg:${messageId}`;
             }
-            // Fallback to conversation-based key only when id is unavailable
             const conversationId = entry.message.chat_id != null
                 ? `chat:${entry.message.chat_id}`
                 : (entry.message.chat_guid ?? entry.message.chat_identifier ?? "unknown");
@@ -162,18 +142,19 @@ export async function monitorIMessageProvider(opts = {}) {
         },
         shouldDebounce: (entry) => {
             const text = entry.message.text?.trim() ?? "";
-            if (!text)
+            if (!text) {
                 return false;
-            // Messages with attachments should not be debounced across message boundaries
-            // to preserve attachment context
-            if (entry.message.attachments && entry.message.attachments.length > 0)
+            }
+            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)
+            if (!last) {
                 return;
+            }
             if (entries.length === 1) {
                 await handleMessageNow(last.message);
                 return;
@@ -185,9 +166,7 @@ export async function monitorIMessageProvider(opts = {}) {
             const syntheticMessage = {
                 ...last.message,
                 text: combinedText,
-                // Preserve attachments from the last message in the batch
-                // (should always be null here due to shouldDebounce guard, but keep for safety)
-                attachments: last.message.attachments ?? null,
+                attachments: null,
             };
             await handleMessageNow(syntheticMessage);
         },
@@ -196,140 +175,7 @@ export async function monitorIMessageProvider(opts = {}) {
         },
     });
     async function handleMessageNow(message) {
-        const senderRaw = message.sender ?? "";
-        const sender = senderRaw.trim();
-        if (!sender)
-            return;
-        const senderNormalized = normalizeIMessageHandle(sender);
-        if (message.is_from_me)
-            return;
-        const chatId = message.chat_id ?? undefined;
-        const chatGuid = message.chat_guid ?? undefined;
-        const chatIdentifier = message.chat_identifier ?? undefined;
-        const groupIdCandidate = chatId !== undefined ? String(chatId) : undefined;
-        const groupListPolicy = groupIdCandidate
-            ? resolveChannelGroupPolicy({
-                cfg,
-                channel: "imessage",
-                accountId: accountInfo.accountId,
-                groupId: groupIdCandidate,
-            })
-            : {
-                allowlistEnabled: false,
-                allowed: true,
-                groupConfig: undefined,
-                defaultConfig: undefined,
-            };
-        // Some iMessage threads can have multiple participants but still report
-        // is_group=false depending on how Messages stores the identifier.
-        // If the owner explicitly configures a chat_id under imessage.groups, treat
-        // that thread as a "group" for permission gating and session isolation.
-        const treatAsGroupByConfig = Boolean(groupIdCandidate && groupListPolicy.allowlistEnabled && groupListPolicy.groupConfig);
-        const isGroup = Boolean(message.is_group) || treatAsGroupByConfig;
-        if (isGroup && !chatId)
-            return;
-        const groupId = isGroup ? groupIdCandidate : undefined;
-        const storeAllowFrom = await readChannelAllowFromStore("imessage").catch(() => []);
-        const effectiveDmAllowFrom = Array.from(new Set([...allowFrom, ...storeAllowFrom]))
-            .map((v) => String(v).trim())
-            .filter(Boolean);
-        const effectiveGroupAllowFrom = Array.from(new Set([...groupAllowFrom, ...storeAllowFrom]))
-            .map((v) => String(v).trim())
-            .filter(Boolean);
-        if (isGroup) {
-            if (groupPolicy === "disabled") {
-                logVerbose("Blocked iMessage group message (groupPolicy: disabled)");
-                return;
-            }
-            if (groupPolicy === "allowlist") {
-                if (effectiveGroupAllowFrom.length === 0) {
-                    logVerbose("Blocked iMessage group message (groupPolicy: allowlist, no groupAllowFrom)");
-                    return;
-                }
-                const allowed = isAllowedIMessageSender({
-                    allowFrom: effectiveGroupAllowFrom,
-                    sender,
-                    chatId: chatId ?? undefined,
-                    chatGuid,
-                    chatIdentifier,
-                });
-                if (!allowed) {
-                    logVerbose(`Blocked iMessage sender ${sender} (not in groupAllowFrom)`);
-                    return;
-                }
-            }
-            if (groupListPolicy.allowlistEnabled && !groupListPolicy.allowed) {
-                logVerbose(`imessage: skipping group message (${groupId ?? "unknown"}) not in allowlist`);
-                return;
-            }
-        }
-        const dmHasWildcard = effectiveDmAllowFrom.includes("*");
-        const dmAuthorized = dmPolicy === "open"
-            ? true
-            : dmHasWildcard ||
-                (effectiveDmAllowFrom.length > 0 &&
-                    isAllowedIMessageSender({
-                        allowFrom: effectiveDmAllowFrom,
-                        sender,
-                        chatId: chatId ?? undefined,
-                        chatGuid,
-                        chatIdentifier,
-                    }));
-        if (!isGroup) {
-            if (dmPolicy === "disabled")
-                return;
-            if (!dmAuthorized) {
-                if (dmPolicy === "pairing") {
-                    const senderId = normalizeIMessageHandle(sender);
-                    const { code, created } = await upsertChannelPairingRequest({
-                        channel: "imessage",
-                        id: senderId,
-                        meta: {
-                            sender: senderId,
-                            chatId: chatId ? String(chatId) : undefined,
-                        },
-                    });
-                    if (created) {
-                        logVerbose(`imessage pairing request sender=${senderId}`);
-                        try {
-                            await sendMessageIMessage(sender, buildPairingReply({
-                                channel: "imessage",
-                                idLine: `Your iMessage sender id: ${senderId}`,
-                                code,
-                            }), {
-                                client,
-                                maxBytes: mediaMaxBytes,
-                                accountId: accountInfo.accountId,
-                                ...(chatId ? { chatId } : {}),
-                            });
-                        }
-                        catch (err) {
-                            logVerbose(`imessage pairing reply failed for ${senderId}: ${String(err)}`);
-                        }
-                    }
-                }
-                else {
-                    logVerbose(`Blocked iMessage sender ${sender} (dmPolicy=${dmPolicy})`);
-                }
-                return;
-            }
-        }
-        const route = resolveAgentRoute({
-            cfg,
-            channel: "imessage",
-            accountId: accountInfo.accountId,
-            peer: {
-                kind: isGroup ? "group" : "dm",
-                id: isGroup ? String(chatId ?? "unknown") : normalizeIMessageHandle(sender),
-            },
-        });
-        const mentionRegexes = buildMentionRegexes(cfg, route.agentId);
         const messageText = (message.text ?? "").trim();
-        const echoScope = `${accountInfo.accountId}:${isGroup ? formatIMessageChatTarget(chatId) : `imessage:${sender}`}`;
-        if (messageText && sentMessageCache.has(echoScope, messageText)) {
-            logVerbose(`imessage: skipping echo message (matches recently sent text within 5s): "${truncateUtf16Safe(messageText, 50)}"`);
-            return;
-        }
         const attachments = includeAttachments ? (message.attachments ?? []) : [];
         // Filter to valid attachments with paths
         const validAttachments = attachments.filter((entry) => entry?.original_path && !entry?.missing);
@@ -342,184 +188,94 @@ export async function monitorIMessageProvider(opts = {}) {
         const kind = mediaKindFromMime(mediaType ?? undefined);
         const placeholder = kind ? `<media:${kind}>` : attachments?.length ? "<media:attachment>" : "";
         const bodyText = messageText || placeholder;
-        if (!bodyText)
-            return;
-        const replyContext = describeReplyContext(message);
-        const createdAt = message.created_at ? Date.parse(message.created_at) : undefined;
-        const historyKey = isGroup
-            ? String(chatId ?? chatGuid ?? chatIdentifier ?? "unknown")
-            : undefined;
-        const mentioned = isGroup ? matchesMentionPatterns(messageText, mentionRegexes) : true;
-        const requireMention = resolveChannelGroupRequireMention({
+        const storeAllowFrom = await readChannelAllowFromStore("imessage").catch(() => []);
+        const decision = resolveIMessageInboundDecision({
             cfg,
-            channel: "imessage",
             accountId: accountInfo.accountId,
-            groupId,
-            requireMentionOverride: opts.requireMention,
-            overrideOrder: "before-config",
+            message,
+            opts,
+            messageText,
+            bodyText,
+            allowFrom,
+            groupAllowFrom,
+            groupPolicy,
+            dmPolicy,
+            storeAllowFrom,
+            historyLimit,
+            groupHistories,
+            echoCache: sentMessageCache,
+            logVerbose,
         });
-        const canDetectMention = mentionRegexes.length > 0;
-        const useAccessGroups = cfg.commands?.useAccessGroups !== false;
-        const ownerAllowedForCommands = effectiveDmAllowFrom.length > 0
-            ? isAllowedIMessageSender({
-                allowFrom: effectiveDmAllowFrom,
-                sender,
-                chatId: chatId ?? undefined,
-                chatGuid,
-                chatIdentifier,
-            })
-            : false;
-        const groupAllowedForCommands = effectiveGroupAllowFrom.length > 0
-            ? isAllowedIMessageSender({
-                allowFrom: effectiveGroupAllowFrom,
-                sender,
-                chatId: chatId ?? undefined,
-                chatGuid,
-                chatIdentifier,
-            })
-            : false;
-        const hasControlCommandInMessage = hasControlCommand(messageText, cfg);
-        const commandGate = resolveControlCommandGate({
-            useAccessGroups,
-            authorizers: [
-                { configured: effectiveDmAllowFrom.length > 0, allowed: ownerAllowedForCommands },
-                { configured: effectiveGroupAllowFrom.length > 0, allowed: groupAllowedForCommands },
-            ],
-            allowTextCommands: true,
-            hasControlCommand: hasControlCommandInMessage,
-        });
-        const commandAuthorized = isGroup ? commandGate.commandAuthorized : dmAuthorized;
-        if (isGroup && commandGate.shouldBlock) {
-            logInboundDrop({
-                log: logVerbose,
-                channel: "imessage",
-                reason: "control command (unauthorized)",
-                target: sender,
-            });
+        if (decision.kind === "drop") {
             return;
         }
-        const shouldBypassMention = isGroup && requireMention && !mentioned && commandAuthorized && hasControlCommandInMessage;
-        const effectiveWasMentioned = mentioned || shouldBypassMention;
-        if (isGroup && requireMention && canDetectMention && !mentioned && !shouldBypassMention) {
-            logVerbose(`imessage: skipping group message (no mention)`);
-            recordPendingHistoryEntryIfEnabled({
-                historyMap: groupHistories,
-                historyKey: historyKey ?? "",
-                limit: historyLimit,
-                entry: historyKey
-                    ? {
-                        sender: senderNormalized,
-                        body: bodyText,
-                        timestamp: createdAt,
-                        messageId: message.id ? String(message.id) : undefined,
-                    }
-                    : null,
+        const chatId = message.chat_id ?? undefined;
+        if (decision.kind === "pairing") {
+            const sender = (message.sender ?? "").trim();
+            if (!sender) {
+                return;
+            }
+            const { code, created } = await upsertChannelPairingRequest({
+                channel: "imessage",
+                id: decision.senderId,
+                meta: {
+                    sender: decision.senderId,
+                    chatId: chatId ? String(chatId) : undefined,
+                },
             });
+            if (created) {
+                logVerbose(`imessage pairing request sender=${decision.senderId}`);
+                try {
+                    await sendMessageIMessage(sender, buildPairingReply({
+                        channel: "imessage",
+                        idLine: `Your iMessage sender id: ${decision.senderId}`,
+                        code,
+                    }), {
+                        client,
+                        maxBytes: mediaMaxBytes,
+                        accountId: accountInfo.accountId,
+                        ...(chatId ? { chatId } : {}),
+                    });
+                }
+                catch (err) {
+                    logVerbose(`imessage pairing reply failed for ${decision.senderId}: ${String(err)}`);
+                }
+            }
             return;
         }
-        const chatTarget = formatIMessageChatTarget(chatId);
-        const fromLabel = formatInboundFromLabel({
-            isGroup,
-            groupLabel: message.chat_name ?? undefined,
-            groupId: chatId !== undefined ? String(chatId) : "unknown",
-            groupFallback: "Group",
-            directLabel: senderNormalized,
-            directId: sender,
-        });
         const storePath = resolveStorePath(cfg.session?.store, {
-            agentId: route.agentId,
+            agentId: decision.route.agentId,
         });
-        const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
         const previousTimestamp = readSessionUpdatedAt({
             storePath,
-            sessionKey: route.sessionKey,
+            sessionKey: decision.route.sessionKey,
         });
-        const replySuffix = replyContext
-            ? `\n\n[Replying to ${replyContext.sender ?? "unknown sender"}${replyContext.id ? ` id:${replyContext.id}` : ""}]\n${replyContext.body}\n[/Replying]`
-            : "";
-        const body = formatInboundEnvelope({
-            channel: "iMessage",
-            from: fromLabel,
-            timestamp: createdAt,
-            body: `${bodyText}${replySuffix}`,
-            chatType: isGroup ? "group" : "direct",
-            sender: { name: senderNormalized, id: sender },
+        const { ctxPayload, chatTarget } = buildIMessageInboundContext({
+            cfg,
+            decision,
+            message,
             previousTimestamp,
-            envelope: envelopeOptions,
-        });
-        let combinedBody = body;
-        if (isGroup && historyKey) {
-            combinedBody = buildPendingHistoryContextFromMap({
-                historyMap: groupHistories,
-                historyKey,
-                limit: historyLimit,
-                currentMessage: combinedBody,
-                formatEntry: (entry) => formatInboundEnvelope({
-                    channel: "iMessage",
-                    from: fromLabel,
-                    timestamp: entry.timestamp,
-                    body: `${entry.body}${entry.messageId ? ` [id:${entry.messageId}]` : ""}`,
-                    chatType: "group",
-                    senderLabel: entry.sender,
-                    envelope: envelopeOptions,
-                }),
-            });
-        }
-        const imessageTo = (isGroup ? chatTarget : undefined) || `imessage:${sender}`;
-        const inboundHistory = isGroup && historyKey && historyLimit > 0
-            ? (groupHistories.get(historyKey) ?? []).map((entry) => ({
-                sender: entry.sender,
-                body: entry.body,
-                timestamp: entry.timestamp,
-            }))
-            : undefined;
-        const ctxPayload = finalizeInboundContext({
-            Body: combinedBody,
-            BodyForAgent: bodyText,
-            InboundHistory: inboundHistory,
-            RawBody: bodyText,
-            CommandBody: bodyText,
-            From: isGroup ? `imessage:group:${chatId ?? "unknown"}` : `imessage:${sender}`,
-            To: imessageTo,
-            SessionKey: route.sessionKey,
-            AccountId: route.accountId,
-            ChatType: isGroup ? "group" : "direct",
-            ConversationLabel: fromLabel,
-            GroupSubject: isGroup ? (message.chat_name ?? undefined) : undefined,
-            GroupMembers: isGroup ? (message.participants ?? []).filter(Boolean).join(", ") : undefined,
-            SenderName: senderNormalized,
-            SenderId: sender,
-            Provider: "imessage",
-            Surface: "imessage",
-            MessageSid: message.id ? String(message.id) : undefined,
-            ReplyToId: replyContext?.id,
-            ReplyToBody: replyContext?.body,
-            ReplyToSender: replyContext?.sender,
-            Timestamp: createdAt,
-            MediaPath: mediaPath,
-            MediaType: mediaType,
-            MediaUrl: mediaPath,
-            MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
-            MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
-            MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
-            MediaRemoteHost: remoteHost,
-            WasMentioned: effectiveWasMentioned,
-            CommandAuthorized: commandAuthorized,
-            // Originating channel for reply routing.
-            OriginatingChannel: "imessage",
-            OriginatingTo: imessageTo,
+            remoteHost,
+            historyLimit,
+            groupHistories,
+            media: {
+                path: mediaPath,
+                type: mediaType,
+                paths: mediaPaths,
+                types: mediaTypes,
+            },
         });
-        const updateTarget = (isGroup ? chatTarget : undefined) || sender;
+        const updateTarget = chatTarget || decision.sender;
         await recordInboundSession({
             storePath,
-            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+            sessionKey: ctxPayload.SessionKey ?? decision.route.sessionKey,
             ctx: ctxPayload,
-            updateLastRoute: !isGroup && updateTarget
+            updateLastRoute: !decision.isGroup && updateTarget
                 ? {
-                    sessionKey: route.mainSessionKey,
+                    sessionKey: decision.route.mainSessionKey,
                     channel: "imessage",
                     to: updateTarget,
-                    accountId: route.accountId,
+                    accountId: decision.route.accountId,
                 }
                 : undefined,
             onRecordError: (err) => {
@@ -527,18 +283,27 @@ export async function monitorIMessageProvider(opts = {}) {
             },
         });
         if (shouldLogVerbose()) {
-            const preview = truncateUtf16Safe(body, 200).replace(/\n/g, "\\n");
-            logVerbose(`imessage inbound: chatId=${chatId ?? "unknown"} from=${ctxPayload.From} len=${body.length} preview="${preview}"`);
+            const preview = truncateUtf16Safe(String(ctxPayload.Body ?? ""), 200).replace(/\n/g, "\\n");
+            logVerbose(`imessage inbound: chatId=${chatId ?? "unknown"} from=${ctxPayload.From} len=${String(ctxPayload.Body ?? "").length} preview="${preview}"`);
         }
-        const prefixContext = createReplyPrefixContext({ cfg, agentId: route.agentId });
+        const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+            cfg,
+            agentId: decision.route.agentId,
+            channel: "imessage",
+            accountId: decision.route.accountId,
+        });
         const dispatcher = createReplyDispatcher({
-            responsePrefix: prefixContext.responsePrefix,
-            responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
-            humanDelay: resolveHumanDelayConfig(cfg, route.agentId),
+            ...prefixOptions,
+            humanDelay: resolveHumanDelayConfig(cfg, decision.route.agentId),
             deliver: async (payload) => {
+                const target = ctxPayload.To;
+                if (!target) {
+                    runtime.error?.(danger("imessage: missing delivery target"));
+                    return;
+                }
                 await deliverReplies({
                     replies: [payload],
-                    target: ctxPayload.To,
+                    target,
                     client,
                     accountId: accountInfo.accountId,
                     runtime,
@@ -559,28 +324,33 @@ export async function monitorIMessageProvider(opts = {}) {
                 disableBlockStreaming: typeof accountInfo.config.blockStreaming === "boolean"
                     ? !accountInfo.config.blockStreaming
                     : undefined,
-                onModelSelected: prefixContext.onModelSelected,
+                onModelSelected,
             },
         });
         if (!queuedFinal) {
-            if (isGroup && historyKey) {
+            if (decision.isGroup && decision.historyKey) {
                 clearHistoryEntriesIfEnabled({
                     historyMap: groupHistories,
-                    historyKey,
+                    historyKey: decision.historyKey,
                     limit: historyLimit,
                 });
             }
             return;
         }
-        if (isGroup && historyKey) {
-            clearHistoryEntriesIfEnabled({ historyMap: groupHistories, historyKey, limit: historyLimit });
+        if (decision.isGroup && decision.historyKey) {
+            clearHistoryEntriesIfEnabled({
+                historyMap: groupHistories,
+                historyKey: decision.historyKey,
+                limit: historyLimit,
+            });
         }
     }
     const handleMessage = async (raw) => {
-        const params = raw;
-        const message = params?.message ?? null;
-        if (!message)
+        const message = parseIMessageNotification(raw);
+        if (!message) {
+            logVerbose("imessage: dropping malformed RPC message payload");
             return;
+        }
         await inboundDebouncer.enqueue({ message });
     };
     await waitForTransportReady({
@@ -593,16 +363,18 @@ export async function monitorIMessageProvider(opts = {}) {
         runtime,
         check: async () => {
             const probe = await probeIMessage(probeTimeoutMs, { cliPath, dbPath, runtime });
-            if (probe.ok)
+            if (probe.ok) {
                 return { ok: true };
+            }
             if (probe.fatal) {
                 throw new Error(probe.error ?? "imsg rpc unavailable");
             }
             return { ok: false, error: probe.error ?? "unreachable" };
         },
     });
-    if (opts.abortSignal?.aborted)
+    if (opts.abortSignal?.aborted) {
         return;
+    }
     const client = await createIMessageRpcClient({
         cliPath,
         dbPath,
@@ -620,21 +392,11 @@ export async function monitorIMessageProvider(opts = {}) {
     });
     let subscriptionId = null;
     const abort = opts.abortSignal;
-    const onAbort = () => {
-        if (subscriptionId) {
-            void client
-                .request("watch.unsubscribe", {
-                subscription: subscriptionId,
-            })
-                .catch(() => {
-                // Ignore disconnect errors during shutdown.
-            });
-        }
-        void client.stop().catch(() => {
-            // Ignore disconnect errors during shutdown.
-        });
-    };
-    abort?.addEventListener("abort", onAbort, { once: true });
+    const detachAbortHandler = attachIMessageMonitorAbortHandler({
+        abortSignal: abort,
+        client,
+        getSubscriptionId: () => subscriptionId,
+    });
     try {
         const result = await client.request("watch.subscribe", {
             attachments: includeAttachments,
@@ -643,13 +405,14 @@ export async function monitorIMessageProvider(opts = {}) {
         await client.waitForClose();
     }
     catch (err) {
-        if (abort?.aborted)
+        if (abort?.aborted) {
             return;
+        }
         runtime.error?.(danger(`imessage: monitor failed: ${String(err)}`));
         throw err;
     }
     finally {
-        abort?.removeEventListener("abort", onAbort);
+        detachAbortHandler();
         await client.stop();
     }
 }