@spinabot/brigade 1.7.0 → 1.8.0

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

@@ -0,0 +1,56 @@
+/**
+ * BlueBubbles rolling-history context fetch.
+ *
+ * When an untagged GROUP message arrives, the agent has no idea what the group
+ * was just talking about — iMessage delivers one webhook per message with no
+ * thread context. This module fetches the last N messages for the chat and
+ * returns them as compact `{ sender, body }` entries the connection prepends to
+ * the inbound as a fenced context block, so the agent replies INTO the
+ * conversation rather than at a single stray line.
+ *
+ * BlueBubbles' message-listing endpoint shape varies by server version, so this
+ * tries several known paths in order and accepts the first that returns a
+ * recognised response (array / `data[]` / `messages[]`). `fetch` is INJECTABLE
+ * (the test seam); never throws — a failure returns `{ entries: [], resolved:false }`
+ * and the caller simply attaches no context.
+ */
+import { type FetchLike } from "./types.js";
+/** One compact history line. */
+export interface BlueBubblesHistoryEntry {
+    /** Display name / handle of the speaker (or "me" for the bot's own past messages). */
+    sender: string;
+    /** Message text (truncated). */
+    body: string;
+    /** When it was sent (epoch ms), when known. */
+    timestamp?: number;
+    /** The message GUID, when known. */
+    messageId?: string;
+}
+/** The result of a history fetch. `resolved` is false when every path failed. */
+export interface BlueBubblesHistoryFetchResult {
+    entries: BlueBubblesHistoryEntry[];
+    resolved: boolean;
+}
+/** Args for a history fetch. */
+export interface FetchBlueBubblesHistoryArgs {
+    serverUrl: string;
+    password: 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;
+}
+/**
+ * Fetch recent message history for a chat. Tries several known endpoint shapes;
+ * the first recognised response wins. Returns entries oldest-first (so a reader
+ * sees the conversation in order), capped to `limit`. Never throws.
+ */
+export declare function fetchBlueBubblesHistory(chatIdentifier: string, limit: number, args: FetchBlueBubblesHistoryArgs): Promise<BlueBubblesHistoryFetchResult>;
+/**
+ * Render history entries as a clearly-fenced context block to PREPEND to the
+ * inbound body. Returns "" when there are no entries. The block is delimited so
+ * the agent can tell prior context from the current message.
+ */
+export declare function renderBlueBubblesHistoryBlock(entries: BlueBubblesHistoryEntry[]): string;
+//# sourceMappingURL=history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAuD,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjG,gCAAgC;AAChC,MAAM,WAAW,uBAAuB;IACvC,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,6BAA6B;IAC7C,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,2BAA2B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAwDD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC5C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,2BAA2B,GAC/B,OAAO,CAAC,6BAA6B,CAAC,CAoDxC;AAaD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,MAAM,CAIxF"}

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

