@ouro.bot/cli 0.1.0-alpha.19 → 0.1.0-alpha.190

package/dist/senses/attention-queue.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAttentionQueue = buildAttentionQueue;
+exports.dequeueAttentionItem = dequeueAttentionItem;
+exports.attentionQueueEmpty = attentionQueueEmpty;
+exports.buildAttentionQueueSummary = buildAttentionQueueSummary;
+const runtime_1 = require("../nerves/runtime");
+// ── Queue construction ───────────────────────────────────────────
+function generateItemId() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function originKey(friendId, channel, key) {
+    return `${friendId}/${channel}/${key}`;
+}
+function buildAttentionQueue(input) {
+    const { drainedPending, outstandingObligations, friendNameResolver } = input;
+    const seen = new Set();
+    const items = [];
+    // Source 1: drained pending messages with delegatedFrom (current-turn delegations)
+    for (const msg of drainedPending) {
+        if (!msg.delegatedFrom)
+            continue;
+        const { friendId, channel, key, bridgeId } = msg.delegatedFrom;
+        const oKey = originKey(friendId, channel, key);
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: msg.obligationId ?? generateItemId(),
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: msg.content,
+            ...(msg.obligationId ? { obligationId: msg.obligationId } : {}),
+            source: "drained",
+            timestamp: msg.timestamp,
+        });
+    }
+    // Source 2: outstanding obligations (crash recovery)
+    for (const obligation of outstandingObligations) {
+        const { friendId, channel, key, bridgeId } = obligation.origin;
+        const oKey = originKey(friendId, channel, key);
+        if (seen.has(oKey))
+            continue; // deduplicate: prefer drained version
+        seen.add(oKey);
+        const resolvedName = friendNameResolver(friendId);
+        items.push({
+            id: obligation.id,
+            friendId,
+            friendName: resolvedName ?? friendId,
+            channel,
+            key,
+            ...(bridgeId ? { bridgeId } : {}),
+            delegatedContent: obligation.delegatedContent,
+            obligationId: obligation.id,
+            source: "obligation-recovery",
+            timestamp: obligation.createdAt,
+        });
+    }
+    // Sort FIFO (oldest first)
+    items.sort((a, b) => a.timestamp - b.timestamp);
+    (0, runtime_1.emitNervesEvent)({
+        event: "senses.attention_queue_built",
+        component: "senses",
+        message: `attention queue built with ${items.length} item(s)`,
+        meta: {
+            drainedCount: items.filter((i) => i.source === "drained").length,
+            recoveredCount: items.filter((i) => i.source === "obligation-recovery").length,
+        },
+    });
+    return items;
+}
+// ── Queue operations ─────────────────────────────────────────────
+function dequeueAttentionItem(queue, id) {
+    const index = queue.findIndex((item) => item.id === id);
+    if (index === -1)
+        return null;
+    return queue.splice(index, 1)[0];
+}
+function attentionQueueEmpty(queue) {
+    return queue.length === 0;
+}
+// ── Queue visibility ─────────────────────────────────────────────
+const CONTENT_PREVIEW_MAX = 80;
+function buildAttentionQueueSummary(queue) {
+    if (queue.length === 0)
+        return "";
+    const lines = ["you're holding:"];
+    for (const item of queue) {
+        const preview = item.delegatedContent.length > CONTENT_PREVIEW_MAX
+            ? `${item.delegatedContent.slice(0, CONTENT_PREVIEW_MAX - 3)}...`
+            : item.delegatedContent;
+        lines.push(`- [${item.id}] ${item.friendName} asked: "${preview}"`);
+    }
+    return lines.join("\n");
+}

package/dist/senses/bluebubbles-client.js

@@ -170,6 +170,12 @@ function applyRepairNotice(event, notice) {
         repairNotice: notice,
     };
 }
