@ouro.bot/cli 0.1.0-alpha.65 → 0.1.0-alpha.651

package/dist/senses/attention-queue.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAttentionQueue = buildAttentionQueue;
+exports.dequeueAttentionItem = dequeueAttentionItem;
+exports.attentionQueueEmpty = attentionQueueEmpty;
+exports.buildAttentionQueueSummary = buildAttentionQueueSummary;
+exports.buildAttentionQueueStatusFrame = buildAttentionQueueStatusFrame;
+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}`;
+}
+const PACKET_RETURN_HINT_MAX = 180;
+const PACKET_RETURN_HINT_COUNT_MAX = 4;
+const LITERAL_MARKER_RE = /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){2,}\b/;
+const RETURN_HINT_KEY_RE = /(expected|return|marker|answer|verdict)/i;
+function addReturnHint(hints, seen, value) {
+    if (typeof value !== "string")
+        return;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > PACKET_RETURN_HINT_MAX)
+        return;
+    if (!LITERAL_MARKER_RE.test(trimmed))
+        return;
+    if (seen.has(trimmed))
+        return;
+    seen.add(trimmed);
+    hints.push(trimmed);
+}
+function extractQuotedReturnHints(value, hints, seen) {
+    for (const match of value.matchAll(/"([^"\n]{1,180})"/g)) {
+        addReturnHint(hints, seen, match[1]);
+        if (hints.length >= PACKET_RETURN_HINT_COUNT_MAX)
+            return;
+    }
+}
+function extractPacketReturnHints(packet) {
+    const hints = [];
+    const seen = new Set();
+    const sourceRequest = typeof packet.payload.sourceRequest === "string" ? packet.payload.sourceRequest : "";
+    if (sourceRequest)
+        extractQuotedReturnHints(sourceRequest, hints, seen);
+    for (const [key, value] of Object.entries(packet.payload)) {
+        if (hints.length >= PACKET_RETURN_HINT_COUNT_MAX)
+            break;
+        if (key === "sourceRequest" || !RETURN_HINT_KEY_RE.test(key))
+            continue;
+        addReturnHint(hints, seen, value);
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                addReturnHint(hints, seen, item);
+                if (hints.length >= PACKET_RETURN_HINT_COUNT_MAX)
+                    break;
+            }
+        }
+    }
+    return hints;
+}
+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,
+            packetSuccessCriteria: packet.successCriteria,
+            packetSourceRequest: typeof packet.payload.sourceRequest === "string" ? packet.payload.sourceRequest : undefined,
+            packetReturnHints: extractPacketReturnHints(packet),
+        };
+    };
+    // 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;
+const PACKET_SOURCE_PREVIEW_MAX = 240;
+function preview(value, max) {
+    return value.length > max ? `${value.slice(0, max - 3)}...` : value;
+}
+function buildAttentionQueueSummary(queue) {
+    if (queue.length === 0)
+        return "";
+    const lines = [
+        "[internal: current held work items — not messages to send]",
+        "Only listed items are waiting now; older transcript mentions and completed returns/probes are not current pressure.",
+        "To return one, call surface with delegationId set to the bracketed id.",
+        "Return only the requested result; do not add commentary about prior attempts, old loops, or completed probes.",
+        "If literal return options are listed, copy the chosen option exactly, including suffixes and punctuation.",
+    ];
+    for (const item of queue) {
+        if (item.packetKind && item.packetObjective) {
+            lines.push(`- [${item.id}] ${item.friendName} -> ${item.packetKind}: ${item.packetObjective}`);
+            if (item.packetSuccessCriteria?.length) {
+                lines.push(`  return criteria: ${item.packetSuccessCriteria.join("; ")}`);
+            }
+            if (item.packetReturnHints?.length) {
+                lines.push(`  literal return options: ${item.packetReturnHints.map((hint) => `"${hint}"`).join("; ")}`);
+            }
+            const sourceRequest = item.packetSourceRequest ?? item.delegatedContent;
+            if (sourceRequest.trim().length > 0 && sourceRequest.trim() !== item.packetObjective.trim()) {
+                lines.push(`  source request: "${preview(sourceRequest, PACKET_SOURCE_PREVIEW_MAX)}"`);
+            }
+            continue;
+        }
+        lines.push(`- [${item.id}] ${item.friendName} asked: "${preview(item.delegatedContent, CONTENT_PREVIEW_MAX)}"`);
+    }
+    return lines.join("\n");
+}
+function buildAttentionQueueStatusFrame(queue) {
+    return buildAttentionQueueSummary(queue);
+}

package/dist/senses/await-turn-message.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAwaitTurnMessage = buildAwaitTurnMessage;
+const runtime_1 = require("../nerves/runtime");
+function formatElapsed(ms) {
+    if (ms < 60_000)
+        return "<1m ago";
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+function relativeAge(lastCheckedAt, now) {
+    if (!lastCheckedAt)
+        return null;
+    const lastMs = new Date(lastCheckedAt).getTime();
+    if (!Number.isFinite(lastMs))
+        return null;
+    return formatElapsed(now().getTime() - lastMs);
+}
+function buildAwaitTurnMessage(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.await_turn_message_built",
+        message: "built await tick message",
+        meta: { awaitName: options.awaitName, checkedCount: options.checkedCount },
+    });
+    const lines = [];
+    lines.push(`await tick: ${options.awaitName} — ${options.condition}`);
+    if (options.body && options.body.trim().length > 0) {
+        lines.push("");
+        lines.push("what would count as ready:");
+        lines.push(options.body.trim());
+    }
+    const age = relativeAge(options.lastCheckedAt, options.now);
+    const obs = options.lastObservation && options.lastObservation.trim().length > 0
+        ? `last observation: "${options.lastObservation.trim()}"`
+        : "last observation: (none yet)";
+    if (options.checkedCount === 0) {
+        lines.push("");
+        lines.push("history: never checked. this is my first look.");
+    }
+    else {
+        lines.push("");
+        lines.push(`history: checked ${options.checkedCount}x so far. last checked ${age ?? "(unknown)"}. ${obs}.`);
+    }
+    if (options.checkpoint) {
+        lines.push("");
+        lines.push(`last checkpoint: ${options.checkpoint}`);
+    }
+    lines.push("");
+    lines.push("look around and decide. if the condition is met, call resolve_await with verdict='yes' and a one-line observation. otherwise call resolve_await with verdict='no' and a one-line observation of what i saw this tick.");
+    return lines.join("\n");
+}

package/dist/senses/bluebubbles/active-turns.js

@@ -0,0 +1,216 @@
+"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.beginBlueBubblesActiveTurn = beginBlueBubblesActiveTurn;
+exports.noteBlueBubblesActiveTurnVisibleActivity = noteBlueBubblesActiveTurnVisibleActivity;
+exports.finishBlueBubblesActiveTurn = finishBlueBubblesActiveTurn;
+exports.listBlueBubblesActiveTurns = listBlueBubblesActiveTurns;
+exports.snapshotBlueBubblesActiveTurns = snapshotBlueBubblesActiveTurns;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../heart/config");
+const identity_1 = require("../../heart/identity");
+const runtime_1 = require("../../nerves/runtime");
+function activeTurnsDir(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "active-turns");
+}
+function activeTurnPath(agentName, turnId) {
+    return path.join(activeTurnsDir(agentName), `${(0, config_1.sanitizeKey)(turnId)}.json`);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseActiveTurn(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed.turnId || !parsed.messageGuid || !parsed.sessionKey || !parsed.startedAt)
+            return null;
+        if (typeof parsed.pid !== "number")
+            return null;
+        return {
+            turnId: parsed.turnId,
+            pid: parsed.pid,
+            startedAt: parsed.startedAt,
+            lastVisibleActivityAt: typeof parsed.lastVisibleActivityAt === "string"
+                ? parsed.lastVisibleActivityAt
+                : undefined,
+            messageGuid: parsed.messageGuid,
+            sessionKey: parsed.sessionKey,
+            chatGuid: parsed.chatGuid ?? null,
+            chatIdentifier: parsed.chatIdentifier ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function beginBlueBubblesActiveTurn(agentName, event) {
+    const turnId = `${event.chat.sessionKey}:${event.messageGuid}:${process.pid}`;
+    const entry = {
+        turnId,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        messageGuid: event.messageGuid,
+        sessionKey: event.chat.sessionKey,
+        chatGuid: event.chat.chatGuid ?? null,
+        chatIdentifier: event.chat.chatIdentifier ?? null,
+    };
+    const filePath = activeTurnPath(agentName, turnId);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(entry, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_active_turn_write_error",
+            message: "failed to record active bluebubbles turn",
+            meta: {
+                agentName,
+                messageGuid: event.messageGuid,
+                sessionKey: event.chat.sessionKey,
+                /* v8 ignore next -- filesystem writes throw Error instances; stringify guard is defensive @preserve */
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return turnId;
+}
+function noteBlueBubblesActiveTurnVisibleActivity(agentName, turnId) {
+    const filePath = activeTurnPath(agentName, turnId);
+    let entry = null;
+    try {
+        entry = parseActiveTurn(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return;
+    }
+    if (!entry)
+        return;
+    try {
+        fs.writeFileSync(filePath, JSON.stringify({ ...entry, lastVisibleActivityAt: new Date().toISOString() }, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_active_turn_write_error",
+            message: "failed to update active bluebubbles turn",
+            meta: {
+                agentName,
+                turnId,
+                /* v8 ignore next -- filesystem writes throw Error instances; stringify guard is defensive @preserve */
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function finishBlueBubblesActiveTurn(agentName, turnId) {
+    try {
+        fs.unlinkSync(activeTurnPath(agentName, turnId));
+    }
+    catch {
+        // Missing active-turn files are harmless: this is best-effort telemetry.
+    }
+}
+function listBlueBubblesActiveTurns(agentName) {
+    let files;
+    try {
+        files = fs.readdirSync(activeTurnsDir(agentName)).filter((name) => name.endsWith(".json")).sort();
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files) {
+        const filePath = path.join(activeTurnsDir(agentName), file);
+        let entry = null;
+        try {
+            entry = parseActiveTurn(fs.readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            entry = null;
+        }
+        if (!entry) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore corrupt cleanup races */ }
+            continue;
+        }
+        if (!isPidAlive(entry.pid)) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore stale cleanup races */ }
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_active_turn_pruned",
+                message: "pruned stale bluebubbles active-turn marker",
+                meta: {
+                    agentName,
+                    messageGuid: entry.messageGuid,
+                    sessionKey: entry.sessionKey,
+                    pid: entry.pid,
+                },
+            });
+            continue;
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+function snapshotBlueBubblesActiveTurns(agentName, stalledAfterMs, nowMs = Date.now()) {
+    const entries = listBlueBubblesActiveTurns(agentName);
+    const started = entries
+        .map((entry) => ({ value: entry.startedAt, ms: Date.parse(entry.startedAt) }))
+        .filter((entry) => Number.isFinite(entry.ms))
+        .sort((left, right) => left.ms - right.ms);
+    const oldest = started[0];
+    return {
+        activeTurnCount: entries.length,
+        stalledTurnCount: started.filter((entry) => nowMs - entry.ms >= stalledAfterMs).length,
+        oldestActiveTurnStartedAt: oldest?.value,
+        oldestActiveTurnAgeMs: oldest ? Math.max(0, nowMs - oldest.ms) : undefined,
+    };
+}

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheBlueBubblesAttachment = cacheBlueBubblesAttachment;
+exports.lookupBlueBubblesAttachment = lookupBlueBubblesAttachment;
+exports.resetBlueBubblesAttachmentCache = resetBlueBubblesAttachmentCache;
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * Bounded process-local 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 cacheBlueBubblesAttachment(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,
+    };
+}