@spinabot/brigade 1.6.1 → 1.8.0

package/dist/agents/channels/bluebubbles/connection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * BlueBubbles transport connection — webhook-in + REST-out.
+ *
+ * Unlike a polling channel there is no socket to open: inbound arrives via the
+ * gateway webhook route, which calls `feedWebhookEvent(eventType, payload)` on
+ * the started adapter (bridged through `account-registry.ts` on the multi-account
+ * path). This module owns BOTH directions:
+ *
+ *   INBOUND  `feedWebhookEvent` → normalize (defensive) → dedupe (claim-once) →
+ *            tapback-drop → defer media download → `onMessage`.
+ *   OUTBOUND `sendText` (bubble-split into N text POSTs), `sendMedia` (multipart
+ *            upload + caption as a SEPARATE bubble after), plus `react`/`edit`/
+ *            `unsend` for `handleAction`.
+ *
+ * `fetch` is INJECTABLE end-to-end (threaded into every REST call), so the whole
+ * connection is exercised in tests with no live server. Private-API status is
+ * cached from the last probe and gates the rich actions.
+ */
+import { type InboundMediaAttachment, type OutboundMedia, type OutboundSendOptions } from "../sdk.js";
+import type { ResolvedBlueBubblesAccount } from "./account-config.js";
+import { type NormalizedBlueBubblesMessage } from "./normalize.js";
+import { type BlueBubblesCatchupSummary } from "./catchup.js";
+import type { BlueBubblesCursorStore } from "./catchup-cursor.js";
+import type { FetchLike } from "./types.js";
+/** The inbound message handed to the adapter (carries the deferred-media thunk). */
+export interface BlueBubblesInboundMessage extends NormalizedBlueBubblesMessage {
+    resolveMedia?: () => Promise<InboundMediaAttachment[]>;
+}
+/** Optional note emitted when an inbound tapback is observed (surfaced as a system line). */
+export interface BlueBubblesTapbackNote {
+    emoji: string;
+    action: "added" | "removed";
+    chatGuid: string;
+    conversationId: string;
+    from: string;
+    isGroup: boolean;
+    targetGuid?: string;
+}
+export interface ConnectBlueBubblesArgs {
+    account: ResolvedBlueBubblesAccount;
+    log: (msg: string, meta?: Record<string, unknown>) => void;
+    /** Dispatched inbound (post normalize + dedupe). */
+    onMessage: (msg: BlueBubblesInboundMessage) => void;
+    /** Optional inbound tapback observation (when `actions.reactions` is on). */
+    onTapback?: (note: BlueBubblesTapbackNote) => void;
+    /** Private-API status from the last probe (gates rich actions). null = unknown. */
+    privateApi?: boolean | null;
+    /** macOS MAJOR version of the BlueBubbles host from the last probe (gates `edit` on ≥ 26). null = unknown. */
+    macOSMajor?: number | null;
+    /** TEST SEAM — inject a mock fetch for every REST call. */
+    fetchImpl?: FetchLike;
+    /** TEST SEAM — override the late-index attachment re-fetch delay (ms). Default 2000. */
+    attachmentRefetchDelayMs?: number;
+    /** TEST SEAM — inject the catch-up cursor store (default: filesystem under the channel state dir). */
+    catchupCursorStore?: BlueBubblesCursorStore;
+}
+/** The live connection handle the adapter drives. */
+export interface BlueBubblesConnection {
+    feedWebhookEvent(eventType: string | undefined, payload: unknown): void;
+    sendText(conversationId: string, text: string, opts?: OutboundSendOptions): Promise<{
+        messageId?: string;
+    }>;
+    sendMedia(conversationId: string, media: OutboundMedia): Promise<{
+        messageId?: string;
+    }>;
+    react(params: {
+        conversationId: string;
+        messageId: string;
+        reaction: string;
+    }): Promise<void>;
+    edit(params: {
+        messageId: string;
+        text: string;
+    }): Promise<void>;
+    unsend(params: {
+        messageId: string;
+    }): Promise<void>;
+    /** Signal "typing…" (or stop) in a conversation. Cosmetic; no-ops when the Private API is off. */
+    setTyping(conversationId: string, typing: boolean): Promise<void>;
+    /** Mark a conversation read (read receipt). Cosmetic; no-ops when the Private API is off. */
+    markRead(conversationId: string): Promise<void>;
+    /** Run a bounded backfill of recently-missed messages through the live inbound path. */
+    runCatchup(): Promise<BlueBubblesCatchupSummary>;
+    setPrivateApi(status: boolean | null): void;
+    /** Update the probed macOS major version (gates `edit` on ≥ 26). */
+    setMacOSMajor(major: number | null): void;
+    connectedAt(): number | null;
+    close(): void;
+}
+/**
+ * Build a BlueBubbles connection. Synchronous — there is nothing to connect to
+ * (inbound is push); the returned handle wires inbound + outbound.
+ */
+export declare function connectBlueBubbles(args: ConnectBlueBubblesArgs): BlueBubblesConnection;
+//# sourceMappingURL=connection.d.ts.map