@@ -0,0 +1,140 @@
+/**
+ * BlueBubbles rolling-history context fetch.
+ *
+ * When an untagged GROUP message arrives, the agent has no idea what the group
+ * was just talking about — iMessage delivers one webhook per message with no
+ * thread context. This module fetches the last N messages for the chat and
+ * returns them as compact `{ sender, body }` entries the connection prepends to
+ * the inbound as a fenced context block, so the agent replies INTO the
+ * conversation rather than at a single stray line.
+ *
+ * BlueBubbles' message-listing endpoint shape varies by server version, so this
+ * tries several known paths in order and accepts the first that returns a
+ * recognised response (array / `data[]` / `messages[]`). `fetch` is INJECTABLE
+ * (the test seam); never throws — a failure returns `{ entries: [], resolved:false }`
+ * and the caller simply attaches no context.
+ */
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+/** Hard ceiling on a single history fetch. */
+const MAX_HISTORY_FETCH_LIMIT = 100;
+/** How many records to scan looking for `limit` text-bearing ones. */
+const HISTORY_SCAN_MULTIPLIER = 8;
+const MAX_HISTORY_SCAN_MESSAGES = 500;
+/** Cap on a single history line's length (keeps the context block bounded). */
+const MAX_HISTORY_BODY_CHARS = 2_000;
+/** Clamp the requested limit into `[0, MAX]`. */
+function clampHistoryLimit(limit) {
+    if (!Number.isFinite(limit))
+        return 0;
+    const n = Math.floor(limit);
+    if (n <= 0)
+        return 0;
+    return Math.min(n, MAX_HISTORY_FETCH_LIMIT);
+}
+/** Truncate a history line body, marking the cut. */
+function truncateBody(text) {
+    if (text.length <= MAX_HISTORY_BODY_CHARS)
+        return text;
+    return `${text.slice(0, MAX_HISTORY_BODY_CHARS).trimEnd()}...`;
+}
+/** Resolve a display label for a message's sender. */
+function resolveSender(msg) {
+    if (msg.is_from_me === true || msg.isFromMe === true)
+        return "me";
+    const handleObj = typeof msg.handle === "object" && msg.handle ? msg.handle : undefined;
+    return (msg.sender?.display_name ||
+        msg.sender?.displayName ||
+        msg.sender?.address ||
+        handleObj?.display_name ||
+        handleObj?.displayName ||
+        handleObj?.address ||
+        (typeof msg.handle === "string" ? msg.handle : undefined) ||
+        msg.handle_id ||
+        "Unknown");
+}
+/**
+ * Fetch recent message history for a chat. Tries several known endpoint shapes;
+ * the first recognised response wins. Returns entries oldest-first (so a reader
+ * sees the conversation in order), capped to `limit`. Never throws.
+ */
+export async function fetchBlueBubblesHistory(chatIdentifier, limit, args) {
+    const effectiveLimit = clampHistoryLimit(limit);
+    if (!chatIdentifier.trim() || effectiveLimit <= 0)
+        return { entries: [], resolved: true };
+    const fetchOpts = {
+        ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+        ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+        ...(args.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    };
+    const encoded = encodeURIComponent(chatIdentifier);
+    // Known listing shapes, in order — the first that returns a recognised body wins.
+    const paths = [
+        { path: `chat/${encoded}/message`, query: { limit: effectiveLimit, sort: "DESC" } },
+        { path: `chat/${encoded}/messages`, query: { limit: effectiveLimit } },
+        { path: "messages", query: { chatGuid: chatIdentifier, limit: effectiveLimit } },
+    ];
+    for (const { path, query } of paths) {
+        try {
+            const url = buildBlueBubblesApiUrl({ serverUrl: args.serverUrl, path, password: args.password, ...(query ? { query } : {}) });
+            const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, fetchOpts);
+            if (!res.ok)
+                continue;
+            const text = await res.text();
+            const body = text ? JSON.parse(text) : null;
+            if (!body)
+                continue;
+            const messages = extractMessageArray(body);
+            if (!messages)
+                continue;
+            const entries = [];
+            const maxScan = Math.min(Math.max(effectiveLimit * HISTORY_SCAN_MULTIPLIER, effectiveLimit), MAX_HISTORY_SCAN_MESSAGES);
+            for (let i = 0; i < messages.length && i < maxScan; i++) {
+                const msg = messages[i];
+                if (!msg || typeof msg !== "object")
+                    continue;
+                const t = (msg.text ?? "").trim();
+                if (!t)
+                    continue;
+                const timestamp = msg.date_created ?? msg.dateCreated ?? msg.date_delivered;
+                entries.push({
+                    sender: resolveSender(msg),
+                    body: truncateBody(t),
+                    ...(typeof timestamp === "number" ? { timestamp } : {}),
+                    ...(typeof msg.guid === "string" ? { messageId: msg.guid } : {}),
+                });
+            }
+            // Oldest-first so the agent reads the conversation in order.
+            entries.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
+            return { entries: entries.slice(0, effectiveLimit), resolved: true };
+        }
+        catch {
+            continue;
+        }
+    }
+    return { entries: [], resolved: false };
+}
+/** Pull a message array out of the various response shapes (array / data[] / messages[]). */
+function extractMessageArray(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body && typeof body === "object") {
+        const rec = body;
+        if (Array.isArray(rec.data))
+            return rec.data;
+        if (Array.isArray(rec.messages))
+            return rec.messages;
+    }
+    return null;
+}
+/**
+ * Render history entries as a clearly-fenced context block to PREPEND to the
+ * inbound body. Returns "" when there are no entries. The block is delimited so
+ * the agent can tell prior context from the current message.
+ */
+export function renderBlueBubblesHistoryBlock(entries) {
+    if (!entries || entries.length === 0)
+        return "";
+    const lines = entries.map((e) => `${e.sender}: ${e.body}`);
+    return ["[recent conversation context]", ...lines, "[end context]"].join("\n");
+}
+//# sourceMappingURL=history.js.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * BlueBubbles channel — public barrel.
+ *
+ * Re-exports the channel's public surface (adapter, plugin, config resolvers,
+ * probe, webhook builders, the module) so the gateway boot + central registries
+ * import from one place.
+ */
+export { bluebubblesChannelEnabled, listBlueBubblesAccountIds, resolveBlueBubblesAccount, resolveBlueBubblesServerUrl, resolveBlueBubblesPassword, resolveBlueBubblesWebhookPath, resolveBlueBubblesProbeTimeoutMs, resolveBlueBubblesActions, resolveBlueBubblesCatchup, bluebubblesThreadIdleTtlMs, normalizeBlueBubblesServerUrl, BLUEBUBBLES_CHANNEL_ID, BLUEBUBBLES_DEFAULT_ACCOUNT_ID, BLUEBUBBLES_DEFAULT_WEBHOOK_PATH, type ResolvedBlueBubblesAccount, type BlueBubblesActionFlags, } from "./account-config.js";
+export { createBlueBubblesAdapter, type BlueBubblesAdapter } from "./adapter.js";
+export { createBlueBubblesPlugin, type BlueBubblesPluginHandle, type BlueBubblesPluginDeps } from "./plugin.js";
+export { probeBlueBubbles, type BlueBubblesProbeResult } from "./probe.js";
+export { buildBlueBubblesWebhookRoute, verifyBlueBubblesWebhook, parseBlueBubblesBody, safeEqualToken, type BlueBubblesWebhookSink, } from "./webhook.js";
+export { bluebubblesMessagingAdapter } from "./messaging.js";
+export { bluebubblesModule } from "./module.js";
+export { sendBlueBubblesTyping, markBlueBubblesChatRead, renameBlueBubblesChat, addBlueBubblesParticipant, removeBlueBubblesParticipant, leaveBlueBubblesChat, setBlueBubblesGroupIcon, } from "./chat.js";
+export { resolveBlueBubblesContactName, clearBlueBubblesContactCache, type ResolveContactNameArgs, } from "./contact-names.js";
+export { runBlueBubblesCatchup, type BlueBubblesCatchupConfig, type BlueBubblesCatchupSummary, } from "./catchup.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACN,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,EACd,KAAK,sBAAsB,GAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,uBAAuB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,6BAA6B,EAC7B,4BAA4B,EAC5B,KAAK,sBAAsB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC9B,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * BlueBubbles channel — public barrel.
+ *
+ * Re-exports the channel's public surface (adapter, plugin, config resolvers,
+ * probe, webhook builders, the module) so the gateway boot + central registries
+ * import from one place.
+ */
+export { bluebubblesChannelEnabled, listBlueBubblesAccountIds, resolveBlueBubblesAccount, resolveBlueBubblesServerUrl, resolveBlueBubblesPassword, resolveBlueBubblesWebhookPath, resolveBlueBubblesProbeTimeoutMs, resolveBlueBubblesActions, resolveBlueBubblesCatchup, bluebubblesThreadIdleTtlMs, normalizeBlueBubblesServerUrl, BLUEBUBBLES_CHANNEL_ID, BLUEBUBBLES_DEFAULT_ACCOUNT_ID, BLUEBUBBLES_DEFAULT_WEBHOOK_PATH, } from "./account-config.js";
+export { createBlueBubblesAdapter } from "./adapter.js";
+export { createBlueBubblesPlugin } from "./plugin.js";
+export { probeBlueBubbles } from "./probe.js";
+export { buildBlueBubblesWebhookRoute, verifyBlueBubblesWebhook, parseBlueBubblesBody, safeEqualToken, } from "./webhook.js";
+export { bluebubblesMessagingAdapter } from "./messaging.js";
+export { bluebubblesModule } from "./module.js";
+export { sendBlueBubblesTyping, markBlueBubblesChatRead, renameBlueBubblesChat, addBlueBubblesParticipant, removeBlueBubblesParticipant, leaveBlueBubblesChat, setBlueBubblesGroupIcon, } from "./chat.js";
+export { resolveBlueBubblesContactName, clearBlueBubblesContactCache, } from "./contact-names.js";
+export { runBlueBubblesCatchup, } from "./catchup.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,gCAAgC,GAGhC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAA2B,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAA4D,MAAM,aAAa,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAA+B,MAAM,YAAY,CAAC;AAC3E,OAAO,EACN,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,GAEd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,uBAAuB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,6BAA6B,EAC7B,4BAA4B,GAE5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,qBAAqB,GAGrB,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,104 @@
+/**
+ * BlueBubbles media helpers — inbound download + cache, outbound resolution.
+ *
+ * Unlike the native `imessage` channel (where the `imsg` bridge has already
+ * saved inbound bytes to local disk), BlueBubbles serves attachments over HTTP:
+ * `GET /api/v1/attachment/{guid}/download`. So this module DOWNLOADS each inbound
+ * attachment to a per-account cache dir under the OS cache (outside `~/.brigade`),
+ * applying a small extension-normalisation map (HEIC→jpg, caf→mp3) so the agent's
+ * `read` tool + downstream tools see a friendlier extension.
+ *
+ * OUTBOUND resolution reuses the iMessage exfil guard + kind classifiers so a
+ * prompt-injected "send ~/.ssh/id_rsa" can't attach a secret.
+ */
+import { kindFromExt, kindFromMime, resolveOutboundAttachment, inferOutboundMediaKind } from "../imessage/media.js";
+import { type FetchLike } from "./types.js";
+import type { InboundMediaAttachment } from "../sdk.js";
+export { kindFromExt, kindFromMime, resolveOutboundAttachment, inferOutboundMediaKind };
+/** Apply the inbound extension map to a filename (`photo.heic` → `photo.jpg`). */
+export declare function mapInboundExtension(fileName: string): string;
+/** The result of classifying a candidate voice attachment. */
+export interface BlueBubblesVoiceInfo {
+    /** True when the file looks like audio at all. */
+    isAudio: boolean;
+    /** True when it is mp3 (by extension or mime). */
+    isMp3: boolean;
+    /** True when it is caf (by extension or mime). */
+    isCaf: boolean;
+}
+/**
+ * Classify a candidate voice attachment by extension + (optional) MIME type. A
+ * BlueBubbles voice memo must be mp3 or caf — the server converts mp3 → caf when
+ * `isAudioMessage` is set.
+ */
+export declare function resolveVoiceInfo(filename: string, contentType?: string): BlueBubblesVoiceInfo;
+/**
+ * Ensure a filename ends with `extension` (e.g. `.mp3`), swapping any existing
+ * extension. `fallbackBase` is used when the input has no stem.
+ */
+export declare function ensureExtension(filename: string, extension: string, fallbackBase: string): string;
+/** The outcome of the outbound voice pre-flight. */
+export interface ResolvedVoiceAttachment {
+    /** The (possibly extension-coerced) filename to send. */
+    filename: string;
+    /** The (possibly defaulted) content type to send. */
+    contentType: string | undefined;
+}
+/**
+ * Pre-flight an outbound VOICE attachment: validate it is mp3/caf, coerce the
+ * filename's extension to match, and default the MIME type when absent. Throws a
+ * clear operator-facing error when the file is not mp3/caf audio so the send
+ * fails fast (rather than the server silently rejecting / mis-handling it).
+ */
+export declare function resolveOutboundVoiceAttachment(filename: string, contentType?: string): ResolvedVoiceAttachment;
+/** One raw inbound attachment as the BlueBubbles webhook reports it. */
+export interface RawBlueBubblesAttachment {
+    guid?: string;
+    transferName?: string;
+    mimeType?: string;
+    totalBytes?: number;
+}
+/** Args for downloading + caching inbound attachments. */
+export interface DownloadInboundArgs {
+    serverUrl: string;
+    password: string;
+    /** Per-account cache dir the bytes are written under. */
+    cacheDir: string;
+    /** Max bytes to accept per attachment (skips oversize ones). */
+    maxBytes: number;
+    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;
+}
+/**
+ * Download + cache a single inbound attachment by GUID, returning the saved
+ * `InboundMediaAttachment` (or null when it has no GUID / is oversize / fails).
+ * The saved filename runs through `mapInboundExtension`.
+ */
+export declare function downloadBlueBubblesAttachment(att: RawBlueBubblesAttachment, args: DownloadInboundArgs): Promise<InboundMediaAttachment | null>;
+/**
+ * Download all inbound attachments for a message, dropping any that fail / are
+ * oversize. Returns [] when none resolve.
+ */
+export declare function downloadInboundAttachments(raw: RawBlueBubblesAttachment[] | null | undefined, args: DownloadInboundArgs): Promise<InboundMediaAttachment[]>;
+/** Args for the late-index attachment re-fetch. */
+export interface FetchMessageAttachmentsArgs {
+    serverUrl: string;
+    password: string;
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+    allowPrivateNetwork?: boolean;
+}
+/**
+ * Re-fetch a message's attachment descriptors by GUID
+ * (`GET /api/v1/message/{guid}?with=attachment`).
+ *
+ * BlueBubbles can fire the `new-message` webhook BEFORE attachment indexing
+ * finishes, so the webhook's `attachments` arrives empty for a message that
+ * actually has media. A short delay + this single re-fetch recovers the media
+ * that would otherwise be silently lost. Returns [] on any failure (never throws).
+ */
+export declare function fetchBlueBubblesMessageAttachments(messageGuid: string, args: FetchMessageAttachmentsArgs): Promise<RawBlueBubblesAttachment[]>;
+//# sourceMappingURL=media.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAGN,KAAK,SAAS,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAC;AAexF,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM5D;AASD,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACpC,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAO7F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAKjG;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACvC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,uBAAuB,CAc9G;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,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,wBAAsB,6BAA6B,CAClD,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,mBAAmB,GACvB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA0CxC;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC/C,GAAG,EAAE,wBAAwB,EAAE,GAAG,IAAI,GAAG,SAAS,EAClD,IAAI,EAAE,mBAAmB,GACvB,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAQnC;AAmCD,mDAAmD;AACnD,MAAM,WAAW,2BAA2B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kCAAkC,CACvD,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,2BAA2B,GAC/B,OAAO,CAAC,wBAAwB,EAAE,CAAC,CA0BrC"}

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

