@spinabot/brigade 1.7.0 → 1.9.0

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

@@ -0,0 +1,114 @@
+/**
+ * BlueBubbles catch-up backfill.
+ *
+ * BlueBubbles delivers inbound via webhook POST. When Brigade is down (restart,
+ * crash, upgrade) the server's webhook fire fails and is NOT retried, so any
+ * message that arrived during the outage is lost. On (re)connect, catch-up
+ * queries the server for messages delivered in a bounded recent window
+ * (`POST /api/v1/message/query`, `after: <sinceMs>`, capped by `limit`) and
+ * re-feeds each one through the SAME path a live webhook event takes —
+ * normalize → dedupe → dispatch.
+ *
+ * The dedupe is what makes this safe: a message already delivered live (or in a
+ * previous catch-up pass) is claimed in the connection's dedupe cache, so the
+ * replay is dropped there and the agent NEVER replies twice. Catch-up therefore
+ * recovers ONLY the genuinely-missed messages.
+ *
+ * `fetch` is INJECTABLE (the test seam) so the whole query → replay path runs
+ * with no live server. Never throws — a query failure logs and leaves the live
+ * webhook path untouched.
+ */
+import { type BlueBubblesCursorStore } from "./catchup-cursor.js";
+import { type FetchLike } from "./types.js";
+/** Default lookback window when running catch-up (30 min). */
+export declare const BLUEBUBBLES_CATCHUP_DEFAULT_LOOKBACK_MS: number;
+/** Default per-run message cap. */
+export declare const BLUEBUBBLES_CATCHUP_DEFAULT_LIMIT = 50;
+/** Hard ceiling on the per-run cap (defends against an unbounded backlog). */
+export declare const BLUEBUBBLES_CATCHUP_MAX_LIMIT = 500;
+/** Default per-message consecutive-failure ceiling before catch-up gives up + force-advances past it. */
+export declare const BLUEBUBBLES_CATCHUP_DEFAULT_MAX_FAILURE_RETRIES = 10;
+/** Hard ceiling on `maxFailureRetries`. */
+export declare const BLUEBUBBLES_CATCHUP_MAX_FAILURE_RETRIES = 1000;
+/** Tunables for one catch-up run. */
+export interface BlueBubblesCatchupConfig {
+    /** Disable catch-up entirely. */
+    enabled?: boolean;
+    /** How far back to look on the FIRST run (no cursor yet) (ms). Also the legacy fixed-lookback when no accountId is given. */
+    lookbackMs?: number;
+    /** Max messages to fetch in one run. */
+    limit?: number;
+    /**
+     * Per-message retry ceiling. After this many consecutive failed replays of the
+     * same GUID, catch-up logs + force-advances the cursor past it (instead of
+     * holding indefinitely). Defaults to 10; clamped to [1, 1000]. Only meaningful
+     * when a persisted cursor is in use (an `accountId` was provided).
+     */
+    maxFailureRetries?: number;
+}
+/** Args for one catch-up run. */
+export interface RunBlueBubblesCatchupArgs {
+    serverUrl: string;
+    password: string;
+    config?: BlueBubblesCatchupConfig;
+    timeoutMs?: number;
+    /**
+     * Account id — enables the PERSISTED cursor (`lastSeenMs` + give-up retries).
+     * When omitted, catch-up falls back to the legacy fixed-lookback window with no
+     * persistence (unchanged behaviour).
+     */
+    accountId?: string;
+    /** TEST SEAM — inject a mock fetch. */
+    fetchImpl?: FetchLike;
+    /** Allow private/LAN/loopback hosts through the SSRF guard (default TRUE for BlueBubbles). */
+    allowPrivateNetwork?: boolean;
+    /**
+     * Re-feed one raw message record through the connection's live webhook path
+     * (normalize → dedupe → dispatch). The connection wires this to the SAME
+     * `feedWebhookEvent` a real webhook uses, so dedupe drops any already-seen
+     * message. THROWING from this marks the record as a failed replay (the cursor
+     * holds before it, and after `maxFailureRetries` it's given up + skipped).
+     */
+    feedRecord: (record: Record<string, unknown>) => void;
+    /** Optional logger. */
+    log?: (msg: string) => void;
+    /** Clock seam (tests). */
+    now?: () => number;
+    /** TEST SEAM — inject the cursor store (default: filesystem under the channel state dir). */
+    cursorStore?: BlueBubblesCursorStore;
+}
+/** Outcome of a catch-up run (for logging + tests). */
+export interface BlueBubblesCatchupSummary {
+    /** True when the server query returned a recognised response. */
+    querySucceeded: boolean;
+    /** How many records the query returned. */
+    fetched: number;
+    /** How many were re-fed into the inbound path (pre-dedupe). */
+    replayed: number;
+    /** How many failed records crossed `maxFailureRetries` on THIS run (fresh give-ups). */
+    givenUp: number;
+    /** How many records were skipped because they were ALREADY given up in a prior run. */
+    skippedGivenUp: number;
+    /** How many records' replay threw on this run. */
+    failed: number;
+    /** The cursor before this run (epoch ms), or null on first run / no persistence. */
+    cursorBefore: number | null;
+    /** The cursor after this run (epoch ms). */
+    cursorAfter: number;
+    /** The `after` timestamp the query used (epoch ms). */
+    windowStartMs: number;
+}
+/**
+ * Run one bounded catch-up pass.
+ *
+ * With an `accountId`, queries strictly AFTER the persisted cursor (`lastSeenMs`),
+ * re-feeds each record through `feedRecord` (the connection's normalize+dedupe
+ * path), then advances the cursor: to "now" on a clean pass, held just before the
+ * earliest still-retrying failure, force-advanced past any GUID that has failed
+ * `maxFailureRetries` times, or to the page boundary when the fetch hit the
+ * per-run limit (so a long backlog drains across runs instead of stranding the
+ * tail). Without an `accountId`, falls back to the legacy fixed-lookback window
+ * with no persistence. Returns a summary; never throws.
+ */
+export declare function runBlueBubblesCatchup(args: RunBlueBubblesCatchupArgs): Promise<BlueBubblesCatchupSummary>;
+//# sourceMappingURL=catchup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catchup.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/catchup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAKN,KAAK,sBAAsB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAuD,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjG,8DAA8D;AAC9D,eAAO,MAAM,uCAAuC,QAAiB,CAAC;AACtE,mCAAmC;AACnC,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,yGAAyG;AACzG,eAAO,MAAM,+CAA+C,KAAK,CAAC;AAClE,2CAA2C;AAC3C,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAE7D,qCAAqC;AACrC,MAAM,WAAW,wBAAwB;IACxC,iCAAiC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6HAA6H;IAC7H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iCAAiC;AACjC,MAAM,WAAW,yBAAyB;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACtD,uBAAuB;IACvB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACrC;AAED,uDAAuD;AACvD,MAAM,WAAW,yBAAyB;IACzC,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;CACtB;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA8J/G"}

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

