@ouro.bot/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/repertoire/tools-teams.js

@@ -82,7 +82,7 @@ exports.teamsToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_query",
-                description: "GET or POST (for WIQL read queries) any Azure DevOps API endpoint. Use ado_docs first to look up the correct path.",
+                description: "GET or POST (for WIQL read queries) any Azure DevOps API endpoint. Use ado_docs first to look up the correct path and host.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -90,6 +90,7 @@ exports.teamsToolDefinitions = [
                         path: { type: "string", description: "ADO API path after /{org}, e.g. /_apis/wit/wiql" },
                         method: { type: "string", enum: ["GET", "POST"], description: "HTTP method (defaults to GET)" },
                         body: { type: "string", description: "JSON request body (optional, used with POST for WIQL)" },
+                        host: { type: "string", description: "API host override for non-standard APIs (e.g. 'vsapm.dev.azure.com' for entitlements, 'vssps.dev.azure.com' for users). Omit for standard dev.azure.com." },
                     },
                     required: ["organization", "path"],
                 },
@@ -100,7 +101,7 @@ exports.teamsToolDefinitions = [
                 return "AUTH_REQUIRED:ado -- I need access to Azure DevOps. Please sign in when prompted.";
             }
             const method = args.method || "GET";
-            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, method, args.organization, args.path, args.body);
+            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, method, args.organization, args.path, args.body, args.host);
             checkAndRecord403(result, "ado", args.organization, method, ctx);
             return result;
         },
@@ -111,7 +112,7 @@ exports.teamsToolDefinitions = [
             type: "function",
             function: {
                 name: "ado_mutate",
-                description: "POST/PATCH/DELETE any Azure DevOps API endpoint for actual mutations. Use ado_docs first to look up the correct path.",
+                description: "POST/PATCH/DELETE any Azure DevOps API endpoint for actual mutations. Use ado_docs first to look up the correct path and host.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -119,6 +120,7 @@ exports.teamsToolDefinitions = [
                         organization: { type: "string", description: "Azure DevOps organization name" },
                         path: { type: "string", description: "ADO API path after /{org}" },
                         body: { type: "string", description: "JSON request body (optional)" },
+                        host: { type: "string", description: "API host override for non-standard APIs (e.g. 'vsapm.dev.azure.com' for entitlements, 'vssps.dev.azure.com' for users). Omit for standard dev.azure.com." },
                     },
                     required: ["method", "organization", "path"],
                 },
@@ -133,7 +135,7 @@ exports.teamsToolDefinitions = [
             }
             /* v8 ignore next -- fallback unreachable: method is validated against MUTATE_METHODS above @preserve */
             const action = METHOD_TO_ACTION[args.method] || args.method;
-            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, args.method, args.organization, args.path, args.body);
+            const result = await (0, ado_client_1.adoRequest)(ctx.adoToken, args.method, args.organization, args.path, args.body, args.host);
             checkAndRecord403(result, "ado", args.organization, action, ctx);
             return result;
         },
@@ -201,6 +203,53 @@ exports.teamsToolDefinitions = [
         },
         integration: "ado",
     },
