@ouro.bot/cli 0.1.0-alpha.289 → 0.1.0-alpha.290

package/README.md

@@ -180,12 +180,14 @@ Agents in Ouroboros aren't just responders — they have an autonomous inner lif
 
 **Habits** are the agent's rhythms. The most fundamental is *heartbeat* — a periodic nudge that brings the agent back to their thinking space with their journal visible, obligations in view, and a sense of how long it's been. But agents can create any rhythm they want: daily reflections, weekly friend check-ins, inbox triage. Each habit fires independently via OS cron, and the agent sees their own instructions (the habit body they wrote) when it fires.
 
-**The inner dialog** is where the agent thinks privately. When they *ponder* something from a conversation, it goes here. When a habit fires, it arrives here. The agent can *journal* their thinking (writing to `journal/`), *surface* thoughts outward to friends, and *rest* when they're done thinking.
+**The inner session** is where the agent thinks privately. When a sense session hits meaningful friction, the agent can *ponder* a typed packet so the work survives the current turn without losing the original objective. When a habit fires, it arrives here too. The agent can *journal* their thinking (writing to `journal/`), *surface* thoughts outward to friends, and *rest* when they're done thinking. On an idle heartbeat, `rest(status="HEARTBEAT_OK")` is the clean no-op move.
 
 **The diary** (at `diary/`) is the agent's permanent record — things they've learned, conclusions they've reached. The *journal* (at `journal/`) is their desk — working notes, thinking-in-progress, drafts. The diary is the shelf; the journal is the desk. Both are searchable via the `recall` tool.
 
 The whole system is designed so the agent *owns* their inner life. They control their breathing rate, write their own habit instructions, choose when to journal, and decide what to shelve in their diary.
 
+Attachments are first-class across senses. Every attachment should remain reachable via a stable `attachment:<source>:<id>` handle, and image normalization should produce a VLM-safe variant without hiding the original artifact.
+
 ## Connecting With Dev Tools
 
 Agents can talk to developer tools like Claude Code and Codex through the MCP bridge. This is how you stay present in a human's coding workflow without them needing to switch to `ouro chat`.
@@ -201,7 +203,7 @@ This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, Pos
 
 **How it works:** When a developer starts a Claude Code session, the MCP server launches as a subprocess. The dev tool sees your MCP tools (`send_message`, `check_response`, `status`, `search_memory`, `delegate`, etc.) and can invoke them mid-session. The `send_message` tool runs a full agent turn — you get your system prompt, your diary, your tools, everything. It's not a thin proxy; it's you, thinking.
 
