@ouro.bot/cli 0.1.0-alpha.30 → 0.1.0-alpha.301

package/dist/heart/agent-entry.js

@@ -1,4 +1,37 @@
 "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.
@@ -7,10 +40,12 @@ if (!process.argv.includes("--agent")) {
     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");
 (0, cli_logging_1.configureCliRuntimeLogger)("self");
-(0, inner_dialog_worker_1.startInnerDialogWorker)().catch((error) => {
+// 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("../senses/inner-dialog-worker"))).then(({ startInnerDialogWorker }) => startInnerDialogWorker())
+    .catch((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,230 @@
+"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.persistBlueBubblesAttachmentSource = persistBlueBubblesAttachmentSource;
+exports.materializeAttachment = materializeAttachment;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../identity");
+const config_1 = require("../config");
+const image_normalize_1 = require("./image-normalize");
+const store_1 = require("./store");
+const types_1 = require("./types");
+const attachment_download_1 = require("../../senses/bluebubbles/attachment-download");
+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,
+    };
+}
+async function persistBlueBubblesAttachmentSource(agentName, attachment, input, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    const targetPath = originalStoragePath(agentRoot, attachment, input.mimeType);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, input.buffer);
+    const updated = (0, types_1.buildBlueBubblesAttachmentRecord)({
+        ...attachment.sourceData,
+        mimeType: input.mimeType ?? attachment.sourceData.mimeType,
+        totalBytes: input.byteCount ?? attachment.byteCount,
+    }, attachment.createdAt, {
+        localPath: targetPath,
+        mimeType: input.mimeType ?? attachment.mimeType,
+        byteCount: input.byteCount ?? attachment.byteCount,
+    });
+    updated.lastSeenAt = Date.now();
+    (0, store_1.rememberRecentAttachment)(agentName, updated, agentRoot);
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_source_persisted",
+        message: "attachment materialization updated",
+        meta: {
+            attachmentId: attachment.id,
+            source: attachment.source,
+            mimeType: updated.mimeType,
+        },
+    });
+    return updated;
+}
+async function materializeOriginalAttachment(agentName, attachment, agentRoot) {
+    void agentName;
+    void agentRoot;
+    switch (attachment.source) {
+        case "cli-local-file": {
+            await ensureReadableFile(attachment.sourceData.path);
+            (0, runtime_1.emitNervesEvent)({
+                component: "engine",
+                event: "engine.attachment_materialized",
+                message: "attachment materialization updated",
+                meta: {
+                    attachmentId: attachment.id,
+                    variant: "original",
+                    source: attachment.source,
+                },
+            });
+            return {
+                attachmentId: attachment.id,
+                variant: "original",
+                path: attachment.sourceData.path,
+                displayName: attachment.displayName,
+                mimeType: attachment.mimeType,
+                byteCount: attachment.byteCount,
+            };
+        }
+        case "bluebubbles": {
+            const localPath = attachment.sourceData.localPath?.trim();
+            if (localPath) {
+                await ensureReadableFile(localPath);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "engine",
+                    event: "engine.attachment_materialized",
+                    message: "attachment materialization updated",
+                    meta: {
+                        attachmentId: attachment.id,
+                        variant: "original",
+                        source: attachment.source,
+                    },
+                });
+                return buildOriginalMaterializedAttachment(attachment, localPath);
+            }
+            const fallbackPath = originalStoragePath(agentRoot, attachment);
+            try {
+                await ensureReadableFile(fallbackPath);
+                return buildOriginalMaterializedAttachment(attachment, fallbackPath);
+            }
+            catch {
+                const config = (0, config_1.getBlueBubblesConfig)();
+                const channelConfig = (0, config_1.getBlueBubblesChannelConfig)();
+                const downloaded = await (0, attachment_download_1.downloadBlueBubblesAttachment)(attachment.sourceData, config, channelConfig);
+                const updated = await persistBlueBubblesAttachmentSource(agentName, attachment, {
+                    buffer: downloaded.buffer,
+                    mimeType: downloaded.contentType,
+                    byteCount: downloaded.buffer.length,
+                }, 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 buildOriginalMaterializedAttachment(updated, updated.sourceData.localPath, downloaded.contentType ?? updated.mimeType, downloaded.buffer.length);
+            }
+        }
+    }
+}
+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/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/store.js

@@ -0,0 +1,103 @@
+"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_RECENT_ATTACHMENTS = void 0;
+exports.getRecentAttachmentsPath = getRecentAttachmentsPath;
+exports.readRecentAttachments = readRecentAttachments;
+exports.rememberRecentAttachment = rememberRecentAttachment;
+exports.getRecentAttachment = getRecentAttachment;
+exports.listRecentAttachments = listRecentAttachments;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../identity");
+exports.MAX_RECENT_ATTACHMENTS = 100;
+function getRecentAttachmentsPath(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return path.join(agentRoot, "state", "attachments", "recent.json");
+}
+function readRecentAttachments(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    const targetPath = getRecentAttachmentsPath(agentName, agentRoot);
+    if (!fs.existsSync(targetPath)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(targetPath, "utf-8"));
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "engine",
+            event: "engine.attachment_store_read_error",
+            message: "failed to read recent attachments store",
+            meta: {
+                path: targetPath,
+                reason: String(error),
+            },
+        });
+        return [];
+    }
+}
+function writeRecentAttachments(agentName, agentRoot, attachments) {
+    const targetPath = getRecentAttachmentsPath(agentName, agentRoot);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, JSON.stringify(attachments, null, 2), "utf-8");
+}
+function rememberRecentAttachment(agentName, attachment, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    const deduped = readRecentAttachments(agentName, agentRoot).filter((entry) => entry.id !== attachment.id);
+    const updated = [attachment, ...deduped]
+        .sort((a, b) => b.lastSeenAt - a.lastSeenAt)
+        .slice(0, exports.MAX_RECENT_ATTACHMENTS);
+    writeRecentAttachments(agentName, agentRoot, updated);
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.attachment_store_updated",
+        message: "recent attachment stored",
+        meta: { attachmentId: attachment.id, source: attachment.source, kind: attachment.kind },
+    });
+    return attachment;
+}
+function getRecentAttachment(agentName, attachmentId, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return readRecentAttachments(agentName, agentRoot).find((entry) => entry.id === attachmentId) ?? null;
+}
+function listRecentAttachments(agentName, options = {}, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    const limit = Math.max(1, options.limit ?? exports.MAX_RECENT_ATTACHMENTS);
+    return readRecentAttachments(agentName, agentRoot)
+        .filter((entry) => !options.kind || entry.kind === options.kind)
+        .slice(0, limit);
+}