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

package/dist/senses/{bluebubbles-media.js → bluebubbles/media.js}

@@ -33,15 +33,32 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadBlueBubblesAttachment = exports.VLM_TEXT_WRAPPERS = void 0;
 exports.hydrateBlueBubblesAttachments = hydrateBlueBubblesAttachments;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs/promises"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
-const runtime_1 = require("../nerves/runtime");
-const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../../heart/identity");
+const model_capabilities_1 = require("../../heart/model-capabilities");
+const image_normalize_1 = require("../../heart/attachments/image-normalize");
+const store_1 = require("../../heart/attachments/store");
+const types_1 = require("../../heart/attachments/types");
+const materialize_1 = require("../../heart/attachments/materialize");
+const attachment_download_1 = require("./attachment-download");
+// Pin the exact wrapper strings so tests and code read from one source.
+exports.VLM_TEXT_WRAPPERS = {
+    description: (desc) => `[image description: ${desc}]`,
+    failure: (reason) => `[image description failed: ${reason}]`,
+};
+// D3 prompt template. Included here (not templated out) because the contract
+// is load-bearing — see planning doc section D3 and AX-4.
+function buildVlmPrompt(userText) {
+    const body = userText ?? "";
+    return `User message: "${body}"\n\nDescribe this image in detail, focusing on anything relevant to what the user said above.\nInclude any text visible in the image verbatim.`;
+}
 const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".m4a", ".caf", ".ogg"]);