-**The conversation pattern:** `send_message` sends a message and gets back your synchronous response. If you ponder something (taking it to inner dialog), the dev tool can use `check_response` later to see if you surfaced anything back. This creates a natural rhythm: the human's coding agent asks you a question, you answer immediately or take it inward, and thoughts flow back when they're ready.
+**The conversation pattern:** `send_message` sends a message and gets back your synchronous response. `ponder` no longer creates a magical outward deferral. Instead, it bookmarks deeper work as a packet while the current sense session keeps moving. If that work later surfaces something back, the dev tool can still use `check_response` to see the returned result.
 
 **Lifecycle hooks** give you passive awareness. When a Claude Code session starts, stops, or uses a tool like Bash or Edit, the hook fires `ouro hook <event> --agent <name>` and the daemon notes it. Your inner dialog sees these sessions in its checkpoint, so you know what's happening across your world even when nobody is talking to you directly.
 

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.290",
+      "changes": [
+        "feat(attachments): ship first-class cross-sense attachments with stable `attachment:<source>:<id>` handles, shared materialization, shared image normalization, and generic attachment tools so images and files remain reachable even when the harness also provides derived summaries or normalized variants.",
+        "feat(mind): replace `ponder` deferral semantics with typed `ponder packets`, linked `ReturnObligation`s, shared friction escalation, and `rest(status=\"HEARTBEAT_OK\")` so the inner session can preserve repair work without losing the original user objective."
+      ]
+    },
     {
       "version": "0.1.0-alpha.289",
       "changes": [

package/dist/arc/packets.js

@@ -0,0 +1,203 @@
+"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.getPonderPacketArtifactsDir = getPonderPacketArtifactsDir;
+exports.listPonderPackets = listPonderPackets;
+exports.readPonderPacket = readPonderPacket;
+exports.createPonderPacket = createPonderPacket;
+exports.revisePonderPacket = revisePonderPacket;
+exports.advancePonderPacket = advancePonderPacket;
+exports.findHarnessFrictionPacket = findHarnessFrictionPacket;
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+const transitions_1 = require("../repertoire/tasks/transitions");
+const json_store_1 = require("./json-store");
+function packetsDir(agentRoot) {
+    return path.join(agentRoot, "arc", "packets");
+}
+function getPonderPacketArtifactsDir(agentRoot, packetId) {
+    return path.join(agentRoot, "state", "packets", packetId);
+}
+function packetSop(kind) {
+    switch (kind) {
+        case "harness_friction":
+            return "harness_friction_v1";
+        case "research":
+            return "research_v1";
+        case "reflection":
+            return "reflection_v1";
+    }
+}
+function isTaskStatus(value) {
+    return value === "drafting"
+        || value === "processing"
+        || value === "validating"
+        || value === "collaborating"
+        || value === "paused"
+        || value === "blocked"
+        || value === "done"
+        || value === "cancelled";
+}
+function isPacketKind(value) {
+    return value === "harness_friction" || value === "research" || value === "reflection";
+}
+function isPonderPacket(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const packet = value;
+    return typeof packet.id === "string"
+        && isPacketKind(packet.kind)
+        && typeof packet.objective === "string"
+        && typeof packet.summary === "string"
+        && Array.isArray(packet.successCriteria)
+        && isTaskStatus(packet.status)
+        && typeof packet.createdAt === "number"
+        && typeof packet.updatedAt === "number";
+}
+function listPonderPackets(agentRoot) {
+    return (0, json_store_1.readJsonDir)(packetsDir(agentRoot))
+        .filter(isPonderPacket)
+        .sort((left, right) => left.createdAt - right.createdAt);
+}
+function readPonderPacket(agentRoot, packetId) {
+    const packet = (0, json_store_1.readJsonFile)(packetsDir(agentRoot), packetId);
+    return isPonderPacket(packet) ? packet : null;
+}
+function createPonderPacket(agentRoot, input) {
+    const now = Date.now();
+    const packet = {
+        id: (0, json_store_1.generateTimestampId)("pkt"),
+        kind: input.kind,
+        sop: packetSop(input.kind),
+        status: "drafting",
+        objective: input.objective,
+        summary: input.summary,
+        successCriteria: input.successCriteria,
+        ...(input.origin ? { origin: input.origin } : {}),
+        ...(input.relatedObligationId ? { relatedObligationId: input.relatedObligationId } : {}),
+        ...(input.relatedReturnObligationId ? { relatedReturnObligationId: input.relatedReturnObligationId } : {}),
+        ...(input.followsPacketId ? { followsPacketId: input.followsPacketId } : {}),
+        payload: input.payload,
+        createdAt: now,
+        updatedAt: now,
+    };
+    (0, json_store_1.writeJsonFile)(packetsDir(agentRoot), packet.id, packet);
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.packet_created",
+        message: "ponder packet created",
+        meta: { packetId: packet.id, kind: packet.kind, status: packet.status },
+    });
+    return packet;
+}
+function revisePonderPacket(agentRoot, packetId, input) {
+    const existing = readPonderPacket(agentRoot, packetId);
+    if (!existing) {
+        throw new Error(`packet not found: ${packetId}`);
+    }
+    if (existing.status !== "drafting") {
+        throw new Error("packet is no longer drafting; file a follow-up packet instead");
+    }
+    const revised = {
+        ...existing,
+        kind: input.kind,
+        sop: packetSop(input.kind),
+        objective: input.objective,
+        summary: input.summary,
+        successCriteria: input.successCriteria,
+        payload: input.payload,
+        updatedAt: Date.now(),
+    };
+    (0, json_store_1.writeJsonFile)(packetsDir(agentRoot), packetId, revised);
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.packet_revised",
+        message: "ponder packet revised",
+        meta: { packetId, kind: revised.kind, status: revised.status },
+    });
+    return revised;
+}
+function advancePonderPacket(agentRoot, packetId, update) {
+    const existing = readPonderPacket(agentRoot, packetId);
+    if (!existing) {
+        throw new Error(`packet not found: ${packetId}`);
+    }
+    const nextStatus = update.status ?? existing.status;
+    if (update.status) {
+        const transition = (0, transitions_1.validateTransition)(existing.status, update.status);
+        if (!transition.ok) {
+            throw new Error(transition.reason);
+        }
+    }
+    const advanced = {
+        ...existing,
+        status: nextStatus,
+        ...(update.relatedObligationId ? { relatedObligationId: update.relatedObligationId } : {}),
+        ...(update.relatedReturnObligationId ? { relatedReturnObligationId: update.relatedReturnObligationId } : {}),
+        updatedAt: Date.now(),
+    };
+    (0, json_store_1.writeJsonFile)(packetsDir(agentRoot), packetId, advanced);
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.packet_advanced",
+        message: "ponder packet advanced",
+        meta: { packetId, status: advanced.status },
+    });
+    return advanced;
+}
+function findHarnessFrictionPacket(agentRoot, origin, frictionSignature) {
+    const found = listPonderPackets(agentRoot).find((packet) => {
+        if (packet.kind !== "harness_friction")
+            return false;
+        if (!packet.origin)
+            return false;
+        return packet.origin.friendId === origin.friendId
+            && packet.origin.channel === origin.channel
+            && packet.origin.key === origin.key
+            && packet.payload.frictionSignature === frictionSignature;
+    }) ?? null;
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.packet_lookup",
+        message: "ponder packet lookup completed",
+        meta: {
+            kind: "harness_friction",
+            found: found !== null,
+            origin: `${origin.friendId}/${origin.channel}/${origin.key}`,
+            frictionSignature,
+        },
+    });
+    return found;
+}

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,
+    };
+}