@ouro.bot/cli 0.1.0-alpha.34 → 0.1.0-alpha.340

package/dist/repertoire/vault-setup.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Vault setup module — Bitwarden/Vaultwarden account creation.
+ *
+ * Implements the Bitwarden registration protocol using Node.js crypto:
+ * - PBKDF2-SHA256 for master key derivation
+ * - HKDF-SHA256 for key stretching
+ * - AES-256-CBC for symmetric key protection
+ * - RSA-2048 keypair for asymmetric encryption
+ *
+ * All crypto follows the Bitwarden security whitepaper:
+ * https://bitwarden.com/help/bitwarden-security-white-paper/
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveMasterKey = deriveMasterKey;
+exports.deriveMasterPasswordHash = deriveMasterPasswordHash;
+exports.deriveStretchedMasterKey = deriveStretchedMasterKey;
+exports.makeProtectedSymmetricKey = makeProtectedSymmetricKey;
+exports.createVaultAccount = createVaultAccount;
+const crypto = __importStar(require("node:crypto"));
+const runtime_1 = require("../nerves/runtime");
+// ---------------------------------------------------------------------------
+// Crypto primitives
+// ---------------------------------------------------------------------------
+/**
+ * Derive the master key from password and email using PBKDF2-SHA256.
+ * Email is lowercased and used as the salt per Bitwarden spec.
+ */
+function deriveMasterKey(password, email, iterations) {
+    return new Promise((resolve, reject) => {
+        crypto.pbkdf2(password, email.toLowerCase(), iterations, 32, "sha256", (err, key) => {
+            /* v8 ignore next -- defensive: pbkdf2 rejects on invalid input @preserve */
+            if (err)
+                reject(err);
+            else
+                resolve(key);
+        });
+    });
+}
+/**
+ * Derive the master password hash: PBKDF2-SHA256(masterKey, password, 1 iteration).
+ * This hash is sent to the server for authentication — it never sees the master key.
+ */
+function deriveMasterPasswordHash(masterKey, password) {
+    return new Promise((resolve, reject) => {
+        crypto.pbkdf2(masterKey, password, 1, 32, "sha256", (err, hash) => {
+            /* v8 ignore next -- defensive: pbkdf2 rejects on invalid input @preserve */
+            if (err)
+                reject(err);
+            else
+                resolve(hash.toString("base64"));
+        });
+    });
+}
+/**
+ * Stretch the master key using HKDF-Expand-only (RFC 5869 §2.3) to produce a 64-byte key.
+ * First 32 bytes = encryption key, last 32 bytes = MAC key.
+ *
+ * CRITICAL: Bitwarden uses HKDF-Expand ONLY (no Extract step).
+ * Node.js crypto.hkdfSync() does Extract+Expand which produces DIFFERENT output.
+ * Reference: https://github.com/bitwarden/sdk-internal/blob/main/crates/bitwarden-crypto/src/util.rs
+ * Bitwarden calls Hkdf::<Sha256>::from_prk(masterKey).expand(info, output) — Expand only.
+ */
+function deriveStretchedMasterKey(masterKey) {
+    const encKey = hkdfExpandOnly(masterKey, "enc", 32);
+    const macKey = hkdfExpandOnly(masterKey, "mac", 32);
+    return Buffer.concat([encKey, macKey]);
+}
+/**
+ * HKDF-Expand only (RFC 5869 §2.3) — no Extract step.
+ * Matches Bitwarden's Hkdf::from_prk(prk).expand(info).
+ */
+function hkdfExpandOnly(prk, info, length) {
+    const hashLen = 32; // SHA-256
+    const n = Math.ceil(length / hashLen);
+    let okm = Buffer.alloc(0);
+    let t = Buffer.alloc(0);
+    for (let i = 1; i <= n; i++) {
+        t = crypto.createHmac("sha256", prk)
+            .update(Buffer.concat([t, Buffer.from(info, "utf8"), Buffer.from([i])]))
+            .digest();
+        okm = Buffer.concat([okm, t]);
+    }
+    return okm.subarray(0, length);
+}
+/**
+ * Encrypt data with AES-256-CBC and HMAC-SHA256 MAC.
+ * Returns a Bitwarden "type 2" cipherstring: "2.<iv>|<ct>|<mac>"
+ */
+function encryptWithStretchedKey(data, stretchedKey) {
+    const encKey = stretchedKey.subarray(0, 32);
+    const macKey = stretchedKey.subarray(32, 64);
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv("aes-256-cbc", encKey, iv);
+    const ct = Buffer.concat([cipher.update(data), cipher.final()]);
+    // MAC covers iv + ct
+    const mac = crypto.createHmac("sha256", macKey)
+        .update(iv)
+        .update(ct)
+        .digest();
+    return `2.${iv.toString("base64")}|${ct.toString("base64")}|${mac.toString("base64")}`;
+}
+/**
+ * Generate a 64-byte symmetric key, encrypt it with the stretched master key.
+ * Returns the "protected symmetric key" cipherstring.
+ */
+function makeProtectedSymmetricKey(stretchedMasterKey) {
+    const symKey = crypto.randomBytes(64);
+    return encryptWithStretchedKey(symKey, stretchedMasterKey);
+}
+/**
+ * Generate an RSA-2048 keypair.
+ * Returns { publicKey: base64-DER, privateKeyDer: Buffer }.
+ */
+function generateRsaKeypair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "der" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    return {
+        publicKeyB64: publicKey.toString("base64"),
+        privateKeyDer: privateKey,
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+const KDF_PBKDF2 = 0;
+const KDF_ITERATIONS = 600000;
+/**
+ * Create a Bitwarden account on the configured Vaultwarden server.
+ * Uses the Bitwarden registration API with standard KDF implementation.
+ */
+async function createVaultAccount(agentName, serverUrl, email, masterPassword) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "repertoire.vault_setup_start",
+        component: "repertoire",
+        message: `creating vault account for ${agentName}`,
+        meta: { agentName, serverUrl, email },
+    });
+    try {
+        // Step 1: Derive keys
+        const masterKey = await deriveMasterKey(masterPassword, email, KDF_ITERATIONS);
+        const masterPasswordHash = await deriveMasterPasswordHash(masterKey, masterPassword);
+        const stretchedKey = deriveStretchedMasterKey(masterKey);
+        // Step 2: Generate symmetric key (64 bytes = 32 enc + 32 mac), encrypt with stretched key
+        const symKey = crypto.randomBytes(64);
+        const protectedSymKey = encryptWithStretchedKey(symKey, stretchedKey);
+        // Step 3: Generate RSA keypair, encrypt private key with the symmetric key
+        const { publicKeyB64, privateKeyDer } = generateRsaKeypair();
+        const encryptedPrivateKey = encryptWithStretchedKey(privateKeyDer, symKey);
+        // Step 4: POST registration
+        const res = await fetch(`${serverUrl}/api/accounts/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                name: agentName,
+                email,
+                masterPasswordHash,
+                masterPasswordHint: null,
+                key: protectedSymKey,
+                kdf: KDF_PBKDF2,
+                kdfIterations: KDF_ITERATIONS,
+                keys: {
+                    publicKey: publicKeyB64,
+                    encryptedPrivateKey,
+                },
+            }),
+        });
+        if (!res.ok) {
+            let errorDetail;
+            try {
+                const body = await res.json();
+                errorDetail = body.message ?? `HTTP ${res.status} ${res.statusText}`;
+            }
+            catch {
+                errorDetail = `HTTP ${res.status} ${res.statusText}`;
+            }
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                event: "repertoire.vault_setup_error",
+                component: "repertoire",
+                message: `vault registration failed: ${errorDetail}`,
+                meta: { agentName, serverUrl, email, reason: errorDetail },
+            });
+            return { success: false, email, serverUrl, error: errorDetail };
+        }
+        (0, runtime_1.emitNervesEvent)({
+            event: "repertoire.vault_setup_end",
+            component: "repertoire",
+            message: `vault account created for ${agentName}`,
+            meta: { agentName, serverUrl, email },
+        });
+        return { success: true, email, serverUrl };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "repertoire.vault_setup_error",
+            component: "repertoire",
+            message: `vault setup failed: ${reason}`,
+            meta: { agentName, serverUrl, email, reason },
+        });
+        return { success: false, email, serverUrl, error: reason };
+    }
+}

package/dist/scripts/claude-code-hook.js

@@ -0,0 +1,41 @@
+"use strict";
+// Claude Code lifecycle hook handler.
+// Receives events from Claude Code's hooks system (SessionStart, Stop, PostToolUse)
+// and forwards them to the Ouroboros daemon for agent awareness.
+//
+// This module exports handleHookEvent for testability.
+// The actual hook scripts (scripts/claude-code-hook.js) read stdin and call this.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = handleHookEvent;
+const socket_client_1 = require("../heart/daemon/socket-client");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Handle a Claude Code lifecycle hook event.
+ * Sends the event to the daemon and always exits 0 (hooks must not block the IDE).
+ */
+async function handleHookEvent(hookEvent) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.hook_event_received",
+        message: "claude code hook event received",
+        meta: { hookEvent: hookEvent.event, sessionId: hookEvent.sessionId },
+    });
+    try {
+        await (0, socket_client_1.sendDaemonCommand)(socket_client_1.DEFAULT_DAEMON_SOCKET_PATH, {
+            kind: "hook.event",
+            event: hookEvent.event,
+            sessionId: hookEvent.sessionId,
+            toolName: hookEvent.toolName,
+        });
+    }
+    catch {
+        // Daemon unavailable — silently ignore. Hooks must not block.
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.hook_event_daemon_unavailable",
+            message: "daemon unavailable for hook event",
+            meta: { hookEvent: hookEvent.event },
+        });
+    }
+    return { exitCode: 0 };
+}

package/dist/scripts/claude-code-stop-hook.js

@@ -0,0 +1,47 @@
+"use strict";
+// Claude Code stop hook — checks the agent's pending queue and returns
+// any messages as additionalContext for injection into the next turn.
+//
+// This is how the agent can proactively communicate back to the dev tool user:
+// the agent surfaces a message to the pending queue, and the stop hook picks
+// it up and injects it as context in the Claude Code session.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleStopHook = handleStopHook;
+const pending_1 = require("../mind/pending");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Check the pending queue for messages from the agent to this dev tool session.
+ * Returns accumulated message text as additionalContext.
+ */
+async function handleStopHook(input) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.stop_hook_check_start",
+        message: "checking pending queue for stop hook",
+        meta: { agentName: input.agentName, friendId: input.friendId, sessionId: input.sessionId },
+    });
+    try {
+        const pendingDir = (0, pending_1.getPendingDir)(input.agentName, input.friendId, "mcp", input.sessionId);
+        const pending = (0, pending_1.drainPending)(pendingDir);
+        if (pending.length === 0) {
+            return { additionalContext: "" };
+        }
+        const text = pending.map((m) => m.content).join("\n\n---\n\n");
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.stop_hook_check_end",
+            message: "pending messages found for stop hook",
+            meta: { agentName: input.agentName, count: pending.length },
+        });
+        return { additionalContext: text };
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.stop_hook_check_error",
+            message: "error checking pending queue in stop hook",
+            meta: { agentName: input.agentName },
+        });
+        return { additionalContext: "" };
+    }
+}

package/dist/senses/attention-queue.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAttentionQueue = buildAttentionQueue;
+exports.dequeueAttentionItem = dequeueAttentionItem;
+exports.attentionQueueEmpty = attentionQueueEmpty;
+exports.buildAttentionQueueSummary = buildAttentionQueueSummary;
+const runtime_1 = require("../nerves/runtime");
+// ── Queue construction ───────────────────────────────────────────
+function generateItemId() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function originKey(friendId, channel, key) {
+    return `${friendId}/${channel}/${key}`;
+}
+function buildAttentionQueue(input) {
+    const { drainedPending, outstandingObligations, friendNameResolver, packetResolver } = input;
+    const seen = new Set();
+    const items = [];
+    const enrichPacket = (packetId) => {
+        if (!packetId || !packetResolver)
+            return {};
+        const packet = packetResolver(packetId);
+        if (!packet)
+            return { packetId };
+        return {
+            packetId,
+            packetKind: packet.kind,
+            packetObjective: packet.objective,
+            packetSummary: packet.summary,
+        };
+    };
+    // Source 1: drained pending messages with delegatedFrom (current-turn delegations)
+    for (const msg of drainedPending) {
+        if (!msg.delegatedFrom)
+            continue;
+        const { friendId, channel, key, bridgeId } = msg.delegatedFrom;
+        const oKey = originKey(friendId, channel, key);
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: msg.obligationId ?? generateItemId(),
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: msg.content,
+            ...(msg.obligationId ? { obligationId: msg.obligationId } : {}),
+            ...enrichPacket(msg.packetId),
+            source: "drained",
+            timestamp: msg.timestamp,
+        });
+    }
+    // Source 2: outstanding obligations (crash recovery)
+    for (const obligation of outstandingObligations) {
+        const { friendId, channel, key, bridgeId } = obligation.origin;
+        const oKey = originKey(friendId, channel, key);
+        if (seen.has(oKey))
+            continue; // deduplicate: prefer drained version
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: obligation.id,
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: obligation.delegatedContent,
+            obligationId: obligation.id,
+            ...enrichPacket(obligation.packetId),
+            source: "obligation-recovery",
+            timestamp: obligation.createdAt,
+        });
+    }
+    // Sort FIFO (oldest first)
+    items.sort((a, b) => a.timestamp - b.timestamp);
+    (0, runtime_1.emitNervesEvent)({
+        event: "senses.attention_queue_built",
+        component: "senses",
+        message: `attention queue built with ${items.length} item(s)`,
+        meta: {
+            drainedCount: items.filter((i) => i.source === "drained").length,
+            recoveredCount: items.filter((i) => i.source === "obligation-recovery").length,
+        },
+    });
+    return items;
+}
+// ── Queue operations ─────────────────────────────────────────────
+function dequeueAttentionItem(queue, id) {
+    const index = queue.findIndex((item) => item.id === id);
+    if (index === -1)
+        return null;
+    return queue.splice(index, 1)[0];
+}
+function attentionQueueEmpty(queue) {
+    return queue.length === 0;
+}
+// ── Queue visibility ─────────────────────────────────────────────
+const CONTENT_PREVIEW_MAX = 80;
+function buildAttentionQueueSummary(queue) {
+    if (queue.length === 0)
+        return "";
+    const lines = ["you're holding:"];
+    for (const item of queue) {
+        if (item.packetKind && item.packetObjective) {
+            lines.push(`- [${item.id}] ${item.friendName} -> ${item.packetKind}: ${item.packetObjective}`);
+            continue;
+        }
+        const preview = item.delegatedContent.length > CONTENT_PREVIEW_MAX
+            ? `${item.delegatedContent.slice(0, CONTENT_PREVIEW_MAX - 3)}...`
+            : item.delegatedContent;
+        lines.push(`- [${item.id}] ${item.friendName} asked: "${preview}"`);
+    }
+    return lines.join("\n");
+}

package/dist/senses/bluebubbles/attachment-cache.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rememberBlueBubblesAttachment = rememberBlueBubblesAttachment;
+exports.lookupBlueBubblesAttachment = lookupBlueBubblesAttachment;
+exports.resetBlueBubblesAttachmentCache = resetBlueBubblesAttachmentCache;
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * Bounded in-memory cache of recently-seen BlueBubbles attachment summaries.
+ *
+ * Populated at attachment-hydration time so the `describe_image` tool can
+ * look up a guid → summary later in the same turn (or a few turns later)
+ * and re-download the bytes on demand. Intentionally NOT persisted — per
+ * planning doc D4, session storage holds only the VLM description text,
+ * never the raw image bytes. The cache is cleared on daemon restart, which
+ * matches the product expectation that "describe_image works on recent
+ * messages in this session".
+ *
+ * Bounded at MAX_CACHED_ATTACHMENTS entries; oldest entries evict first
+ * when the limit is hit.
+ */
+const MAX_CACHED_ATTACHMENTS = 50;
+const cache = new Map();
+function rememberBlueBubblesAttachment(summary) {
+    const guid = summary.guid?.trim();
+    if (!guid)
+        return;
+    // Re-insert to move to end (LRU behavior via Map insertion order).
+    if (cache.has(guid))
+        cache.delete(guid);
+    cache.set(guid, { ...summary });
+    while (cache.size > MAX_CACHED_ATTACHMENTS) {
+        // cache.size > 0 here, so keys().next().value is always defined.
+        const oldestKey = cache.keys().next().value;
+        cache.delete(oldestKey);
+    }
+}
+function lookupBlueBubblesAttachment(guid) {
+    const trimmed = guid?.trim();
+    if (!trimmed)
+        return undefined;
+    return cache.get(trimmed);
+}
+function resetBlueBubblesAttachmentCache() {
+    cache.clear();
+}
+/* v8 ignore start — module-level observability event */
+(0, runtime_1.emitNervesEvent)({
+    component: "senses",
+    event: "senses.bluebubbles_attachment_cache_loaded",
+    message: "bluebubbles attachment cache module loaded",
+    meta: { maxEntries: MAX_CACHED_ATTACHMENTS },
+});
+/* v8 ignore stop */

package/dist/senses/bluebubbles/attachment-download.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlueBubblesImageAttachment = isBlueBubblesImageAttachment;
+exports.downloadBlueBubblesAttachment = downloadBlueBubblesAttachment;
+const path = __importStar(require("node:path"));
+const image_normalize_1 = require("../../heart/attachments/image-normalize");
+const runtime_1 = require("../../nerves/runtime");
+const MAX_NON_IMAGE_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif", ".tif", ".tiff", ".bmp"]);
+function buildBlueBubblesApiUrl(baseUrl, endpoint, password) {
+    const root = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = new URL(endpoint.replace(/^\//, ""), root);
+    url.searchParams.set("password", password);
+    return url.toString();
+}
+function inferContentType(attachment, responseType) {
+    const normalizedResponseType = responseType?.split(";")[0]?.trim().toLowerCase();
+    if (normalizedResponseType) {
+        return normalizedResponseType;
+    }
+    return attachment.mimeType?.trim().toLowerCase() || undefined;
+}
+function isBlueBubblesImageAttachment(attachment, contentType) {
+    if (contentType?.startsWith("image/"))
+        return true;
+    const normalizedMime = attachment.mimeType?.trim().toLowerCase();
+    if (normalizedMime?.startsWith("image/"))
+        return true;
+    const extension = path.extname(attachment.transferName ?? "").toLowerCase();
+    return IMAGE_EXTENSIONS.has(extension);
+}
+function maxDownloadBytesForAttachment(attachment, contentType) {
+    return isBlueBubblesImageAttachment(attachment, contentType)
+        ? image_normalize_1.MAX_ATTACHMENT_DOWNLOAD_BYTES_IMAGE
+        : MAX_NON_IMAGE_ATTACHMENT_BYTES;
+}
+async function downloadBlueBubblesAttachment(attachment, config, channelConfig, fetchImpl = fetch) {
+    const guid = attachment.guid?.trim();
+    if (!guid) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_attachment_download_error",
+            message: "bluebubbles attachment download failed",
+            meta: { reason: "missing_guid" },
+        });
+        throw new Error("attachment guid missing");
+    }
+    const advertisedLimit = maxDownloadBytesForAttachment(attachment);
+    if (typeof attachment.totalBytes === "number" && attachment.totalBytes > advertisedLimit) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_attachment_download_error",
+            message: "bluebubbles attachment download failed",
+            meta: { attachmentGuid: guid, reason: "advertised_limit_exceeded", advertisedLimit, totalBytes: attachment.totalBytes },
+        });
+        throw new Error(`attachment exceeds ${advertisedLimit} byte limit`);
+    }
+    const url = buildBlueBubblesApiUrl(config.serverUrl, `/api/v1/attachment/${encodeURIComponent(guid)}/download`, config.password);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_attachment_download_start",
+        message: "bluebubbles attachment download started",
+        meta: { attachmentGuid: guid, advertisedLimit },
+    });
+    const response = await fetchImpl(url, {
+        method: "GET",
+        signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+    });
+    if (!response.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_attachment_download_error",
+            message: "bluebubbles attachment download failed",
+            meta: { attachmentGuid: guid, reason: "http_error", status: response.status },
+        });
+        throw new Error(`HTTP ${response.status}`);
+    }
+    const contentType = inferContentType(attachment, response.headers.get("content-type"));
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const actualLimit = maxDownloadBytesForAttachment(attachment, contentType);
+    if (buffer.length > actualLimit) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_attachment_download_error",
+            message: "bluebubbles attachment download failed",
+            meta: { attachmentGuid: guid, reason: "actual_limit_exceeded", actualLimit, byteCount: buffer.length, contentType: contentType ?? null },
+        });
+        throw new Error(`attachment exceeds ${actualLimit} byte limit`);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_attachment_download_end",
+        message: "bluebubbles attachment download completed",
+        meta: { attachmentGuid: guid, byteCount: buffer.length, contentType: contentType ?? null },
+    });
+    return {
+        buffer,
+        contentType,
+    };
+}