+function hasRecoverableMessageContent(event) {
+    return event.kind === "message"
+        && (event.textForAgent.trim().length > 0
+            || event.attachments.length > 0
+            || event.hasPayloadData);
+}
 function hydrateTextForAgent(event, rawData) {
     if (event.kind !== "message") {
         return { ...event, requiresRepair: false };
@@ -196,7 +202,8 @@ function extractRepairData(payload) {
     return asRecord(record?.data) ?? record;
 }
 function providerSupportsAudioInput(provider) {
-    return provider === "azure" || provider === "openai-codex";
+    void provider;
+    return false;
 }
 async function resolveChatGuid(chat, config, channelConfig) {
     return chat.chatGuid
@@ -322,6 +329,40 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                 throw new Error(`BlueBubbles read failed (${response.status}): ${errorText || "unknown"}`);
             }
         },
+        async checkHealth() {
+            const url = buildBlueBubblesApiUrl(config.serverUrl, "/api/v1/message/count", config.password);
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_healthcheck_start",
+                message: "probing bluebubbles upstream health",
+                meta: { serverUrl: config.serverUrl },
+            });
+            const response = await fetch(url, {
+                method: "GET",
+                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_healthcheck_error",
+                    message: "bluebubbles upstream health probe failed",
+                    meta: {
+                        serverUrl: config.serverUrl,
+                        status: response.status,
+                        reason: errorText || "unknown",
+                    },
+                });
+                throw new Error(`BlueBubbles upstream health check failed (${response.status}): ${errorText || "unknown"}`);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_healthcheck_end",
+                message: "bluebubbles upstream health probe succeeded",
+                meta: { serverUrl: config.serverUrl },
+            });
+        },
         async repairEvent(event) {
             if (!event.requiresRepair) {
                 (0, runtime_1.emitNervesEvent)({
@@ -386,12 +427,21 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                     type: event.eventType,
                     data,
                 });
-                let hydrated = hydrateTextForAgent(normalized, data);
+                const recoveredMessage = event.kind === "mutation"
+                    && !event.shouldNotifyAgent
+                    ? (0, bluebubbles_model_1.normalizeBlueBubblesEvent)({
+                        type: "new-message",
+                        data,
+                    })
+                    : null;
+                let hydrated = recoveredMessage && hasRecoverableMessageContent(recoveredMessage)
+                    ? hydrateTextForAgent(recoveredMessage, data)
+                    : hydrateTextForAgent(normalized, data);
                 if (hydrated.kind === "message" &&
                     hydrated.balloonBundleId !== "com.apple.messages.URLBalloonProvider" &&
                     hydrated.attachments.length > 0) {
                     const media = await (0, bluebubbles_media_1.hydrateBlueBubblesAttachments)(hydrated.attachments, config, channelConfig, {
-                        preferAudioInput: providerSupportsAudioInput((0, identity_1.loadAgentConfig)().provider),
+                        preferAudioInput: providerSupportsAudioInput((0, identity_1.loadAgentConfig)().humanFacing.provider),
                     });
                     const transcriptSuffix = media.transcriptAdditions.map((entry) => `[${entry}]`).join("\n");
                     const noticeSuffix = media.notices.map((entry) => `[${entry}]`).join("\n");
@@ -410,6 +460,7 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                         kind: hydrated.kind,
                         messageGuid: hydrated.messageGuid,
                         repairedFrom: event.kind,
+                        promotedFromMutation: event.kind === "mutation" && hydrated.kind === "message",
                     },
                 });
                 return hydrated;
@@ -429,5 +480,53 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                 return applyRepairNotice(event, `BlueBubbles repair failed: ${reason}`);
             }
         },
+        async getMessageText(messageGuid) {
+            const url = buildRepairUrl(config.serverUrl, messageGuid, config.password);
+            try {
+                const response = await fetch(url, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+                });
+                if (!response.ok) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_get_message_text_error",
+                        message: "failed to fetch message text",
+                        meta: { messageGuid, status: response.status },
+                    });
+                    return null;
+                }
+                const payload = await parseJsonBody(response);
+                const data = extractRepairData(payload);
+                if (!data || typeof data.text !== "string") {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_get_message_text_error",
+                        message: "message payload missing text field",
+                        meta: { messageGuid, hasData: !!data, textType: data ? typeof data.text : "n/a" },
+                    });
+                    return null;
+                }
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_get_message_text",
+                    message: "fetched message text by guid",
+                    meta: { messageGuid },
+                });
+                return data.text.trim() || null;
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_get_message_text_error",
+                    message: "exception fetching message text",
+                    meta: { messageGuid, reason: error instanceof Error ? error.message : String(error) },
+                });
+                return null;
+            }
+        },
     };
 }

package/dist/senses/bluebubbles-entry.js

@@ -8,4 +8,6 @@ if (!process.argv.includes("--agent")) {
     process.exit(1);
 }
 const bluebubbles_1 = require("./bluebubbles");
+const runtime_logging_1 = require("../heart/daemon/runtime-logging");
+(0, runtime_logging_1.configureDaemonRuntimeLogger)("bluebubbles");
 (0, bluebubbles_1.startBlueBubblesApp)();

