@ouro.bot/cli 0.1.0-alpha.5 → 0.1.0-alpha.500

package/dist/senses/bluebubbles/media.js

@@ -0,0 +1,389 @@
+"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.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 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 bluebubbles_1 = require("../../heart/attachments/sources/bluebubbles");
+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 AUDIO_EXTENSION_BY_CONTENT_TYPE = {
+    "audio/wav": ".wav",
+    "audio/x-wav": ".wav",
+    "audio/mp3": ".mp3",
+    "audio/mpeg": ".mp3",
+    "audio/x-caf": ".caf",
+    "audio/caf": ".caf",
+    "audio/mp4": ".m4a",
+    "audio/x-m4a": ".m4a",
+};
+const AUDIO_INPUT_FORMAT_BY_CONTENT_TYPE = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mp3": "mp3",
+    "audio/mpeg": "mp3",
+};
+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}`;
+// 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 isAudioAttachment(attachment, contentType) {
+    if (contentType?.startsWith("audio/"))
+        return true;
+    const extension = path.extname(attachment.transferName ?? "").toLowerCase();
+    return AUDIO_EXTENSIONS.has(extension);
+}
+function sanitizeFilename(name) {
+    return path.basename(name).replace(/[\r\n"\\]/g, "_");
+}
+function fileExtensionForAudio(attachment, contentType) {
+    const transferExt = path.extname(attachment.transferName ?? "").toLowerCase();
+    if (transferExt) {
+        return transferExt;
+    }
+    if (contentType && AUDIO_EXTENSION_BY_CONTENT_TYPE[contentType]) {
+        return AUDIO_EXTENSION_BY_CONTENT_TYPE[contentType];
+    }
+    return ".audio";
+}
+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 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) {
+    const { modelsDir, modelPath } = whisperCppPaths();
+    try {
+        await fs.access(modelPath);
+        return modelPath;
+    }
+    catch {
+        await fs.mkdir(modelsDir, { 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(modelPath, Buffer.from(await response.arrayBuffer()));
+        return modelPath;
+    }
+}
+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);
+        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);
+        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);
+    }
+}
+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 = {}) {
+    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.cacheRecentAttachment)(agentName, (0, bluebubbles_1.buildBlueBubblesAttachmentRecord)(attachment), agentRoot)
+            : null;
+        try {
+            const downloaded = await (0, attachment_download_1.downloadBlueBubblesAttachment)(attachment, config, channelConfig, fetchImpl);
+            const base64 = downloaded.buffer.toString("base64");
+            const byteCount = downloaded.buffer.length;
+            const persistedRecord = initialRecord && initialRecord.source === "bluebubbles"
+                ? await (0, bluebubbles_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;
+            }
+            if (isAudioAttachment(attachment, downloaded.contentType)) {
+                const audioFormat = audioFormatForInput(downloaded.contentType, attachment);
+                if (preferAudioInput && audioFormat) {
+                    inputParts.push({
+                        type: "input_audio",
+                        input_audio: {
+                            data: base64,
+                            format: audioFormat,
+                        },
+                    });
+                    continue;
+                }
+                const transcript = (await transcribeAudio({
+                    attachment,
+                    buffer: downloaded.buffer,
+                    contentType: downloaded.contentType,
+                    timeoutMs: channelConfig.requestTimeoutMs,
+                })).trim();
+                if (!transcript) {
+                    notices.push(`attachment hydration failed for ${name}: empty audio transcript`);
+                    continue;
+                }
+                transcriptAdditions.push(`voice note transcript: ${transcript}`);
+                continue;
+            }
+            inputParts.push({
+                type: "file",
+                file: {
+                    file_data: base64,
+                    filename: sanitizeFilename(name),
+                },
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            notices.push(`attachment hydration failed for ${name}: ${reason}`);
+        }
+    }
+    return {
+        inputParts,
+        transcriptAdditions,
+        notices,
+    };
+}

package/dist/senses/bluebubbles/model.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlueBubblesIgnoredEventError = void 0;
+exports.normalizeBlueBubblesEvent = normalizeBlueBubblesEvent;
+const runtime_1 = require("../../nerves/runtime");
+const render_1 = require("../../heart/attachments/render");
+const bluebubbles_1 = require("../../heart/attachments/sources/bluebubbles");
+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
+        : null;
+}
+function readString(record, key) {
+    if (!record)
+        return undefined;
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readNumber(record, key) {
+    if (!record)
+        return undefined;
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function readBoolean(record, key) {
+    const value = record[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+function normalizeHandle(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.includes("@"))
+        return trimmed.toLowerCase();
+    const compact = trimmed.replace(/[^\d+]/g, "");
+    return compact || trimmed;
+}
+function extractChatIdentifierFromGuid(chatGuid) {
+    if (!chatGuid)
+        return undefined;
+    const parts = chatGuid.split(";");
+    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");
+    const chatIdentifier = readString(chat, "chatIdentifier") ??
+        readString(chat, "identifier") ??
+        extractChatIdentifierFromGuid(chatGuid);
+    const displayName = readString(chat, "displayName")?.trim() || undefined;
+    const style = readNumber(chat, "style");
+    const isGroup = style === 43 || (chatGuid?.includes(";+;") ?? false) || Boolean(displayName);
+    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,
+        displayName,
+        isGroup,
+        sessionKey,
+        sendTarget: chatGuid?.trim()
+            ? { kind: "chat_guid", value: chatGuid.trim() }
+            : { kind: "chat_identifier", value: (chatIdentifier ?? "unknown").trim() },
+        participantHandles,
+    };
+}
+function extractSender(data, chat) {
+    const handle = asRecord(data.handle) ?? asRecord(data.sender) ?? null;
+    const rawId = readString(handle, "address") ??
+        readString(handle, "id") ??
+        readString(data, "senderId") ??
+        chat.chatIdentifier ??
+        chat.chatGuid ??
+        "unknown";
+    const externalId = normalizeHandle(rawId);
+    const displayName = externalId || rawId || "Unknown";
+    return {
+        provider: "imessage-handle",
+        externalId,
+        rawId,
+        displayName,
+    };
+}
+function extractAttachments(data) {
+    const raw = Array.isArray(data.attachments) ? data.attachments : [];
+    return raw
+        .map((entry) => asRecord(entry))
+        .filter((entry) => entry !== null)
+        .map((entry) => ({
+        guid: readString(entry, "guid"),
+        mimeType: readString(entry, "mimeType"),
+        transferName: readString(entry, "transferName"),
+        totalBytes: readNumber(entry, "totalBytes"),
+        height: readNumber(entry, "height"),
+        width: readNumber(entry, "width"),
+    }));
+}
+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, bluebubbles_1.buildBlueBubblesAttachmentRecord)(attachment));
+    if (renderable.length > 0) {
+        return (0, render_1.renderAttachmentBlock)(renderable);
+    }
+    const [first] = attachments;
+    return `[attachment: ${first.transferName?.trim() || "unknown"}]`;
+}
+function formatMessageText(data, attachments) {
+    const text = readString(data, "text")?.trim() ?? "";
+    const balloonBundleId = readString(data, "balloonBundleId")?.trim();
+    if (text) {
+        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);
+}
+function normalizeReactionName(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+function stripPartPrefix(guid) {
+    if (!guid)
+        return undefined;
+    const trimmed = guid.trim();
+    const marker = trimmed.lastIndexOf("/");
+    return marker >= 0 ? trimmed.slice(marker + 1) : trimmed;
+}
+function buildMutationText(mutationType, data, reactionName) {
+    if (mutationType === "reaction") {
+        return `reacted with ${reactionName}`;
+    }
+    if (mutationType === "edit") {
+        const editedText = readString(data, "text")?.trim() ?? "";
+        return editedText ? `edited message: ${editedText}` : "edited a message";
+    }
+    if (mutationType === "unsend") {
+        return "unsent a message";
+    }
+    if (mutationType === "read") {
+        return "message marked as read";
+    }
+    return "message marked as delivered";
+}
+function detectMutationType(eventType, data, reactionName) {
+    if (reactionName)
+        return "reaction";
+    if (eventType === "updated-message") {
+        if (readNumber(data, "dateRetracted"))
+            return "unsend";
+        if (readNumber(data, "dateEdited"))
+            return "edit";
+        if (readNumber(data, "dateRead"))
+            return "read";
+        if (readBoolean(data, "isDelivered") || readNumber(data, "dateDelivered"))
+            return "delivery";
+    }
+    return null;
+}
+function normalizeBlueBubblesEvent(payload) {
+    const envelope = asRecord(payload);
+    const eventType = readString(envelope, "type")?.trim() ?? "";
+    const data = asRecord(envelope?.data);
+    if (!eventType || !data) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_event_ignored",
+            message: "ignored invalid bluebubbles payload",
+            meta: { hasEnvelope: Boolean(envelope), eventType },
+        });
+        throw new Error("Invalid BlueBubbles payload");
+    }
+    const messageGuid = readString(data, "guid")?.trim();
+    if (!messageGuid) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_event_ignored",
+            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;
+    const chat = buildChatRef(data, threadOriginatorGuid);
+    const sender = extractSender(data, chat);
+    const timestamp = readNumber(data, "dateCreated") ?? Date.now();
+    const fromMe = readBoolean(data, "isFromMe") ?? false;
+    const attachments = extractAttachments(data);
+    const reactionName = normalizeReactionName(data.associatedMessageType);
+    const mutationType = detectMutationType(eventType, data, reactionName);
+    const requiresRepair = (readBoolean(data, "hasPayloadData") ?? false) ||
+        attachments.length > 0 ||
+        eventType === "updated-message";
+    const result = mutationType
+        ? {
+            kind: "mutation",
+            eventType,
+            mutationType,
+            messageGuid,
+            targetMessageGuid: mutationType === "reaction"
+                ? stripPartPrefix(readString(data, "associatedMessageGuid"))
+                : undefined,
+            timestamp,
+            fromMe,
+            sender,
+            chat,
+            shouldNotifyAgent: mutationType === "reaction" || mutationType === "edit" || mutationType === "unsend",
+            textForAgent: buildMutationText(mutationType, data, reactionName),
+            requiresRepair,
+        }
+        : {
+            kind: "message",
+            eventType,
+            messageGuid,
+            timestamp,
+            fromMe,
+            sender,
+            chat,
+            text: readString(data, "text")?.trim() ?? "",
+            textForAgent: formatMessageText(data, attachments),
+            attachments,
+            balloonBundleId: readString(data, "balloonBundleId")?.trim() || undefined,
+            hasPayloadData: readBoolean(data, "hasPayloadData") ?? false,
+            requiresRepair,
+            threadOriginatorGuid,
+            replyToGuid: threadOriginatorGuid,
+        };
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_event_normalized",
+        message: "normalized bluebubbles event",
+        meta: {
+            eventType,
+            kind: result.kind,
+            mutationType: result.kind === "mutation" ? result.mutationType : null,
+            sessionKey: result.chat.sessionKey,
+            fromMe,
+        },
+    });
+    return result;
+}