@elizaos/agent 2.0.0-alpha.358 → 2.0.0-alpha.376

package/plugins/plugin-imessage/typescript/src/service.js

@@ -1,1116 +0,0 @@
-/**
- * iMessage service implementation for ElizaOS.
- */
-import { exec } from "node:child_process";
-import { existsSync } from "node:fs";
-import { platform } from "node:os";
-import { promisify } from "node:util";
-import { ChannelType, ContentType, createUniqueUuid, EventType, logger, MemoryType, Service, } from "@elizaos/core";
-import { DEFAULT_CHAT_DB_PATH, getLastChatDbAccessIssue, openChatDb, } from "./chatdb-reader.js";
-import { addContact, deleteContact, listAllContacts, loadContacts, normalizeContactHandle, updateContact, } from "./contacts-reader.js";
-import { DEFAULT_POLL_INTERVAL_MS, formatPhoneNumber, IMESSAGE_SERVICE_NAME, IMessageCliError, IMessageConfigurationError, IMessageEventTypes, IMessageNotSupportedError, isPhoneNumber, splitMessageForIMessage, } from "./types.js";
-const execAsync = promisify(exec);
-/**
- * iMessage service for ElizaOS agents.
- * Note: This only works on macOS.
- */
-export class IMessageService extends Service {
-    static serviceType = IMESSAGE_SERVICE_NAME;
-    capabilityDescription = "iMessage service for sending and receiving messages on macOS";
-    settings = null;
-    connected = false;
-    pollInterval = null;
-    /**
-     * Highest `message.ROWID` we've already dispatched to the agent. The
-     * polling loop asks chat.db for rows strictly greater than this value,
-     * then advances the cursor to the largest row it actually processed.
-     * Initialized to 0 on start; bumped on every successful dispatch so
-     * we skip backlog on a fresh launch without ever double-delivering.
-     */
-    lastRowId = 0;
-    /**
-     * Reentrancy gate for the polling loop. Dispatch calls
-     * `messageService.handleMessage` which invokes the LLM and typically
-     * takes several seconds per message. With a 2-second poll interval
-     * that means multiple ticks can land on top of each other, each
-     * seeing the same stale cursor and re-dispatching the same rows.
-     * This flag ensures at most one poll is in flight at a time; ticks
-     * that arrive while a poll is active are dropped (the next scheduled
-     * tick will pick up where the current one left off).
-     */
-    pollInFlight = false;
-    /**
-     * Room keys we've already emitted a WORLD_JOINED event for in this
-     * service lifetime. Not persisted — on restart every room is
-     * re-greeted, which is correct: a fresh Milady process doesn't know
-     * what previous processes already synced, and the bootstrap plugin's
-     * WORLD_JOINED handler is idempotent (handleServerSync tolerates
-     * already-known rooms via upsert semantics).
-     */
-    seenWorlds = new Set();
-    /**
-     * Entity keys we've already emitted an ENTITY_JOINED event for.
-     * Same lifetime + rationale as seenWorlds.
-     */
-    seenEntities = new Set();
-    /**
-     * Live chat.db handle, bound to the lifetime of this service. Non-null
-     * means inbound polling is active. Null means either (a) not running
-     * under Bun, or (b) chat.db couldn't be opened — in both cases the
-     * service remains send-only and logs a one-time warning on start.
-     */
-    chatDb = null;
-    chatDbPath = DEFAULT_CHAT_DB_PATH;
-    /**
-     * Cached handle → display name map from the user's Apple Contacts.
-     * Populated once on service start via AppleScript against Contacts.app
-     * and used to rewrite raw phone numbers and email addresses into real
-     * contact names in Memory metadata. Empty map means either the user
-     * hasn't authorized Contacts access yet or the address book is empty.
-     */
-    contacts = new Map();
-    /**
-     * Start the iMessage service.
-     */
-    static async start(runtime) {
-        logger.info("Starting iMessage service...");
-        const service = new IMessageService(runtime);
-        // Check if running on macOS
-        if (!service.isMacOS()) {
-            throw new IMessageNotSupportedError();
-        }
-        // Load settings
-        service.settings = service.loadSettings();
-        await service.validateSettings();
-        // Open chat.db for inbound polling. A null return here is non-fatal —
-        // the service degrades to send-only and logs its own warning. We seed
-        // the polling cursor from the current tip of the database so a freshly
-        // started agent doesn't re-process its entire message backlog.
-        service.chatDbPath = service.settings.dbPath || DEFAULT_CHAT_DB_PATH;
-        service.chatDb = await openChatDb(service.chatDbPath);
-        if (service.chatDb) {
-            const tip = service.chatDb.getLatestRowId();
-            // Resolve IMESSAGE_BACKFILL from every plausible source — character
-            // settings (runtime.getSetting), the raw process env, and the
-            // character's settings object. Whichever arrives first wins.
-            const settingFromRuntime = typeof service.runtime?.getSetting === "function"
-                ? service.runtime.getSetting("IMESSAGE_BACKFILL")
-                : undefined;
-            const settingFromEnv = process.env.IMESSAGE_BACKFILL;
-            const resolvedRaw = (typeof settingFromRuntime === "string" && settingFromRuntime) || settingFromEnv || "";
-            const backfill = Math.max(0, Number(resolvedRaw) || 0);
-            service.lastRowId = Math.max(0, tip - backfill);
-            logger.debug(`[imessage][boot] dbPath=${service.chatDbPath} tip=${tip} backfillRaw=${JSON.stringify(resolvedRaw)} backfillResolved=${backfill} lastRowId=${service.lastRowId}`);
-            logger.info(`[imessage] chat.db opened, inbound polling ready (cursor starts at ROWID ${service.lastRowId}, backfilled ${backfill} from tip ${tip})`);
-        }
-        // Load the Apple Contacts map so we can turn raw phone numbers and
-        // email addresses into real names when building Memory objects for
-        // inbound messages. Failure here is non-fatal — the service proceeds
-        // with anonymous handles and logs its own warning.
-        service.contacts = await loadContacts();
-        // Start polling only when chat.db is available. When the database cannot
-        // be opened, the service is intentionally send-only until the next start.
-        if (service.chatDb && service.settings.pollIntervalMs > 0) {
-            service.startPolling();
-        }
-        else if (!service.chatDb && service.settings.pollIntervalMs > 0) {
-            logger.debug("[imessage] inbound polling not started because chat.db is unavailable");
-        }
-        // Register the heartbeat task worker + create a recurring task.
-        // See registerHeartbeat for what it actually does. We gate on the
-        // existence of runtime.registerTaskWorker to stay compatible with
-        // older cores that predate the task system.
-        await service.registerHeartbeat();
-        service.connected = true;
-        logger.info("iMessage service started");
-        // Emit connection ready event
-        runtime.emitEvent(IMessageEventTypes.CONNECTION_READY, {
-            runtime,
-            service,
-        });
-        return service;
-    }
-    /**
-     * Stop the iMessage service.
-     */
-    async stop() {
-        logger.info("Stopping iMessage service...");
-        this.connected = false;
-        if (this.pollInterval) {
-            clearInterval(this.pollInterval);
-            this.pollInterval = null;
-        }
-        if (this.chatDb) {
-            this.chatDb.close();
-            this.chatDb = null;
-        }
-        this.settings = null;
-        this.lastRowId = 0;
-        logger.info("iMessage service stopped");
-    }
-    /**
-     * Check if the service is connected.
-     */
-    isConnected() {
-        return this.connected;
-    }
-    getStatus() {
-        const chatDbAvailable = this.chatDb !== null;
-        const accessIssue = chatDbAvailable ? null : getLastChatDbAccessIssue(this.chatDbPath);
-        return {
-            available: true,
-            connected: this.connected,
-            chatDbAvailable,
-            sendOnly: this.connected && !chatDbAvailable,
-            chatDbPath: this.chatDbPath,
-            reason: accessIssue?.reason ?? (chatDbAvailable ? null : "chat.db reader not available"),
-            permissionAction: accessIssue?.permissionAction ?? null,
-        };
-    }
-    /**
-     * Check if running on macOS.
-     */
-    isMacOS() {
-        return platform() === "darwin";
-    }
-    /**
-     * Send a message via iMessage.
-     */
-    async sendMessage(to, text, options) {
-        if (!this.settings) {
-            return { success: false, error: "Service not initialized" };
-        }
-        // Format phone number if needed
-        const target = isPhoneNumber(to) ? formatPhoneNumber(to) : to;
-        // Split message if too long
-        const chunks = splitMessageForIMessage(text);
-        for (const chunk of chunks) {
-            const result = await this.sendSingleMessage(target, chunk, options);
-            if (!result.success) {
-                return result;
-            }
-        }
-        // Emit sent events — both the plugin-namespaced form (for iMessage-
-        // specific listeners) and the generic core EventType.MESSAGE_SENT
-        // so trajectory loggers, analytics, and any plugin hooking into
-        // the standard event bus see outbound iMessage sends the same way
-        // they see Telegram / Discord / Slack sends.
-        if (this.runtime) {
-            this.runtime.emitEvent(IMessageEventTypes.MESSAGE_SENT, {
-                runtime: this.runtime,
-                source: "imessage",
-                to: target,
-                text,
-                hasMedia: Boolean(options?.mediaUrl),
-            });
-            this.runtime.emitEvent(EventType.MESSAGE_SENT, {
-                runtime: this.runtime,
-                source: "imessage",
-                message: {
-                    id: createUniqueUuid(this.runtime, `imessage-outbound-${Date.now()}`),
-                    entityId: this.runtime.agentId,
-                    agentId: this.runtime.agentId,
-                    roomId: createUniqueUuid(this.runtime, target),
-                    content: { text, source: "imessage" },
-                    createdAt: Date.now(),
-                },
-            });
-        }
-        return {
-            success: true,
-            messageId: Date.now().toString(),
-            chatId: target,
-        };
-    }
-    /**
-     * Get recent messages by reading chat.db. Returns the most recent
-     * `limit` messages (any sender, any chat) in chronological order.
-     *
-     * Returns an empty array if the chat.db reader is unavailable (plugin
-     * running under plain Node without bun:sqlite, or Full Disk Access not
-     * granted, etc.).
-     */
-    async getRecentMessages(limit = 50) {
-        return this.getMessages({ limit });
-    }
-    /**
-     * Return the newest messages in chronological order, optionally scoped
-     * to a single chat identifier. Returns an empty array if chat.db is not
-     * available and the connector is currently running in send-only mode.
-     */
-    async getMessages(options = {}) {
-        if (!this.chatDb) {
-            return [];
-        }
-        const rows = this.chatDb.listMessages(options);
-        return rows.map(chatDbMessageToPublicShape);
-    }
-    /**
-     * List every chat the Messages.app database knows about, joined with
-     * participant handles. Returns an empty list if the chat.db reader is
-     * unavailable (Node runtime, missing FDA, etc.).
-     *
-     * Previously this method used an AppleScript stub against
-     * Messages.app's `chats` collection. That verb works but is slow and
-     * returns a coarser view (no participant handles, no style field), so
-     * the chat.db path is strictly better when it's available.
-     */
-    async getChats() {
-        if (!this.chatDb) {
-            return [];
-        }
-        // Convert the reader's richer ChatDbChatSummary into the plugin's
-        // public IMessageChat shape for backwards-compat with consumers of
-        // the existing IIMessageService interface. Callers that want the
-        // richer fields (serviceName, last read timestamp) can go straight
-        // to the reader via `chatDb.listChats()`.
-        return this.chatDb.listChats().map((c) => ({
-            chatId: c.chatId,
-            chatType: c.chatType,
-            displayName: c.displayName ?? undefined,
-            participants: c.participants.map((handle) => ({
-                handle,
-                isPhoneNumber: /^\+?\d{7,}$/.test(handle),
-            })),
-        }));
-    }
-    /**
-     * Get current settings.
-     */
-    getSettings() {
-        return this.settings;
-    }
-    /**
-     * Get the cached Apple Contacts map loaded at service start.
-     *
-     * Keys are normalized handles (phones in digits-only + optional leading `+`,
-     * emails lowercased). Values carry the contact's display name.
-     *
-     * Exposed for providers that want to inject contact lookups into agent
-     * state so the LLM can resolve a person's name ("text Shaw") to a handle
-     * it can pass to `sendMessage`.
-     *
-     * Returns an empty map if Contacts access was denied, failed to load,
-     * or the service hasn't finished starting.
-     */
-    getContacts() {
-        return this.contacts;
-    }
-    /**
-     * List every contact in the user's address book as a full record with
-     * id, name, and all phones/emails. Delegates to contacts-reader's
-     * `listAllContacts` which goes through Contacts.app's AppleScript
-     * dump. Returns `[]` on failure (permission denied, etc.).
-     */
-    async listAllContacts() {
-        return listAllContacts();
-    }
-    /**
-     * Create a new contact in Contacts.app. Requires Contacts WRITE
-     * permission (macOS prompts on first call). Returns the new person's
-     * id on success, or null on failure.
-     *
-     * After a successful create we refresh the cached handle→name map so
-     * inbound messages from the new contact resolve to their name on the
-     * very next poll, without requiring a service restart.
-     */
-    async addContact(input) {
-        const id = await addContact(input);
-        if (id) {
-            this.contacts = await loadContacts();
-        }
-        return id;
-    }
-    /**
-     * Patch an existing contact (name fields, add/remove phones, add/remove
-     * emails). Returns true on success, false on failure. Refreshes the
-     * cached map on success so name resolution reflects the change.
-     */
-    async updateContact(personId, patch) {
-        const ok = await updateContact(personId, patch);
-        if (ok) {
-            this.contacts = await loadContacts();
-        }
-        return ok;
-    }
-    /**
-     * Delete a contact by Contacts.app id. Returns true on success,
-     * false on failure. Refreshes the cached map on success.
-     */
-    async deleteContact(personId) {
-        const ok = await deleteContact(personId);
-        if (ok) {
-            this.contacts = await loadContacts();
-        }
-        return ok;
-    }
-    // Private methods
-    loadSettings() {
-        if (!this.runtime) {
-            throw new IMessageConfigurationError("Runtime not initialized");
-        }
-        const getStringSetting = (key, envKey, defaultValue = "") => {
-            const value = this.runtime?.getSetting(key);
-            if (typeof value === "string")
-                return value;
-            return process.env[envKey] || defaultValue;
-        };
-        const cliPath = getStringSetting("IMESSAGE_CLI_PATH", "IMESSAGE_CLI_PATH", "imsg");
-        const dbPath = getStringSetting("IMESSAGE_DB_PATH", "IMESSAGE_DB_PATH") || undefined;
-        const pollIntervalRaw = getStringSetting("IMESSAGE_POLL_INTERVAL_MS", "IMESSAGE_POLL_INTERVAL_MS");
-        const parsedPollIntervalMs = Number(pollIntervalRaw);
-        const pollIntervalMs = pollIntervalRaw.trim() === "" || !Number.isFinite(parsedPollIntervalMs)
-            ? DEFAULT_POLL_INTERVAL_MS
-            : Math.max(0, parsedPollIntervalMs);
-        const dmPolicy = getStringSetting("IMESSAGE_DM_POLICY", "IMESSAGE_DM_POLICY", "pairing");
-        const groupPolicy = getStringSetting("IMESSAGE_GROUP_POLICY", "IMESSAGE_GROUP_POLICY", "allowlist");
-        const allowFromRaw = getStringSetting("IMESSAGE_ALLOW_FROM", "IMESSAGE_ALLOW_FROM");
-        const allowFrom = allowFromRaw
-            ? allowFromRaw
-                .split(",")
-                .map((s) => s.trim())
-                .filter(Boolean)
-            : [];
-        const enabledRaw = getStringSetting("IMESSAGE_ENABLED", "IMESSAGE_ENABLED", "true");
-        const enabled = enabledRaw !== "false";
-        return {
-            cliPath,
-            dbPath,
-            pollIntervalMs,
-            dmPolicy,
-            groupPolicy,
-            allowFrom,
-            enabled,
-        };
-    }
-    async validateSettings() {
-        if (!this.settings) {
-            throw new IMessageConfigurationError("Settings not loaded");
-        }
-        // Check if CLI tool exists (if specified and not default)
-        if (this.settings.cliPath !== "imsg") {
-            if (!existsSync(this.settings.cliPath)) {
-                logger.warn(`iMessage CLI not found at ${this.settings.cliPath}, will use AppleScript`);
-            }
-        }
-        // Check if Messages app is accessible
-        try {
-            await this.runAppleScript('tell application "Messages" to return 1');
-        }
-        catch (_error) {
-            throw new IMessageConfigurationError("Cannot access Messages app. Ensure Full Disk Access is granted.");
-        }
-    }
-    async sendSingleMessage(to, text, options) {
-        // Try CLI first if available
-        if (this.settings?.cliPath && this.settings.cliPath !== "imsg") {
-            try {
-                return await this.sendViaCli(to, text, options);
-            }
-            catch (error) {
-                logger.debug(`CLI send failed, falling back to AppleScript: ${error}`);
-            }
-        }
-        // Fall back to AppleScript
-        return await this.sendViaAppleScript(to, text, options);
-    }
-    async sendViaCli(to, text, options) {
-        if (!this.settings) {
-            return { success: false, error: "Service not initialized" };
-        }
-        const args = [to, text];
-        if (options?.mediaUrl) {
-            args.push("--attachment", options.mediaUrl);
-        }
-        try {
-            await execAsync(`"${this.settings.cliPath}" ${args.map((a) => `"${a}"`).join(" ")}`);
-            return { success: true, messageId: Date.now().toString(), chatId: to };
-        }
-        catch (error) {
-            const err = error;
-            throw new IMessageCliError(err.message || "CLI command failed", err.code);
-        }
-    }
-    async sendViaAppleScript(to, text, options) {
-        const escapedText = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-        const isChatTarget = to.startsWith("chat_id:");
-        const chatId = isChatTarget ? to.slice(8) : null;
-        // Build the `set target...` clause once — used by both the text
-        // send and the (optional) attachment send below.
-        const targetBlock = isChatTarget
-            ? `set targetRef to chat id "${chatId}"`
-            : `
-        set targetService to 1st account whose service type = iMessage
-        set targetRef to participant "${to}" of targetService
-      `;
-        // Text body (possibly empty if caller is attachment-only).
-        if (text && text.length > 0) {
-            const textScript = `
-        tell application "Messages"
-          ${targetBlock}
-          send "${escapedText}" to targetRef
-        end tell
-      `;
-            try {
-                await this.runAppleScript(textScript);
-            }
-            catch (error) {
-                return { success: false, error: `AppleScript error: ${error}` };
-            }
-        }
-        // Attachment, if any. Messages.app's scripting dictionary accepts a
-        // file as the direct-parameter of `send`, so we resolve the media
-        // path to a POSIX file and hand it to the same `send` verb. Works
-        // for images, video, audio, PDFs, anything Messages.app would let
-        // you drag into the compose area.
-        if (options?.mediaUrl) {
-            const mediaPath = options.mediaUrl.startsWith("file://")
-                ? options.mediaUrl.slice(7)
-                : options.mediaUrl;
-            const escapedMediaPath = mediaPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-            const attachmentScript = `
-        tell application "Messages"
-          ${targetBlock}
-          send (POSIX file "${escapedMediaPath}") to targetRef
-        end tell
-      `;
-            try {
-                await this.runAppleScript(attachmentScript);
-            }
-            catch (error) {
-                return {
-                    success: false,
-                    error: `AppleScript attachment error: ${error}`,
-                };
-            }
-        }
-        return { success: true, messageId: Date.now().toString(), chatId: to };
-    }
-    async runAppleScript(script) {
-        try {
-            const { stdout } = await execAsync(`osascript -e '${script.replace(/'/g, "'\"'\"'")}'`);
-            return stdout.trim();
-        }
-        catch (error) {
-            const err = error;
-            throw new Error(err.stderr || err.message || "AppleScript execution failed");
-        }
-    }
-    startPolling() {
-        if (!this.settings) {
-            return;
-        }
-        this.pollInterval = setInterval(async () => {
-            try {
-                await this.pollForNewMessages();
-            }
-            catch (error) {
-                logger.debug(`Polling error: ${error}`);
-            }
-        }, this.settings.pollIntervalMs);
-    }
-    /**
-     * Poll chat.db for rows newer than the cursor and route each inbound
-     * message through the agent's message pipeline.
-     *
-     * Flow per message:
-     *   1. Read new rows from chat.db via the bun:sqlite reader.
-     *   2. Skip outbound (is_from_me=1), already-seen, and policy-denied rows.
-     *   3. Build a Memory object in the shape the bootstrap plugin expects.
-     *   4. Ensure the entity + room + world exist via ensureConnection.
-     *   5. Call runtime.messageService.handleMessage with a callback that
-     *      sends the agent's reply back through sendViaAppleScript.
-     *   6. Also emit the plugin-namespaced IMESSAGE_MESSAGE_RECEIVED event
-     *      and the core EventType.MESSAGE_RECEIVED event for any listeners.
-     *
-     * Advances this.lastRowId unconditionally to the max rowId we saw in
-     * this batch — even for skipped rows — so the cursor keeps moving
-     * forward and we never get stuck re-reading the same row on every poll.
-     */
-    async pollForNewMessages() {
-        if (!this.runtime || !this.chatDb) {
-            return;
-        }
-        // Reentrancy gate — see field-level comment on pollInFlight.
-        if (this.pollInFlight) {
-            return;
-        }
-        this.pollInFlight = true;
-        try {
-            await this.pollForNewMessagesInner();
-        }
-        finally {
-            this.pollInFlight = false;
-        }
-    }
-    async pollForNewMessagesInner() {
-        if (!this.runtime || !this.chatDb)
-            return;
-        // Cap batch size to 50 to keep per-tick latency bounded on busy
-        // inboxes. If traffic exceeds that, subsequent ticks catch up.
-        const batch = this.chatDb.fetchNewMessages(this.lastRowId, 50);
-        if (batch.length === 0) {
-            return;
-        }
-        // CRITICAL: advance the cursor synchronously, BEFORE any async
-        // dispatch work. If we advance after the for loop, a slow dispatch
-        // gives setInterval time to fire the next tick, which would re-read
-        // the stale cursor and re-dispatch the same rows. Since chat.db's
-        // ROWID is monotonic, we know every row in `batch` is unique and
-        // each has rowId > sinceRowId, so advancing to the max NOW is safe
-        // even if individual dispatches fail later.
-        const maxRowIdInBatch = batch.reduce((max, row) => (row.rowId > max ? row.rowId : max), this.lastRowId);
-        this.lastRowId = maxRowIdInBatch;
-        logger.debug(`[imessage][poll-start] fetched=${batch.length} cursor advanced to ${this.lastRowId}`);
-        for (const row of batch) {
-            // Skip outbound messages — the agent sent these itself via AppleScript,
-            // we don't want it reacting to its own output.
-            if (row.isFromMe) {
-                continue;
-            }
-            // Policy gate: DM allowlist, group allowlist, disabled, etc.
-            if (!this.isAllowed(row.handle)) {
-                continue;
-            }
-            // Skip non-text rows for the main dispatch path. Reactions and
-            // system events still emit their own plugin-namespaced events
-            // below so downstream listeners can react to them, but they
-            // don't flow through messageService.handleMessage (which is
-            // for conversational turns only).
-            if (row.kind !== "text") {
-                this.emitAuxiliaryEvent(row);
-                continue;
-            }
-            // Undecodable text (attributedBody decode miss) would produce an
-            // empty-string turn the agent has nothing to do with. Skip with a
-            // debug log so the cursor still advances.
-            if (!row.text || row.text.trim().length === 0) {
-                logger.debug(`[imessage] skipping ROWID=${row.rowId} — text column and attributedBody both empty after decode`);
-                continue;
-            }
-            logger.debug(`[imessage][dispatch] ROWID=${row.rowId} handle=${row.handle} text="${row.text.slice(0, 40)}"`);
-            try {
-                await this.dispatchInboundMessage(row);
-            }
-            catch (error) {
-                logger.error(`[imessage] Failed to dispatch inbound message ROWID=${row.rowId}: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-        logger.debug(`[imessage][poll-end] done. lastRowId=${this.lastRowId}`);
-    }
-    /**
-     * Turn a single chat.db row into a `Memory`, wire up a reply callback,
-     * and hand the whole thing to `runtime.messageService.handleMessage`.
-     *
-     * Mirrors the shape used by @elizaos/plugin-telegram so the bootstrap
-     * plugin's message pipeline picks up inbound iMessages the same way it
-     * picks up Telegram messages — same entity/room/world creation, same
-     * `source: "imessage"` tag on content, same HandlerCallback signature
-     * for the reply path.
-     */
-    async dispatchInboundMessage(row) {
-        if (!this.runtime)
-            return;
-        // chat_identifier is stable across messages in the same chat; use it
-        // as the room key. Fall back to the handle for the edge case where
-        // chat_message_join is empty (shouldn't happen on a healthy chat.db).
-        const roomKey = row.chatId || row.handle || `imessage-room-${row.rowId}`;
-        const entityKey = row.handle || roomKey;
-        const entityId = createUniqueUuid(this.runtime, entityKey);
-        const roomId = createUniqueUuid(this.runtime, roomKey);
-        const worldId = createUniqueUuid(this.runtime, `imessage-world-${roomKey}`);
-        // Key the Memory id by the chat.db message guid, not the ROWID —
-        // guids are stable across restarts and CloudKit syncs, so reply
-        // threading (which targets guids) can resolve via createUniqueUuid
-        // against the same key.
-        const messageId = createUniqueUuid(this.runtime, `imessage-guid-${row.guid}`);
-        const channelType = row.chatType === "group" ? ChannelType.GROUP : ChannelType.DM;
-        // Resolve the sender handle against the Apple Contacts map loaded at
-        // service start. On a miss we fall back to the raw handle, so the
-        // conversation still works — it just looks uglier in logs and state.
-        const resolvedContact = this.contacts.get(normalizeContactHandle(row.handle)) ?? null;
-        const resolvedName = resolvedContact?.name ?? null;
-        // Make sure the agent's memory store knows about this entity + room +
-        // world before we try to persist a Memory into it — otherwise FK
-        // constraints fire downstream.
-        await this.runtime.ensureConnection({
-            entityId,
-            roomId,
-            worldId,
-            source: "imessage",
-            channelId: roomKey,
-            type: channelType,
-            name: resolvedName ?? row.displayName ?? row.handle ?? undefined,
-            worldName: row.displayName ? `imessage-chat-${row.displayName}` : `imessage-chat-${roomKey}`,
-            userName: resolvedName ?? row.handle ?? undefined,
-        });
-        // Lifecycle events — WORLD_JOINED + ENTITY_JOINED fire ONCE per
-        // room/entity per service lifetime. These are the architectural
-        // signals that Milady's bootstrap plugin and any other observer
-        // (trajectory logger, analytics, onboarding flows) subscribe to in
-        // order to sync data, update rosters, or trigger side effects.
-        // Without them, a plugin that writes Memories directly via
-        // createMemory leaves observers in the dark about new rooms.
-        if (!this.seenWorlds.has(roomKey)) {
-            this.seenWorlds.add(roomKey);
-            this.runtime.emitEvent(EventType.WORLD_JOINED, {
-                runtime: this.runtime,
-                source: "imessage",
-                world: {
-                    id: worldId,
-                    name: row.displayName ? `imessage-chat-${row.displayName}` : `imessage-chat-${roomKey}`,
-                    agentId: this.runtime.agentId,
-                    serverId: roomKey,
-                    metadata: {
-                        type: channelType,
-                        chatId: roomKey,
-                        displayName: row.displayName ?? undefined,
-                    },
-                },
-                rooms: [
-                    {
-                        id: roomId,
-                        name: row.displayName ?? roomKey,
-                        type: channelType,
-                        source: "imessage",
-                        worldId,
-                        channelId: roomKey,
-                        serverId: roomKey,
-                        agentId: this.runtime.agentId,
-                        metadata: { chatType: row.chatType },
-                    },
-                ],
-                entities: [],
-            });
-            logger.debug(`[imessage][world-joined] roomKey=${roomKey}`);
-        }
-        if (!this.seenEntities.has(entityKey)) {
-            this.seenEntities.add(entityKey);
-            this.runtime.emitEvent(EventType.ENTITY_JOINED, {
-                runtime: this.runtime,
-                source: "imessage",
-                entityId,
-                worldId,
-                roomId,
-                metadata: {
-                    originalId: row.handle,
-                    username: row.handle,
-                    displayName: resolvedName ?? row.handle,
-                    type: channelType,
-                },
-            });
-            logger.debug(`[imessage][entity-joined] entityKey=${entityKey} name=${resolvedName ?? row.handle}`);
-        }
-        // Resolve the in-reply-to link. If this message is an inline reply to
-        // an earlier one, we build the same UUID the earlier dispatch would
-        // have used (same rule: `imessage-${rowId}` keyed off the reader's
-        // stable guid), so the agent's threading actually resolves. We don't
-        // know the target's ROWID from the guid alone without an extra query,
-        // but createUniqueUuid is content-addressable — hashing the guid gives
-        // the same UUID the original dispatch did if we key both on guid.
-        const inReplyTo = row.replyToGuid
-            ? createUniqueUuid(this.runtime, `imessage-guid-${row.replyToGuid}`)
-            : undefined;
-        const memoryContent = {
-            text: row.text,
-            source: "imessage",
-            channelType,
-            ...(inReplyTo ? { inReplyTo } : {}),
-            ...(row.attachments.length > 0
-                ? {
-                    attachments: row.attachments.map((a) => ({
-                        id: a.guid,
-                        url: "",
-                        title: a.filename ?? a.guid,
-                        contentType: mimeToContentType(a.mimeType, a.uti),
-                        source: "imessage",
-                        description: a.isSticker ? "sticker" : (a.filename ?? a.mimeType ?? a.uti ?? ""),
-                        text: "",
-                    })),
-                }
-                : {}),
-        };
-        const memory = {
-            id: messageId,
-            entityId,
-            agentId: this.runtime.agentId,
-            roomId,
-            content: memoryContent,
-            // The core `MemoryMetadata` type constrains its keys to a fixed set
-            // (`type`, `source`, etc.), so we stash plugin-specific fields by
-            // widening via an unknown cast. Downstream providers read these
-            // keys dynamically so the static shape doesn't matter at runtime.
-            metadata: {
-                type: MemoryType.MESSAGE,
-                source: "imessage",
-                // Raw handle + resolved contact name for chatContextProvider.
-                ...(row.handle ? { imessageHandle: row.handle } : {}),
-                ...(resolvedName ? { imessageContactName: resolvedName } : {}),
-                // Delivery service: iMessage / SMS / RCS.
-                ...(row.service ? { imessageService: row.service } : {}),
-                // Stable correlation keys across restarts.
-                imessageGuid: row.guid,
-                imessageRowId: row.rowId,
-                // Editing / retraction state for downstream filters.
-                ...(row.dateEdited ? { imessageEditedAt: row.dateEdited } : {}),
-                ...(row.dateRetracted ? { imessageRetractedAt: row.dateRetracted } : {}),
-            },
-            createdAt: row.timestamp || Date.now(),
-        };
-        // Reply callback: when the agent produces a response, send it back out
-        // through the existing AppleScript send path. For groups we send to
-        // `chat_id:<identifier>` so AppleScript targets the whole chat; for
-        // DMs we target the sender's handle directly.
-        const replyTarget = row.chatType === "group" ? `chat_id:${row.chatId}` : row.handle;
-        const callback = async (content) => {
-            const replyText = content.text?.trim();
-            if (!replyText || !this.runtime) {
-                return [];
-            }
-            const sendResult = await this.sendViaAppleScript(replyTarget, replyText);
-            if (!sendResult.success) {
-                logger.error(`[imessage] Reply send failed for ROWID=${row.rowId}: ${sendResult.error}`);
-                return [];
-            }
-            const responseMemory = {
-                id: createUniqueUuid(this.runtime, `imessage-reply-${row.rowId}-${Date.now()}`),
-                entityId: this.runtime.agentId,
-                agentId: this.runtime.agentId,
-                roomId,
-                content: {
-                    ...content,
-                    source: "imessage",
-                    channelType,
-                    inReplyTo: messageId,
-                },
-                metadata: {
-                    type: MemoryType.MESSAGE,
-                    source: "imessage",
-                },
-                createdAt: Date.now(),
-            };
-            await this.runtime.createMemory(responseMemory, "messages");
-            return [responseMemory];
-        };
-        // Emit the plugin-namespaced event for any iMessage-specific listeners
-        // (kept for backwards compatibility with pre-fix code) and the generic
-        // core event so anything subscribed to EventType.MESSAGE_RECEIVED sees it.
-        this.runtime.emitEvent(IMessageEventTypes.MESSAGE_RECEIVED, {
-            runtime: this.runtime,
-            message: memory,
-            source: "imessage",
-            callback,
-        });
-        this.runtime.emitEvent(EventType.MESSAGE_RECEIVED, {
-            runtime: this.runtime,
-            message: memory,
-            source: "imessage",
-            callback,
-        });
-        // Route through the message service — this is what actually triggers
-        // the agent's decision pipeline (shouldRespond → generate → callback).
-        if (!this.runtime.messageService) {
-            logger.error("[imessage] runtime.messageService is null; cannot route inbound message. " +
-                "Ensure the bootstrap plugin (or a custom IMessageService) is registered " +
-                "before the iMessage plugin starts.");
-            return;
-        }
-        await this.runtime.messageService.handleMessage(this.runtime, memory, callback);
-    }
-    /**
-     * Handle non-conversational chat.db rows — reactions, group events,
-     * anything that isn't a normal text turn. These shouldn't flow through
-     * `messageService.handleMessage` (which would try to generate a reply)
-     * but they're still useful to surface as plugin-namespaced events so
-     * listeners can react, log, or update state.
-     *
-     * Emits two events:
-     *   - A plugin-namespaced event on the existing `IMessageEventTypes`
-     *     enum (e.g. `IMESSAGE_REACTION_RECEIVED`).
-     *   - The generic `EventType.REACTION_RECEIVED` from core when the
-     *     row is a reaction, so core-level handlers see it.
-     */
-    emitAuxiliaryEvent(row) {
-        if (!this.runtime)
-            return;
-        if (row.kind === "reaction" && row.reaction) {
-            logger.debug(`[imessage] reaction ${row.reaction.add ? "+" : "-"}${row.reaction.kind} on guid=${row.reaction.targetGuid} by ${row.handle}`);
-            this.runtime.emitEvent(IMessageEventTypes.REACTION_RECEIVED, {
-                runtime: this.runtime,
-                source: "imessage",
-                chatId: row.chatId,
-                handle: row.handle,
-                targetGuid: row.reaction.targetGuid,
-                reactionKind: row.reaction.kind,
-                add: row.reaction.add,
-                emoji: row.reaction.emoji,
-                service: row.service,
-            });
-            this.runtime.emitEvent(EventType.REACTION_RECEIVED, {
-                runtime: this.runtime,
-                source: "imessage",
-                targetGuid: row.reaction.targetGuid,
-                reactionKind: row.reaction.kind,
-                add: row.reaction.add,
-                emoji: row.reaction.emoji,
-            });
-            return;
-        }
-        if (row.kind === "system") {
-            logger.debug(`[imessage] system event ROWID=${row.rowId} handle=${row.handle} chat=${row.chatId}`);
-            // No core equivalent — plugin-namespaced only.
-            this.runtime.emitEvent("IMESSAGE_SYSTEM_EVENT", {
-                runtime: this.runtime,
-                source: "imessage",
-                chatId: row.chatId,
-                handle: row.handle,
-                rowId: row.rowId,
-                guid: row.guid,
-            });
-        }
-    }
-    isAllowed(handle) {
-        if (!this.settings) {
-            return false;
-        }
-        if (this.settings.dmPolicy === "open") {
-            return true;
-        }
-        if (this.settings.dmPolicy === "disabled") {
-            return false;
-        }
-        if (this.settings.dmPolicy === "allowlist") {
-            return this.settings.allowFrom.some((allowed) => allowed.toLowerCase() === handle.toLowerCase());
-        }
-        // pairing - allow and track
-        return true;
-    }
-    /**
-     * Register a recurring heartbeat task with Milady's task system and
-     * kick off one if it isn't already queued.
-     *
-     * The heartbeat runs once a minute (configurable via
-     * `IMESSAGE_HEARTBEAT_INTERVAL_MS`) and does a lightweight health
-     * probe: (a) chat.db reader is still open and responsive,
-     * (b) Contacts map still populated, (c) polling cursor is advancing
-     * when expected. On failure it logs + emits
-     * `IMESSAGE_HEARTBEAT_UNHEALTHY`; on success it emits
-     * `IMESSAGE_HEARTBEAT_OK`. Observers (Milady's heartbeat UI, ops
-     * dashboards, trajectory logger) subscribe to these events.
-     *
-     * The task is tagged `["queue", "repeat", "imessage"]` so Milady's
-     * built-in TaskService picks it up via its standard polling loop.
-     * Without `updateInterval` being set in metadata, the task fires
-     * once and then deletes; with it, the task service re-schedules.
-     */
-    async registerHeartbeat() {
-        if (!this.runtime)
-            return;
-        const taskRuntime = this.runtime;
-        if (typeof taskRuntime.registerTaskWorker !== "function") {
-            logger.debug("[imessage][heartbeat] runtime does not support registerTaskWorker — skipping");
-            return;
-        }
-        const heartbeatIntervalMs = Number(process.env.IMESSAGE_HEARTBEAT_INTERVAL_MS) || 60_000;
-        taskRuntime.registerTaskWorker({
-            name: "IMESSAGE_HEARTBEAT",
-            execute: async (runtime, _options, _task) => {
-                let ok = true;
-                let reason = "";
-                let tip = 0;
-                let contactsCount = 0;
-                try {
-                    if (!this.chatDb) {
-                        ok = false;
-                        reason = "chat.db reader not available (send-only mode)";
-                    }
-                    else {
-                        tip = this.chatDb.getLatestRowId();
-                        if (tip <= 0) {
-                            ok = false;
-                            reason = "chat.db getLatestRowId returned 0";
-                        }
-                    }
-                    contactsCount = this.contacts.size;
-                }
-                catch (err) {
-                    ok = false;
-                    reason = err instanceof Error ? err.message : String(err);
-                }
-                logger.debug(`[imessage][heartbeat] ok=${ok} tip=${tip} cursor=${this.lastRowId} contacts=${contactsCount}${reason ? ` reason=${reason}` : ""}`);
-                runtime.emitEvent(ok ? "IMESSAGE_HEARTBEAT_OK" : "IMESSAGE_HEARTBEAT_UNHEALTHY", {
-                    runtime,
-                    source: "imessage",
-                    ok,
-                    reason,
-                    tip,
-                    cursor: this.lastRowId,
-                    contactsCount,
-                    connected: this.connected,
-                    timestamp: Date.now(),
-                });
-            },
-            validate: async () => true,
-        });
-        // Only create the task if one doesn't already exist. This is safe
-        // across restarts — on a cold boot no task exists yet, on a warm
-        // restart the previous one is still in the queue and we skip.
-        if (typeof taskRuntime.getTasksByName === "function") {
-            try {
-                const existing = await taskRuntime.getTasksByName("IMESSAGE_HEARTBEAT");
-                if (Array.isArray(existing) && existing.length > 0) {
-                    logger.debug(`[imessage][heartbeat] task already registered (${existing.length} existing) — skipping createTask`);
-                    return;
-                }
-            }
-            catch {
-                // If the query fails, fall through and try createTask anyway.
-            }
-        }
-        if (typeof taskRuntime.createTask === "function") {
-            try {
-                await taskRuntime.createTask({
-                    name: "IMESSAGE_HEARTBEAT",
-                    description: "Periodic health probe for the iMessage connector (chat.db reader, contacts, polling cursor).",
-                    metadata: {
-                        updatedAt: Date.now(),
-                        updateInterval: heartbeatIntervalMs,
-                        blocking: true,
-                    },
-                    tags: ["queue", "repeat", "imessage"],
-                });
-                logger.debug(`[imessage][heartbeat] task registered, interval ${heartbeatIntervalMs}ms`);
-            }
-            catch (err) {
-                logger.warn(`[imessage][heartbeat] createTask failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-}
-/**
- * Resolve a chat.db attachment's mime/UTI to one of the five ContentType
- * buckets the core Memory.content type accepts. Anything we can't bucket
- * falls back to `"document"` which is the catch-all.
- */
-function mimeToContentType(mimeType, uti) {
-    const m = (mimeType ?? "").toLowerCase();
-    const u = (uti ?? "").toLowerCase();
-    if (m.startsWith("image/") || u.includes("image"))
-        return ContentType.IMAGE;
-    if (m.startsWith("video/") || u.includes("movie") || u.includes("video")) {
-        return ContentType.VIDEO;
-    }
-    if (m.startsWith("audio/") || u.includes("audio"))
-        return ContentType.AUDIO;
-    return ContentType.DOCUMENT;
-}
-/**
- * Convert a `ChatDbMessage` (the shape the bun:sqlite reader returns)
- * into the public `IMessageMessage` shape exposed by this plugin's API.
- * Exported so the test suite can exercise it in isolation without
- * spinning up a full runtime + service instance.
- */
-export function chatDbMessageToPublicShape(row) {
-    return {
-        id: String(row.rowId),
-        text: row.text,
-        handle: row.handle,
-        chatId: row.chatId,
-        timestamp: row.timestamp,
-        isFromMe: row.isFromMe,
-        hasAttachments: row.attachments.length > 0,
-        ...(row.attachments.length > 0
-            ? {
-                attachmentPaths: row.attachments
-                    .map((attachment) => attachment.filename)
-                    .filter((filename) => Boolean(filename)),
-            }
-            : {}),
-    };
-}
-/**
- * Parse tab-delimited AppleScript messages output.
- * Expected format per line: "id\ttext\tdate_sent\tis_from_me\tchat_identifier\tsender"
- */
-export function parseMessagesFromAppleScript(result) {
-    const messages = [];
-    if (!result?.trim()) {
-        return messages;
-    }
-    for (const line of result.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
-        const fields = trimmed.split("\t");
-        if (fields.length < 6) {
-            continue;
-        }
-        const [id, text, dateSent, isFromMeStr, chatIdentifier, sender] = fields;
-        const isFromMe = isFromMeStr === "1" || isFromMeStr.toLowerCase() === "true";
-        let timestamp;
-        const parsed = Number(dateSent);
-        if (!Number.isNaN(parsed) && parsed > 0) {
-            timestamp = parsed;
-        }
-        else {
-            const dateObj = new Date(dateSent);
-            timestamp = Number.isNaN(dateObj.getTime()) ? 0 : dateObj.getTime();
-        }
-        messages.push({
-            id: id || "",
-            text: text || "",
-            handle: sender || "",
-            chatId: chatIdentifier || "",
-            timestamp,
-            isFromMe,
-            hasAttachments: false,
-        });
-    }
-    return messages;
-}
-/**
- * Parse tab-delimited AppleScript chats output.
- * Expected format per line: "chat_identifier\tdisplay_name\tparticipant_count\tlast_message_date"
- */
-export function parseChatsFromAppleScript(result) {
-    const chats = [];
-    if (!result?.trim()) {
-        return chats;
-    }
-    const listStyleEntryPattern = /\{\s*"([^"]*)"\s*,\s*(?:"([^"]*)"|(missing value))\s*\}/g;
-    const listStyleMatches = Array.from(result.matchAll(listStyleEntryPattern));
-    if (listStyleMatches.length > 0) {
-        for (const match of listStyleMatches) {
-            const chatIdentifier = match[1] ?? "";
-            const displayName = match[2];
-            chats.push({
-                chatId: chatIdentifier,
-                chatType: chatIdentifier.includes(";+;") ? "group" : "direct",
-                displayName: displayName || undefined,
-                participants: [],
-            });
-        }
-        return chats;
-    }
-    for (const line of result.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
-        const fields = trimmed.split("\t");
-        if (fields.length < 4) {
-            continue;
-        }
-        const [chatIdentifier, displayName, participantCountStr] = fields;
-        const participantCount = Number(participantCountStr) || 0;
-        const chatType = participantCount > 1 ? "group" : "direct";
-        chats.push({
-            chatId: chatIdentifier || "",
-            chatType,
-            displayName: displayName || undefined,
-            participants: [],
-        });
-    }
-    return chats;
-}