package/dist/senses/bluebubbles-inbound-log.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.getBlueBubblesInboundLogPath = getBlueBubblesInboundLogPath;
+exports.hasRecordedBlueBubblesInbound = hasRecordedBlueBubblesInbound;
+exports.recordBlueBubblesInbound = recordBlueBubblesInbound;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../heart/config");
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+function getBlueBubblesInboundLogPath(agentName, sessionKey) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "inbound", `${(0, config_1.sanitizeKey)(sessionKey)}.ndjson`);
+}
+function readEntries(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        return raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line))
+            .filter((entry) => typeof entry.messageGuid === "string" && typeof entry.sessionKey === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function hasRecordedBlueBubblesInbound(agentName, sessionKey, messageGuid) {
+    if (!messageGuid.trim())
+        return false;
+    const filePath = getBlueBubblesInboundLogPath(agentName, sessionKey);
+    return readEntries(filePath).some((entry) => entry.messageGuid === messageGuid);
+}
+function recordBlueBubblesInbound(agentName, event, source) {
+    const filePath = getBlueBubblesInboundLogPath(agentName, event.chat.sessionKey);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify({
+            recordedAt: new Date(event.timestamp).toISOString(),
+            messageGuid: event.messageGuid,
+            chatGuid: event.chat.chatGuid ?? null,
+            chatIdentifier: event.chat.chatIdentifier ?? null,
+            sessionKey: event.chat.sessionKey,
+            textForAgent: event.textForAgent,
+            source,
+        }) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_inbound_log_error",
+            message: "failed to record bluebubbles inbound sidecar log",
+            meta: {
+                agentName,
+                messageGuid: event.messageGuid,
+                sessionKey: event.chat.sessionKey,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return filePath;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_inbound_logged",
+        message: "recorded bluebubbles inbound message to sidecar log",
+        meta: {
+            agentName,
+            messageGuid: event.messageGuid,
+            sessionKey: event.chat.sessionKey,
+            source,
+            path: filePath,
+        },
+    });
+    return filePath;
+}

package/dist/senses/bluebubbles-media.js

@@ -39,6 +39,7 @@ 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 identity_1 = require("../heart/identity");
 const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
 const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".m4a", ".caf", ".ogg"]);
 const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif"]);
@@ -62,6 +63,12 @@ const AUDIO_INPUT_FORMAT_BY_EXTENSION = {
     ".wav": "wav",
     ".mp3": "mp3",
 };