-const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif"]);
 const AUDIO_EXTENSION_BY_CONTENT_TYPE = {
     "audio/wav": ".wav",
     "audio/x-wav": ".wav",
@@ -65,31 +82,19 @@ const AUDIO_INPUT_FORMAT_BY_EXTENSION = {
 const WHISPER_CPP_FORMULA = "whisper-cpp";
 const WHISPER_CPP_MODEL_NAME = "ggml-base.en.bin";
 const WHISPER_CPP_MODEL_URL = `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/${WHISPER_CPP_MODEL_NAME}`;
-const WHISPER_CPP_TOOLS_DIR = path.join(os.homedir(), ".agentstate", "tools", "whisper-cpp");
-const WHISPER_CPP_MODELS_DIR = path.join(WHISPER_CPP_TOOLS_DIR, "models");
-const WHISPER_CPP_MODEL_PATH = path.join(WHISPER_CPP_MODELS_DIR, WHISPER_CPP_MODEL_NAME);
-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();
+// Lazy — getAgentToolsRoot() requires identity to be resolved, which isn't
+// true at module-load time in most unit test contexts. Tests that only touch
+// the image/VLM path shouldn't break because the audio path asked for a
+// tools root they don't need.
+function whisperCppPaths() {
+    const toolsDir = path.join((0, identity_1.getAgentToolsRoot)(), "whisper-cpp");
+    const modelsDir = path.join(toolsDir, "models");
+    const modelPath = path.join(modelsDir, WHISPER_CPP_MODEL_NAME);
+    return { toolsDir, modelsDir, modelPath };
 }
 function describeAttachment(attachment) {
     return attachment.transferName?.trim() || attachment.guid?.trim() || "attachment";
 }
-function inferContentType(attachment, responseType) {
-    const normalizedResponseType = responseType?.split(";")[0]?.trim().toLowerCase();
-    if (normalizedResponseType) {
-        return normalizedResponseType;
-    }
-    return attachment.mimeType?.trim().toLowerCase() || undefined;
-}
-function isImageAttachment(attachment, contentType) {
-    if (contentType?.startsWith("image/"))
-        return true;
-    const extension = path.extname(attachment.transferName ?? "").toLowerCase();
-    return IMAGE_EXTENSIONS.has(extension);
-}
 function isAudioAttachment(attachment, contentType) {
     if (contentType?.startsWith("audio/"))
         return true;
@@ -169,12 +174,13 @@ async function resolveWhisperCppBinary(timeoutMs) {
     return candidate;
 }
 async function ensureWhisperCppModel(timeoutMs, fetchImpl) {
+    const { modelsDir, modelPath } = whisperCppPaths();
     try {
-        await fs.access(WHISPER_CPP_MODEL_PATH);
-        return WHISPER_CPP_MODEL_PATH;
+        await fs.access(modelPath);
+        return modelPath;
     }
     catch {
-        await fs.mkdir(WHISPER_CPP_MODELS_DIR, { recursive: true });
+        await fs.mkdir(modelsDir, { recursive: true });
         const response = await fetchImpl(WHISPER_CPP_MODEL_URL, {
             method: "GET",
             signal: AbortSignal.timeout(Math.max(timeoutMs, 300_000)),
@@ -182,8 +188,8 @@ async function ensureWhisperCppModel(timeoutMs, fetchImpl) {
         if (!response.ok) {
             throw new Error(`failed to download whisper.cpp model: HTTP ${response.status}`);
         }
-        await fs.writeFile(WHISPER_CPP_MODEL_PATH, Buffer.from(await response.arrayBuffer()));
-        return WHISPER_CPP_MODEL_PATH;
+        await fs.writeFile(modelPath, Buffer.from(await response.arrayBuffer()));
+        return modelPath;
     }
 }
 async function convertAudioForWhisperCpp(sourcePath, outputPath, timeoutMs) {
@@ -235,59 +241,105 @@ async function transcribeAudioWithWhisperCpp(params, modelFetchImpl = fetch) {
         await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
-async function downloadAttachment(attachment, config, channelConfig, fetchImpl) {
-    const guid = attachment.guid?.trim();
-    if (!guid) {
-        throw new Error("attachment guid missing");
-    }
-    if (typeof attachment.totalBytes === "number" && attachment.totalBytes > MAX_ATTACHMENT_BYTES) {
-        throw new Error(`attachment exceeds ${MAX_ATTACHMENT_BYTES} byte limit`);
-    }
-    const url = buildBlueBubblesApiUrl(config.serverUrl, `/api/v1/attachment/${encodeURIComponent(guid)}/download`, config.password);
-    const response = await fetchImpl(url, {
-        method: "GET",
-        signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
-    });
-    if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
-    }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    if (buffer.length > MAX_ATTACHMENT_BYTES) {
-        throw new Error(`attachment exceeds ${MAX_ATTACHMENT_BYTES} byte limit`);
-    }
-    return {
-        buffer,
-        contentType: inferContentType(attachment, response.headers.get("content-type")),
-    };
-}
+var attachment_download_2 = require("./attachment-download");
+Object.defineProperty(exports, "downloadBlueBubblesAttachment", { enumerable: true, get: function () { return attachment_download_2.downloadBlueBubblesAttachment; } });
 async function hydrateBlueBubblesAttachments(attachments, config, channelConfig, deps = {}) {
-    (0, runtime_1.emitNervesEvent)({
-        component: "senses",
-        event: "senses.bluebubbles_media_hydrate",
-        message: "hydrating bluebubbles attachments",
-        meta: {
-            attachmentCount: attachments.length,
-            preferAudioInput: deps.preferAudioInput ?? false,
-        },
-    });
     const fetchImpl = deps.fetchImpl ?? fetch;
     const modelFetchImpl = deps.modelFetchImpl ?? fetch;
     const transcribeAudio = deps.transcribeAudio ?? ((params) => transcribeAudioWithWhisperCpp(params, modelFetchImpl));
     const preferAudioInput = deps.preferAudioInput ?? false;
+    const chatModel = deps.chatModel;
+    const visionCapable = chatModel ? (0, model_capabilities_1.getModelCapabilities)(chatModel).vision === true : true;
+    const agentName = (0, identity_1.getAgentName)();
+    const agentRoot = (0, identity_1.getAgentRoot)(agentName);
     const inputParts = [];
     const transcriptAdditions = [];
     const notices = [];
     for (const attachment of attachments) {
         const name = describeAttachment(attachment);
+        const initialRecord = attachment.guid?.trim()
+            ? (0, store_1.rememberRecentAttachment)(agentName, (0, types_1.buildBlueBubblesAttachmentRecord)(attachment), agentRoot)
+            : null;
         try {
-            const downloaded = await downloadAttachment(attachment, config, channelConfig, fetchImpl);
+            const downloaded = await (0, attachment_download_1.downloadBlueBubblesAttachment)(attachment, config, channelConfig, fetchImpl);
             const base64 = downloaded.buffer.toString("base64");
-            if (isImageAttachment(attachment, downloaded.contentType)) {
-                inputParts.push({
-                    type: "image_url",
-                    image_url: {
-                        url: `data:${downloaded.contentType ?? "application/octet-stream"};base64,${base64}`,
-                        detail: "auto",
+            const byteCount = downloaded.buffer.length;
+            const persistedRecord = initialRecord && initialRecord.source === "bluebubbles"
+                ? await (0, materialize_1.persistBlueBubblesAttachmentSource)(agentName, initialRecord, {
+                    buffer: downloaded.buffer,
+                    mimeType: downloaded.contentType,
+                    byteCount,
+                }, agentRoot)
+                : null;
+            if ((0, attachment_download_1.isBlueBubblesImageAttachment)(attachment, downloaded.contentType)) {
+                const mimeType = downloaded.contentType ?? "application/octet-stream";
+                if (visionCapable) {
+                    inputParts.push({
+                        type: "image_url",
+                        image_url: {
+                            url: `data:${mimeType};base64,${base64}`,
+                            detail: "auto",
+                        },
+                    });
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_media_hydrate",
+                        message: "bluebubbles media hydrate",
+                        meta: {
+                            attachmentGuid: attachment.guid,
+                            mimeType,
+                            byteCount,
+                            hydrationPath: "native-passthrough",
+                        },
+                    });
+                    continue;
+                }
+                try {
+                    if (!deps.vlmDescribe) {
+                        throw new Error("no VLM describer configured — wire a vlmDescribe dep or configure a vision-capable chat model");
+                    }
+                    if (!persistedRecord?.sourceData.localPath) {
+                        throw new Error("image attachment could not be persisted for normalization");
+                    }
+                    const normalized = await (0, image_normalize_1.normalizeImageForVision)({
+                        attachment: persistedRecord,
+                        sourcePath: persistedRecord.sourceData.localPath,
+                        agentName,
+                        agentRoot,
+                    });
+                    const normalizedBuffer = await fs.readFile(normalized.path);
+                    const normalizedMime = normalized.mimeType ?? persistedRecord.mimeType ?? "image/jpeg";
+                    const dataUrl = `data:${normalizedMime};base64,${normalizedBuffer.toString("base64")}`;
+                    const description = await deps.vlmDescribe({
+                        prompt: buildVlmPrompt(deps.userText),
+                        imageDataUrl: dataUrl,
+                        attachmentGuid: attachment.guid,
+                        mimeType: normalizedMime,
+                        chatModel,
+                    });
+                    inputParts.push({
+                        type: "text",
+                        text: exports.VLM_TEXT_WRAPPERS.description(description),
+                    });
+                }
+                catch (vlmError) {
+                    const reason = vlmError instanceof Error ? vlmError.message : String(vlmError);
+                    inputParts.push({
+                        type: "text",
+                        text: exports.VLM_TEXT_WRAPPERS.failure(reason),
+                    });
+                }
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_media_hydrate",
+                    message: "bluebubbles media hydrate",
+                    meta: {
+                        attachmentGuid: attachment.guid,
+                        mimeType: persistedRecord?.mimeType ?? mimeType,
+                        byteCount,
+                        hydrationPath: "vlm-describe",
                     },
                 });
                 continue;

package/dist/senses/{bluebubbles-model.js → bluebubbles/model.js}

@@ -1,7 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlueBubblesIgnoredEventError = void 0;
 exports.normalizeBlueBubblesEvent = normalizeBlueBubblesEvent;
-const runtime_1 = require("../nerves/runtime");
+const runtime_1 = require("../../nerves/runtime");
+const render_1 = require("../../heart/attachments/render");
+const types_1 = require("../../heart/attachments/types");
+const IGNORABLE_GUIDLESS_EVENT_TYPES = new Set([
+    "chat-read-status-changed",
+]);
+class BlueBubblesIgnoredEventError extends Error {
+    eventType;
+    constructor(eventType, message) {
+        super(message);
+        this.name = "BlueBubblesIgnoredEventError";
+        this.eventType = eventType;
+    }
+}
+exports.BlueBubblesIgnoredEventError = BlueBubblesIgnoredEventError;
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -52,6 +67,15 @@ function buildChatRef(data, threadOriginatorGuid) {
     const sessionKey = chatGuid?.trim()
         ? `chat:${chatGuid.trim()}`
         : `chat_identifier:${(chatIdentifier ?? "unknown").trim()}`;
+    // Extract participant handles from chat.participants (when available from BB API)
+    const rawParticipants = Array.isArray(chat?.participants) ? chat.participants : [];
+    const participantHandles = rawParticipants
+        .map((p) => {
+        const rec = asRecord(p);
+        const addr = readString(rec, "address") ?? readString(rec, "id");
+        return addr ? normalizeHandle(addr) : "";
+    })
+        .filter(Boolean);
     return {
         chatGuid: chatGuid?.trim() || undefined,
         chatIdentifier: chatIdentifier?.trim() || undefined,
@@ -61,6 +85,7 @@ function buildChatRef(data, threadOriginatorGuid) {
         sendTarget: chatGuid?.trim()
             ? { kind: "chat_guid", value: chatGuid.trim() }
             : { kind: "chat_identifier", value: (chatIdentifier ?? "unknown").trim() },
+        participantHandles,
     };
 }
 function extractSender(data, chat) {
@@ -97,18 +122,14 @@ function extractAttachments(data) {
 function formatAttachmentText(attachments) {
     if (attachments.length === 0)
         return "";
+    const renderable = attachments
+        .filter((attachment) => typeof attachment.guid === "string" && attachment.guid.trim().length > 0)
+        .map((attachment) => (0, types_1.buildBlueBubblesAttachmentRecord)(attachment));
+    if (renderable.length > 0) {
+        return (0, render_1.renderAttachmentBlock)(renderable);
+    }
     const [first] = attachments;
-    const mime = first.mimeType ?? "";
-    const label = mime.startsWith("image/")
-        ? "image attachment"
-        : mime.startsWith("audio/")
-            ? "audio attachment"
-            : "attachment";
-    const name = first.transferName ? `: ${first.transferName}` : "";
-    const dimensions = typeof first.width === "number" && typeof first.height === "number" && first.width > 0 && first.height > 0
-        ? ` (${first.width}x${first.height})`
-        : "";
-    return `[${label}${name}${dimensions}]`;
+    return `[attachment: ${first.transferName?.trim() || "unknown"}]`;
 }
 function formatMessageText(data, attachments) {
     const text = readString(data, "text")?.trim() ?? "";
@@ -117,6 +138,13 @@ function formatMessageText(data, attachments) {
         if (balloonBundleId === "com.apple.messages.URLBalloonProvider") {
             return `${text}\n[link preview attached]`;
         }
+        // B2 fix: when text and attachments both exist, append the attachment
+        // marker so downstream senses can see the guid/filename. Previously the
+        // marker was dropped whenever text was non-empty, which hid images from
+        // the agent when the user captioned a screenshot.
+        if (attachments.length > 0) {
+            return `${text}\n${formatAttachmentText(attachments)}`;
+        }
         return text;
     }
     return formatAttachmentText(attachments);
@@ -188,6 +216,9 @@ function normalizeBlueBubblesEvent(payload) {
             message: "ignored bluebubbles payload without guid",
             meta: { eventType },
         });
+        if (IGNORABLE_GUIDLESS_EVENT_TYPES.has(eventType)) {
+            throw new BlueBubblesIgnoredEventError(eventType, `Ignored BlueBubbles event '${eventType}' without data.guid`);
+        }
         throw new Error("BlueBubbles payload is missing data.guid");
     }
     const threadOriginatorGuid = readString(data, "threadOriginatorGuid")?.trim() || undefined;

package/dist/senses/{bluebubbles-mutation-log.js → bluebubbles/mutation-log.js}

@@ -35,15 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBlueBubblesMutationLogPath = getBlueBubblesMutationLogPath;
 exports.recordBlueBubblesMutation = recordBlueBubblesMutation;
+exports.listBlueBubblesRecoveryCandidates = listBlueBubblesRecoveryCandidates;
 const fs = __importStar(require("node:fs"));
-const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
-const runtime_1 = require("../nerves/runtime");
-function sanitizeKey(key) {
-    return key.replace(/[/:]/g, "_");
-}
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../../heart/identity");
+const config_1 = require("../../heart/config");
 function getBlueBubblesMutationLogPath(agentName, sessionKey) {
-    return path.join(os.homedir(), ".agentstate", agentName, "senses", "bluebubbles", "mutations", `${sanitizeKey(sessionKey)}.ndjson`);
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "mutations", `${(0, config_1.sanitizeKey)(sessionKey)}.ndjson`);
 }
 function recordBlueBubblesMutation(agentName, event) {
     const filePath = getBlueBubblesMutationLogPath(agentName, event.chat.sessionKey);
@@ -74,3 +73,44 @@ function recordBlueBubblesMutation(agentName, event) {
     });
     return filePath;
 }
+function listBlueBubblesRecoveryCandidates(agentName) {
+    const rootDir = path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "mutations");
+    let files;
+    try {
+        files = fs.readdirSync(rootDir);
+    }
+    catch {
+        return [];
+    }
+    const deduped = new Map();
+    for (const file of files.filter((entry) => entry.endsWith(".ndjson")).sort()) {
+        const filePath = path.join(rootDir, file);
+        let raw = "";
+        try {
+            raw = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (typeof entry.messageGuid !== "string"
+                    || !entry.messageGuid.trim()
+                    || entry.fromMe
+                    || entry.shouldNotifyAgent
+                    || (entry.mutationType !== "read" && entry.mutationType !== "delivery")) {
+                    continue;
+                }
+                deduped.set(entry.messageGuid, entry);
+            }
+            catch {
+                // ignore malformed recovery candidates
+            }
+        }
+    }
+    return [...deduped.values()].sort((left, right) => left.recordedAt.localeCompare(right.recordedAt));
+}

package/dist/senses/bluebubbles/replay.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replayBlueBubblesMessage = replayBlueBubblesMessage;
+exports.formatBlueBubblesReplayText = formatBlueBubblesReplayText;
+const render_1 = require("../../heart/attachments/render");
+const types_1 = require("../../heart/attachments/types");
+const identity_1 = require("../../heart/identity");
+const runtime_1 = require("../../nerves/runtime");
+const client_1 = require("./client");
+const model_1 = require("./model");
+function buildReplayHint(probeEventType, event) {
+    if (probeEventType === "updated-message"
+        && event.kind === "mutation"
+        && (event.mutationType === "read" || event.mutationType === "delivery")) {
+        return "replay resolved to a state-only mutation; rerun with --event-type new-message to inspect the original message payload.";
+    }
+    return undefined;
+}
+async function replayBlueBubblesMessage(params, deps = {}) {
+    const agentName = params.agentName.trim();
+    const messageGuid = params.messageGuid.trim();
+    const eventType = params.eventType ?? "new-message";
+    if (!agentName) {
+        throw new Error("bluebubbles replay requires agentName");
+    }
+    if (!messageGuid) {
+        throw new Error("bluebubbles replay requires messageGuid");
+    }
+    const setReplayAgentName = deps.setAgentName ?? identity_1.setAgentName;
+    const resetReplayIdentity = deps.resetIdentity ?? identity_1.resetIdentity;
+    const normalizeEvent = deps.normalizeEvent ?? model_1.normalizeBlueBubblesEvent;
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_replay_start",
+        message: "starting bluebubbles historical replay",
+        meta: {
+            agentName,
+            messageGuid,
+            eventType,
+        },
+    });
+    setReplayAgentName(agentName);
+    try {
+        const client = deps.createClient ? deps.createClient() : (0, client_1.createBlueBubblesClient)();
+        const probe = normalizeEvent({
+            type: eventType,
+            data: {
+                guid: messageGuid,
+                hasPayloadData: true,
+            },
+        });
+        const event = await client.repairEvent(probe);
+        const attachmentRecords = event.kind === "message"
+            ? event.attachments
+                .filter((attachment) => typeof attachment.guid === "string" && attachment.guid.trim().length > 0)
+                .map((attachment) => (0, types_1.buildBlueBubblesAttachmentRecord)(attachment))
+            : [];
+        const result = {
+            probe: {
+                agentName,
+                messageGuid,
+                eventType,
+            },
+            event,
+            attachmentIds: attachmentRecords.map((attachment) => attachment.id),
+            attachmentBlock: (0, render_1.renderAttachmentBlock)(attachmentRecords),
+            ...(buildReplayHint(eventType, event) ? { hint: buildReplayHint(eventType, event) } : {}),
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_replay_end",
+            message: "completed bluebubbles historical replay",
+            meta: {
+                agentName,
+                messageGuid,
+                eventType,
+                kind: event.kind,
+                attachmentCount: attachmentRecords.length,
+            },
+        });
+        return result;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_replay_error",
+            message: "bluebubbles historical replay failed",
+            meta: {
+                agentName,
+                messageGuid,
+                eventType,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        throw error;
+    }
+    finally {
+        resetReplayIdentity();
+    }
+}
+function formatBlueBubblesReplayText(result) {
+    const lines = [
+        `probe: ${result.probe.eventType}`,
+        `agent: ${result.probe.agentName}`,
+        `message_guid: ${result.probe.messageGuid}`,
+        `result_kind: ${result.event.kind}`,
+        `session: ${result.event.chat.sessionKey}`,
+    ];
+    if (result.event.kind === "mutation") {
+        lines.push(`mutation_type: ${result.event.mutationType}`);
+    }
+    if (result.event.kind === "message" && result.event.inputPartsForAgent?.length) {
+        lines.push(`input_parts_for_agent: ${result.event.inputPartsForAgent.length}`);
+    }
+    if (result.event.repairNotice?.trim()) {
+        lines.push(`repair_notice: ${result.event.repairNotice.trim()}`);
+    }
+    if (result.attachmentBlock && !result.event.textForAgent.includes(result.attachmentBlock)) {
+        lines.push(result.attachmentBlock);
+    }
+    lines.push("[text_for_agent]");
+    lines.push(result.event.textForAgent || "(empty)");
+    if (result.hint) {
+        lines.push("[hint]");
+        lines.push(result.hint);
+    }
+    return lines.join("\n");
+}

package/dist/senses/bluebubbles/runtime-state.js

@@ -0,0 +1,109 @@
+"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.getBlueBubblesRuntimeStatePath = getBlueBubblesRuntimeStatePath;
+exports.readBlueBubblesRuntimeState = readBlueBubblesRuntimeState;
+exports.writeBlueBubblesRuntimeState = writeBlueBubblesRuntimeState;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const identity_1 = require("../../heart/identity");
+const runtime_1 = require("../../nerves/runtime");
+const DEFAULT_RUNTIME_STATE = {
+    upstreamStatus: "unknown",
+    detail: "startup health probe pending",
+    pendingRecoveryCount: 0,
+};
+function getBlueBubblesRuntimeStatePath(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return path.join(agentRoot, "state", "senses", "bluebubbles", "runtime.json");
+}
+function readBlueBubblesRuntimeState(agentName, agentRoot) {
+    const filePath = getBlueBubblesRuntimeStatePath(agentName, agentRoot);
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            upstreamStatus: parsed.upstreamStatus === "ok" || parsed.upstreamStatus === "error"
+                ? parsed.upstreamStatus
+                : "unknown",
+            detail: typeof parsed.detail === "string" && parsed.detail.trim()
+                ? parsed.detail
+                : DEFAULT_RUNTIME_STATE.detail,
+            lastCheckedAt: typeof parsed.lastCheckedAt === "string" ? parsed.lastCheckedAt : undefined,
+            pendingRecoveryCount: typeof parsed.pendingRecoveryCount === "number" && Number.isFinite(parsed.pendingRecoveryCount)
+                ? parsed.pendingRecoveryCount
+                : 0,
+            lastRecoveredAt: typeof parsed.lastRecoveredAt === "string" ? parsed.lastRecoveredAt : undefined,
+            lastRecoveredMessageGuid: typeof parsed.lastRecoveredMessageGuid === "string"
+                ? parsed.lastRecoveredMessageGuid
+                : undefined,
+        };
+    }
+    catch {
+        return { ...DEFAULT_RUNTIME_STATE };
+    }
+}
+function writeBlueBubblesRuntimeState(agentName, state, agentRoot) {
+    const filePath = getBlueBubblesRuntimeStatePath(agentName, agentRoot);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_runtime_state_error",
+            message: "failed to write bluebubbles runtime state",
+            meta: {
+                agentName,
+                upstreamStatus: state.upstreamStatus,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return filePath;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_runtime_state_written",
+        message: "wrote bluebubbles runtime state",
+        meta: {
+            agentName,
+            upstreamStatus: state.upstreamStatus,
+            pendingRecoveryCount: state.pendingRecoveryCount,
+            path: filePath,
+        },
+    });
+    return filePath;
+}