@@ -0,0 +1,222 @@
+/**
+ * BlueBubbles media helpers — inbound download + cache, outbound resolution.
+ *
+ * Unlike the native `imessage` channel (where the `imsg` bridge has already
+ * saved inbound bytes to local disk), BlueBubbles serves attachments over HTTP:
+ * `GET /api/v1/attachment/{guid}/download`. So this module DOWNLOADS each inbound
+ * attachment to a per-account cache dir under the OS cache (outside `~/.brigade`),
+ * applying a small extension-normalisation map (HEIC→jpg, caf→mp3) so the agent's
+ * `read` tool + downstream tools see a friendlier extension.
+ *
+ * OUTBOUND resolution reuses the iMessage exfil guard + kind classifiers so a
+ * prompt-injected "send ~/.ssh/id_rsa" can't attach a secret.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { kindFromExt, kindFromMime, resolveOutboundAttachment, inferOutboundMediaKind } from "../imessage/media.js";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl, } from "./types.js";
+// Re-export the shared classifiers so callers import them from one place.
+export { kindFromExt, kindFromMime, resolveOutboundAttachment, inferOutboundMediaKind };
+/**
+ * Inbound extension-normalisation map. iMessage delivers Apple-native container
+ * formats that most tools can't open; map them to a friendlier extension on
+ * download. The bytes are NOT transcoded — only the on-disk extension is changed
+ * (a HEIC renamed `.jpg` is still HEIC bytes, but the friendlier extension keeps
+ * downstream readers from choking on the `.heic` suffix).
+ */
+const EXTENSION_MAP = {
+    heic: "jpg",
+    heif: "jpg",
+    caf: "mp3",
+};
+/** Apply the inbound extension map to a filename (`photo.heic` → `photo.jpg`). */
+export function mapInboundExtension(fileName) {
+    const ext = path.extname(fileName).toLowerCase().replace(/^\./, "");
+    const mapped = EXTENSION_MAP[ext];
+    if (!mapped)
+        return fileName;
+    const stem = fileName.slice(0, fileName.length - (ext.length + 1));
+    return `${stem || "attachment"}.${mapped}`;
+}
+/* ───────────────────────── outbound voice pre-flight ───────────────────────── */
+/** MIME types BlueBubbles accepts as an mp3 voice memo. */
+const VOICE_MIME_MP3 = new Set(["audio/mpeg", "audio/mp3"]);
+/** MIME types BlueBubbles accepts as a caf voice memo. */
+const VOICE_MIME_CAF = new Set(["audio/x-caf", "audio/caf"]);
+/**
+ * Classify a candidate voice attachment by extension + (optional) MIME type. A
+ * BlueBubbles voice memo must be mp3 or caf — the server converts mp3 → caf when
+ * `isAudioMessage` is set.
+ */
+export function resolveVoiceInfo(filename, contentType) {
+    const type = (contentType ?? "").trim().toLowerCase() || undefined;
+    const ext = path.extname(filename).toLowerCase();
+    const isMp3 = ext === ".mp3" || (type ? VOICE_MIME_MP3.has(type) : false);
+    const isCaf = ext === ".caf" || (type ? VOICE_MIME_CAF.has(type) : false);
+    const isAudio = isMp3 || isCaf || Boolean(type?.startsWith("audio/"));
+    return { isAudio, isMp3, isCaf };
+}
+/**
+ * Ensure a filename ends with `extension` (e.g. `.mp3`), swapping any existing
+ * extension. `fallbackBase` is used when the input has no stem.
+ */
+export function ensureExtension(filename, extension, fallbackBase) {
+    const current = path.extname(filename);
+    if (current.toLowerCase() === extension)
+        return filename;
+    const base = current ? filename.slice(0, -current.length) : filename;
+    return `${base || fallbackBase}${extension}`;
+}
+/**
+ * Pre-flight an outbound VOICE attachment: validate it is mp3/caf, coerce the
+ * filename's extension to match, and default the MIME type when absent. Throws a
+ * clear operator-facing error when the file is not mp3/caf audio so the send
+ * fails fast (rather than the server silently rejecting / mis-handling it).
+ */
+export function resolveOutboundVoiceAttachment(filename, contentType) {
+    const fallbackBase = "Audio Message";
+    const info = resolveVoiceInfo(filename, contentType);
+    if (!info.isAudio) {
+        throw new Error("BlueBubbles voice messages require audio media (mp3 or caf).");
+    }
+    if (info.isMp3) {
+        return { filename: ensureExtension(filename, ".mp3", fallbackBase), contentType: contentType ?? "audio/mpeg" };
+    }
+    if (info.isCaf) {
+        return { filename: ensureExtension(filename, ".caf", fallbackBase), contentType: contentType ?? "audio/x-caf" };
+    }
+    // Audio, but not mp3/caf (e.g. wav/m4a) — BlueBubbles can't send it as a voice memo.
+    throw new Error("BlueBubbles voice messages require mp3 or caf audio (convert before sending).");
+}
+/**
+ * Download + cache a single inbound attachment by GUID, returning the saved
+ * `InboundMediaAttachment` (or null when it has no GUID / is oversize / fails).
+ * The saved filename runs through `mapInboundExtension`.
+ */
+export async function downloadBlueBubblesAttachment(att, args) {
+    const guid = (att.guid ?? "").trim();
+    if (!guid)
+        return null;
+    if (args.maxBytes > 0 && typeof att.totalBytes === "number" && att.totalBytes > args.maxBytes)
+        return null;
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: args.serverUrl,
+        path: `attachment/${encodeURIComponent(guid)}/download`,
+        password: args.password,
+    });
+    let bytes;
+    let contentType;
+    try {
+        const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, { timeoutMs: args.timeoutMs ?? 30_000, ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}), ...(args.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}) });
+        if (!res.ok)
+            return null;
+        const buf = await res.arrayBuffer();
+        bytes = new Uint8Array(buf);
+        if (args.maxBytes > 0 && bytes.byteLength > args.maxBytes)
+            return null;
+        const ct = res.headers.get("content-type");
+        contentType = ct ? ct.split(";")[0]?.trim() || undefined : undefined;
+    }
+    catch {
+        return null;
+    }
+    const rawName = (att.transferName ?? "").trim() || `${guid}`;
+    const fileName = mapInboundExtension(rawName);
+    const dest = path.join(args.cacheDir, `${guid}-${fileName}`);
+    try {
+        await mkdir(args.cacheDir, { recursive: true });
+        await writeFile(dest, bytes);
+    }
+    catch {
+        return null;
+    }
+    const mimeType = (att.mimeType ?? contentType ?? "").trim() || undefined;
+    return {
+        kind: mimeType ? kindFromMime(mimeType) : kindFromExt(fileName),
+        path: dest,
+        ...(mimeType ? { mimeType } : {}),
+        fileName,
+    };
+}
+/**
+ * Download all inbound attachments for a message, dropping any that fail / are
+ * oversize. Returns [] when none resolve.
+ */
+export async function downloadInboundAttachments(raw, args) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return [];
+    const out = [];
+    for (const att of raw) {
+        const resolved = await downloadBlueBubblesAttachment(att, args);
+        if (resolved)
+            out.push(resolved);
+    }
+    return out;
+}
+/** Pull the raw attachment descriptors out of a `message/{guid}` response record. */
+function extractAttachmentsFromMessage(data) {
+    const rec = data && typeof data === "object" ? data : null;
+    const raw = rec?.attachments;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const a of raw) {
+        const r = a && typeof a === "object" ? a : null;
+        const guid = typeof r?.guid === "string" ? r.guid.trim() : "";
+        if (!guid)
+            continue;
+        const transferName = (typeof r?.transferName === "string" && r.transferName) ||
+            (typeof r?.transfer_name === "string" && r.transfer_name) ||
+            undefined;
+        const mimeType = (typeof r?.mimeType === "string" && r.mimeType) ||
+            (typeof r?.mime_type === "string" && r.mime_type) ||
+            (typeof r?.uti === "string" && r.uti) ||
+            undefined;
+        const totalBytes = (typeof r?.totalBytes === "number" && r.totalBytes) ||
+            (typeof r?.total_bytes === "number" && r.total_bytes) ||
+            undefined;
+        out.push({
+            guid,
+            ...(transferName ? { transferName } : {}),
+            ...(mimeType ? { mimeType } : {}),
+            ...(totalBytes !== undefined ? { totalBytes } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Re-fetch a message's attachment descriptors by GUID
+ * (`GET /api/v1/message/{guid}?with=attachment`).
+ *
+ * BlueBubbles can fire the `new-message` webhook BEFORE attachment indexing
+ * finishes, so the webhook's `attachments` arrives empty for a message that
+ * actually has media. A short delay + this single re-fetch recovers the media
+ * that would otherwise be silently lost. Returns [] on any failure (never throws).
+ */
+export async function fetchBlueBubblesMessageAttachments(messageGuid, args) {
+    const guid = (messageGuid ?? "").trim();
+    if (!guid)
+        return [];
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: args.serverUrl,
+        path: `message/${encodeURIComponent(guid)}`,
+        password: args.password,
+        query: { with: "attachment" },
+    });
+    try {
+        const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, {
+            timeoutMs: args.timeoutMs ?? 10_000,
+            ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),
+            ...(args.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+        });
+        if (!res.ok)
+            return [];
+        const text = await res.text();
+        const body = text ? JSON.parse(text) : {};
+        return extractAttachmentsFromMessage(body.data);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=media.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EACN,2BAA2B,EAC3B,sBAAsB,GAEtB,MAAM,YAAY,CAAC;AAGpB,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,aAAa,GAA2B;IAC7C,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,GAAG,EAAE,KAAK;CACV,CAAC;AAEF,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC;IAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,GAAG,IAAI,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;AAC5C,CAAC;AAED,mFAAmF;AAEnF,2DAA2D;AAC3D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;AAC5D,0DAA0D;AAC1D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAY7D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,WAAoB;IACtE,MAAM,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC;IACnE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACjD,MAAM,KAAK,GAAG,GAAG,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,GAAG,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,SAAiB,EAAE,YAAoB;IACxF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,OAAO,CAAC,WAAW,EAAE,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACrE,OAAO,GAAG,IAAI,IAAI,YAAY,GAAG,SAAS,EAAE,CAAC;AAC9C,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAAC,QAAgB,EAAE,WAAoB;IACpF,MAAM,YAAY,GAAG,eAAe,CAAC;IACrC,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE,WAAW,IAAI,YAAY,EAAE,CAAC;IAChH,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE,WAAW,IAAI,aAAa,EAAE,CAAC;IACjH,CAAC;IACD,qFAAqF;IACrF,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;AAClG,CAAC;AAyBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAClD,GAA6B,EAC7B,IAAyB;IAEzB,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3G,MAAM,GAAG,GAAG,sBAAsB,CAAC;QAClC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,IAAI,EAAE,cAAc,kBAAkB,CAAC,IAAI,CAAC,WAAW;QACvD,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACvB,CAAC,CAAC;IACH,IAAI,KAAiB,CAAC;IACtB,IAAI,WAA+B,CAAC;IACpC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,MAAM,2BAA2B,CAC5C,GAAG,EACH,EAAE,MAAM,EAAE,KAAK,EAAE,EACjB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAChL,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC;QACpC,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QACvE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAC3C,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC;IAC7D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC;QACJ,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,QAAQ,IAAI,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IACzE,OAAO;QACN,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC;QAC/D,IAAI,EAAE,IAAI;QACV,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,QAAQ;KACR,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,GAAkD,EAClD,IAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAChE,IAAI,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,qFAAqF;AACrF,SAAS,6BAA6B,CAAC,IAAa;IACnD,MAAM,GAAG,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAgC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,MAAM,GAAG,GAAG,GAAG,EAAE,WAAW,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7E,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,YAAY,GACjB,CAAC,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,YAAY,CAAC;YACvD,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,QAAQ,IAAI,CAAC,CAAC,aAAa,CAAC;YACzD,SAAS,CAAC;QACX,MAAM,QAAQ,GACb,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC;YAC/C,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC;YACjD,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC;YACrC,SAAS,CAAC;QACX,MAAM,UAAU,GACf,CAAC,OAAO,CAAC,EAAE,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,CAAC;YACnD,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC;YACrD,SAAS,CAAC;QACX,GAAG,CAAC,IAAI,CAAC;YACR,IAAI;YACJ,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACvD,WAAmB,EACnB,IAAiC;IAEjC,MAAM,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,GAAG,GAAG,sBAAsB,CAAC;QAClC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,IAAI,EAAE,WAAW,kBAAkB,CAAC,IAAI,CAAC,EAAE;QAC3C,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE;KAC7B,CAAC,CAAC;IACH,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,MAAM,2BAA2B,CAC5C,GAAG,EACH,EAAE,MAAM,EAAE,KAAK,EAAE,EACjB;YACC,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,MAAM;YACnC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,IAAI,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E,CACD,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * BlueBubbles outbound-addressing adapter (the `ChannelPlugin.messaging` slot).
+ *
+ * Turns the loose `to` the agent hands `send_message` ("+1 555 123 4567",
+ * "bluebubbles:user@example.com", "chat_guid:…") into a concrete target the
+ * runtime `sendText` understands. BlueBubbles shares iMessage's target grammar,
+ * so this reuses the iMessage target primitives (chat_guid / chat_id / handle)
+ * and only swaps the channel-name prefix to `bluebubbles:`.
+ */
+import type { ChannelMessagingAdapter } from "../sdk.js";
+/** The BlueBubbles messaging adapter. */
+export declare const bluebubblesMessagingAdapter: ChannelMessagingAdapter;
+//# sourceMappingURL=messaging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAwB,MAAM,WAAW,CAAC;AAO/E,yCAAyC;AACzC,eAAO,MAAM,2BAA2B,EAAE,uBAmBzC,CAAC"}