+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((0, identity_1.getAgentToolsRoot)(), "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);
@@ -107,36 +114,123 @@ function audioFormatForInput(contentType, attachment) {
     const extension = path.extname(attachment?.transferName ?? "").toLowerCase();
     return AUDIO_INPUT_FORMAT_BY_CONTENT_TYPE[contentType ?? ""] ?? AUDIO_INPUT_FORMAT_BY_EXTENSION[extension];
 }
-async function transcribeAudioWithWhisper(params) {
+async function execFileText(file, args, timeout) {
+    return await new Promise((resolve, reject) => {
+        (0, node_child_process_1.execFile)(file, args, { timeout }, (error, stdout = "", stderr = "") => {
+            if (error) {
+                const detail = stderr.trim() || stdout.trim() || error.message;
+                reject(new Error(detail));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveWhisperCppBinary(timeoutMs) {
+    try {
+        const existing = (await execFileText("which", ["whisper-cli"], timeoutMs)).trim();
+        if (existing) {
+            return existing;
+        }
+    }
+    catch {
+        // fall through to managed install
+    }
+    let prefix = "";
+    try {
+        prefix = (await execFileText("brew", ["--prefix", WHISPER_CPP_FORMULA], timeoutMs)).trim();
+        if (prefix) {
+            const candidate = path.join(prefix, "bin", "whisper-cli");
+            if (await pathExists(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    catch {
+        // fall through to managed install
+    }
+    await execFileText("brew", ["install", WHISPER_CPP_FORMULA], Math.max(timeoutMs, 300_000));
+    prefix = (await execFileText("brew", ["--prefix", WHISPER_CPP_FORMULA], timeoutMs)).trim();
+    if (!prefix) {
+        throw new Error("whisper.cpp installed but brew did not return a usable prefix");
+    }
+    const candidate = path.join(prefix, "bin", "whisper-cli");
+    if (!await pathExists(candidate)) {
+        throw new Error("whisper.cpp installed but whisper-cli binary is missing");
+    }
+    return candidate;
+}
+async function ensureWhisperCppModel(timeoutMs, fetchImpl) {
+    try {
+        await fs.access(WHISPER_CPP_MODEL_PATH);
+        return WHISPER_CPP_MODEL_PATH;
+    }
+    catch {
+        await fs.mkdir(WHISPER_CPP_MODELS_DIR, { recursive: true });
+        const response = await fetchImpl(WHISPER_CPP_MODEL_URL, {
+            method: "GET",
+            signal: AbortSignal.timeout(Math.max(timeoutMs, 300_000)),
+        });
+        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;
+    }
+}
+async function convertAudioForWhisperCpp(sourcePath, outputPath, timeoutMs) {
+    try {
+        await execFileText("ffmpeg", ["-y", "-i", sourcePath, "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le", outputPath], Math.max(timeoutMs, 120_000));
+        return;
+    }
+    catch (ffmpegError) {
+        try {
+            await execFileText("afconvert", ["-f", "WAVE", "-d", "LEI16@16000", "-c", "1", sourcePath, outputPath], Math.max(timeoutMs, 120_000));
+            return;
+        }
+        catch (afconvertError) {
+            const ffmpegReason = ffmpegError.message;
+            const afconvertReason = afconvertError.message;
+            throw new Error(`failed to prepare audio for whisper.cpp (ffmpeg: ${ffmpegReason}; afconvert: ${afconvertReason})`);
+        }
+    }
+}
+async function transcribeAudioWithWhisperCpp(params, modelFetchImpl = fetch) {
     const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "ouro-bb-audio-"));
     const filename = sanitizeFilename(describeAttachment(params.attachment));
     const extension = fileExtensionForAudio(params.attachment, params.contentType);
     const audioPath = path.join(workDir, `${path.parse(filename).name}${extension}`);
+    const wavPath = path.join(workDir, `${path.parse(audioPath).name}.wav`);
+    const outputBase = path.join(workDir, path.parse(audioPath).name);
     try {
         await fs.writeFile(audioPath, params.buffer);
-        await new Promise((resolve, reject) => {
-            (0, node_child_process_1.execFile)("whisper", [
-                audioPath,
-                "--model",
-                "turbo",
-                "--output_dir",
-                workDir,
-                "--output_format",
-                "json",
-                "--verbose",
-                "False",
-            ], { timeout: Math.max(params.timeoutMs, 120000) }, (error) => {
-                if (error) {
-                    reject(error);
-                    return;
-                }
-                resolve();
-            });
-        });
-        const transcriptPath = path.join(workDir, `${path.parse(audioPath).name}.json`);
+        const whisperCliPath = await resolveWhisperCppBinary(params.timeoutMs);
+        const modelPath = await ensureWhisperCppModel(params.timeoutMs, modelFetchImpl);
+        await convertAudioForWhisperCpp(audioPath, wavPath, params.timeoutMs);
+        await execFileText(whisperCliPath, ["-m", modelPath, "-f", wavPath, "-oj", "-of", outputBase], Math.max(params.timeoutMs, 120_000));
+        const transcriptPath = `${outputBase}.json`;
         const raw = await fs.readFile(transcriptPath, "utf8");
         const parsed = JSON.parse(raw);
-        return typeof parsed.text === "string" ? parsed.text.trim() : "";
+        if (typeof parsed.text === "string") {
+            return parsed.text.trim();
+        }
+        if (Array.isArray(parsed.transcription)) {
+            return parsed.transcription
+                .map((entry) => (typeof entry?.text === "string" ? entry.text.trim() : ""))
+                .filter(Boolean)
+                .join(" ")
+                .trim();
+        }
+        return "";
     }
     finally {
         await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
@@ -178,7 +272,8 @@ async function hydrateBlueBubblesAttachments(attachments, config, channelConfig,
         },
     });
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const transcribeAudio = deps.transcribeAudio ?? transcribeAudioWithWhisper;
+    const modelFetchImpl = deps.modelFetchImpl ?? fetch;
+    const transcribeAudio = deps.transcribeAudio ?? ((params) => transcribeAudioWithWhisperCpp(params, modelFetchImpl));
     const preferAudioInput = deps.preferAudioInput ?? false;
     const inputParts = [];
     const transcriptAdditions = [];

package/dist/senses/bluebubbles-model.js

@@ -39,6 +39,7 @@ function extractChatIdentifierFromGuid(chatGuid) {
     return parts.length >= 3 ? parts[2]?.trim() || undefined : undefined;
 }
 function buildChatRef(data, threadOriginatorGuid) {
+    void threadOriginatorGuid;
     const chats = Array.isArray(data.chats) ? data.chats : [];
     const chat = asRecord(chats[0]) ?? null;
     const chatGuid = readString(chat, "guid");
@@ -48,12 +49,18 @@ function buildChatRef(data, threadOriginatorGuid) {
     const displayName = readString(chat, "displayName")?.trim() || undefined;
     const style = readNumber(chat, "style");
     const isGroup = style === 43 || (chatGuid?.includes(";+;") ?? false) || Boolean(displayName);
-    const baseKey = chatGuid?.trim()
+    const sessionKey = chatGuid?.trim()
         ? `chat:${chatGuid.trim()}`
         : `chat_identifier:${(chatIdentifier ?? "unknown").trim()}`;
-    const sessionKey = threadOriginatorGuid?.trim()
-        ? `${baseKey}:thread:${threadOriginatorGuid.trim()}`
-        : baseKey;
+    // 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,
@@ -63,6 +70,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) {

package/dist/senses/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 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));
+}