package/dist/agents/channels/bluebubbles/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/connection.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/bluebubbles/connection.js

@@ -0,0 +1,413 @@
+/**
+ * BlueBubbles transport connection — webhook-in + REST-out.
+ *
+ * Unlike a polling channel there is no socket to open: inbound arrives via the
+ * gateway webhook route, which calls `feedWebhookEvent(eventType, payload)` on
+ * the started adapter (bridged through `account-registry.ts` on the multi-account
+ * path). This module owns BOTH directions:
+ *
+ *   INBOUND  `feedWebhookEvent` → normalize (defensive) → dedupe (claim-once) →
+ *            tapback-drop → defer media download → `onMessage`.
+ *   OUTBOUND `sendText` (bubble-split into N text POSTs), `sendMedia` (multipart
+ *            upload + caption as a SEPARATE bubble after), plus `react`/`edit`/
+ *            `unsend` for `handleAction`.
+ *
+ * `fetch` is INJECTABLE end-to-end (threaded into every REST call), so the whole
+ * connection is exercised in tests with no live server. Private-API status is
+ * cached from the last probe and gates the rich actions.
+ */
+import path from "node:path";
+import { createDedupeCache, ensureDir, resolveOsCacheDir, } from "../sdk.js";
+import { BLUEBUBBLES_DEDUPE_MAX_ENTRIES, BLUEBUBBLES_DEDUPE_TTL_MS, resolveBlueBubblesDedupeKey } from "./dedupe.js";
+import { isUnderAllowedRoot, resolveOutboundAttachment } from "../imessage/media.js";
+import { markdownToIMessageText, resolveDeliveredText, sanitizeOutboundIMessageText } from "../imessage/format.js";
+import { downloadInboundAttachments, fetchBlueBubblesMessageAttachments, resolveOutboundVoiceAttachment } from "./media.js";
+import { normalizeBlueBubblesWebhook } from "./normalize.js";
+import { bubbleSplit, editBlueBubblesMessage, reactBlueBubbles, resolveChatGuid, sendBlueBubblesAttachment, sendBlueBubblesText, unsendBlueBubblesMessage, } from "./send.js";
+import { markBlueBubblesChatRead, sendBlueBubblesTyping } from "./chat.js";
+import { peekBlueBubblesContactName, warmBlueBubblesContactDirectory } from "./contact-names.js";
+import { runBlueBubblesCatchup } from "./catchup.js";
+import { createBlueBubblesInboundDebouncer } from "./debounce.js";
+import { fetchBlueBubblesHistory, renderBlueBubblesHistoryBlock } from "./history.js";
+import { isMacOSEditUnsupported } from "./probe.js";
+/** Delay before the single late-index attachment re-fetch (BB indexes media ~2s after the webhook). */
+const BLUEBUBBLES_ATTACHMENT_REFETCH_DELAY_MS = 2_000;
+/**
+ * Build a BlueBubbles connection. Synchronous — there is nothing to connect to
+ * (inbound is push); the returned handle wires inbound + outbound.
+ */
+export function connectBlueBubbles(args) {
+    const { account } = args;
+    let privateApi = args.privateApi ?? null;
+    let macOSMajor = args.macOSMajor ?? null;
+    const connectedAtMs = Date.now();
+    const dedupe = createDedupeCache({
+        maxEntries: BLUEBUBBLES_DEDUPE_MAX_ENTRIES,
+        ttlMs: BLUEBUBBLES_DEDUPE_TTL_MS,
+    });
+    const cacheDir = path.join(resolveOsCacheDir(), "bluebubbles", account.accountId, "inbound-media");
+    // Optional inbound coalescing: when `inboundDebounceMs > 0`, a text + its
+    // link-preview balloon (or a text + a split-out attachment) arriving as TWO
+    // `new-message` webhooks are merged into ONE turn. Default 0 = disabled =
+    // the historical synchronous dispatch path (unchanged behaviour).
+    const debounceMs = account.inboundDebounceMs ?? 0;
+    const debouncer = debounceMs > 0
+        ? createBlueBubblesInboundDebouncer({
+            accountId: account.accountId,
+            debounceMs,
+            dispatch: (msg) => args.onMessage(msg),
+            ...(account.verbose ? { log: (m) => args.log(m) } : {}),
+        })
+        : null;
+    /** Dispatch an inbound — through the debouncer when enabled, else straight to `onMessage`. */
+    const dispatchInbound = (msg) => {
+        if (debouncer)
+            debouncer.enqueue(msg);
+        else
+            args.onMessage(msg);
+    };
+    /** Shared args for a rolling-history fetch. */
+    const historyArgs = () => ({
+        serverUrl: account.serverUrl,
+        password: account.password,
+        ...(account.probeTimeoutMs !== undefined ? { timeoutMs: account.probeTimeoutMs } : {}),
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    });
+    /**
+     * Resolve the rolling-history limit that applies to THIS inbound. Group
+     * messages use `historyLimit`; DMs use `dmHistoryLimit`. History is attached
+     * only for an UNTAGGED message (no self-mention, not itself a reply) — a tagged
+     * or reply message already carries its own context. Returns 0 (skip) otherwise.
+     */
+    const historyLimitFor = (msg) => {
+        if (msg.mentions && msg.mentions.length > 0)
+            return 0;
+        if (msg.replyToGuid)
+            return 0;
+        if (!msg.text || !msg.text.trim())
+            return 0;
+        return msg.isGroup ? account.historyLimit : account.dmHistoryLimit;
+    };
+    /**
+     * Dispatch an inbound, first fetching + PREPENDING rolling-history context when
+     * it applies (untagged group/DM message, limit > 0). The history fetch is
+     * bounded + never throws; on any failure the message dispatches with no context.
+     * When history doesn't apply, dispatch is synchronous (unchanged behaviour).
+     */
+    const dispatchWithHistory = (msg) => {
+        const limit = historyLimitFor(msg);
+        if (limit <= 0) {
+            dispatchInbound(msg);
+            return;
+        }
+        void (async () => {
+            try {
+                const { entries } = await fetchBlueBubblesHistory(msg.chatGuid, limit, historyArgs());
+                // Drop the current message from the tail if the listing already includes it.
+                const prior = entries.filter((e) => !msg.messageGuid || e.messageId !== msg.messageGuid);
+                const block = renderBlueBubblesHistoryBlock(prior);
+                if (block) {
+                    msg.text = `${block}\n\n${msg.text}`;
+                }
+            }
+            catch {
+                /* best-effort — dispatch without context */
+            }
+            dispatchInbound(msg);
+        })();
+    };
+    const restBase = () => ({
+        serverUrl: account.serverUrl,
+        password: account.password,
+        timeoutMs: account.probeTimeoutMs,
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        privateApiEnabled: privateApi === true,
+        ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    });
+    const contactArgs = () => ({
+        serverUrl: account.serverUrl,
+        password: account.password,
+        accountId: account.accountId,
+        ...(account.probeTimeoutMs !== undefined ? { timeoutMs: account.probeTimeoutMs } : {}),
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    });
+    /**
+     * Resolve an inbound sender handle → a human display name, SYNCHRONOUSLY, from
+     * the already-warm per-account contact directory (no network on the hot path,
+     * so dispatch stays synchronous). On a cache miss, kick a background warm so
+     * the NEXT message from this sender resolves. Mutates `fromName` in place when
+     * a cached name is found; the raw handle flows otherwise.
+     */
+    const enrichFromNameSync = (inbound) => {
+        if (inbound.fromName && inbound.fromName.trim())
+            return;
+        if (!inbound.from || !inbound.from.trim())
+            return;
+        const cached = peekBlueBubblesContactName(inbound.from, account.accountId);
+        if (cached) {
+            inbound.fromName = cached;
+            return;
+        }
+        // Cold cache — warm it in the background (best-effort, never throws).
+        void warmBlueBubblesContactDirectory(contactArgs()).catch(() => { });
+    };
+    const downloadArgs = () => ({
+        serverUrl: account.serverUrl,
+        password: account.password,
+        cacheDir,
+        maxBytes: account.mediaMaxBytes,
+        timeoutMs: account.probeTimeoutMs,
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    });
+    const refetchArgs = () => ({
+        serverUrl: account.serverUrl,
+        password: account.password,
+        ...(account.probeTimeoutMs !== undefined ? { timeoutMs: account.probeTimeoutMs } : {}),
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    });
+    /** Wait the late-index delay (skippable in tests). */
+    const refetchDelay = async () => {
+        const delayMs = args.attachmentRefetchDelayMs ?? BLUEBUBBLES_ATTACHMENT_REFETCH_DELAY_MS;
+        if (delayMs <= 0)
+            return;
+        await new Promise((resolve) => {
+            const t = setTimeout(resolve, delayMs);
+            if (typeof t.unref === "function")
+                t.unref();
+        });
+    };
+    const feedWebhookEvent = (eventType, payload) => {
+        const allowed = new Set(["new-message", "updated-message", undefined]);
+        if (eventType && !allowed.has(eventType))
+            return;
+        const result = normalizeBlueBubblesWebhook(payload, eventType, account.selfHandle);
+        if (result.kind === "skip") {
+            // An "empty message" with a guid MIGHT be a media message whose
+            // attachments indexed late. Kick a SINGLE bounded background re-fetch; if
+            // media turns up, dispatch a synthetic inbound (deferred-media thunk).
+            // A genuinely empty message finds nothing and is never dispatched (no
+            // agent spam). Dedupe still guards against a follow-up `updated-message`.
+            if (result.mediaCandidate) {
+                const cand = result.mediaCandidate;
+                const key = resolveBlueBubblesDedupeKey(account.accountId, payload, eventType);
+                if (key && !dedupe.claim(key)) {
+                    if (account.verbose)
+                        args.log("inbound dropped: duplicate");
+                    return;
+                }
+                void (async () => {
+                    try {
+                        await refetchDelay();
+                        const refetched = await fetchBlueBubblesMessageAttachments(cand.messageGuid, refetchArgs());
+                        if (refetched.length === 0)
+                            return;
+                        if (account.verbose)
+                            args.log(`attachment late-index re-fetch found ${refetched.length} for ${cand.messageGuid}`);
+                        const inbound = {
+                            conversationId: `chat_guid:${cand.chatGuid}`,
+                            chatGuid: cand.chatGuid,
+                            messageGuid: cand.messageGuid,
+                            from: cand.from,
+                            ...(cand.fromName ? { fromName: cand.fromName } : {}),
+                            text: "",
+                            isGroup: cand.isGroup,
+                            ...(cand.timestampMs !== undefined ? { timestampMs: cand.timestampMs } : {}),
+                            attachments: refetched,
+                            raw: payload,
+                            resolveMedia: async () => downloadInboundAttachments(refetched, downloadArgs()),
+                        };
+                        enrichFromNameSync(inbound);
+                        dispatchInbound(inbound);
+                    }
+                    catch (err) {
+                        if (account.verbose)
+                            args.log(`attachment re-fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                })();
+                return;
+            }
+            if (account.verbose)
+                args.log(`inbound dropped: ${result.reason}`);
+            return;
+        }
+        if (result.kind === "tapback") {
+            // Tapbacks are dropped as normal messages; optionally surface a note.
+            if (account.actions.reactions && args.onTapback) {
+                args.onTapback({
+                    emoji: result.tapback.emoji,
+                    action: result.tapback.action,
+                    chatGuid: result.chatGuid,
+                    conversationId: `chat_guid:${result.chatGuid}`,
+                    from: result.from,
+                    isGroup: result.isGroup,
+                    ...(result.targetGuid ? { targetGuid: result.targetGuid } : {}),
+                });
+            }
+            return;
+        }
+        // Dedupe (claim-once) — BlueBubbles replays its lookback window on restart.
+        const key = resolveBlueBubblesDedupeKey(account.accountId, payload, eventType);
+        if (key && !dedupe.claim(key)) {
+            if (account.verbose)
+                args.log("inbound dropped: duplicate");
+            return;
+        }
+        const message = result.message;
+        const inbound = { ...message };
+        if (message.attachments.length > 0) {
+            inbound.resolveMedia = async () => downloadInboundAttachments(message.attachments, downloadArgs());
+        }
+        else if (message.messageGuid && eventType === "updated-message") {
+            // An `updated-message` follow-up with text but no attachments may carry
+            // media that indexed late. Defer a SINGLE bounded re-fetch (short delay →
+            // `message/{guid}` → download); resolves [] when there was truly none.
+            inbound.resolveMedia = async () => {
+                await refetchDelay();
+                const refetched = await fetchBlueBubblesMessageAttachments(message.messageGuid, refetchArgs());
+                if (refetched.length === 0)
+                    return [];
+                if (account.verbose)
+                    args.log(`attachment late-index re-fetch found ${refetched.length} for ${message.messageGuid}`);
+                return downloadInboundAttachments(refetched, downloadArgs());
+            };
+        }
+        // Resolve a human display name for the sender from the warm cache (sync) and
+        // dispatch — a cold cache warms in the background for next time. An untagged
+        // group/DM message first picks up rolling-history context (when configured).
+        enrichFromNameSync(inbound);
+        dispatchWithHistory(inbound);
+    };
+    const sendText = async (conversationId, text, opts) => {
+        const base = restBase();
+        const chatGuid = await resolveChatGuid(base, conversationId);
+        // Strip internal directive tags / role scaffolding / reasoning residue
+        // (the outbound twin of the reflection guard) BEFORE bubble-splitting.
+        const bubbles = bubbleSplit(sanitizeOutboundIMessageText(markdownToIMessageText(text)));
+        if (bubbles.length === 0)
+            return {};
+        let lastMessageId;
+        let first = true;
+        for (const bubble of bubbles) {
+            const sent = await sendBlueBubblesText(chatGuid, bubble, {
+                ...base,
+                // Native reply target applies to the FIRST bubble only.
+                ...(first && opts?.replyToId ? { replyToMessageGuid: opts.replyToId } : {}),
+            });
+            if (sent.messageId)
+                lastMessageId = sent.messageId;
+            first = false;
+        }
+        return lastMessageId ? { messageId: lastMessageId } : {};
+    };
+    const sendMedia = async (conversationId, media) => {
+        const base = restBase();
+        const chatGuid = await resolveChatGuid(base, conversationId);
+        // Validate + size-cap the local path (central exfil/denylist guard).
+        const resolved = resolveOutboundAttachment(media.path, account.mediaMaxBytes);
+        // Layer the per-account local-root ALLOW-LIST on top of the central denylist:
+        // when configured, an attachment must resolve UNDER one of the allowed roots.
+        if (account.mediaLocalRoots.length > 0 && !isUnderAllowedRoot(resolved.path, account.mediaLocalRoots)) {
+            throw new Error(`BlueBubbles refused to attach "${media.path}": path is outside the allowed media roots (channels.bluebubbles.mediaLocalRoots).`);
+        }
+        const asVoice = media.kind === "voice";
+        // Voice pre-flight: a voice memo must be mp3/caf — validate + coerce the
+        // extension / default the mime, failing fast with a clear error otherwise.
+        const voice = asVoice ? resolveOutboundVoiceAttachment(resolved.path, resolved.mimeType) : undefined;
+        const contentType = voice?.contentType ?? resolved.mimeType;
+        const sent = await sendBlueBubblesAttachment(chatGuid, {
+            ...base,
+            filePath: resolved.path,
+            ...(voice?.filename ? { fileName: voice.filename } : {}),
+            ...(contentType ? { contentType } : {}),
+            ...(asVoice ? { asVoice: true } : {}),
+        });
+        // iMessage has NO native caption — deliver any caption as a SEPARATE text
+        // bubble AFTER the media.
+        const caption = resolveDeliveredText(media.caption ?? "", media.kind);
+        if (caption && caption.trim() && !caption.startsWith("<media:")) {
+            await sendBlueBubblesText(chatGuid, sanitizeOutboundIMessageText(caption), base);
+        }
+        return sent.messageId ? { messageId: sent.messageId } : {};
+    };
+    const react = async (params) => {
+        const base = restBase();
+        const chatGuid = await resolveChatGuid(base, params.conversationId);
+        await reactBlueBubbles(base, { chatGuid, messageGuid: params.messageId, reaction: params.reaction });
+    };
+    const edit = async (params) => {
+        // macOS 26+ removed iMessage message EDIT — refuse cleanly rather than firing
+        // a request the server will reject.
+        if (isMacOSEditUnsupported(macOSMajor)) {
+            throw new Error("message edit isn't supported on macOS 26+");
+        }
+        await editBlueBubblesMessage(restBase(), { messageGuid: params.messageId, editedMessage: params.text });
+    };
+    const unsend = async (params) => {
+        await unsendBlueBubblesMessage(restBase(), { messageGuid: params.messageId });
+    };
+    const setTyping = async (conversationId, typing) => {
+        const base = restBase();
+        const chatGuid = await resolveChatGuid(base, conversationId);
+        await sendBlueBubblesTyping(base, { chatGuid, typing });
+    };
+    const markRead = async (conversationId) => {
+        const base = restBase();
+        const chatGuid = await resolveChatGuid(base, conversationId);
+        await markBlueBubblesChatRead(base, { chatGuid });
+    };
+    const runCatchup = async () => {
+        const catchupConfig = account.catchup;
+        return runBlueBubblesCatchup({
+            serverUrl: account.serverUrl,
+            password: account.password,
+            // Enable the PERSISTED cursor (lastSeenMs + give-up retries) per account.
+            accountId: account.accountId,
+            ...(args.catchupCursorStore ? { cursorStore: args.catchupCursorStore } : {}),
+            ...(catchupConfig ? { config: catchupConfig } : {}),
+            ...(account.probeTimeoutMs !== undefined ? { timeoutMs: account.probeTimeoutMs } : {}),
+            ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+            ...(account.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+            // Re-feed each fetched record through the SAME normalize+dedupe path a
+            // live webhook uses (as a `new-message` event), so dedupe drops anything
+            // already delivered — no double-delivery.
+            feedRecord: (record) => feedWebhookEvent("new-message", { type: "new-message", data: record }),
+            log: (msg) => args.log(msg),
+        });
+    };
+    // Ensure the cache dir exists lazily (best-effort; download also mkdir's).
+    try {
+        ensureDir(cacheDir);
+    }
+    catch {
+        /* best-effort */
+    }
+    return {
+        feedWebhookEvent,
+        sendText,
+        sendMedia,
+        react,
+        edit,
+        unsend,
+        setTyping,
+        markRead,
+        runCatchup,
+        setPrivateApi: (status) => {
+            privateApi = status;
+        },
+        setMacOSMajor: (major) => {
+            macOSMajor = major;
+        },
+        connectedAt: () => connectedAtMs,
+        close: () => {
+            // Flush any buffered (debounced) inbound so a pending coalesced turn isn't
+            // silently dropped on teardown, then clear timers.
+            debouncer?.flushAll();
+            debouncer?.clear();
+        },
+    };
+}
+//# sourceMappingURL=connection.js.map

package/dist/agents/channels/bluebubbles/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/connection.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/bluebubbles/contact-names.d.ts

@@ -0,0 +1,79 @@
+/**
+ * BlueBubbles contact-name resolution.
+ *
+ * An inbound BlueBubbles message carries the sender as a raw handle — a phone
+ * number (`+15551234567`) or an email. For the agent's context it reads far
+ * better as a human display name ("Alex Rivera"). The BlueBubbles server exposes
+ * the host Mac's Contacts via `GET /api/v1/contact`, so this module asks the
+ * server for the address book ONCE per account, indexes it by a normalised phone
+ * key + lowercased email, and resolves a sender address → display name from that
+ * cache.
+ *
+ * The directory is cached per account in a small LRU with a TTL (like Discord's
+ * directory cache): the first inbound for an account warms it, subsequent
+ * inbound hits the in-memory index. A NEGATIVE result (no match) is cached for a
+ * shorter TTL so an unknown number isn't re-queried on every message. `fetch` is
+ * INJECTABLE (the test seam) so the whole path runs with no live server.
+ */
+import { type FetchLike } from "./types.js";
+/** One BlueBubbles contact record (server `GET /api/v1/contact` shape, defensive). */
+interface RawBlueBubblesContact {
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    nickname?: string;
+    phoneNumbers?: Array<{
+        address?: string;
+    } | string>;
+    emails?: Array<{
+        address?: string;
+    } | string>;
+    [key: string]: unknown;
+}
+/** Args every resolution call threads (the REST base + the account scope). */
+export interface ResolveContactNameArgs {
+    serverUrl: string;
+    password: string;
+    accountId: string;
+    timeoutMs?: number;
+    /** TEST SEAM — inject a mock fetch. */
+    fetchImpl?: FetchLike;
+    /** Allow private/LAN/loopback hosts through the SSRF guard (default TRUE for BlueBubbles). */
+    allowPrivateNetwork?: boolean;
+}
+/**
+ * Normalise a phone-ish string to a comparison key: digits only, dropping a
+ * leading US country code so `+1 (555) 123-4567` and `5551234567` collide.
+ * Returns null for a too-short / non-numeric value (e.g. an email).
+ */
+export declare function normalizePhoneKey(value: string): string | null;
+/** Build the lookup key for a sender address (email lowercased, phone digit-normalised). */
+export declare function contactLookupKey(address: string): string | null;
+/** Build the phone/email → name index from the raw contact list. */
+export declare function buildContactIndex(contacts: RawBlueBubblesContact[]): Map<string, string>;
+/**
+ * Resolve an inbound sender address → a human display name, or `undefined` when
+ * unknown. Warms (and caches) the account's contact directory on first use;
+ * subsequent calls hit the in-memory index. Negative results are cached briefly
+ * so an unknown number isn't re-queried every message. NEVER throws — a transport
+ * failure just yields `undefined` (the message still flows with the raw handle).
+ */
+export declare function resolveBlueBubblesContactName(address: string, args: ResolveContactNameArgs, now?: number): Promise<string | undefined>;
+/**
+ * SYNCHRONOUS cache-only peek: resolve an address from an ALREADY-WARM account
+ * directory, or `undefined` when the directory isn't cached yet / it's a miss.
+ * Never fetches — use this on the hot inbound path so dispatch stays synchronous;
+ * pair it with `warmBlueBubblesContactDirectory` to populate the cache in the
+ * background.
+ */
+export declare function peekBlueBubblesContactName(address: string, accountId: string, now?: number): string | undefined;
+/**
+ * Warm the account's contact directory cache in the background (best-effort).
+ * Fetches + indexes ONLY when the cache is cold/expired; a warm cache is a
+ * no-op. Never throws. Returns a promise the caller can ignore.
+ */
+export declare function warmBlueBubblesContactDirectory(args: ResolveContactNameArgs, now?: number): Promise<void>;
+/** Drop every cached account directory (test isolation + reload teardown). */
+export declare function clearBlueBubblesContactCache(): void;
+export {};
+//# sourceMappingURL=contact-names.d.ts.map

package/dist/agents/channels/bluebubbles/contact-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-names.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/contact-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAuD,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AASjG,sFAAsF;AACtF,UAAU,qBAAqB;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,CAAC;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAaD,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D;AAqBD,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBxF;AAwCD;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CAClD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,sBAAsB,EAC5B,GAAG,GAAE,MAAmB,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB7B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,SAAS,CAM3H;AAED;;;;GAIG;AACH,wBAAsB,+BAA+B,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3H;AAED,8EAA8E;AAC9E,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}