@@ -0,0 +1,220 @@
+/**
+ * BlueBubbles catch-up backfill.
+ *
+ * BlueBubbles delivers inbound via webhook POST. When Brigade is down (restart,
+ * crash, upgrade) the server's webhook fire fails and is NOT retried, so any
+ * message that arrived during the outage is lost. On (re)connect, catch-up
+ * queries the server for messages delivered in a bounded recent window
+ * (`POST /api/v1/message/query`, `after: <sinceMs>`, capped by `limit`) and
+ * re-feeds each one through the SAME path a live webhook event takes —
+ * normalize → dedupe → dispatch.
+ *
+ * The dedupe is what makes this safe: a message already delivered live (or in a
+ * previous catch-up pass) is claimed in the connection's dedupe cache, so the
+ * replay is dropped there and the agent NEVER replies twice. Catch-up therefore
+ * recovers ONLY the genuinely-missed messages.
+ *
+ * `fetch` is INJECTABLE (the test seam) so the whole query → replay path runs
+ * with no live server. Never throws — a query failure logs and leaves the live
+ * webhook path untouched.
+ */
+import { capFailureRetriesMap, filesystemCursorStore, BLUEBUBBLES_MAX_FAILURE_RETRY_MAP_SIZE, } from "./catchup-cursor.js";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+/** Default lookback window when running catch-up (30 min). */
+export const BLUEBUBBLES_CATCHUP_DEFAULT_LOOKBACK_MS = 30 * 60 * 1000;
+/** Default per-run message cap. */
+export const BLUEBUBBLES_CATCHUP_DEFAULT_LIMIT = 50;
+/** Hard ceiling on the per-run cap (defends against an unbounded backlog). */
+export const BLUEBUBBLES_CATCHUP_MAX_LIMIT = 500;
+/** Default per-message consecutive-failure ceiling before catch-up gives up + force-advances past it. */
+export const BLUEBUBBLES_CATCHUP_DEFAULT_MAX_FAILURE_RETRIES = 10;
+/** Hard ceiling on `maxFailureRetries`. */
+export const BLUEBUBBLES_CATCHUP_MAX_FAILURE_RETRIES = 1_000;
+/** Clamp the per-run limit into `[1, MAX]`. */
+function clampLimit(raw) {
+    const n = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : BLUEBUBBLES_CATCHUP_DEFAULT_LIMIT;
+    return Math.min(Math.max(n, 1), BLUEBUBBLES_CATCHUP_MAX_LIMIT);
+}
+/** Clamp `maxFailureRetries` into `[1, MAX]`. */
+function clampMaxFailureRetries(raw) {
+    const n = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : BLUEBUBBLES_CATCHUP_DEFAULT_MAX_FAILURE_RETRIES;
+    return Math.min(Math.max(n, 1), BLUEBUBBLES_CATCHUP_MAX_FAILURE_RETRIES);
+}
+/**
+ * Read a record's timestamp (epoch ms) across camel/snake shapes; 0 when absent.
+ * BlueBubbles `dateCreated` is already epoch ms, so the value is taken raw (the
+ * cursor compares it against other `dateCreated` values + `now`).
+ */
+function recordTimestampMs(rec) {
+    for (const k of ["dateCreated", "date_created", "date", "timestamp"]) {
+        const v = rec[k];
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return 0;
+}
+/** Read a record's GUID (the retry-map key), or "" when absent. */
+function recordGuid(rec) {
+    const g = rec.guid ?? rec.messageGuid;
+    return typeof g === "string" ? g.trim() : "";
+}
+/**
+ * Run one bounded catch-up pass.
+ *
+ * With an `accountId`, queries strictly AFTER the persisted cursor (`lastSeenMs`),
+ * re-feeds each record through `feedRecord` (the connection's normalize+dedupe
+ * path), then advances the cursor: to "now" on a clean pass, held just before the
+ * earliest still-retrying failure, force-advanced past any GUID that has failed
+ * `maxFailureRetries` times, or to the page boundary when the fetch hit the
+ * per-run limit (so a long backlog drains across runs instead of stranding the
+ * tail). Without an `accountId`, falls back to the legacy fixed-lookback window
+ * with no persistence. Returns a summary; never throws.
+ */
+export async function runBlueBubblesCatchup(args) {
+    const cfg = args.config ?? {};
+    const nowMs = (args.now ?? Date.now)();
+    const lookbackMs = typeof cfg.lookbackMs === "number" && cfg.lookbackMs > 0 ? cfg.lookbackMs : BLUEBUBBLES_CATCHUP_DEFAULT_LOOKBACK_MS;
+    const limit = clampLimit(cfg.limit);
+    const maxFailureRetries = clampMaxFailureRetries(cfg.maxFailureRetries);
+    const accountId = (args.accountId ?? "").trim();
+    const usePersistedCursor = accountId.length > 0;
+    const store = args.cursorStore ?? filesystemCursorStore;
+    // Load the persisted cursor (only when an accountId is in play).
+    const existing = usePersistedCursor
+        ? (() => {
+            try {
+                return store.load(accountId);
+            }
+            catch {
+                return null;
+            }
+        })()
+        : null;
+    const prevRetries = existing?.failureRetries ?? {};
+    const cursorBefore = usePersistedCursor ? (existing?.lastSeenMs ?? null) : null;
+    // Window start: after a USABLE cursor (not future-dated), else the first-run lookback.
+    const cursorUsable = existing !== null && existing.lastSeenMs <= nowMs;
+    const windowStartMs = cursorUsable ? existing.lastSeenMs : nowMs - lookbackMs;
+    const summary = {
+        querySucceeded: false,
+        fetched: 0,
+        replayed: 0,
+        givenUp: 0,
+        skippedGivenUp: 0,
+        failed: 0,
+        cursorBefore,
+        cursorAfter: usePersistedCursor ? (cursorBefore ?? windowStartMs) : windowStartMs,
+        windowStartMs,
+    };
+    if (cfg.enabled === false)
+        return summary;
+    let records = [];
+    try {
+        const url = buildBlueBubblesApiUrl({ serverUrl: args.serverUrl, path: "message/query", password: args.password });
+        const res = await blueBubblesFetchWithTimeout(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                limit,
+                sort: "ASC",
+                after: windowStartMs,
+                // Match the fields the live webhook carries so normalize sees the same shape.
+                with: ["chat", "chat.participants", "attachment", "handle"],
+            }),
+        }, { ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}), ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}), ...(args.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}) });
+        if (!res.ok) {
+            args.log?.(`catchup: message/query returned HTTP ${res.status}`);
+            return summary; // leave cursor unchanged → next run retries the same window
+        }
+        const text = await res.text();
+        const body = text ? JSON.parse(text) : {};
+        const data = body.data;
+        if (!Array.isArray(data)) {
+            args.log?.("catchup: message/query returned no data array");
+            return summary;
+        }
+        records = data.filter((r) => !!r && typeof r === "object" && !Array.isArray(r));
+        summary.querySucceeded = true;
+        summary.fetched = records.length;
+    }
+    catch (err) {
+        args.log?.(`catchup: message/query failed: ${err instanceof Error ? err.message : String(err)}`);
+        return summary;
+    }
+    // Build a fresh retry map each run (GUIDs not seen this run are dropped — the
+    // cursor advanced past them). Hold the cursor before the earliest STILL-RETRYING
+    // failure; track the latest fetched ts for page-boundary advance.
+    const nextRetries = {};
+    let earliestFailureTs = null;
+    let latestFetchedTs = windowStartMs;
+    for (const record of records) {
+        const ts = recordTimestampMs(record);
+        if (ts > latestFetchedTs)
+            latestFetchedTs = ts;
+        const guid = recordGuid(record);
+        // A GUID already given up in a prior run is skipped on sight (no replay,
+        // doesn't hold the cursor) — preserve its count so give-up stays sticky.
+        const prevCount = guid ? (prevRetries[guid] ?? 0) : 0;
+        if (guid && prevCount >= maxFailureRetries) {
+            summary.skippedGivenUp++;
+            nextRetries[guid] = prevCount;
+            continue;
+        }
+        // Re-feed through the SAME normalize+dedupe path a live webhook uses. The
+        // connection's dedupe cache drops anything already delivered, so a replay
+        // can never double-deliver. A THROW marks this record as a failed replay.
+        try {
+            args.feedRecord(record);
+            summary.replayed++;
+            // Success clears any accrued retries for this GUID (we just don't copy it).
+        }
+        catch (err) {
+            summary.failed++;
+            const nextCount = prevCount + 1;
+            if (guid && nextCount >= maxFailureRetries) {
+                // Crossed the ceiling: give up + force-advance past it (don't hold).
+                summary.givenUp++;
+                nextRetries[guid] = nextCount;
+                args.log?.(`catchup: giving up on guid=${guid} after ${nextCount} failures; future runs will skip it. ${err instanceof Error ? err.message : String(err)}`);
+            }
+            else {
+                // Still retrying: hold the cursor just before the earliest such failure.
+                if (guid)
+                    nextRetries[guid] = nextCount;
+                if (ts > 0 && (earliestFailureTs === null || ts < earliestFailureTs))
+                    earliestFailureTs = ts;
+            }
+        }
+    }
+    // Compute + persist the new cursor (only when persistence is in play).
+    if (usePersistedCursor) {
+        const isTruncated = summary.fetched >= limit;
+        let nextCursorMs = nowMs;
+        if (earliestFailureTs !== null) {
+            // Hold just before the earliest still-retrying failure.
+            nextCursorMs = Math.min(Math.max(earliestFailureTs - 1, cursorBefore ?? windowStartMs), nowMs);
+        }
+        else if (isTruncated) {
+            // Advance only to the page boundary so the unfetched tail is reachable next run.
+            nextCursorMs = Math.min(Math.max(latestFetchedTs, cursorBefore ?? windowStartMs), nowMs);
+        }
+        summary.cursorAfter = nextCursorMs;
+        const retriesToPersist = capFailureRetriesMap(nextRetries, BLUEBUBBLES_MAX_FAILURE_RETRY_MAP_SIZE);
+        try {
+            store.save(accountId, {
+                lastSeenMs: nextCursorMs,
+                updatedAt: nowMs,
+                ...(Object.keys(retriesToPersist).length > 0 ? { failureRetries: retriesToPersist } : {}),
+            });
+        }
+        catch (err) {
+            args.log?.(`catchup: cursor save failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (isTruncated) {
+            args.log?.(`catchup: WARNING fetched=${summary.fetched} hit limit=${limit}; cursor advanced only to page boundary, remaining picked up next run. Raise catchup.limit to drain larger backlogs.`);
+        }
+    }
+    args.log?.(`catchup: fetched=${summary.fetched} replayed=${summary.replayed} failed=${summary.failed} given_up=${summary.givenUp} skipped_givenUp=${summary.skippedGivenUp} window_ms=${nowMs - windowStartMs}`);
+    return summary;
+}
+//# sourceMappingURL=catchup.js.map

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

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

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

@@ -0,0 +1,75 @@
+/**
+ * BlueBubbles chat-level REST actions — typing, mark-read, and group admin.
+ *
+ * These are the chat-scoped operations on top of the per-message send surface
+ * in `send.ts`. Like every BlueBubbles REST helper they go through
+ * `buildBlueBubblesApiUrl` + `blueBubblesFetchWithTimeout` (password in the
+ * query string, INJECTABLE `fetchImpl` as the test seam) and share the
+ * `BlueBubblesRestBase` shape.
+ *
+ * Surface:
+ *   - `sendBlueBubblesTyping`        POST/DELETE chat/{guid}/typing (Private API)
+ *   - `markBlueBubblesChatRead`      POST chat/{guid}/read          (Private API)
+ *   - `renameBlueBubblesChat`        PUT  chat/{guid}               (Private API)
+ *   - `addBlueBubblesParticipant`    POST chat/{guid}/participant/add    (Private API)
+ *   - `removeBlueBubblesParticipant` POST chat/{guid}/participant/remove (Private API)
+ *   - `leaveBlueBubblesChat`         POST chat/{guid}/leave         (Private API)
+ *   - `setBlueBubblesGroupIcon`      POST chat/{guid}/icon (multipart) (Private API)
+ *
+ * EVERY action here needs the BlueBubbles server's Private API (the AppleScript /
+ * helper bundle that drives Messages.app); a server with the Private API off
+ * cannot type, mark-read, rename, or change membership. Typing + mark-read are
+ * COSMETIC, so they silently no-op when the Private API is off (matching how the
+ * pipeline treats read-receipts/typing as best-effort); the group-admin ops
+ * THROW an operator-facing error so the agent tool can report the refusal.
+ */
+import type { BlueBubblesRestBase } from "./send.js";
+/**
+ * Signal "typing…" (or stop) in a chat. `POST` starts the indicator, `DELETE`
+ * clears it. COSMETIC — silently no-ops when the Private API is off (a server
+ * without it simply cannot drive the typing bubble). Best-effort: a transport
+ * error propagates so the caller can swallow it (the pipeline treats typing as
+ * cosmetic).
+ */
+export declare function sendBlueBubblesTyping(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+    typing: boolean;
+}): Promise<void>;
+/**
+ * Mark a chat read (clears the unread badge + sends a read receipt). COSMETIC —
+ * silently no-ops when the Private API is off.
+ */
+export declare function markBlueBubblesChatRead(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+}): Promise<void>;
+/** Rename a group chat's display name (Private API). */
+export declare function renameBlueBubblesChat(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+    displayName: string;
+}): Promise<void>;
+/** Add a participant (phone/email handle) to a group chat (Private API). */
+export declare function addBlueBubblesParticipant(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+    address: string;
+}): Promise<void>;
+/** Remove a participant (phone/email handle) from a group chat (Private API). */
+export declare function removeBlueBubblesParticipant(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+    address: string;
+}): Promise<void>;
+/** Leave a group chat (Private API). */
+export declare function leaveBlueBubblesChat(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+}): Promise<void>;
+/**
+ * Set (or change) a group chat's icon/photo via a multipart upload (Private
+ * API). `bytes` is the image; `filename` is sanitised. A longer default timeout
+ * applies (uploads are heavier than a JSON call).
+ */
+export declare function setBlueBubblesGroupIcon(base: BlueBubblesRestBase, params: {
+    chatGuid: string;
+    bytes: Uint8Array;
+    filename?: string;
+    contentType?: string;
+}): Promise<void>;
+//# sourceMappingURL=chat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAkBrD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAC1C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC5C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,wDAAwD;AACxD,wBAAsB,qBAAqB,CAC1C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/C,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,4EAA4E;AAC5E,wBAAsB,yBAAyB,CAC9C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,iFAAiF;AACjF,wBAAsB,4BAA4B,CACjD,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,wCAAwC;AACxC,wBAAsB,oBAAoB,CACzC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAWf;AAQD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC5C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

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

@@ -0,0 +1,182 @@
+/**
+ * BlueBubbles chat-level REST actions — typing, mark-read, and group admin.
+ *
+ * These are the chat-scoped operations on top of the per-message send surface
+ * in `send.ts`. Like every BlueBubbles REST helper they go through
+ * `buildBlueBubblesApiUrl` + `blueBubblesFetchWithTimeout` (password in the
+ * query string, INJECTABLE `fetchImpl` as the test seam) and share the
+ * `BlueBubblesRestBase` shape.
+ *
+ * Surface:
+ *   - `sendBlueBubblesTyping`        POST/DELETE chat/{guid}/typing (Private API)
+ *   - `markBlueBubblesChatRead`      POST chat/{guid}/read          (Private API)
+ *   - `renameBlueBubblesChat`        PUT  chat/{guid}               (Private API)
+ *   - `addBlueBubblesParticipant`    POST chat/{guid}/participant/add    (Private API)
+ *   - `removeBlueBubblesParticipant` POST chat/{guid}/participant/remove (Private API)
+ *   - `leaveBlueBubblesChat`         POST chat/{guid}/leave         (Private API)
+ *   - `setBlueBubblesGroupIcon`      POST chat/{guid}/icon (multipart) (Private API)
+ *
+ * EVERY action here needs the BlueBubbles server's Private API (the AppleScript /
+ * helper bundle that drives Messages.app); a server with the Private API off
+ * cannot type, mark-read, rename, or change membership. Typing + mark-read are
+ * COSMETIC, so they silently no-op when the Private API is off (matching how the
+ * pipeline treats read-receipts/typing as best-effort); the group-admin ops
+ * THROW an operator-facing error so the agent tool can report the refusal.
+ */
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl, readBlueBubblesJson, } from "./types.js";
+/** Shared fetch-option assembly so every helper threads timeout + fetchImpl + the SSRF knob identically. */
+function fetchOpts(base) {
+    return {
+        ...(base.timeoutMs !== undefined ? { timeoutMs: base.timeoutMs } : {}),
+        ...(base.fetchImpl ? { fetchImpl: base.fetchImpl } : {}),
+        ...(base.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}),
+    };
+}
+/** Refuse a Private-API-only group action when the server has the Private API off. */
+function assertPrivateApi(base, feature) {
+    if (base.privateApiEnabled === false) {
+        throw new Error(`BlueBubbles ${feature} requires the Private API to be enabled on the server`);
+    }
+}
+/**
+ * Signal "typing…" (or stop) in a chat. `POST` starts the indicator, `DELETE`
+ * clears it. COSMETIC — silently no-ops when the Private API is off (a server
+ * without it simply cannot drive the typing bubble). Best-effort: a transport
+ * error propagates so the caller can swallow it (the pipeline treats typing as
+ * cosmetic).
+ */
+export async function sendBlueBubblesTyping(base, params) {
+    const chatGuid = (params.chatGuid ?? "").trim();
+    if (!chatGuid)
+        return;
+    // Private API drives the typing indicator; without it there is nothing to do.
+    if (base.privateApiEnabled === false)
+        return;
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/typing`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: params.typing ? "POST" : "DELETE" }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/typing");
+}
+/**
+ * Mark a chat read (clears the unread badge + sends a read receipt). COSMETIC —
+ * silently no-ops when the Private API is off.
+ */
+export async function markBlueBubblesChatRead(base, params) {
+    const chatGuid = (params.chatGuid ?? "").trim();
+    if (!chatGuid)
+        return;
+    if (base.privateApiEnabled === false)
+        return;
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/read`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/read");
+}
+/** Rename a group chat's display name (Private API). */
+export async function renameBlueBubblesChat(base, params) {
+    assertPrivateApi(base, "group rename");
+    const chatGuid = (params.chatGuid ?? "").trim();
+    if (!chatGuid)
+        throw new Error("BlueBubbles group rename requires a chatGuid");
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ displayName: params.displayName ?? "" }),
+    }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/rename");
+}
+/** Add a participant (phone/email handle) to a group chat (Private API). */
+export async function addBlueBubblesParticipant(base, params) {
+    assertPrivateApi(base, "add participant");
+    const chatGuid = (params.chatGuid ?? "").trim();
+    const address = (params.address ?? "").trim();
+    if (!chatGuid)
+        throw new Error("BlueBubbles add participant requires a chatGuid");
+    if (!address)
+        throw new Error("BlueBubbles add participant requires an address");
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/participant/add`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address }) }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/participant/add");
+}
+/** Remove a participant (phone/email handle) from a group chat (Private API). */
+export async function removeBlueBubblesParticipant(base, params) {
+    assertPrivateApi(base, "remove participant");
+    const chatGuid = (params.chatGuid ?? "").trim();
+    const address = (params.address ?? "").trim();
+    if (!chatGuid)
+        throw new Error("BlueBubbles remove participant requires a chatGuid");
+    if (!address)
+        throw new Error("BlueBubbles remove participant requires an address");
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/participant/remove`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address }) }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/participant/remove");
+}
+/** Leave a group chat (Private API). */
+export async function leaveBlueBubblesChat(base, params) {
+    assertPrivateApi(base, "leave group");
+    const chatGuid = (params.chatGuid ?? "").trim();
+    if (!chatGuid)
+        throw new Error("BlueBubbles leave group requires a chatGuid");
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/leave`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, fetchOpts(base));
+    await readBlueBubblesJson(res, "chat/leave");
+}
+/** Sanitise a filename for a multipart header (CWE-93 / header injection guard). */
+function sanitizeIconFilename(name) {
+    const base = path.basename(name || "icon.png").replace(/[\r\n"\\]/g, "_").trim();
+    return base || "icon.png";
+}
+/**
+ * Set (or change) a group chat's icon/photo via a multipart upload (Private
+ * API). `bytes` is the image; `filename` is sanitised. A longer default timeout
+ * applies (uploads are heavier than a JSON call).
+ */
+export async function setBlueBubblesGroupIcon(base, params) {
+    assertPrivateApi(base, "set group icon");
+    const chatGuid = (params.chatGuid ?? "").trim();
+    if (!chatGuid)
+        throw new Error("BlueBubbles set group icon requires a chatGuid");
+    if (!params.bytes || params.bytes.length === 0)
+        throw new Error("BlueBubbles set group icon requires image bytes");
+    const filename = sanitizeIconFilename(params.filename ?? "icon.png");
+    const form = new FormData();
+    const ab = params.bytes.buffer.slice(params.bytes.byteOffset, params.bytes.byteOffset + params.bytes.byteLength);
+    const blob = new Blob([ab], params.contentType ? { type: params.contentType } : {});
+    form.append("icon", blob, filename);
+    form.append("tempGuid", `temp-${Date.now()}-${randomUUID().slice(0, 8)}`);
+    const url = buildBlueBubblesApiUrl({
+        serverUrl: base.serverUrl,
+        path: `chat/${encodeURIComponent(chatGuid)}/icon`,
+        password: base.password,
+    });
+    const res = await blueBubblesFetchWithTimeout(url, { method: "POST", body: form }, 
+    // Uploads can be large — give a generous default timeout.
+    { ...fetchOpts(base), timeoutMs: base.timeoutMs ?? 60_000 });
+    await readBlueBubblesJson(res, "chat/icon");
+}
+//# sourceMappingURL=chat.js.map

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

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