+    // -- Proactive messaging --
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "teams_send_message",
+                description: "send a proactive 1:1 Teams message to a user. requires their AAD object ID (use graph_query /users to find it). the message appears as coming from the bot.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        user_id: { type: "string", description: "AAD object ID of the user to message" },
+                        user_name: { type: "string", description: "display name of the user (for logging)" },
+                        message: { type: "string", description: "message text to send" },
+                        tenant_id: { type: "string", description: "tenant ID (optional, defaults to current conversation tenant)" },
+                    },
+                    required: ["user_id", "message"],
+                },
+            },
+        },
+        /* v8 ignore start -- proactive messaging requires live Teams SDK conversation client @preserve */
+        handler: async (args, ctx) => {
+            if (!ctx?.botApi) {
+                return "proactive messaging is not available -- no bot API context (this tool only works in the Teams channel)";
+            }
+            try {
+                const tenantId = args.tenant_id || ctx.tenantId;
+                // Cast to the SDK's ConversationClient shape (kept as `unknown` in ToolContext to avoid type coupling)
+                const conversations = ctx.botApi.conversations;
+                const conversation = await conversations.create({
+                    bot: { id: ctx.botApi.id },
+                    members: [{ id: args.user_id, role: "user", name: args.user_name || args.user_id }],
+                    tenantId,
+                    isGroup: false,
+                });
+                await conversations.activities(conversation.id).create({
+                    type: "message",
+                    text: args.message,
+                });
+                return `message sent to ${args.user_name || args.user_id}`;
+            }
+            catch (e) {
+                return `failed to send proactive message: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        },
+        /* v8 ignore stop */
+        confirmationRequired: true,
+    },
     // -- Documentation tools --
     {
         tool: {
@@ -268,6 +317,8 @@ function searchEndpoints(entries, query) {
             `  ${e.description}`,
             `  Params: ${e.params || "none"}`,
         ];
+        if (e.host)
+            lines.push(`  Host: ${e.host}`);
         if (e.scopes)
             lines.push(`  Scopes: ${e.scopes}`);
         return lines.join("\n");
@@ -304,5 +355,7 @@ function summarizeTeamsArgs(name, args) {
         return summarizeKeyValues(["query"]);
     if (name === "ado_docs")
         return summarizeKeyValues(["query"]);
+    if (name === "teams_send_message")
+        return summarizeKeyValues(["user_name", "user_id"]);
     return undefined;
 }

package/dist/repertoire/tools.js

@@ -19,9 +19,29 @@ Object.defineProperty(exports, "teamsTools", { enumerable: true, get: function (
 // All tool definitions in a single registry
 const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
 const REMOTE_BLOCKED_LOCAL_TOOLS = new Set(["shell", "read_file", "write_file", "git_commit", "gh_cli"]);
-function baseToolsForCapabilities(capabilities) {
-    const isRemoteChannel = capabilities?.channel === "teams";
-    if (!isRemoteChannel)
+function isRemoteChannel(capabilities) {
+    return capabilities?.channel === "teams" || capabilities?.channel === "bluebubbles";
+}
+function isSharedRemoteContext(friend) {
+    const externalIds = friend.externalIds ?? [];
+    return externalIds.some((externalId) => externalId.externalId.startsWith("group:") || externalId.provider === "teams-conversation");
+}
+function isTrustedRemoteContext(context) {
+    if (!context?.friend || !isRemoteChannel(context.channel))
+        return false;
+    const trustLevel = context.friend.trustLevel ?? "stranger";
+    return trustLevel !== "stranger" && !isSharedRemoteContext(context.friend);
+}
+function shouldBlockLocalTools(capabilities, context) {
+    if (!isRemoteChannel(capabilities))
+        return false;
+    return !isTrustedRemoteContext(context);
+}
+function blockedLocalToolMessage() {
+    return "I can't do that from here because I'm talking to multiple people in a shared remote channel, and local shell/file/git/gh operations could let conversations interfere with each other. Ask me for a remote-safe alternative (Graph/ADO/web), or run that operation from CLI.";
+}
+function baseToolsForCapabilities(capabilities, context) {
+    if (!shouldBlockLocalTools(capabilities, context))
         return tools_base_1.tools;
     return tools_base_1.tools.filter((tool) => !REMOTE_BLOCKED_LOCAL_TOOLS.has(tool.function.name));
 }
@@ -39,13 +59,15 @@ function applyPreference(tool, pref) {
 // Base tools (no integration) are always included.
 // Teams/integration tools are included only if their integration is in availableIntegrations.
 // When toolPreferences is provided, matching preferences are appended to tool descriptions.
-function getToolsForChannel(capabilities, toolPreferences) {
-    const baseTools = baseToolsForCapabilities(capabilities);
+function getToolsForChannel(capabilities, toolPreferences, context) {
+    const baseTools = baseToolsForCapabilities(capabilities, context);
     if (!capabilities || capabilities.availableIntegrations.length === 0) {
         return baseTools;
     }
     const available = new Set(capabilities.availableIntegrations);
-    const integrationDefs = [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions].filter((d) => d.integration && available.has(d.integration));
+    const channelDefs = [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
+    // Include tools whose integration is available, plus channel tools with no integration gate (e.g. teams_send_message)
+    const integrationDefs = channelDefs.filter((d) => d.integration ? available.has(d.integration) : capabilities.channel === "teams");
     if (!toolPreferences || Object.keys(toolPreferences).length === 0) {
         return [...baseTools, ...integrationDefs.map((d) => d.tool)];
     }
@@ -87,15 +109,14 @@ async function execTool(name, args, ctx) {
         });
         return `unknown: ${name}`;
     }
-    const isRemoteChannel = ctx?.context?.channel?.channel === "teams";
-    if (isRemoteChannel && REMOTE_BLOCKED_LOCAL_TOOLS.has(name)) {
-        const message = "I can't do that from here because I'm talking to multiple people in a shared remote channel, and local shell/file/git/gh operations could let conversations interfere with each other. Ask me for a remote-safe alternative (Graph/ADO/web), or run that operation from CLI.";
+    if (shouldBlockLocalTools(ctx?.context?.channel, ctx?.context) && REMOTE_BLOCKED_LOCAL_TOOLS.has(name)) {
+        const message = blockedLocalToolMessage();
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             event: "tool.error",
             component: "tools",
             message: "blocked local tool in remote channel",
-            meta: { name, channel: "teams" },
+            meta: { name, channel: ctx?.context?.channel?.channel },
         });
         return message;
     }
@@ -163,7 +184,9 @@ function summarizeArgs(name, args) {
     if (name === "load_skill")
         return summarizeKeyValues(args, ["name"]);
     if (name === "task_create")
-        return summarizeKeyValues(args, ["title", "type", "category"]);
+        return summarizeKeyValues(args, ["title", "type", "category", "scheduledAt", "cadence"]);
+    if (name === "schedule_reminder")
+        return summarizeKeyValues(args, ["title", "scheduledAt", "cadence"]);
     if (name === "task_update_status")
         return summarizeKeyValues(args, ["name", "status"]);
     if (name === "task_board_status")
@@ -176,6 +199,8 @@ function summarizeArgs(name, args) {
         return summarizeKeyValues(args, ["runner", "workdir", "taskRef"]);
     if (name === "coding_status")
         return summarizeKeyValues(args, ["sessionId"]);
+    if (name === "coding_tail")
+        return summarizeKeyValues(args, ["sessionId"]);
     if (name === "coding_send_input")
         return summarizeKeyValues(args, ["sessionId", "input"]);
     if (name === "coding_kill")
@@ -195,5 +220,13 @@ function summarizeArgs(name, args) {
     }
     if (name === "ado_backlog_list")
         return summarizeKeyValues(args, ["organization", "project"]);
+    if (name === "ado_batch_update")
+        return summarizeKeyValues(args, ["organization", "project"]);
+    if (name === "ado_create_epic" || name === "ado_create_issue")
+        return summarizeKeyValues(args, ["organization", "project", "title"]);
+    if (name === "ado_move_items")
+        return summarizeKeyValues(args, ["organization", "project", "workItemIds"]);
+    if (name === "ado_restructure_backlog")
+        return summarizeKeyValues(args, ["organization", "project"]);
     return summarizeUnknownArgs(args);
 }

package/dist/senses/bluebubbles-client.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBlueBubblesClient = createBlueBubblesClient;
+const node_crypto_1 = require("node:crypto");
+const config_1 = require("../heart/config");
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const bluebubbles_model_1 = require("./bluebubbles-model");
+const bluebubbles_media_1 = require("./bluebubbles-media");
+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();
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function extractMessageGuid(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const record = payload;
+    const data = record.data && typeof record.data === "object" && !Array.isArray(record.data)
+        ? record.data
+        : null;
+    const candidates = [
+        record.messageGuid,
+        record.messageId,
+        record.guid,
+        data?.messageGuid,
+        data?.messageId,
+        data?.guid,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+async function parseJsonBody(response) {
+    const raw = await response.text();
+    if (!raw.trim())
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function buildRepairUrl(baseUrl, messageGuid, password) {
+    const url = buildBlueBubblesApiUrl(baseUrl, `/api/v1/message/${encodeURIComponent(messageGuid)}`, password);
+    const parsed = new URL(url);
+    parsed.searchParams.set("with", "attachments,payloadData,chats,messageSummaryInfo");
+    return parsed.toString();
+}
+function extractChatIdentifierFromGuid(chatGuid) {
+    const parts = chatGuid.split(";");
+    return parts.length >= 3 ? parts[2]?.trim() || undefined : undefined;
+}
+function extractChatGuid(value) {
+    const record = asRecord(value);
+    const candidates = [
+        record?.chatGuid,
+        record?.guid,
+        record?.chat_guid,
+        record?.identifier,
+        record?.chatIdentifier,
+        record?.chat_identifier,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function extractQueriedChatIdentifier(chat, chatGuid) {
+    const explicitIdentifier = readString(chat, "chatIdentifier")
+        ?? readString(chat, "identifier")
+        ?? readString(chat, "chat_identifier");
+    if (explicitIdentifier) {
+        return explicitIdentifier;
+    }
+    return extractChatIdentifierFromGuid(chatGuid);
+}
+function extractChatQueryRows(payload) {
+    const record = asRecord(payload);
+    const data = Array.isArray(record?.data) ? record.data : payload;
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data.map((entry) => asRecord(entry)).filter((entry) => entry !== null);
+}
+async function resolveChatGuidForIdentifier(config, channelConfig, chatIdentifier) {
+    const trimmedIdentifier = chatIdentifier.trim();
+    if (!trimmedIdentifier)
+        return undefined;
+    const url = buildBlueBubblesApiUrl(config.serverUrl, "/api/v1/chat/query", config.password);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            limit: 500,
+            offset: 0,
+            with: ["participants"],
+        }),
+        signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+    });
+    if (!response.ok) {
+        return undefined;
+    }
+    const payload = await parseJsonBody(response);
+    const rows = extractChatQueryRows(payload);
+    for (const row of rows) {
+        const guid = extractChatGuid(row);
+        if (!guid)
+            continue;
+        const identifier = extractQueriedChatIdentifier(row, guid);
+        if (identifier === trimmedIdentifier || guid === trimmedIdentifier) {
+            return guid;
+        }
+    }
+    return undefined;
+}
+function collectPreviewStrings(value, out, depth = 0) {
+    if (depth > 4 || out.length >= 4)
+        return;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed)
+            out.push(trimmed);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectPreviewStrings(entry, out, depth + 1);
+        return;
+    }
+    const record = asRecord(value);
+    if (!record)
+        return;
+    const preferredKeys = ["title", "summary", "subtitle", "previewText", "siteName", "host", "url"];
+    for (const key of preferredKeys) {
+        if (out.length >= 4)
+            break;
+        collectPreviewStrings(record[key], out, depth + 1);
+    }
+}
+function extractLinkPreviewText(data) {
+    const values = [];
+    collectPreviewStrings(data.payloadData, values);
+    collectPreviewStrings(data.messageSummaryInfo, values);
+    const unique = [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+    if (unique.length === 0)
+        return undefined;
+    return unique.slice(0, 2).join(" — ");
+}
+function applyRepairNotice(event, notice) {
+    return {
+        ...event,
+        requiresRepair: false,
+        repairNotice: notice,
+    };
+}
+function hydrateTextForAgent(event, rawData) {
+    if (event.kind !== "message") {
+        return { ...event, requiresRepair: false };
+    }
+    if (event.balloonBundleId !== "com.apple.messages.URLBalloonProvider") {
+        return { ...event, requiresRepair: false };
+    }
+    const previewText = extractLinkPreviewText(rawData);
+    if (!previewText) {
+        return { ...event, requiresRepair: false };
+    }
+    const base = event.text.trim();
+    const textForAgent = base
+        ? `${base}\n[link preview: ${previewText}]`
+        : `[link preview: ${previewText}]`;
+    return {
+        ...event,
+        textForAgent,
+        requiresRepair: false,
+    };
+}
+function extractRepairData(payload) {
+    const record = asRecord(payload);
+    return asRecord(record?.data) ?? record;
+}
+function providerSupportsAudioInput(provider) {
+    return provider === "azure" || provider === "openai-codex";
+}
+async function resolveChatGuid(chat, config, channelConfig) {
+    return chat.chatGuid
+        ?? await resolveChatGuidForIdentifier(config, channelConfig, chat.chatIdentifier ?? "");
+}
+function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(), channelConfig = (0, config_1.getBlueBubblesChannelConfig)()) {
+    return {
+        async sendText(params) {
+            const trimmedText = params.text.trim();
+            if (!trimmedText) {
+                throw new Error("BlueBubbles send requires non-empty text.");
+            }
+            const resolvedChatGuid = await resolveChatGuid(params.chat, config, channelConfig);
+            if (!resolvedChatGuid) {
+                throw new Error("BlueBubbles send currently requires chat.chatGuid from the inbound event.");
+            }
+            const url = buildBlueBubblesApiUrl(config.serverUrl, "/api/v1/message/text", config.password);
+            const body = {
+                chatGuid: resolvedChatGuid,
+                tempGuid: (0, node_crypto_1.randomUUID)(),
+                message: trimmedText,
+            };
+            if (params.replyToMessageGuid?.trim()) {
+                body.method = "private-api";
+                body.selectedMessageGuid = params.replyToMessageGuid.trim();
+                body.partIndex = 0;
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_send_start",
+                message: "sending bluebubbles message",
+                meta: {
+                    chatGuid: resolvedChatGuid,
+                    hasReplyTarget: Boolean(params.replyToMessageGuid?.trim()),
+                },
+            });
+            const response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.bluebubbles_send_error",
+                    message: "bluebubbles send failed",
+                    meta: {
+                        status: response.status,
+                        reason: errorText || "unknown",
+                    },
+                });
+                throw new Error(`BlueBubbles send failed (${response.status}): ${errorText || "unknown"}`);
+            }
+            const payload = await parseJsonBody(response);
+            const messageGuid = extractMessageGuid(payload);
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_send_end",
+                message: "bluebubbles message sent",
+                meta: {
+                    chatGuid: resolvedChatGuid,
+                    messageGuid: messageGuid ?? null,
+                },
+            });
+            return { messageGuid };
+        },
+        async editMessage(params) {
+            const messageGuid = params.messageGuid.trim();
+            const text = params.text.trim();
+            if (!messageGuid) {
+                throw new Error("BlueBubbles edit requires messageGuid.");
+            }
+            if (!text) {
+                throw new Error("BlueBubbles edit requires non-empty text.");
+            }
+            const editTimeoutMs = Math.max(channelConfig.requestTimeoutMs, 120000);
+            const url = buildBlueBubblesApiUrl(config.serverUrl, `/api/v1/message/${encodeURIComponent(messageGuid)}/edit`, config.password);
+            const response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    editedMessage: text,
+                    backwardsCompatibilityMessage: params.backwardsCompatibilityMessage ?? `Edited to: ${text}`,
+                    partIndex: typeof params.partIndex === "number" ? params.partIndex : 0,
+                }),
+                signal: AbortSignal.timeout(editTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`BlueBubbles edit failed (${response.status}): ${errorText || "unknown"}`);
+            }
+        },
+        async setTyping(chat, typing) {
+            const resolvedChatGuid = await resolveChatGuid(chat, config, channelConfig);
+            if (!resolvedChatGuid) {
+                return;
+            }
+            const url = buildBlueBubblesApiUrl(config.serverUrl, `/api/v1/chat/${encodeURIComponent(resolvedChatGuid)}/typing`, config.password);
+            const response = await fetch(url, {
+                method: typing ? "POST" : "DELETE",
+                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`BlueBubbles typing failed (${response.status}): ${errorText || "unknown"}`);
+            }
+        },
+        async markChatRead(chat) {
+            const resolvedChatGuid = await resolveChatGuid(chat, config, channelConfig);
+            if (!resolvedChatGuid) {
+                return;
+            }
+            const url = buildBlueBubblesApiUrl(config.serverUrl, `/api/v1/chat/${encodeURIComponent(resolvedChatGuid)}/read`, config.password);
+            const response = await fetch(url, {
+                method: "POST",
+                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`BlueBubbles read failed (${response.status}): ${errorText || "unknown"}`);
+            }
+        },
+        async repairEvent(event) {
+            if (!event.requiresRepair) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_repair_skipped",
+                    message: "bluebubbles event repair skipped",
+                    meta: {
+                        kind: event.kind,
+                        messageGuid: event.messageGuid,
+                    },
+                });
+                return event;
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_repair_start",
+                message: "repairing bluebubbles event by guid",
+                meta: {
+                    kind: event.kind,
+                    messageGuid: event.messageGuid,
+                    eventType: event.eventType,
+                },
+            });
+            const url = buildRepairUrl(config.serverUrl, event.messageGuid, config.password);
+            try {
+                const response = await fetch(url, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+                });
+                if (!response.ok) {
+                    const errorText = await response.text().catch(() => "");
+                    const repaired = applyRepairNotice(event, `BlueBubbles repair failed: ${errorText || `HTTP ${response.status}`}`);
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_repair_error",
+                        message: "bluebubbles repair request failed",
+                        meta: {
+                            messageGuid: event.messageGuid,
+                            status: response.status,
+                            reason: errorText || "unknown",
+                        },
+                    });
+                    return repaired;
+                }
+                const payload = await parseJsonBody(response);
+                const data = extractRepairData(payload);
+                if (!data || typeof data.guid !== "string") {
+                    const repaired = applyRepairNotice(event, "BlueBubbles repair failed: invalid message payload");
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_repair_error",
+                        message: "bluebubbles repair returned unusable payload",
+                        meta: {
+                            messageGuid: event.messageGuid,
+                        },
+                    });
+                    return repaired;
+                }
+                const normalized = (0, bluebubbles_model_1.normalizeBlueBubblesEvent)({
+                    type: event.eventType,
+                    data,
+                });
+                let hydrated = 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),
+                    });
+                    const transcriptSuffix = media.transcriptAdditions.map((entry) => `[${entry}]`).join("\n");
+                    const noticeSuffix = media.notices.map((entry) => `[${entry}]`).join("\n");
+                    const combinedSuffix = [transcriptSuffix, noticeSuffix].filter(Boolean).join("\n");
+                    hydrated = {
+                        ...hydrated,
+                        inputPartsForAgent: media.inputParts.length > 0 ? media.inputParts : undefined,
+                        textForAgent: [hydrated.textForAgent, combinedSuffix].filter(Boolean).join("\n"),
+                    };
+                }
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_repair_end",
+                    message: "bluebubbles event repaired",
+                    meta: {
+                        kind: hydrated.kind,
+                        messageGuid: hydrated.messageGuid,
+                        repairedFrom: event.kind,
+                    },
+                });
+                return hydrated;
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_repair_error",
+                    message: "bluebubbles repair threw",
+                    meta: {
+                        messageGuid: event.messageGuid,
+                        reason,
+                    },
+                });
+                return applyRepairNotice(event, `BlueBubbles repair failed: ${reason}`);
+            }
+        },
+    };
+}

package/dist/senses/bluebubbles-entry.js

@@ -0,0 +1,11 @@
+"use strict";
+// Thin entrypoint for `npm run bluebubbles` / `node dist/senses/bluebubbles-entry.js --agent <name>`.
+// Separated from bluebubbles.ts so the BlueBubbles adapter stays testable.
+Object.defineProperty(exports, "__esModule", { value: true });
+if (!process.argv.includes("--agent")) {
+    // eslint-disable-next-line no-console -- pre-boot guard: --agent check before imports
+    console.error("Missing required --agent <name> argument.\nUsage: node dist/senses/bluebubbles-entry.js --agent ouroboros");
+    process.exit(1);
+}
+const bluebubbles_1 = require("./bluebubbles");
+(0, bluebubbles_1.startBlueBubblesApp)();