@ouro.bot/cli 0.1.0-alpha.66 → 0.1.0-alpha.661

package/dist/heart/agent-entry.js

@@ -1,16 +1,82 @@
 "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 });
 // Unified agent runtime entrypoint.
 // Requires --agent before importing runtime modules that rely on identity.
-if (!process.argv.includes("--agent")) {
+const agentArgIndex = process.argv.indexOf("--agent");
+const agentName = agentArgIndex >= 0 ? process.argv[agentArgIndex + 1] : undefined;
+if (!agentName) {
     // eslint-disable-next-line no-console -- pre-boot guard
     console.error("Missing required --agent <name> argument.\nUsage: node dist/heart/agent-entry.js --agent ouroboros");
     process.exit(1);
 }
-const inner_dialog_worker_1 = require("../senses/inner-dialog-worker");
 const cli_logging_1 = require("../nerves/cli-logging");
+const runtime_1 = require("../nerves/runtime");
 (0, cli_logging_1.configureCliRuntimeLogger)("self");
-(0, inner_dialog_worker_1.startInnerDialogWorker)().catch((error) => {
+(0, runtime_1.emitNervesEvent)({
+    component: "senses",
+    event: "senses.entry_boot",
+    message: "booting inner-dialog entrypoint",
+    meta: { entry: "inner-dialog", agentName },
+});
+// Dynamic import: agent-entry is boot-time wiring that starts a sense process.
+// Using dynamic import avoids a static heart/ -> senses/ dependency.
+Promise.resolve().then(() => __importStar(require("./runtime-credentials"))).then(async ({ readMachineRuntimeCredentialConfig, readRuntimeCredentialConfig, refreshMachineRuntimeCredentialConfig, refreshRuntimeCredentialConfig, waitForRuntimeCredentialBootstrap, }) => {
+    await waitForRuntimeCredentialBootstrap(agentName);
+    if (!readRuntimeCredentialConfig(agentName).ok) {
+        void refreshRuntimeCredentialConfig(agentName, { preserveCachedOnFailure: true }).catch(() => undefined);
+    }
+    /* v8 ignore next 7 -- boot-time best-effort machine credential refresh runs in a child entrypoint and is covered operationally by daemon startup tests @preserve */
+    if (!readMachineRuntimeCredentialConfig(agentName).ok) {
+        void Promise.resolve().then(() => __importStar(require("./machine-identity"))).then(({ loadOrCreateMachineIdentity }) => {
+            const machine = loadOrCreateMachineIdentity();
+            return refreshMachineRuntimeCredentialConfig(agentName, machine.machineId, { preserveCachedOnFailure: true });
+        })
+            .catch(() => undefined);
+    }
+    const { startInnerDialogWorker } = await Promise.resolve().then(() => __importStar(require("../senses/inner-dialog-worker")));
+    await startInnerDialogWorker();
+})
+    .catch((error) => {
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "senses",
+        event: "senses.entry_error",
+        message: "inner-dialog entrypoint failed",
+        meta: { entry: "inner-dialog", agentName, error: error instanceof Error ? error.message : String(error) },
+    });
     // eslint-disable-next-line no-console -- fatal startup guard for worker process
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);

package/dist/heart/attachments/image-normalize.js

@@ -0,0 +1,194 @@
+"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.MAX_VLM_IMAGE_BYTES = exports.MAX_ATTACHMENT_DOWNLOAD_BYTES_IMAGE = void 0;
+exports.normalizeImageForVision = normalizeImageForVision;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+exports.MAX_ATTACHMENT_DOWNLOAD_BYTES_IMAGE = 32 * 1024 * 1024;
+exports.MAX_VLM_IMAGE_BYTES = 5 * 1024 * 1024;
+const SAFE_VLM_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+const SIZE_STEPS = [3072, 2560, 2048, 1600, 1280, 1024, 768];
+const JPEG_QUALITIES = ["best", "90", "80", "70", "60"];
+function materializedOutputDir(agentRoot, attachmentId) {
+    return path.join(agentRoot, "state", "attachments", "materialized", attachmentId.replace(/[:/]/g, "_"));
+}
+function execFileText(file, args) {
+    return new Promise((resolve, reject) => {
+        (0, node_child_process_1.execFile)(file, args, (error, stdout = "", stderr = "") => {
+            if (error) {
+                reject(new Error(stderr.trim() || stdout.trim() || error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+async function defaultProbeImage(input) {
+    const output = await execFileText("/usr/bin/sips", ["-g", "hasAlpha", input.sourcePath]);
+    const hasAlpha = /hasAlpha:\s+(yes|1|true)/i.test(output);
+    return { hasAlpha };
+}
+async function defaultRasterizeWithQuickLook(input) {
+    await fs.mkdir(input.outputDir, { recursive: true });
+    await execFileText("/usr/bin/qlmanage", ["-t", "-s", "4096", "-o", input.outputDir, input.sourcePath]);
+    const entries = await fs.readdir(input.outputDir);
+    const candidate = entries
+        .filter((entry) => entry.startsWith(path.basename(input.sourcePath, path.extname(input.sourcePath))))
+        .sort()[0];
+    if (!candidate) {
+        throw new Error("Quick Look did not produce a rasterized image");
+    }
+    return path.join(input.outputDir, candidate);
+}
+async function defaultEncodeVariant(input) {
+    await fs.mkdir(input.outputDir, { recursive: true });
+    const extension = input.targetFormat === "png" ? ".png" : ".jpg";
+    const basename = path.basename(input.sourcePath, path.extname(input.sourcePath));
+    const outputPath = path.join(input.outputDir, `${basename}-${input.maxEdge}-${input.targetFormat}${input.quality ? `-${input.quality}` : ""}${extension}`);
+    const args = [
+        "-s",
+        "format",
+        input.targetFormat,
+        ...(input.targetFormat === "jpeg" && input.quality ? ["-s", "formatOptions", input.quality] : []),
+        "-Z",
+        String(input.maxEdge),
+        input.sourcePath,
+        "--out",
+        outputPath,
+    ];
+    await execFileText("/usr/bin/sips", args);
+    const stats = await fs.stat(outputPath);
+    return {
+        path: outputPath,
+        mimeType: input.targetFormat === "png" ? "image/png" : "image/jpeg",
+        byteCount: stats.size,
+    };
+}
+async function normalizeImageForVision(params) {
+    const maxVlmBytes = params.maxVlmBytes ?? exports.MAX_VLM_IMAGE_BYTES;
+    const originalMimeType = params.attachment.mimeType?.trim().toLowerCase();
+    const originalByteCount = params.attachment.byteCount;
+    const outputDir = materializedOutputDir(params.agentRoot, params.attachment.id);
+    if (originalMimeType
+        && SAFE_VLM_MIME_TYPES.has(originalMimeType)
+        && typeof originalByteCount === "number"
+        && originalByteCount <= maxVlmBytes) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.attachment_normalization_passthrough",
+            message: "attachment image normalization updated",
+            meta: {
+                attachmentId: params.attachment.id,
+                mimeType: originalMimeType,
+                byteCount: originalByteCount,
+            },
+        });
+        return {
+            path: path.resolve(params.sourcePath),
+            mimeType: originalMimeType,
+            byteCount: originalByteCount,
+        };
+    }
+    const probeImage = params.probeImage ?? defaultProbeImage;
+    const rasterizeWithQuickLook = params.rasterizeWithQuickLook ?? defaultRasterizeWithQuickLook;
+    const encodeVariant = params.encodeVariant ?? defaultEncodeVariant;
+    let workingSourcePath = path.resolve(params.sourcePath);
+    let probe;
+    try {
+        probe = await probeImage({ sourcePath: workingSourcePath });
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.attachment_normalization_rasterize",
+            message: "attachment image normalization updated",
+            meta: {
+                attachmentId: params.attachment.id,
+                sourcePath: workingSourcePath,
+            },
+        });
+        workingSourcePath = await rasterizeWithQuickLook({
+            sourcePath: workingSourcePath,
+            outputDir,
+        });
+        probe = await probeImage({ sourcePath: workingSourcePath });
+    }
+    const targetFormats = probe.hasAlpha ? ["png", "jpeg"] : ["jpeg"];
+    for (const targetFormat of targetFormats) {
+        for (const maxEdge of SIZE_STEPS) {
+            const qualities = targetFormat === "jpeg" ? JPEG_QUALITIES : [undefined];
+            for (const quality of qualities) {
+                const variant = await encodeVariant({
+                    sourcePath: workingSourcePath,
+                    outputDir,
+                    targetFormat,
+                    maxEdge,
+                    ...(quality ? { quality } : {}),
+                });
+                if ((variant.byteCount ?? Number.POSITIVE_INFINITY) <= maxVlmBytes) {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "engine",
+                        event: "engine.attachment_normalization_succeeded",
+                        message: "attachment image normalization updated",
+                        meta: {
+                            attachmentId: params.attachment.id,
+                            sourceMimeType: originalMimeType ?? "unknown",
+                            outputMimeType: variant.mimeType ?? `image/${targetFormat}`,
+                            byteCount: variant.byteCount,
+                            maxEdge,
+                            quality: quality ?? null,
+                        },
+                    });
+                    return variant;
+                }
+            }
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_normalization_failed",
+        message: "attachment image normalization updated",
+        meta: {
+            attachmentId: params.attachment.id,
+            sourceMimeType: originalMimeType ?? "unknown",
+            sourceByteCount: originalByteCount ?? null,
+            maxVlmBytes,
+        },
+    });
+    throw new Error(`Attachment ${params.attachment.id} could not be normalized under the VLM byte budget`);
+}

package/dist/heart/attachments/materialize.js

@@ -0,0 +1,97 @@
+"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.materializeAttachment = materializeAttachment;
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../identity");
+const image_normalize_1 = require("./image-normalize");
+const store_1 = require("./store");
+const sources_1 = require("./sources");
+async function materializeOriginalAttachment(agentName, attachment, agentRoot) {
+    const adapter = (0, sources_1.getAttachmentSourceAdapter)(attachment.source);
+    const materialized = await adapter.materializeOriginal({ agentName, attachment, agentRoot });
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_materialized",
+        message: "attachment materialization updated",
+        meta: {
+            attachmentId: attachment.id,
+            variant: "original",
+            source: attachment.source,
+        },
+    });
+    return materialized;
+}
+async function materializeAttachment(agentName, attachmentId, options = {}) {
+    const agentRoot = options.agentRoot ?? (0, identity_1.getAgentRoot)(agentName);
+    const variant = options.variant ?? "original";
+    const attachment = (0, store_1.getRecentAttachment)(agentName, attachmentId, agentRoot);
+    if (!attachment) {
+        throw new Error(`Attachment not found: ${attachmentId}`);
+    }
+    if (variant === "original") {
+        return await materializeOriginalAttachment(agentName, attachment, agentRoot);
+    }
+    if (attachment.kind !== "image") {
+        throw new Error(`Attachment ${attachmentId} is not an image and cannot produce a vision_safe variant`);
+    }
+    const original = await materializeOriginalAttachment(agentName, attachment, agentRoot);
+    const normalizeImage = options.normalizeImage ?? image_normalize_1.normalizeImageForVision;
+    const normalized = await normalizeImage({
+        attachment,
+        sourcePath: original.path,
+        agentName,
+        agentRoot,
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_materialized",
+        message: "attachment materialization updated",
+        meta: {
+            attachmentId: attachment.id,
+            variant: "vision_safe",
+            source: attachment.source,
+        },
+    });
+    return {
+        attachmentId: attachment.id,
+        variant: "vision_safe",
+        path: path.resolve(normalized.path),
+        displayName: attachment.displayName,
+        mimeType: normalized.mimeType ?? attachment.mimeType,
+        byteCount: normalized.byteCount,
+    };
+}

package/dist/heart/attachments/originals.js

@@ -0,0 +1,88 @@
+"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.ensureReadableFile = ensureReadableFile;
+exports.extensionForAttachment = extensionForAttachment;
+exports.originalStoragePath = originalStoragePath;
+exports.buildOriginalMaterializedAttachment = buildOriginalMaterializedAttachment;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+async function ensureReadableFile(filePath) {
+    await fs.access(filePath);
+}
+function extensionForAttachment(displayName, mimeType) {
+    const explicit = path.extname(displayName).trim();
+    if (explicit)
+        return explicit;
+    switch (mimeType?.trim().toLowerCase()) {
+        case "image/jpeg":
+            return ".jpg";
+        case "image/png":
+            return ".png";
+        case "image/webp":
+            return ".webp";
+        case "image/gif":
+            return ".gif";
+        case "image/tiff":
+            return ".tiff";
+        case "image/bmp":
+            return ".bmp";
+        case "image/heic":
+            return ".heic";
+        case "application/pdf":
+            return ".pdf";
+        case "audio/mp3":
+        case "audio/mpeg":
+            return ".mp3";
+        case "audio/mp4":
+            return ".m4a";
+        default:
+            return "";
+    }
+}
+function originalStoragePath(agentRoot, attachment, mimeType) {
+    const extension = extensionForAttachment(attachment.displayName, mimeType ?? attachment.mimeType);
+    return path.join(agentRoot, "state", "attachments", "materialized", attachment.source, attachment.sourceId, `original${extension}`);
+}
+function buildOriginalMaterializedAttachment(attachment, filePath, mimeType, byteCount) {
+    return {
+        attachmentId: attachment.id,
+        variant: "original",
+        path: filePath,
+        displayName: attachment.displayName,
+        mimeType: mimeType ?? attachment.mimeType,
+        byteCount: byteCount ?? attachment.byteCount,
+    };
+}

package/dist/heart/attachments/render.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAttachmentBlock = renderAttachmentBlock;
+const runtime_1 = require("../../nerves/runtime");
+function formatBytes(byteCount) {
+    if (typeof byteCount !== "number" || !Number.isFinite(byteCount) || byteCount < 0) {
+        return "unknown size";
+    }
+    if (byteCount >= 1024 * 1024) {
+        return `${(byteCount / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    if (byteCount >= 1024) {
+        return `${Math.round(byteCount / 1024)} KB`;
+    }
+    return `${byteCount} B`;
+}
+function renderAttachmentBlock(attachments) {
+    if (attachments.length === 0)
+        return "";
+    const body = attachments.map((attachment) => `- ${attachment.id} | ${attachment.kind} | ${attachment.displayName} | ${attachment.mimeType ?? "unknown mime"} | ${formatBytes(attachment.byteCount)}`);
+    const rendered = ["[attachments]", ...body].join("\n");
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_block_rendered",
+        message: "attachment transcript block rendered",
+        meta: { count: attachments.length },
+    });
+    return rendered;
+}

package/dist/heart/attachments/sources/bluebubbles.js

@@ -0,0 +1,156 @@
+"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.blueBubblesAttachmentSourceAdapter = void 0;
+exports.buildBlueBubblesAttachmentRecord = buildBlueBubblesAttachmentRecord;
+exports.persistBlueBubblesAttachmentSource = persistBlueBubblesAttachmentSource;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../../nerves/runtime");
+const attachment_download_1 = require("../../../senses/bluebubbles/attachment-download");
+const config_1 = require("../../config");
+const identity_1 = require("../../identity");
+const originals_1 = require("../originals");
+const store_1 = require("../store");
+const types_1 = require("../types");
+function normalizeBlueBubblesRecord(attachment) {
+    if (attachment.source !== "bluebubbles") {
+        throw new Error(`bluebubbles adapter cannot materialize ${attachment.source} attachments`);
+    }
+    const sourceData = attachment.sourceData;
+    const guid = typeof sourceData?.guid === "string" && sourceData.guid.trim().length > 0
+        ? sourceData.guid.trim()
+        : attachment.sourceId.trim();
+    if (!guid) {
+        throw new Error("BlueBubbles attachment guid is required");
+    }
+    const localPath = typeof sourceData?.localPath === "string" && sourceData.localPath.trim().length > 0
+        ? path.resolve(sourceData.localPath)
+        : undefined;
+    return {
+        ...attachment,
+        source: "bluebubbles",
+        sourceId: guid,
+        sourceData: {
+            guid,
+            mimeType: typeof sourceData?.mimeType === "string" ? sourceData.mimeType : attachment.mimeType,
+            transferName: typeof sourceData?.transferName === "string" ? sourceData.transferName : attachment.displayName,
+            totalBytes: typeof sourceData?.totalBytes === "number" ? sourceData.totalBytes : attachment.byteCount,
+            height: typeof sourceData?.height === "number" ? sourceData.height : undefined,
+            width: typeof sourceData?.width === "number" ? sourceData.width : undefined,
+            ...(localPath ? { localPath } : {}),
+        },
+    };
+}
+function buildBlueBubblesAttachmentRecord(summary, now = Date.now(), options = {}) {
+    const guid = summary.guid?.trim();
+    if (!guid) {
+        throw new Error("BlueBubbles attachment guid is required");
+    }
+    const displayName = summary.transferName?.trim() || guid;
+    const mimeType = options.mimeType?.trim().toLowerCase() || summary.mimeType?.trim().toLowerCase() || undefined;
+    return (0, types_1.createAttachmentRecord)({
+        source: "bluebubbles",
+        sourceId: guid,
+        displayName,
+        mimeType,
+        byteCount: options.byteCount ?? summary.totalBytes,
+        sourceData: {
+            ...summary,
+            guid,
+            ...(options.localPath ? { localPath: path.resolve(options.localPath) } : {}),
+        },
+    }, now);
+}
+async function persistBlueBubblesAttachmentSource(agentName, attachment, input, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    const normalizedAttachment = normalizeBlueBubblesRecord(attachment);
+    const targetPath = (0, originals_1.originalStoragePath)(agentRoot, normalizedAttachment, input.mimeType);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, input.buffer);
+    const updated = buildBlueBubblesAttachmentRecord({
+        ...normalizedAttachment.sourceData,
+        mimeType: input.mimeType ?? normalizedAttachment.sourceData.mimeType,
+        totalBytes: input.byteCount ?? normalizedAttachment.byteCount,
+    }, normalizedAttachment.createdAt, {
+        localPath: targetPath,
+        mimeType: input.mimeType ?? normalizedAttachment.mimeType,
+        byteCount: input.byteCount ?? normalizedAttachment.byteCount,
+    });
+    updated.lastSeenAt = Date.now();
+    (0, store_1.cacheRecentAttachment)(agentName, updated, agentRoot);
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_source_persisted",
+        message: "attachment materialization updated",
+        meta: {
+            attachmentId: normalizedAttachment.id,
+            source: normalizedAttachment.source,
+            mimeType: updated.mimeType,
+        },
+    });
+    return updated;
+}
+exports.blueBubblesAttachmentSourceAdapter = {
+    source: "bluebubbles",
+    async materializeOriginal({ agentName, attachment, agentRoot }) {
+        const normalizedAttachment = normalizeBlueBubblesRecord(attachment);
+        const localPath = normalizedAttachment.sourceData.localPath?.trim();
+        if (localPath) {
+            await (0, originals_1.ensureReadableFile)(localPath);
+            return (0, originals_1.buildOriginalMaterializedAttachment)(normalizedAttachment, localPath);
+        }
+        const fallbackPath = (0, originals_1.originalStoragePath)(agentRoot, normalizedAttachment);
+        try {
+            await (0, originals_1.ensureReadableFile)(fallbackPath);
+            return (0, originals_1.buildOriginalMaterializedAttachment)(normalizedAttachment, fallbackPath);
+        }
+        catch {
+            const config = (0, config_1.getBlueBubblesConfig)();
+            const channelConfig = (0, config_1.getBlueBubblesChannelConfig)();
+            const downloaded = await (0, attachment_download_1.downloadBlueBubblesAttachment)(normalizedAttachment.sourceData, config, channelConfig);
+            const updated = await persistBlueBubblesAttachmentSource(agentName, normalizedAttachment, {
+                buffer: downloaded.buffer,
+                mimeType: downloaded.contentType,
+                byteCount: downloaded.buffer.length,
+            }, agentRoot);
+            const persistedPath = updated.sourceData.localPath;
+            /* v8 ignore next -- persistBlueBubblesAttachmentSource always writes localPath before returning @preserve */
+            if (!persistedPath) {
+                throw new Error("BlueBubbles attachment persistence did not yield a local path");
+            }
+            return (0, originals_1.buildOriginalMaterializedAttachment)(updated, persistedPath, downloaded.contentType ?? updated.mimeType, downloaded.buffer.length);
+        }
+    },
+};