Add ez-assistant and kerberos service folders

docker-compose/ez-assistant/extensions/bluebubbles/clawdbot.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "bluebubbles",
+  "channels": [
+    "bluebubbles"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/index.ts

@@ -0,0 +1,20 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { bluebubblesPlugin } from "./src/channel.js";
+import { handleBlueBubblesWebhookRequest } from "./src/monitor.js";
+import { setBlueBubblesRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "bluebubbles",
+  name: "BlueBubbles",
+  description: "BlueBubbles channel plugin (macOS app)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: MoltbotPluginApi) {
+    setBlueBubblesRuntime(api.runtime);
+    api.registerChannel({ plugin: bluebubblesPlugin });
+    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
+  },
+};
+
+export default plugin;

docker-compose/ez-assistant/extensions/bluebubbles/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@moltbot/bluebubbles",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot BlueBubbles channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "bluebubbles",
+      "label": "BlueBubbles",
+      "selectionLabel": "BlueBubbles (macOS app)",
+      "detailLabel": "BlueBubbles",
+      "docsPath": "/channels/bluebubbles",
+      "docsLabel": "bluebubbles",
+      "blurb": "iMessage via the BlueBubbles mac app + REST API.",
+      "aliases": [
+        "bb"
+      ],
+      "preferOver": [
+        "imessage"
+      ],
+      "systemImage": "bubble.left.and.text.bubble.right",
+      "order": 75
+    },
+    "install": {
+      "npmSpec": "@moltbot/bluebubbles",
+      "localPath": "extensions/bluebubbles",
+      "defaultChoice": "npm"
+    }
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/accounts.ts

@@ -0,0 +1,80 @@
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
+
+export type ResolvedBlueBubblesAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  config: BlueBubblesAccountConfig;
+  configured: boolean;
+  baseUrl?: string;
+};
+
+function listConfiguredAccountIds(cfg: MoltbotConfig): string[] {
+  const accounts = cfg.channels?.bluebubbles?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listBlueBubblesAccountIds(cfg: MoltbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultBlueBubblesAccountId(cfg: MoltbotConfig): string {
+  const ids = listBlueBubblesAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: MoltbotConfig,
+  accountId: string,
+): BlueBubblesAccountConfig | undefined {
+  const accounts = cfg.channels?.bluebubbles?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as BlueBubblesAccountConfig | undefined;
+}
+
+function mergeBlueBubblesAccountConfig(
+  cfg: MoltbotConfig,
+  accountId: string,
+): BlueBubblesAccountConfig {
+  const base = (cfg.channels?.bluebubbles ?? {}) as BlueBubblesAccountConfig & {
+    accounts?: unknown;
+  };
+  const { accounts: _ignored, ...rest } = base;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  const chunkMode = account.chunkMode ?? rest.chunkMode ?? "length";
+  return { ...rest, ...account, chunkMode };
+}
+
+export function resolveBlueBubblesAccount(params: {
+  cfg: MoltbotConfig;
+  accountId?: string | null;
+}): ResolvedBlueBubblesAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = params.cfg.channels?.bluebubbles?.enabled;
+  const merged = mergeBlueBubblesAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const serverUrl = merged.serverUrl?.trim();
+  const password = merged.password?.trim();
+  const configured = Boolean(serverUrl && password);
+  const baseUrl = serverUrl ? normalizeBlueBubblesServerUrl(serverUrl) : undefined;
+  return {
+    accountId,
+    enabled: baseEnabled !== false && accountEnabled,
+    name: merged.name?.trim() || undefined,
+    config: merged,
+    configured,
+    baseUrl,
+  };
+}
+
+export function listEnabledBlueBubblesAccounts(cfg: MoltbotConfig): ResolvedBlueBubblesAccount[] {
+  return listBlueBubblesAccountIds(cfg)
+    .map((accountId) => resolveBlueBubblesAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/actions.test.ts

@@ -0,0 +1,651 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+import { bluebubblesMessageActions } from "./actions.js";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+
+vi.mock("./accounts.js", () => ({
+  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
+    const config = cfg?.channels?.bluebubbles ?? {};
+    return {
+      accountId: accountId ?? "default",
+      enabled: config.enabled !== false,
+      configured: Boolean(config.serverUrl && config.password),
+      config,
+    };
+  }),
+}));
+
+vi.mock("./reactions.js", () => ({
+  sendBlueBubblesReaction: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("./send.js", () => ({
+  resolveChatGuidForTarget: vi.fn().mockResolvedValue("iMessage;-;+15551234567"),
+  sendMessageBlueBubbles: vi.fn().mockResolvedValue({ messageId: "msg-123" }),
+}));
+
+vi.mock("./chat.js", () => ({
+  editBlueBubblesMessage: vi.fn().mockResolvedValue(undefined),
+  unsendBlueBubblesMessage: vi.fn().mockResolvedValue(undefined),
+  renameBlueBubblesChat: vi.fn().mockResolvedValue(undefined),
+  setGroupIconBlueBubbles: vi.fn().mockResolvedValue(undefined),
+  addBlueBubblesParticipant: vi.fn().mockResolvedValue(undefined),
+  removeBlueBubblesParticipant: vi.fn().mockResolvedValue(undefined),
+  leaveBlueBubblesChat: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("./attachments.js", () => ({
+  sendBlueBubblesAttachment: vi.fn().mockResolvedValue({ messageId: "att-msg-123" }),
+}));
+
+vi.mock("./monitor.js", () => ({
+  resolveBlueBubblesMessageId: vi.fn((id: string) => id),
+}));
+
+describe("bluebubblesMessageActions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("listActions", () => {
+    it("returns empty array when account is not enabled", () => {
+      const cfg: MoltbotConfig = {
+        channels: { bluebubbles: { enabled: false } },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).toEqual([]);
+    });
+
+    it("returns empty array when account is not configured", () => {
+      const cfg: MoltbotConfig = {
+        channels: { bluebubbles: { enabled: true } },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).toEqual([]);
+    });
+
+    it("returns react action when enabled and configured", () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            enabled: true,
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).toContain("react");
+    });
+
+    it("excludes react action when reactions are gated off", () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            enabled: true,
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+            actions: { reactions: false },
+          },
+        },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).not.toContain("react");
+      // Other actions should still be present
+      expect(actions).toContain("edit");
+      expect(actions).toContain("unsend");
+    });
+  });
+
+  describe("supportsAction", () => {
+    it("returns true for react action", () => {
+      expect(bluebubblesMessageActions.supportsAction({ action: "react" })).toBe(true);
+    });
+
+    it("returns true for all supported actions", () => {
+      expect(bluebubblesMessageActions.supportsAction({ action: "edit" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "unsend" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "reply" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "sendWithEffect" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "renameGroup" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "setGroupIcon" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "addParticipant" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "removeParticipant" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "leaveGroup" })).toBe(true);
+      expect(bluebubblesMessageActions.supportsAction({ action: "sendAttachment" })).toBe(true);
+    });
+
+    it("returns false for unsupported actions", () => {
+      expect(bluebubblesMessageActions.supportsAction({ action: "delete" })).toBe(false);
+      expect(bluebubblesMessageActions.supportsAction({ action: "unknown" })).toBe(false);
+    });
+  });
+
+  describe("extractToolSend", () => {
+    it("extracts send params from sendMessage action", () => {
+      const result = bluebubblesMessageActions.extractToolSend({
+        args: {
+          action: "sendMessage",
+          to: "+15551234567",
+          accountId: "test-account",
+        },
+      });
+      expect(result).toEqual({
+        to: "+15551234567",
+        accountId: "test-account",
+      });
+    });
+
+    it("returns null for non-sendMessage action", () => {
+      const result = bluebubblesMessageActions.extractToolSend({
+        args: { action: "react", to: "+15551234567" },
+      });
+      expect(result).toBeNull();
+    });
+
+    it("returns null when to is missing", () => {
+      const result = bluebubblesMessageActions.extractToolSend({
+        args: { action: "sendMessage" },
+      });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("handleAction", () => {
+    it("throws for unsupported actions", async () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "unknownAction",
+          params: {},
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow("is not supported");
+    });
+
+    it("throws when emoji is missing for react action", async () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "react",
+          params: { messageId: "msg-123" },
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow(/emoji/i);
+    });
+
+    it("throws when messageId is missing", async () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "react",
+          params: { emoji: "❤️" },
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow("messageId");
+    });
+
+    it("throws when chatGuid cannot be resolved", async () => {
+      const { resolveChatGuidForTarget } = await import("./send.js");
+      vi.mocked(resolveChatGuidForTarget).mockResolvedValueOnce(null);
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "react",
+          params: { emoji: "❤️", messageId: "msg-123", to: "+15551234567" },
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow("chatGuid not found");
+    });
+
+    it("sends reaction successfully with chatGuid", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      const result = await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "❤️",
+          messageId: "msg-123",
+          chatGuid: "iMessage;-;+15551234567",
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chatGuid: "iMessage;-;+15551234567",
+          messageGuid: "msg-123",
+          emoji: "❤️",
+        }),
+      );
+      // jsonResult returns { content: [...], details: payload }
+      expect(result).toMatchObject({
+        details: { ok: true, added: "❤️" },
+      });
+    });
+
+    it("sends reaction removal successfully", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      const result = await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "❤️",
+          messageId: "msg-123",
+          chatGuid: "iMessage;-;+15551234567",
+          remove: true,
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          remove: true,
+        }),
+      );
+      // jsonResult returns { content: [...], details: payload }
+      expect(result).toMatchObject({
+        details: { ok: true, removed: true },
+      });
+    });
+
+    it("resolves chatGuid from to parameter", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+      const { resolveChatGuidForTarget } = await import("./send.js");
+      vi.mocked(resolveChatGuidForTarget).mockResolvedValueOnce("iMessage;-;+15559876543");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "👍",
+          messageId: "msg-456",
+          to: "+15559876543",
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(resolveChatGuidForTarget).toHaveBeenCalled();
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chatGuid: "iMessage;-;+15559876543",
+        }),
+      );
+    });
+
+    it("passes partIndex when provided", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "😂",
+          messageId: "msg-789",
+          chatGuid: "iMessage;-;chat-guid",
+          partIndex: 2,
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          partIndex: 2,
+        }),
+      );
+    });
+
+    it("uses toolContext currentChannelId when no explicit target is provided", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+      const { resolveChatGuidForTarget } = await import("./send.js");
+      vi.mocked(resolveChatGuidForTarget).mockResolvedValueOnce("iMessage;-;+15550001111");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+      await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "👍",
+          messageId: "msg-456",
+        },
+        cfg,
+        accountId: null,
+        toolContext: {
+          currentChannelId: "bluebubbles:chat_guid:iMessage;-;+15550001111",
+        },
+      });
+
+      expect(resolveChatGuidForTarget).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: { kind: "chat_guid", chatGuid: "iMessage;-;+15550001111" },
+        }),
+      );
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chatGuid: "iMessage;-;+15550001111",
+        }),
+      );
+    });
+
+    it("resolves short messageId before reacting", async () => {
+      const { resolveBlueBubblesMessageId } = await import("./monitor.js");
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+      vi.mocked(resolveBlueBubblesMessageId).mockReturnValueOnce("resolved-uuid");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      await bluebubblesMessageActions.handleAction({
+        action: "react",
+        params: {
+          emoji: "❤️",
+          messageId: "1",
+          chatGuid: "iMessage;-;+15551234567",
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(resolveBlueBubblesMessageId).toHaveBeenCalledWith("1", { requireKnownShortId: true });
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          messageGuid: "resolved-uuid",
+        }),
+      );
+    });
+
+    it("propagates short-id errors from the resolver", async () => {
+      const { resolveBlueBubblesMessageId } = await import("./monitor.js");
+      vi.mocked(resolveBlueBubblesMessageId).mockImplementationOnce(() => {
+        throw new Error("short id expired");
+      });
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "react",
+          params: {
+            emoji: "❤️",
+            messageId: "999",
+            chatGuid: "iMessage;-;+15551234567",
+          },
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow("short id expired");
+    });
+
+    it("accepts message param for edit action", async () => {
+      const { editBlueBubblesMessage } = await import("./chat.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      await bluebubblesMessageActions.handleAction({
+        action: "edit",
+        params: { messageId: "msg-123", message: "updated" },
+        cfg,
+        accountId: null,
+      });
+
+      expect(editBlueBubblesMessage).toHaveBeenCalledWith(
+        "msg-123",
+        "updated",
+        expect.objectContaining({ cfg, accountId: undefined }),
+      );
+    });
+
+    it("accepts message/target aliases for sendWithEffect", async () => {
+      const { sendMessageBlueBubbles } = await import("./send.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      const result = await bluebubblesMessageActions.handleAction({
+        action: "sendWithEffect",
+        params: {
+          message: "peekaboo",
+          target: "+15551234567",
+          effect: "invisible ink",
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendMessageBlueBubbles).toHaveBeenCalledWith(
+        "+15551234567",
+        "peekaboo",
+        expect.objectContaining({ effectId: "invisible ink" }),
+      );
+      expect(result).toMatchObject({
+        details: { ok: true, messageId: "msg-123", effect: "invisible ink" },
+      });
+    });
+
+    it("passes asVoice through sendAttachment", async () => {
+      const { sendBlueBubblesAttachment } = await import("./attachments.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      const base64Buffer = Buffer.from("voice").toString("base64");
+
+      await bluebubblesMessageActions.handleAction({
+        action: "sendAttachment",
+        params: {
+          to: "+15551234567",
+          filename: "voice.mp3",
+          buffer: base64Buffer,
+          contentType: "audio/mpeg",
+          asVoice: true,
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(sendBlueBubblesAttachment).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filename: "voice.mp3",
+          contentType: "audio/mpeg",
+          asVoice: true,
+        }),
+      );
+    });
+
+    it("throws when buffer is missing for setGroupIcon", async () => {
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      await expect(
+        bluebubblesMessageActions.handleAction({
+          action: "setGroupIcon",
+          params: { chatGuid: "iMessage;-;chat-guid" },
+          cfg,
+          accountId: null,
+        }),
+      ).rejects.toThrow(/requires an image/i);
+    });
+
+    it("sets group icon successfully with chatGuid and buffer", async () => {
+      const { setGroupIconBlueBubbles } = await import("./chat.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      // Base64 encode a simple test buffer
+      const testBuffer = Buffer.from("fake-image-data");
+      const base64Buffer = testBuffer.toString("base64");
+
+      const result = await bluebubblesMessageActions.handleAction({
+        action: "setGroupIcon",
+        params: {
+          chatGuid: "iMessage;-;chat-guid",
+          buffer: base64Buffer,
+          filename: "group-icon.png",
+          contentType: "image/png",
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(setGroupIconBlueBubbles).toHaveBeenCalledWith(
+        "iMessage;-;chat-guid",
+        expect.any(Uint8Array),
+        "group-icon.png",
+        expect.objectContaining({ contentType: "image/png" }),
+      );
+      expect(result).toMatchObject({
+        details: { ok: true, chatGuid: "iMessage;-;chat-guid", iconSet: true },
+      });
+    });
+
+    it("uses default filename when not provided for setGroupIcon", async () => {
+      const { setGroupIconBlueBubbles } = await import("./chat.js");
+
+      const cfg: MoltbotConfig = {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://localhost:1234",
+            password: "test-password",
+          },
+        },
+      };
+
+      const base64Buffer = Buffer.from("test").toString("base64");
+
+      await bluebubblesMessageActions.handleAction({
+        action: "setGroupIcon",
+        params: {
+          chatGuid: "iMessage;-;chat-guid",
+          buffer: base64Buffer,
+        },
+        cfg,
+        accountId: null,
+      });
+
+      expect(setGroupIconBlueBubbles).toHaveBeenCalledWith(
+        "iMessage;-;chat-guid",
+        expect.any(Uint8Array),
+        "icon.png",
+        expect.anything(),
+      );
+    });
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/actions.ts

@@ -0,0 +1,403 @@
+import {
+  BLUEBUBBLES_ACTION_NAMES,
+  BLUEBUBBLES_ACTIONS,
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelToolSend,
+  type MoltbotConfig,
+} from "clawdbot/plugin-sdk";
+
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { isMacOS26OrHigher } from "./probe.js";
+import { sendBlueBubblesReaction } from "./reactions.js";
+import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
+import {
+  editBlueBubblesMessage,
+  unsendBlueBubblesMessage,
+  renameBlueBubblesChat,
+  setGroupIconBlueBubbles,
+  addBlueBubblesParticipant,
+  removeBlueBubblesParticipant,
+  leaveBlueBubblesChat,
+} from "./chat.js";
+import { sendBlueBubblesAttachment } from "./attachments.js";
+import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
+import type { BlueBubblesSendTarget } from "./types.js";
+
+const providerId = "bluebubbles";
+
+function mapTarget(raw: string): BlueBubblesSendTarget {
+  const parsed = parseBlueBubblesTarget(raw);
+  if (parsed.kind === "chat_guid") return { kind: "chat_guid", chatGuid: parsed.chatGuid };
+  if (parsed.kind === "chat_id") return { kind: "chat_id", chatId: parsed.chatId };
+  if (parsed.kind === "chat_identifier") {
+    return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
+  }
+  return {
+    kind: "handle",
+    address: normalizeBlueBubblesHandle(parsed.to),
+    service: parsed.service,
+  };
+}
+
+function readMessageText(params: Record<string, unknown>): string | undefined {
+  return readStringParam(params, "text") ?? readStringParam(params, "message");
+}
+
+function readBooleanParam(params: Record<string, unknown>, key: string): boolean | undefined {
+  const raw = params[key];
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed === "true") return true;
+    if (trimmed === "false") return false;
+  }
+  return undefined;
+}
+
+/** Supported action names for BlueBubbles */
+const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);
+
+export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const account = resolveBlueBubblesAccount({ cfg: cfg as MoltbotConfig });
+    if (!account.enabled || !account.configured) return [];
+    const gate = createActionGate((cfg as MoltbotConfig).channels?.bluebubbles?.actions);
+    const actions = new Set<ChannelMessageActionName>();
+    const macOS26 = isMacOS26OrHigher(account.accountId);
+    for (const action of BLUEBUBBLES_ACTION_NAMES) {
+      const spec = BLUEBUBBLES_ACTIONS[action];
+      if (!spec?.gate) continue;
+      if (spec.unsupportedOnMacOS26 && macOS26) continue;
+      if (gate(spec.gate)) actions.add(action);
+    }
+    return Array.from(actions);
+  },
+  supportsAction: ({ action }) => SUPPORTED_ACTIONS.has(action),
+  extractToolSend: ({ args }): ChannelToolSend | null => {
+    const action = typeof args.action === "string" ? args.action.trim() : "";
+    if (action !== "sendMessage") return null;
+    const to = typeof args.to === "string" ? args.to : undefined;
+    if (!to) return null;
+    const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
+    return { to, accountId };
+  },
+  handleAction: async ({ action, params, cfg, accountId, toolContext }) => {
+    const account = resolveBlueBubblesAccount({
+      cfg: cfg as MoltbotConfig,
+      accountId: accountId ?? undefined,
+    });
+    const baseUrl = account.config.serverUrl?.trim();
+    const password = account.config.password?.trim();
+    const opts = { cfg: cfg as MoltbotConfig, accountId: accountId ?? undefined };
+
+    // Helper to resolve chatGuid from various params or session context
+    const resolveChatGuid = async (): Promise<string> => {
+      const chatGuid = readStringParam(params, "chatGuid");
+      if (chatGuid?.trim()) return chatGuid.trim();
+
+      const chatIdentifier = readStringParam(params, "chatIdentifier");
+      const chatId = readNumberParam(params, "chatId", { integer: true });
+      const to = readStringParam(params, "to");
+      // Fall back to session context if no explicit target provided
+      const contextTarget = toolContext?.currentChannelId?.trim();
+
+      const target = chatIdentifier?.trim()
+        ? ({
+            kind: "chat_identifier",
+            chatIdentifier: chatIdentifier.trim(),
+          } as BlueBubblesSendTarget)
+        : typeof chatId === "number"
+          ? ({ kind: "chat_id", chatId } as BlueBubblesSendTarget)
+          : to
+            ? mapTarget(to)
+            : contextTarget
+              ? mapTarget(contextTarget)
+              : null;
+
+      if (!target) {
+        throw new Error(`BlueBubbles ${action} requires chatGuid, chatIdentifier, chatId, or to.`);
+      }
+      if (!baseUrl || !password) {
+        throw new Error(`BlueBubbles ${action} requires serverUrl and password.`);
+      }
+
+      const resolved = await resolveChatGuidForTarget({ baseUrl, password, target });
+      if (!resolved) {
+        throw new Error(`BlueBubbles ${action} failed: chatGuid not found for target.`);
+      }
+      return resolved;
+    };
+
+    // Handle react action
+    if (action === "react") {
+      const { emoji, remove, isEmpty } = readReactionParams(params, {
+        removeErrorMessage: "Emoji is required to remove a BlueBubbles reaction.",
+      });
+      if (isEmpty && !remove) {
+        throw new Error(
+          "BlueBubbles react requires emoji parameter. Use action=react with emoji=<emoji> and messageId=<message_id>.",
+        );
+      }
+      const rawMessageId = readStringParam(params, "messageId");
+      if (!rawMessageId) {
+        throw new Error(
+          "BlueBubbles react requires messageId parameter (the message ID to react to). " +
+            "Use action=react with messageId=<message_id>, emoji=<emoji>, and to/chatGuid to identify the chat.",
+        );
+      }
+      // Resolve short ID (e.g., "1", "2") to full UUID
+      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const partIndex = readNumberParam(params, "partIndex", { integer: true });
+      const resolvedChatGuid = await resolveChatGuid();
+
+      await sendBlueBubblesReaction({
+        chatGuid: resolvedChatGuid,
+        messageGuid: messageId,
+        emoji,
+        remove: remove || undefined,
+        partIndex: typeof partIndex === "number" ? partIndex : undefined,
+        opts,
+      });
+
+      return jsonResult({ ok: true, ...(remove ? { removed: true } : { added: emoji }) });
+    }
+
+    // Handle edit action
+    if (action === "edit") {
+      // Edit is not supported on macOS 26+
+      if (isMacOS26OrHigher(accountId ?? undefined)) {
+        throw new Error(
+          "BlueBubbles edit is not supported on macOS 26 or higher. " +
+            "Apple removed the ability to edit iMessages in this version.",
+        );
+      }
+      const rawMessageId = readStringParam(params, "messageId");
+      const newText =
+        readStringParam(params, "text") ??
+        readStringParam(params, "newText") ??
+        readStringParam(params, "message");
+      if (!rawMessageId || !newText) {
+        const missing: string[] = [];
+        if (!rawMessageId) missing.push("messageId (the message ID to edit)");
+        if (!newText) missing.push("text (the new message content)");
+        throw new Error(
+          `BlueBubbles edit requires: ${missing.join(", ")}. ` +
+            `Use action=edit with messageId=<message_id>, text=<new_content>.`,
+        );
+      }
+      // Resolve short ID (e.g., "1", "2") to full UUID
+      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const partIndex = readNumberParam(params, "partIndex", { integer: true });
+      const backwardsCompatMessage = readStringParam(params, "backwardsCompatMessage");
+
+      await editBlueBubblesMessage(messageId, newText, {
+        ...opts,
+        partIndex: typeof partIndex === "number" ? partIndex : undefined,
+        backwardsCompatMessage: backwardsCompatMessage ?? undefined,
+      });
+
+      return jsonResult({ ok: true, edited: rawMessageId });
+    }
+
+    // Handle unsend action
+    if (action === "unsend") {
+      const rawMessageId = readStringParam(params, "messageId");
+      if (!rawMessageId) {
+        throw new Error(
+          "BlueBubbles unsend requires messageId parameter (the message ID to unsend). " +
+            "Use action=unsend with messageId=<message_id>.",
+        );
+      }
+      // Resolve short ID (e.g., "1", "2") to full UUID
+      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const partIndex = readNumberParam(params, "partIndex", { integer: true });
+
+      await unsendBlueBubblesMessage(messageId, {
+        ...opts,
+        partIndex: typeof partIndex === "number" ? partIndex : undefined,
+      });
+
+      return jsonResult({ ok: true, unsent: rawMessageId });
+    }
+
+    // Handle reply action
+    if (action === "reply") {
+      const rawMessageId = readStringParam(params, "messageId");
+      const text = readMessageText(params);
+      const to = readStringParam(params, "to") ?? readStringParam(params, "target");
+      if (!rawMessageId || !text || !to) {
+        const missing: string[] = [];
+        if (!rawMessageId) missing.push("messageId (the message ID to reply to)");
+        if (!text) missing.push("text or message (the reply message content)");
+        if (!to) missing.push("to or target (the chat target)");
+        throw new Error(
+          `BlueBubbles reply requires: ${missing.join(", ")}. ` +
+            `Use action=reply with messageId=<message_id>, message=<your reply>, target=<chat_target>.`,
+        );
+      }
+      // Resolve short ID (e.g., "1", "2") to full UUID
+      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const partIndex = readNumberParam(params, "partIndex", { integer: true });
+
+      const result = await sendMessageBlueBubbles(to, text, {
+        ...opts,
+        replyToMessageGuid: messageId,
+        replyToPartIndex: typeof partIndex === "number" ? partIndex : undefined,
+      });
+
+      return jsonResult({ ok: true, messageId: result.messageId, repliedTo: rawMessageId });
+    }
+
+    // Handle sendWithEffect action
+    if (action === "sendWithEffect") {
+      const text = readMessageText(params);
+      const to = readStringParam(params, "to") ?? readStringParam(params, "target");
+      const effectId = readStringParam(params, "effectId") ?? readStringParam(params, "effect");
+      if (!text || !to || !effectId) {
+        const missing: string[] = [];
+        if (!text) missing.push("text or message (the message content)");
+        if (!to) missing.push("to or target (the chat target)");
+        if (!effectId)
+          missing.push(
+            "effectId or effect (e.g., slam, loud, gentle, invisible-ink, confetti, lasers, fireworks, balloons, heart)",
+          );
+        throw new Error(
+          `BlueBubbles sendWithEffect requires: ${missing.join(", ")}. ` +
+            `Use action=sendWithEffect with message=<message>, target=<chat_target>, effectId=<effect_name>.`,
+        );
+      }
+
+      const result = await sendMessageBlueBubbles(to, text, {
+        ...opts,
+        effectId,
+      });
+
+      return jsonResult({ ok: true, messageId: result.messageId, effect: effectId });
+    }
+
+    // Handle renameGroup action
+    if (action === "renameGroup") {
+      const resolvedChatGuid = await resolveChatGuid();
+      const displayName = readStringParam(params, "displayName") ?? readStringParam(params, "name");
+      if (!displayName) {
+        throw new Error("BlueBubbles renameGroup requires displayName or name parameter.");
+      }
+
+      await renameBlueBubblesChat(resolvedChatGuid, displayName, opts);
+
+      return jsonResult({ ok: true, renamed: resolvedChatGuid, displayName });
+    }
+
+    // Handle setGroupIcon action
+    if (action === "setGroupIcon") {
+      const resolvedChatGuid = await resolveChatGuid();
+      const base64Buffer = readStringParam(params, "buffer");
+      const filename =
+        readStringParam(params, "filename") ??
+        readStringParam(params, "name") ??
+        "icon.png";
+      const contentType =
+        readStringParam(params, "contentType") ?? readStringParam(params, "mimeType");
+
+      if (!base64Buffer) {
+        throw new Error(
+          "BlueBubbles setGroupIcon requires an image. " +
+            "Use action=setGroupIcon with media=<image_url> or path=<local_file_path> to set the group icon.",
+        );
+      }
+
+      // Decode base64 to buffer
+      const buffer = Uint8Array.from(atob(base64Buffer), (c) => c.charCodeAt(0));
+
+      await setGroupIconBlueBubbles(resolvedChatGuid, buffer, filename, {
+        ...opts,
+        contentType: contentType ?? undefined,
+      });
+
+      return jsonResult({ ok: true, chatGuid: resolvedChatGuid, iconSet: true });
+    }
+
+    // Handle addParticipant action
+    if (action === "addParticipant") {
+      const resolvedChatGuid = await resolveChatGuid();
+      const address = readStringParam(params, "address") ?? readStringParam(params, "participant");
+      if (!address) {
+        throw new Error("BlueBubbles addParticipant requires address or participant parameter.");
+      }
+
+      await addBlueBubblesParticipant(resolvedChatGuid, address, opts);
+
+      return jsonResult({ ok: true, added: address, chatGuid: resolvedChatGuid });
+    }
+
+    // Handle removeParticipant action
+    if (action === "removeParticipant") {
+      const resolvedChatGuid = await resolveChatGuid();
+      const address = readStringParam(params, "address") ?? readStringParam(params, "participant");
+      if (!address) {
+        throw new Error("BlueBubbles removeParticipant requires address or participant parameter.");
+      }
+
+      await removeBlueBubblesParticipant(resolvedChatGuid, address, opts);
+
+      return jsonResult({ ok: true, removed: address, chatGuid: resolvedChatGuid });
+    }
+
+    // Handle leaveGroup action
+    if (action === "leaveGroup") {
+      const resolvedChatGuid = await resolveChatGuid();
+
+      await leaveBlueBubblesChat(resolvedChatGuid, opts);
+
+      return jsonResult({ ok: true, left: resolvedChatGuid });
+    }
+
+    // Handle sendAttachment action
+    if (action === "sendAttachment") {
+      const to = readStringParam(params, "to", { required: true });
+      const filename = readStringParam(params, "filename", { required: true });
+      const caption = readStringParam(params, "caption");
+      const contentType =
+        readStringParam(params, "contentType") ?? readStringParam(params, "mimeType");
+      const asVoice = readBooleanParam(params, "asVoice");
+
+      // Buffer can come from params.buffer (base64) or params.path (file path)
+      const base64Buffer = readStringParam(params, "buffer");
+      const filePath = readStringParam(params, "path") ?? readStringParam(params, "filePath");
+
+      let buffer: Uint8Array;
+      if (base64Buffer) {
+        // Decode base64 to buffer
+        buffer = Uint8Array.from(atob(base64Buffer), (c) => c.charCodeAt(0));
+      } else if (filePath) {
+        // Read file from path (will be handled by caller providing buffer)
+        throw new Error(
+          "BlueBubbles sendAttachment: filePath not supported in action, provide buffer as base64.",
+        );
+      } else {
+        throw new Error("BlueBubbles sendAttachment requires buffer (base64) parameter.");
+      }
+
+      const result = await sendBlueBubblesAttachment({
+        to,
+        buffer,
+        filename,
+        contentType: contentType ?? undefined,
+        caption: caption ?? undefined,
+        asVoice: asVoice ?? undefined,
+        opts,
+      });
+
+      return jsonResult({ ok: true, messageId: result.messageId });
+    }
+
+    throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+  },
+};

docker-compose/ez-assistant/extensions/bluebubbles/src/attachments.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
+import type { BlueBubblesAttachment } from "./types.js";
+
+vi.mock("./accounts.js", () => ({
+  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
+    const config = cfg?.channels?.bluebubbles ?? {};
+    return {
+      accountId: accountId ?? "default",
+      enabled: config.enabled !== false,
+      configured: Boolean(config.serverUrl && config.password),
+      config,
+    };
+  }),
+}));
+
+const mockFetch = vi.fn();
+
+describe("downloadBlueBubblesAttachment", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("throws when guid is missing", async () => {
+    const attachment: BlueBubblesAttachment = {};
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+        password: "test-password",
+      }),
+    ).rejects.toThrow("guid is required");
+  });
+
+  it("throws when guid is empty string", async () => {
+    const attachment: BlueBubblesAttachment = { guid: "  " };
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+        password: "test-password",
+      }),
+    ).rejects.toThrow("guid is required");
+  });
+
+  it("throws when serverUrl is missing", async () => {
+    const attachment: BlueBubblesAttachment = { guid: "att-123" };
+    await expect(downloadBlueBubblesAttachment(attachment, {})).rejects.toThrow(
+      "serverUrl is required",
+    );
+  });
+
+  it("throws when password is missing", async () => {
+    const attachment: BlueBubblesAttachment = { guid: "att-123" };
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+      }),
+    ).rejects.toThrow("password is required");
+  });
+
+  it("downloads attachment successfully", async () => {
+    const mockBuffer = new Uint8Array([1, 2, 3, 4]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers({ "content-type": "image/png" }),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-123" };
+    const result = await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://localhost:1234",
+      password: "test-password",
+    });
+
+    expect(result.buffer).toEqual(mockBuffer);
+    expect(result.contentType).toBe("image/png");
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.stringContaining("/api/v1/attachment/att-123/download"),
+      expect.objectContaining({ method: "GET" }),
+    );
+  });
+
+  it("includes password in URL query", async () => {
+    const mockBuffer = new Uint8Array([1, 2, 3, 4]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers({ "content-type": "image/jpeg" }),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-456" };
+    await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://localhost:1234",
+      password: "my-secret-password",
+    });
+
+    const calledUrl = mockFetch.mock.calls[0][0] as string;
+    expect(calledUrl).toContain("password=my-secret-password");
+  });
+
+  it("encodes guid in URL", async () => {
+    const mockBuffer = new Uint8Array([1]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att/with/special chars" };
+    await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://localhost:1234",
+      password: "test",
+    });
+
+    const calledUrl = mockFetch.mock.calls[0][0] as string;
+    expect(calledUrl).toContain("att%2Fwith%2Fspecial%20chars");
+  });
+
+  it("throws on non-ok response", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 404,
+      text: () => Promise.resolve("Attachment not found"),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-missing" };
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      }),
+    ).rejects.toThrow("download failed (404): Attachment not found");
+  });
+
+  it("throws when attachment exceeds max bytes", async () => {
+    const largeBuffer = new Uint8Array(10 * 1024 * 1024);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(largeBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-large" };
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+        maxBytes: 5 * 1024 * 1024,
+      }),
+    ).rejects.toThrow("too large");
+  });
+
+  it("uses default max bytes when not specified", async () => {
+    const largeBuffer = new Uint8Array(9 * 1024 * 1024);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(largeBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-large" };
+    await expect(
+      downloadBlueBubblesAttachment(attachment, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      }),
+    ).rejects.toThrow("too large");
+  });
+
+  it("uses attachment mimeType as fallback when response has no content-type", async () => {
+    const mockBuffer = new Uint8Array([1, 2, 3]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = {
+      guid: "att-789",
+      mimeType: "video/mp4",
+    };
+    const result = await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://localhost:1234",
+      password: "test",
+    });
+
+    expect(result.contentType).toBe("video/mp4");
+  });
+
+  it("prefers response content-type over attachment mimeType", async () => {
+    const mockBuffer = new Uint8Array([1, 2, 3]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers({ "content-type": "image/webp" }),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = {
+      guid: "att-xyz",
+      mimeType: "image/png",
+    };
+    const result = await downloadBlueBubblesAttachment(attachment, {
+      serverUrl: "http://localhost:1234",
+      password: "test",
+    });
+
+    expect(result.contentType).toBe("image/webp");
+  });
+
+  it("resolves credentials from config when opts not provided", async () => {
+    const mockBuffer = new Uint8Array([1]);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
+    });
+
+    const attachment: BlueBubblesAttachment = { guid: "att-config" };
+    const result = await downloadBlueBubblesAttachment(attachment, {
+      cfg: {
+        channels: {
+          bluebubbles: {
+            serverUrl: "http://config-server:5678",
+            password: "config-password",
+          },
+        },
+      },
+    });
+
+    const calledUrl = mockFetch.mock.calls[0][0] as string;
+    expect(calledUrl).toContain("config-server:5678");
+    expect(calledUrl).toContain("password=config-password");
+    expect(result.buffer).toEqual(new Uint8Array([1]));
+  });
+});
+
+describe("sendBlueBubblesAttachment", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function decodeBody(body: Uint8Array) {
+    return Buffer.from(body).toString("utf8");
+  }
+
+  it("marks voice memos when asVoice is true and mp3 is provided", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-1" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "voice.mp3",
+      contentType: "audio/mpeg",
+      asVoice: true,
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('name="isAudioMessage"');
+    expect(bodyText).toContain("true");
+    expect(bodyText).toContain('filename="voice.mp3"');
+  });
+
+  it("normalizes mp3 filenames for voice memos", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-2" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "voice",
+      contentType: "audio/mpeg",
+      asVoice: true,
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('filename="voice.mp3"');
+    expect(bodyText).toContain('name="voice.mp3"');
+  });
+
+  it("throws when asVoice is true but media is not audio", async () => {
+    await expect(
+      sendBlueBubblesAttachment({
+        to: "chat_guid:iMessage;-;+15551234567",
+        buffer: new Uint8Array([1, 2, 3]),
+        filename: "image.png",
+        contentType: "image/png",
+        asVoice: true,
+        opts: { serverUrl: "http://localhost:1234", password: "test" },
+      }),
+    ).rejects.toThrow("voice messages require audio");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("throws when asVoice is true but audio is not mp3 or caf", async () => {
+    await expect(
+      sendBlueBubblesAttachment({
+        to: "chat_guid:iMessage;-;+15551234567",
+        buffer: new Uint8Array([1, 2, 3]),
+        filename: "voice.wav",
+        contentType: "audio/wav",
+        asVoice: true,
+        opts: { serverUrl: "http://localhost:1234", password: "test" },
+      }),
+    ).rejects.toThrow("require mp3 or caf");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("sanitizes filenames before sending", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-3" })),
+    });
+
+    await sendBlueBubblesAttachment({
+      to: "chat_guid:iMessage;-;+15551234567",
+      buffer: new Uint8Array([1, 2, 3]),
+      filename: "../evil.mp3",
+      contentType: "audio/mpeg",
+      opts: { serverUrl: "http://localhost:1234", password: "test" },
+    });
+
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('filename="evil.mp3"');
+    expect(bodyText).toContain('name="evil.mp3"');
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/attachments.ts

@@ -0,0 +1,282 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { resolveChatGuidForTarget } from "./send.js";
+import { parseBlueBubblesTarget, normalizeBlueBubblesHandle } from "./targets.js";
+import {
+  blueBubblesFetchWithTimeout,
+  buildBlueBubblesApiUrl,
+  type BlueBubblesAttachment,
+  type BlueBubblesSendTarget,
+} from "./types.js";
+
+export type BlueBubblesAttachmentOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: MoltbotConfig;
+};
+
+const DEFAULT_ATTACHMENT_MAX_BYTES = 8 * 1024 * 1024;
+const AUDIO_MIME_MP3 = new Set(["audio/mpeg", "audio/mp3"]);
+const AUDIO_MIME_CAF = new Set(["audio/x-caf", "audio/caf"]);
+
+function sanitizeFilename(input: string | undefined, fallback: string): string {
+  const trimmed = input?.trim() ?? "";
+  const base = trimmed ? path.basename(trimmed) : "";
+  return base || fallback;
+}
+
+function ensureExtension(filename: string, extension: string, fallbackBase: string): string {
+  const currentExt = path.extname(filename);
+  if (currentExt.toLowerCase() === extension) return filename;
+  const base = currentExt ? filename.slice(0, -currentExt.length) : filename;
+  return `${base || fallbackBase}${extension}`;
+}
+
+function resolveVoiceInfo(filename: string, contentType?: string) {
+  const normalizedType = contentType?.trim().toLowerCase();
+  const extension = path.extname(filename).toLowerCase();
+  const isMp3 = extension === ".mp3" || (normalizedType ? AUDIO_MIME_MP3.has(normalizedType) : false);
+  const isCaf = extension === ".caf" || (normalizedType ? AUDIO_MIME_CAF.has(normalizedType) : false);
+  const isAudio = isMp3 || isCaf || Boolean(normalizedType?.startsWith("audio/"));
+  return { isAudio, isMp3, isCaf };
+}
+
+function resolveAccount(params: BlueBubblesAttachmentOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export async function downloadBlueBubblesAttachment(
+  attachment: BlueBubblesAttachment,
+  opts: BlueBubblesAttachmentOpts & { maxBytes?: number } = {},
+): Promise<{ buffer: Uint8Array; contentType?: string }> {
+  const guid = attachment.guid?.trim();
+  if (!guid) throw new Error("BlueBubbles attachment guid is required");
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/attachment/${encodeURIComponent(guid)}/download`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, opts.timeoutMs);
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(
+      `BlueBubbles attachment download failed (${res.status}): ${errorText || "unknown"}`,
+    );
+  }
+  const contentType = res.headers.get("content-type") ?? undefined;
+  const buf = new Uint8Array(await res.arrayBuffer());
+  const maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : DEFAULT_ATTACHMENT_MAX_BYTES;
+  if (buf.byteLength > maxBytes) {
+    throw new Error(`BlueBubbles attachment too large (${buf.byteLength} bytes)`);
+  }
+  return { buffer: buf, contentType: contentType ?? attachment.mimeType ?? undefined };
+}
+
+export type SendBlueBubblesAttachmentResult = {
+  messageId: string;
+};
+
+function resolveSendTarget(raw: string): BlueBubblesSendTarget {
+  const parsed = parseBlueBubblesTarget(raw);
+  if (parsed.kind === "handle") {
+    return {
+      kind: "handle",
+      address: normalizeBlueBubblesHandle(parsed.to),
+      service: parsed.service,
+    };
+  }
+  if (parsed.kind === "chat_id") {
+    return { kind: "chat_id", chatId: parsed.chatId };
+  }
+  if (parsed.kind === "chat_guid") {
+    return { kind: "chat_guid", chatGuid: parsed.chatGuid };
+  }
+  return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
+}
+
+function extractMessageId(payload: unknown): string {
+  if (!payload || typeof payload !== "object") return "unknown";
+  const record = payload as Record<string, unknown>;
+  const data = record.data && typeof record.data === "object" ? (record.data as Record<string, unknown>) : null;
+  const candidates = [
+    record.messageId,
+    record.guid,
+    record.id,
+    data?.messageId,
+    data?.guid,
+    data?.id,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return String(candidate);
+  }
+  return "unknown";
+}
+
+/**
+ * Send an attachment via BlueBubbles API.
+ * Supports sending media files (images, videos, audio, documents) to a chat.
+ * When asVoice is true, expects MP3/CAF audio and marks it as an iMessage voice memo.
+ */
+export async function sendBlueBubblesAttachment(params: {
+  to: string;
+  buffer: Uint8Array;
+  filename: string;
+  contentType?: string;
+  caption?: string;
+  replyToMessageGuid?: string;
+  replyToPartIndex?: number;
+  asVoice?: boolean;
+  opts?: BlueBubblesAttachmentOpts;
+}): Promise<SendBlueBubblesAttachmentResult> {
+  const { to, caption, replyToMessageGuid, replyToPartIndex, asVoice, opts = {} } = params;
+  let { buffer, filename, contentType } = params;
+  const wantsVoice = asVoice === true;
+  const fallbackName = wantsVoice ? "Audio Message" : "attachment";
+  filename = sanitizeFilename(filename, fallbackName);
+  contentType = contentType?.trim() || undefined;
+  const { baseUrl, password } = resolveAccount(opts);
+
+  // Validate voice memo format when requested (BlueBubbles converts MP3 -> CAF when isAudioMessage).
+  const isAudioMessage = wantsVoice;
+  if (isAudioMessage) {
+    const voiceInfo = resolveVoiceInfo(filename, contentType);
+    if (!voiceInfo.isAudio) {
+      throw new Error("BlueBubbles voice messages require audio media (mp3 or caf).");
+    }
+    if (voiceInfo.isMp3) {
+      filename = ensureExtension(filename, ".mp3", fallbackName);
+      contentType = contentType ?? "audio/mpeg";
+    } else if (voiceInfo.isCaf) {
+      filename = ensureExtension(filename, ".caf", fallbackName);
+      contentType = contentType ?? "audio/x-caf";
+    } else {
+      throw new Error(
+        "BlueBubbles voice messages require mp3 or caf audio (convert before sending).",
+      );
+    }
+  }
+
+  const target = resolveSendTarget(to);
+  const chatGuid = await resolveChatGuidForTarget({
+    baseUrl,
+    password,
+    timeoutMs: opts.timeoutMs,
+    target,
+  });
+  if (!chatGuid) {
+    throw new Error(
+      "BlueBubbles attachment send failed: chatGuid not found for target. Use a chat_guid target or ensure the chat exists.",
+    );
+  }
+
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: "/api/v1/message/attachment",
+    password,
+  });
+
+  // Build FormData with the attachment
+  const boundary = `----BlueBubblesFormBoundary${crypto.randomUUID().replace(/-/g, "")}`;
+  const parts: Uint8Array[] = [];
+  const encoder = new TextEncoder();
+
+  // Helper to add a form field
+  const addField = (name: string, value: string) => {
+    parts.push(encoder.encode(`--${boundary}\r\n`));
+    parts.push(encoder.encode(`Content-Disposition: form-data; name="${name}"\r\n\r\n`));
+    parts.push(encoder.encode(`${value}\r\n`));
+  };
+
+  // Helper to add a file field
+  const addFile = (name: string, fileBuffer: Uint8Array, fileName: string, mimeType?: string) => {
+    parts.push(encoder.encode(`--${boundary}\r\n`));
+    parts.push(
+      encoder.encode(
+        `Content-Disposition: form-data; name="${name}"; filename="${fileName}"\r\n`,
+      ),
+    );
+    parts.push(encoder.encode(`Content-Type: ${mimeType ?? "application/octet-stream"}\r\n\r\n`));
+    parts.push(fileBuffer);
+    parts.push(encoder.encode("\r\n"));
+  };
+
+  // Add required fields
+  addFile("attachment", buffer, filename, contentType);
+  addField("chatGuid", chatGuid);
+  addField("name", filename);
+  addField("tempGuid", `temp-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`);
+  addField("method", "private-api");
+
+  // Add isAudioMessage flag for voice memos
+  if (isAudioMessage) {
+    addField("isAudioMessage", "true");
+  }
+
+  const trimmedReplyTo = replyToMessageGuid?.trim();
+  if (trimmedReplyTo) {
+    addField("selectedMessageGuid", trimmedReplyTo);
+    addField(
+      "partIndex",
+      typeof replyToPartIndex === "number" ? String(replyToPartIndex) : "0",
+    );
+  }
+
+  // Add optional caption
+  if (caption) {
+    addField("message", caption);
+    addField("text", caption);
+    addField("caption", caption);
+  }
+
+  // Close the multipart body
+  parts.push(encoder.encode(`--${boundary}--\r\n`));
+
+  // Combine all parts into a single buffer
+  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
+  const body = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    body.set(part, offset);
+    offset += part.length;
+  }
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      },
+      body,
+    },
+    opts.timeoutMs ?? 60_000, // longer timeout for file uploads
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`BlueBubbles attachment send failed (${res.status}): ${errorText || "unknown"}`);
+  }
+
+  const responseBody = await res.text();
+  if (!responseBody) return { messageId: "ok" };
+  try {
+    const parsed = JSON.parse(responseBody) as unknown;
+    return { messageId: extractMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/channel.ts

@@ -0,0 +1,399 @@
+import type { ChannelAccountSnapshot, ChannelPlugin, MoltbotConfig } from "clawdbot/plugin-sdk";
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  collectBlueBubblesStatusIssues,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  resolveBlueBubblesGroupRequireMention,
+  resolveBlueBubblesGroupToolPolicy,
+  setAccountEnabledInConfigSection,
+} from "clawdbot/plugin-sdk";
+
+import {
+  listBlueBubblesAccountIds,
+  type ResolvedBlueBubblesAccount,
+  resolveBlueBubblesAccount,
+  resolveDefaultBlueBubblesAccountId,
+} from "./accounts.js";
+import { BlueBubblesConfigSchema } from "./config-schema.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { probeBlueBubbles, type BlueBubblesProbe } from "./probe.js";
+import { sendMessageBlueBubbles } from "./send.js";
+import {
+  extractHandleFromChatGuid,
+  looksLikeBlueBubblesTargetId,
+  normalizeBlueBubblesHandle,
+  normalizeBlueBubblesMessagingTarget,
+  parseBlueBubblesTarget,
+} from "./targets.js";
+import { bluebubblesMessageActions } from "./actions.js";
+import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
+import { blueBubblesOnboardingAdapter } from "./onboarding.js";
+import { sendBlueBubblesMedia } from "./media-send.js";
+
+const meta = {
+  id: "bluebubbles",
+  label: "BlueBubbles",
+  selectionLabel: "BlueBubbles (macOS app)",
+  detailLabel: "BlueBubbles",
+  docsPath: "/channels/bluebubbles",
+  docsLabel: "bluebubbles",
+  blurb: "iMessage via the BlueBubbles mac app + REST API.",
+  systemImage: "bubble.left.and.text.bubble.right",
+  aliases: ["bb"],
+  order: 75,
+  preferOver: ["imessage"],
+};
+
+export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
+  id: "bluebubbles",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: true,
+    edit: true,
+    unsend: true,
+    reply: true,
+    effects: true,
+    groupManagement: true,
+  },
+  groups: {
+    resolveRequireMention: resolveBlueBubblesGroupRequireMention,
+    resolveToolPolicy: resolveBlueBubblesGroupToolPolicy,
+  },
+  threading: {
+    buildToolContext: ({ context, hasRepliedRef }) => ({
+      currentChannelId: context.To?.trim() || undefined,
+      currentThreadTs: context.ReplyToIdFull ?? context.ReplyToId,
+      hasRepliedRef,
+    }),
+  },
+  reload: { configPrefixes: ["channels.bluebubbles"] },
+  configSchema: buildChannelConfigSchema(BlueBubblesConfigSchema),
+  onboarding: blueBubblesOnboardingAdapter,
+  config: {
+    listAccountIds: (cfg) => listBlueBubblesAccountIds(cfg as MoltbotConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveBlueBubblesAccount({ cfg: cfg as MoltbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultBlueBubblesAccountId(cfg as MoltbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as MoltbotConfig,
+        sectionKey: "bluebubbles",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as MoltbotConfig,
+        sectionKey: "bluebubbles",
+        accountId,
+        clearBaseFields: ["serverUrl", "password", "name", "webhookPath"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.baseUrl,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveBlueBubblesAccount({ cfg: cfg as MoltbotConfig, accountId }).config.allowFrom ??
+        []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^bluebubbles:/i, ""))
+        .map((entry) => normalizeBlueBubblesHandle(entry)),
+  },
+  actions: bluebubblesMessageActions,
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(
+        (cfg as MoltbotConfig).channels?.bluebubbles?.accounts?.[resolvedAccountId],
+      );
+      const basePath = useAccountPath
+        ? `channels.bluebubbles.accounts.${resolvedAccountId}.`
+        : "channels.bluebubbles.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("bluebubbles"),
+        normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
+      };
+    },
+    collectWarnings: ({ account }) => {
+      const groupPolicy = account.config.groupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- BlueBubbles groups: groupPolicy="open" allows any member to trigger the bot. Set channels.bluebubbles.groupPolicy="allowlist" + channels.bluebubbles.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeBlueBubblesMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeBlueBubblesTargetId,
+      hint: "<handle|chat_guid:GUID|chat_id:ID|chat_identifier:ID>",
+    },
+    formatTargetDisplay: ({ target, display }) => {
+      const shouldParseDisplay = (value: string): boolean => {
+        if (looksLikeBlueBubblesTargetId(value)) return true;
+        return /^(bluebubbles:|chat_guid:|chat_id:|chat_identifier:)/i.test(value);
+      };
+
+      // Helper to extract a clean handle from any BlueBubbles target format
+      const extractCleanDisplay = (value: string | undefined): string | null => {
+        const trimmed = value?.trim();
+        if (!trimmed) return null;
+        try {
+          const parsed = parseBlueBubblesTarget(trimmed);
+          if (parsed.kind === "chat_guid") {
+            const handle = extractHandleFromChatGuid(parsed.chatGuid);
+            if (handle) return handle;
+          }
+          if (parsed.kind === "handle") {
+            return normalizeBlueBubblesHandle(parsed.to);
+          }
+        } catch {
+          // Fall through
+        }
+        // Strip common prefixes and try raw extraction
+        const stripped = trimmed
+          .replace(/^bluebubbles:/i, "")
+          .replace(/^chat_guid:/i, "")
+          .replace(/^chat_id:/i, "")
+          .replace(/^chat_identifier:/i, "");
+        const handle = extractHandleFromChatGuid(stripped);
+        if (handle) return handle;
+        // Don't return raw chat_guid formats - they contain internal routing info
+        if (stripped.includes(";-;") || stripped.includes(";+;")) return null;
+        return stripped;
+      };
+
+      // Try to get a clean display from the display parameter first
+      const trimmedDisplay = display?.trim();
+      if (trimmedDisplay) {
+        if (!shouldParseDisplay(trimmedDisplay)) {
+          return trimmedDisplay;
+        }
+        const cleanDisplay = extractCleanDisplay(trimmedDisplay);
+        if (cleanDisplay) return cleanDisplay;
+      }
+
+      // Fall back to extracting from target
+      const cleanTarget = extractCleanDisplay(target);
+      if (cleanTarget) return cleanTarget;
+
+      // Last resort: return display or target as-is
+      return display?.trim() || target?.trim() || "";
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as MoltbotConfig,
+        channelKey: "bluebubbles",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (!input.httpUrl && !input.password) {
+        return "BlueBubbles requires --http-url and --password.";
+      }
+      if (!input.httpUrl) return "BlueBubbles requires --http-url.";
+      if (!input.password) return "BlueBubbles requires --password.";
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as MoltbotConfig,
+        channelKey: "bluebubbles",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "bluebubbles",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            bluebubbles: {
+              ...next.channels?.bluebubbles,
+              enabled: true,
+              ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
+              ...(input.password ? { password: input.password } : {}),
+              ...(input.webhookPath ? { webhookPath: input.webhookPath } : {}),
+            },
+          },
+        } as MoltbotConfig;
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          bluebubbles: {
+            ...next.channels?.bluebubbles,
+            enabled: true,
+            accounts: {
+              ...(next.channels?.bluebubbles?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.bluebubbles?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
+                ...(input.password ? { password: input.password } : {}),
+                ...(input.webhookPath ? { webhookPath: input.webhookPath } : {}),
+              },
+            },
+          },
+        },
+      } as MoltbotConfig;
+    },
+  },
+  pairing: {
+    idLabel: "bluebubblesSenderId",
+    normalizeAllowEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
+    notifyApproval: async ({ cfg, id }) => {
+      await sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
+        cfg: cfg as MoltbotConfig,
+      });
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    resolveTarget: ({ to }) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return {
+          ok: false,
+          error: new Error("Delivering to BlueBubbles requires --to <handle|chat_guid:GUID>"),
+        };
+      }
+      return { ok: true, to: trimmed };
+    },
+    sendText: async ({ cfg, to, text, accountId, replyToId }) => {
+      const rawReplyToId = typeof replyToId === "string" ? replyToId.trim() : "";
+      // Resolve short ID (e.g., "5") to full UUID
+      const replyToMessageGuid = rawReplyToId
+        ? resolveBlueBubblesMessageId(rawReplyToId, { requireKnownShortId: true })
+        : "";
+      const result = await sendMessageBlueBubbles(to, text, {
+        cfg: cfg as MoltbotConfig,
+        accountId: accountId ?? undefined,
+        replyToMessageGuid: replyToMessageGuid || undefined,
+      });
+      return { channel: "bluebubbles", ...result };
+    },
+    sendMedia: async (ctx) => {
+      const { cfg, to, text, mediaUrl, accountId, replyToId } = ctx;
+      const { mediaPath, mediaBuffer, contentType, filename, caption } = ctx as {
+        mediaPath?: string;
+        mediaBuffer?: Uint8Array;
+        contentType?: string;
+        filename?: string;
+        caption?: string;
+      };
+      const resolvedCaption = caption ?? text;
+      const result = await sendBlueBubblesMedia({
+        cfg: cfg as MoltbotConfig,
+        to,
+        mediaUrl,
+        mediaPath,
+        mediaBuffer,
+        contentType,
+        filename,
+        caption: resolvedCaption ?? undefined,
+        replyToId: replyToId ?? null,
+        accountId: accountId ?? undefined,
+      });
+
+      return { channel: "bluebubbles", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: collectBlueBubblesStatusIssues,
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      baseUrl: snapshot.baseUrl ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeBlueBubbles({
+        baseUrl: account.baseUrl,
+        password: account.config.password ?? null,
+        timeoutMs,
+      }),
+    buildAccountSnapshot: ({ account, runtime, probe }) => {
+      const running = runtime?.running ?? false;
+      const probeOk = (probe as BlueBubblesProbe | undefined)?.ok;
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: account.configured,
+        baseUrl: account.baseUrl,
+        running,
+        connected: probeOk ?? running,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        probe,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const webhookPath = resolveWebhookPathFromConfig(account.config);
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.baseUrl,
+      });
+      ctx.log?.info(`[${account.accountId}] starting provider (webhook=${webhookPath})`);
+      return monitorBlueBubblesProvider({
+        account,
+        config: ctx.cfg as MoltbotConfig,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+        webhookPath,
+      });
+    },
+  },
+};

docker-compose/ez-assistant/extensions/bluebubbles/src/chat.test.ts

@@ -0,0 +1,462 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import { markBlueBubblesChatRead, sendBlueBubblesTyping, setGroupIconBlueBubbles } from "./chat.js";
+
+vi.mock("./accounts.js", () => ({
+  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
+    const config = cfg?.channels?.bluebubbles ?? {};
+    return {
+      accountId: accountId ?? "default",
+      enabled: config.enabled !== false,
+      configured: Boolean(config.serverUrl && config.password),
+      config,
+    };
+  }),
+}));
+
+const mockFetch = vi.fn();
+
+describe("chat", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("markBlueBubblesChatRead", () => {
+    it("does nothing when chatGuid is empty", async () => {
+      await markBlueBubblesChatRead("", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("does nothing when chatGuid is whitespace", async () => {
+      await markBlueBubblesChatRead("   ", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("throws when serverUrl is missing", async () => {
+      await expect(markBlueBubblesChatRead("chat-guid", {})).rejects.toThrow(
+        "serverUrl is required",
+      );
+    });
+
+    it("throws when password is missing", async () => {
+      await expect(
+        markBlueBubblesChatRead("chat-guid", {
+          serverUrl: "http://localhost:1234",
+        }),
+      ).rejects.toThrow("password is required");
+    });
+
+    it("marks chat as read successfully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await markBlueBubblesChatRead("iMessage;-;+15551234567", {
+        serverUrl: "http://localhost:1234",
+        password: "test-password",
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/chat/iMessage%3B-%3B%2B15551234567/read"),
+        expect.objectContaining({ method: "POST" }),
+      );
+    });
+
+    it("includes password in URL query", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await markBlueBubblesChatRead("chat-123", {
+        serverUrl: "http://localhost:1234",
+        password: "my-secret",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("password=my-secret");
+    });
+
+    it("throws on non-ok response", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: () => Promise.resolve("Chat not found"),
+      });
+
+      await expect(
+        markBlueBubblesChatRead("missing-chat", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("read failed (404): Chat not found");
+    });
+
+    it("trims chatGuid before using", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await markBlueBubblesChatRead("  chat-with-spaces  ", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("/api/v1/chat/chat-with-spaces/read");
+      expect(calledUrl).not.toContain("%20chat");
+    });
+
+    it("resolves credentials from config", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await markBlueBubblesChatRead("chat-123", {
+        cfg: {
+          channels: {
+            bluebubbles: {
+              serverUrl: "http://config-server:9999",
+              password: "config-pass",
+            },
+          },
+        },
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("config-server:9999");
+      expect(calledUrl).toContain("password=config-pass");
+    });
+  });
+
+  describe("sendBlueBubblesTyping", () => {
+    it("does nothing when chatGuid is empty", async () => {
+      await sendBlueBubblesTyping("", true, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("does nothing when chatGuid is whitespace", async () => {
+      await sendBlueBubblesTyping("   ", false, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("throws when serverUrl is missing", async () => {
+      await expect(sendBlueBubblesTyping("chat-guid", true, {})).rejects.toThrow(
+        "serverUrl is required",
+      );
+    });
+
+    it("throws when password is missing", async () => {
+      await expect(
+        sendBlueBubblesTyping("chat-guid", true, {
+          serverUrl: "http://localhost:1234",
+        }),
+      ).rejects.toThrow("password is required");
+    });
+
+    it("sends typing start with POST method", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("iMessage;-;+15551234567", true, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/chat/iMessage%3B-%3B%2B15551234567/typing"),
+        expect.objectContaining({ method: "POST" }),
+      );
+    });
+
+    it("sends typing stop with DELETE method", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("iMessage;-;+15551234567", false, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/chat/iMessage%3B-%3B%2B15551234567/typing"),
+        expect.objectContaining({ method: "DELETE" }),
+      );
+    });
+
+    it("includes password in URL query", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("chat-123", true, {
+        serverUrl: "http://localhost:1234",
+        password: "typing-secret",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("password=typing-secret");
+    });
+
+    it("throws on non-ok response", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve("Internal error"),
+      });
+
+      await expect(
+        sendBlueBubblesTyping("chat-123", true, {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("typing failed (500): Internal error");
+    });
+
+    it("trims chatGuid before using", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("  trimmed-chat  ", true, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("/api/v1/chat/trimmed-chat/typing");
+    });
+
+    it("encodes special characters in chatGuid", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("iMessage;+;group@chat.com", true, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("iMessage%3B%2B%3Bgroup%40chat.com");
+    });
+
+    it("resolves credentials from config", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesTyping("chat-123", true, {
+        cfg: {
+          channels: {
+            bluebubbles: {
+              serverUrl: "http://typing-server:8888",
+              password: "typing-pass",
+            },
+          },
+        },
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("typing-server:8888");
+      expect(calledUrl).toContain("password=typing-pass");
+    });
+
+    it("can start and stop typing in sequence", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(""),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(""),
+        });
+
+      await sendBlueBubblesTyping("chat-123", true, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+      await sendBlueBubblesTyping("chat-123", false, {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(mockFetch.mock.calls[0][1].method).toBe("POST");
+      expect(mockFetch.mock.calls[1][1].method).toBe("DELETE");
+    });
+  });
+
+  describe("setGroupIconBlueBubbles", () => {
+    it("throws when chatGuid is empty", async () => {
+      await expect(
+        setGroupIconBlueBubbles("", new Uint8Array([1, 2, 3]), "icon.png", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("chatGuid");
+    });
+
+    it("throws when buffer is empty", async () => {
+      await expect(
+        setGroupIconBlueBubbles("chat-guid", new Uint8Array(0), "icon.png", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("image buffer");
+    });
+
+    it("throws when serverUrl is missing", async () => {
+      await expect(
+        setGroupIconBlueBubbles("chat-guid", new Uint8Array([1, 2, 3]), "icon.png", {}),
+      ).rejects.toThrow("serverUrl is required");
+    });
+
+    it("throws when password is missing", async () => {
+      await expect(
+        setGroupIconBlueBubbles("chat-guid", new Uint8Array([1, 2, 3]), "icon.png", {
+          serverUrl: "http://localhost:1234",
+        }),
+      ).rejects.toThrow("password is required");
+    });
+
+    it("sets group icon successfully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      const buffer = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG magic bytes
+      await setGroupIconBlueBubbles("iMessage;-;chat-guid", buffer, "icon.png", {
+        serverUrl: "http://localhost:1234",
+        password: "test-password",
+        contentType: "image/png",
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/chat/iMessage%3B-%3Bchat-guid/icon"),
+        expect.objectContaining({
+          method: "POST",
+          headers: expect.objectContaining({
+            "Content-Type": expect.stringContaining("multipart/form-data"),
+          }),
+        }),
+      );
+    });
+
+    it("includes password in URL query", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await setGroupIconBlueBubbles("chat-123", new Uint8Array([1, 2, 3]), "icon.png", {
+        serverUrl: "http://localhost:1234",
+        password: "my-secret",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("password=my-secret");
+    });
+
+    it("throws on non-ok response", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        text: () => Promise.resolve("Internal error"),
+      });
+
+      await expect(
+        setGroupIconBlueBubbles("chat-123", new Uint8Array([1, 2, 3]), "icon.png", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("setGroupIcon failed (500): Internal error");
+    });
+
+    it("trims chatGuid before using", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await setGroupIconBlueBubbles("  chat-with-spaces  ", new Uint8Array([1]), "icon.png", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("/api/v1/chat/chat-with-spaces/icon");
+      expect(calledUrl).not.toContain("%20chat");
+    });
+
+    it("resolves credentials from config", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await setGroupIconBlueBubbles("chat-123", new Uint8Array([1]), "icon.png", {
+        cfg: {
+          channels: {
+            bluebubbles: {
+              serverUrl: "http://config-server:9999",
+              password: "config-pass",
+            },
+          },
+        },
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("config-server:9999");
+      expect(calledUrl).toContain("password=config-pass");
+    });
+
+    it("includes filename in multipart body", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await setGroupIconBlueBubbles("chat-123", new Uint8Array([1, 2, 3]), "custom-icon.jpg", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+        contentType: "image/jpeg",
+      });
+
+      const body = mockFetch.mock.calls[0][1].body as Uint8Array;
+      const bodyString = new TextDecoder().decode(body);
+      expect(bodyString).toContain('filename="custom-icon.jpg"');
+      expect(bodyString).toContain("image/jpeg");
+    });
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/chat.ts

@@ -0,0 +1,354 @@
+import crypto from "node:crypto";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesChatOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: MoltbotConfig;
+};
+
+function resolveAccount(params: BlueBubblesChatOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export async function markBlueBubblesChatRead(
+  chatGuid: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/read`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, opts.timeoutMs);
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles read failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+export async function sendBlueBubblesTyping(
+  chatGuid: string,
+  typing: boolean,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/typing`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    { method: typing ? "POST" : "DELETE" },
+    opts.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles typing failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Edit a message via BlueBubbles API.
+ * Requires macOS 13 (Ventura) or higher with Private API enabled.
+ */
+export async function editBlueBubblesMessage(
+  messageGuid: string,
+  newText: string,
+  opts: BlueBubblesChatOpts & { partIndex?: number; backwardsCompatMessage?: string } = {},
+): Promise<void> {
+  const trimmedGuid = messageGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles edit requires messageGuid");
+  const trimmedText = newText.trim();
+  if (!trimmedText) throw new Error("BlueBubbles edit requires newText");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/message/${encodeURIComponent(trimmedGuid)}/edit`,
+    password,
+  });
+
+  const payload = {
+    editedMessage: trimmedText,
+    backwardsCompatibilityMessage: opts.backwardsCompatMessage ?? `Edited to: ${trimmedText}`,
+    partIndex: typeof opts.partIndex === "number" ? opts.partIndex : 0,
+  };
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles edit failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Unsend (retract) a message via BlueBubbles API.
+ * Requires macOS 13 (Ventura) or higher with Private API enabled.
+ */
+export async function unsendBlueBubblesMessage(
+  messageGuid: string,
+  opts: BlueBubblesChatOpts & { partIndex?: number } = {},
+): Promise<void> {
+  const trimmedGuid = messageGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles unsend requires messageGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/message/${encodeURIComponent(trimmedGuid)}/unsend`,
+    password,
+  });
+
+  const payload = {
+    partIndex: typeof opts.partIndex === "number" ? opts.partIndex : 0,
+  };
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles unsend failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Rename a group chat via BlueBubbles API.
+ */
+export async function renameBlueBubblesChat(
+  chatGuid: string,
+  displayName: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles rename requires chatGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ displayName }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles rename failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Add a participant to a group chat via BlueBubbles API.
+ */
+export async function addBlueBubblesParticipant(
+  chatGuid: string,
+  address: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles addParticipant requires chatGuid");
+  const trimmedAddress = address.trim();
+  if (!trimmedAddress) throw new Error("BlueBubbles addParticipant requires address");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address: trimmedAddress }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles addParticipant failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Remove a participant from a group chat via BlueBubbles API.
+ */
+export async function removeBlueBubblesParticipant(
+  chatGuid: string,
+  address: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles removeParticipant requires chatGuid");
+  const trimmedAddress = address.trim();
+  if (!trimmedAddress) throw new Error("BlueBubbles removeParticipant requires address");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address: trimmedAddress }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles removeParticipant failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Leave a group chat via BlueBubbles API.
+ */
+export async function leaveBlueBubblesChat(
+  chatGuid: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles leaveChat requires chatGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/leave`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    { method: "POST" },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles leaveChat failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Set a group chat's icon/photo via BlueBubbles API.
+ * Requires Private API to be enabled.
+ */
+export async function setGroupIconBlueBubbles(
+  chatGuid: string,
+  buffer: Uint8Array,
+  filename: string,
+  opts: BlueBubblesChatOpts & { contentType?: string } = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles setGroupIcon requires chatGuid");
+  if (!buffer || buffer.length === 0) {
+    throw new Error("BlueBubbles setGroupIcon requires image buffer");
+  }
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/icon`,
+    password,
+  });
+
+  // Build multipart form-data
+  const boundary = `----BlueBubblesFormBoundary${crypto.randomUUID().replace(/-/g, "")}`;
+  const parts: Uint8Array[] = [];
+  const encoder = new TextEncoder();
+
+  // Add file field named "icon" as per API spec
+  parts.push(encoder.encode(`--${boundary}\r\n`));
+  parts.push(
+    encoder.encode(
+      `Content-Disposition: form-data; name="icon"; filename="${filename}"\r\n`,
+    ),
+  );
+  parts.push(
+    encoder.encode(`Content-Type: ${opts.contentType ?? "application/octet-stream"}\r\n\r\n`),
+  );
+  parts.push(buffer);
+  parts.push(encoder.encode("\r\n"));
+
+  // Close multipart body
+  parts.push(encoder.encode(`--${boundary}--\r\n`));
+
+  // Combine into single buffer
+  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
+  const body = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    body.set(part, offset);
+    offset += part.length;
+  }
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      },
+      body,
+    },
+    opts.timeoutMs ?? 60_000, // longer timeout for file uploads
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles setGroupIcon failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/config-schema.ts

@@ -0,0 +1,51 @@
+import { MarkdownConfigSchema, ToolPolicySchema } from "clawdbot/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const bluebubblesActionSchema = z
+  .object({
+    reactions: z.boolean().default(true),
+    edit: z.boolean().default(true),
+    unsend: z.boolean().default(true),
+    reply: z.boolean().default(true),
+    sendWithEffect: z.boolean().default(true),
+    renameGroup: z.boolean().default(true),
+    setGroupIcon: z.boolean().default(true),
+    addParticipant: z.boolean().default(true),
+    removeParticipant: z.boolean().default(true),
+    leaveGroup: z.boolean().default(true),
+    sendAttachment: z.boolean().default(true),
+  })
+  .optional();
+
+const bluebubblesGroupConfigSchema = z.object({
+  requireMention: z.boolean().optional(),
+  tools: ToolPolicySchema,
+});
+
+const bluebubblesAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema,
+  serverUrl: z.string().optional(),
+  password: z.string().optional(),
+  webhookPath: z.string().optional(),
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+  allowFrom: z.array(allowFromEntry).optional(),
+  groupAllowFrom: z.array(allowFromEntry).optional(),
+  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
+  historyLimit: z.number().int().min(0).optional(),
+  dmHistoryLimit: z.number().int().min(0).optional(),
+  textChunkLimit: z.number().int().positive().optional(),
+  chunkMode: z.enum(["length", "newline"]).optional(),
+  mediaMaxMb: z.number().int().positive().optional(),
+  sendReadReceipts: z.boolean().optional(),
+  blockStreaming: z.boolean().optional(),
+  groups: z.object({}).catchall(bluebubblesGroupConfigSchema).optional(),
+});
+
+export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
+  accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),
+  actions: bluebubblesActionSchema,
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/media-send.ts

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveChannelMediaMaxBytes, type MoltbotConfig } from "clawdbot/plugin-sdk";
+
+import { sendBlueBubblesAttachment } from "./attachments.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { getBlueBubblesRuntime } from "./runtime.js";
+import { sendMessageBlueBubbles } from "./send.js";
+
+const HTTP_URL_RE = /^https?:\/\//i;
+const MB = 1024 * 1024;
+
+function assertMediaWithinLimit(sizeBytes: number, maxBytes?: number): void {
+  if (typeof maxBytes !== "number" || maxBytes <= 0) return;
+  if (sizeBytes <= maxBytes) return;
+  const maxLabel = (maxBytes / MB).toFixed(0);
+  const sizeLabel = (sizeBytes / MB).toFixed(2);
+  throw new Error(`Media exceeds ${maxLabel}MB limit (got ${sizeLabel}MB)`);
+}
+
+function resolveLocalMediaPath(source: string): string {
+  if (!source.startsWith("file://")) return source;
+  try {
+    return fileURLToPath(source);
+  } catch {
+    throw new Error(`Invalid file:// URL: ${source}`);
+  }
+}
+
+function resolveFilenameFromSource(source?: string): string | undefined {
+  if (!source) return undefined;
+  if (source.startsWith("file://")) {
+    try {
+      return path.basename(fileURLToPath(source)) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  if (HTTP_URL_RE.test(source)) {
+    try {
+      return path.basename(new URL(source).pathname) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const base = path.basename(source);
+  return base || undefined;
+}
+
+export async function sendBlueBubblesMedia(params: {
+  cfg: MoltbotConfig;
+  to: string;
+  mediaUrl?: string;
+  mediaPath?: string;
+  mediaBuffer?: Uint8Array;
+  contentType?: string;
+  filename?: string;
+  caption?: string;
+  replyToId?: string | null;
+  accountId?: string;
+  asVoice?: boolean;
+}) {
+  const {
+    cfg,
+    to,
+    mediaUrl,
+    mediaPath,
+    mediaBuffer,
+    contentType,
+    filename,
+    caption,
+    replyToId,
+    accountId,
+    asVoice,
+  } = params;
+  const core = getBlueBubblesRuntime();
+  const maxBytes = resolveChannelMediaMaxBytes({
+    cfg,
+    resolveChannelLimitMb: ({ cfg, accountId }) =>
+      cfg.channels?.bluebubbles?.accounts?.[accountId]?.mediaMaxMb ??
+      cfg.channels?.bluebubbles?.mediaMaxMb,
+    accountId,
+  });
+
+  let buffer: Uint8Array;
+  let resolvedContentType = contentType ?? undefined;
+  let resolvedFilename = filename ?? undefined;
+
+  if (mediaBuffer) {
+    assertMediaWithinLimit(mediaBuffer.byteLength, maxBytes);
+    buffer = mediaBuffer;
+    if (!resolvedContentType) {
+      const hint = mediaPath ?? mediaUrl;
+      const detected = await core.media.detectMime({
+        buffer: Buffer.isBuffer(mediaBuffer) ? mediaBuffer : Buffer.from(mediaBuffer),
+        filePath: hint,
+      });
+      resolvedContentType = detected ?? undefined;
+    }
+    if (!resolvedFilename) {
+      resolvedFilename = resolveFilenameFromSource(mediaPath ?? mediaUrl);
+    }
+  } else {
+    const source = mediaPath ?? mediaUrl;
+    if (!source) {
+      throw new Error("BlueBubbles media delivery requires mediaUrl, mediaPath, or mediaBuffer.");
+    }
+    if (HTTP_URL_RE.test(source)) {
+      const fetched = await core.channel.media.fetchRemoteMedia({
+        url: source,
+        maxBytes: typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : undefined,
+      });
+      buffer = fetched.buffer;
+      resolvedContentType = resolvedContentType ?? fetched.contentType ?? undefined;
+      resolvedFilename = resolvedFilename ?? fetched.fileName;
+    } else {
+      const localPath = resolveLocalMediaPath(source);
+      const fs = await import("node:fs/promises");
+      if (typeof maxBytes === "number" && maxBytes > 0) {
+        const stats = await fs.stat(localPath);
+        assertMediaWithinLimit(stats.size, maxBytes);
+      }
+      const data = await fs.readFile(localPath);
+      assertMediaWithinLimit(data.byteLength, maxBytes);
+      buffer = new Uint8Array(data);
+      if (!resolvedContentType) {
+        const detected = await core.media.detectMime({
+          buffer: data,
+          filePath: localPath,
+        });
+        resolvedContentType = detected ?? undefined;
+      }
+      if (!resolvedFilename) {
+        resolvedFilename = resolveFilenameFromSource(localPath);
+      }
+    }
+  }
+
+  // Resolve short ID (e.g., "5") to full UUID
+  const replyToMessageGuid = replyToId?.trim()
+    ? resolveBlueBubblesMessageId(replyToId.trim(), { requireKnownShortId: true })
+    : undefined;
+
+  const attachmentResult = await sendBlueBubblesAttachment({
+    to,
+    buffer,
+    filename: resolvedFilename ?? "attachment",
+    contentType: resolvedContentType ?? undefined,
+    replyToMessageGuid,
+    asVoice,
+    opts: {
+      cfg,
+      accountId,
+    },
+  });
+
+  const trimmedCaption = caption?.trim();
+  if (trimmedCaption) {
+    await sendMessageBlueBubbles(to, trimmedCaption, {
+      cfg,
+      accountId,
+      replyToMessageGuid,
+    });
+  }
+
+  return attachmentResult;
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/onboarding.ts

@@ -0,0 +1,340 @@
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  MoltbotConfig,
+  DmPolicy,
+  WizardPrompter,
+} from "clawdbot/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  addWildcardAllowFrom,
+  formatDocsLink,
+  normalizeAccountId,
+  promptAccountId,
+} from "clawdbot/plugin-sdk";
+import {
+  listBlueBubblesAccountIds,
+  resolveBlueBubblesAccount,
+  resolveDefaultBlueBubblesAccountId,
+} from "./accounts.js";
+import { normalizeBlueBubblesServerUrl } from "./types.js";
+import { parseBlueBubblesAllowTarget, normalizeBlueBubblesHandle } from "./targets.js";
+
+const channel = "bluebubbles" as const;
+
+function setBlueBubblesDmPolicy(cfg: MoltbotConfig, dmPolicy: DmPolicy): MoltbotConfig {
+  const allowFrom =
+    dmPolicy === "open" ? addWildcardAllowFrom(cfg.channels?.bluebubbles?.allowFrom) : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      bluebubbles: {
+        ...cfg.channels?.bluebubbles,
+        dmPolicy,
+        ...(allowFrom ? { allowFrom } : {}),
+      },
+    },
+  };
+}
+
+function setBlueBubblesAllowFrom(
+  cfg: MoltbotConfig,
+  accountId: string,
+  allowFrom: string[],
+): MoltbotConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        bluebubbles: {
+          ...cfg.channels?.bluebubbles,
+          allowFrom,
+        },
+      },
+    };
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      bluebubbles: {
+        ...cfg.channels?.bluebubbles,
+        accounts: {
+          ...cfg.channels?.bluebubbles?.accounts,
+          [accountId]: {
+            ...cfg.channels?.bluebubbles?.accounts?.[accountId],
+            allowFrom,
+          },
+        },
+      },
+    },
+  };
+}
+
+function parseBlueBubblesAllowFromInput(raw: string): string[] {
+  return raw
+    .split(/[\n,]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+async function promptBlueBubblesAllowFrom(params: {
+  cfg: MoltbotConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<MoltbotConfig> {
+  const accountId =
+    params.accountId && normalizeAccountId(params.accountId)
+      ? (normalizeAccountId(params.accountId) ?? DEFAULT_ACCOUNT_ID)
+      : resolveDefaultBlueBubblesAccountId(params.cfg);
+  const resolved = resolveBlueBubblesAccount({ cfg: params.cfg, accountId });
+  const existing = resolved.config.allowFrom ?? [];
+  await params.prompter.note(
+    [
+      "Allowlist BlueBubbles DMs by handle or chat target.",
+      "Examples:",
+      "- +15555550123",
+      "- user@example.com",
+      "- chat_id:123",
+      "- chat_guid:iMessage;-;+15555550123",
+      "Multiple entries: comma- or newline-separated.",
+      `Docs: ${formatDocsLink("/channels/bluebubbles", "bluebubbles")}`,
+    ].join("\n"),
+    "BlueBubbles allowlist",
+  );
+  const entry = await params.prompter.text({
+    message: "BlueBubbles allowFrom (handle or chat_id)",
+    placeholder: "+15555550123, user@example.com, chat_id:123",
+    initialValue: existing[0] ? String(existing[0]) : undefined,
+    validate: (value) => {
+      const raw = String(value ?? "").trim();
+      if (!raw) return "Required";
+      const parts = parseBlueBubblesAllowFromInput(raw);
+      for (const part of parts) {
+        if (part === "*") continue;
+        const parsed = parseBlueBubblesAllowTarget(part);
+        if (parsed.kind === "handle" && !parsed.handle) {
+          return `Invalid entry: ${part}`;
+        }
+      }
+      return undefined;
+    },
+  });
+  const parts = parseBlueBubblesAllowFromInput(String(entry));
+  const unique = [...new Set(parts)];
+  return setBlueBubblesAllowFrom(params.cfg, accountId, unique);
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "BlueBubbles",
+  channel,
+  policyKey: "channels.bluebubbles.dmPolicy",
+  allowFromKey: "channels.bluebubbles.allowFrom",
+  getCurrent: (cfg) => cfg.channels?.bluebubbles?.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy) => setBlueBubblesDmPolicy(cfg, policy),
+  promptAllowFrom: promptBlueBubblesAllowFrom,
+};
+
+export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const configured = listBlueBubblesAccountIds(cfg).some((accountId) => {
+      const account = resolveBlueBubblesAccount({ cfg, accountId });
+      return account.configured;
+    });
+    return {
+      channel,
+      configured,
+      statusLines: [`BlueBubbles: ${configured ? "configured" : "needs setup"}`],
+      selectionHint: configured ? "configured" : "iMessage via BlueBubbles app",
+      quickstartScore: configured ? 1 : 0,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds }) => {
+    const blueBubblesOverride = accountOverrides.bluebubbles?.trim();
+    const defaultAccountId = resolveDefaultBlueBubblesAccountId(cfg);
+    let accountId = blueBubblesOverride
+      ? normalizeAccountId(blueBubblesOverride)
+      : defaultAccountId;
+    if (shouldPromptAccountIds && !blueBubblesOverride) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "BlueBubbles",
+        currentId: accountId,
+        listAccountIds: listBlueBubblesAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+    const resolvedAccount = resolveBlueBubblesAccount({ cfg: next, accountId });
+
+    // Prompt for server URL
+    let serverUrl = resolvedAccount.config.serverUrl?.trim();
+    if (!serverUrl) {
+      await prompter.note(
+        [
+          "Enter the BlueBubbles server URL (e.g., http://192.168.1.100:1234).",
+          "Find this in the BlueBubbles Server app under Connection.",
+          `Docs: ${formatDocsLink("/channels/bluebubbles", "bluebubbles")}`,
+        ].join("\n"),
+        "BlueBubbles server URL",
+      );
+      const entered = await prompter.text({
+        message: "BlueBubbles server URL",
+        placeholder: "http://192.168.1.100:1234",
+        validate: (value) => {
+          const trimmed = String(value ?? "").trim();
+          if (!trimmed) return "Required";
+          try {
+            const normalized = normalizeBlueBubblesServerUrl(trimmed);
+            new URL(normalized);
+            return undefined;
+          } catch {
+            return "Invalid URL format";
+          }
+        },
+      });
+      serverUrl = String(entered).trim();
+    } else {
+      const keepUrl = await prompter.confirm({
+        message: `BlueBubbles server URL already set (${serverUrl}). Keep it?`,
+        initialValue: true,
+      });
+      if (!keepUrl) {
+        const entered = await prompter.text({
+          message: "BlueBubbles server URL",
+          placeholder: "http://192.168.1.100:1234",
+          initialValue: serverUrl,
+          validate: (value) => {
+            const trimmed = String(value ?? "").trim();
+            if (!trimmed) return "Required";
+            try {
+              const normalized = normalizeBlueBubblesServerUrl(trimmed);
+              new URL(normalized);
+              return undefined;
+            } catch {
+              return "Invalid URL format";
+            }
+          },
+        });
+        serverUrl = String(entered).trim();
+      }
+    }
+
+    // Prompt for password
+    let password = resolvedAccount.config.password?.trim();
+    if (!password) {
+      await prompter.note(
+        [
+          "Enter the BlueBubbles server password.",
+          "Find this in the BlueBubbles Server app under Settings.",
+        ].join("\n"),
+        "BlueBubbles password",
+      );
+      const entered = await prompter.text({
+        message: "BlueBubbles password",
+        validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+      });
+      password = String(entered).trim();
+    } else {
+      const keepPassword = await prompter.confirm({
+        message: "BlueBubbles password already set. Keep it?",
+        initialValue: true,
+      });
+      if (!keepPassword) {
+        const entered = await prompter.text({
+          message: "BlueBubbles password",
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        });
+        password = String(entered).trim();
+      }
+    }
+
+    // Prompt for webhook path (optional)
+    const existingWebhookPath = resolvedAccount.config.webhookPath?.trim();
+    const wantsWebhook = await prompter.confirm({
+      message: "Configure a custom webhook path? (default: /bluebubbles-webhook)",
+      initialValue: Boolean(existingWebhookPath && existingWebhookPath !== "/bluebubbles-webhook"),
+    });
+    let webhookPath = "/bluebubbles-webhook";
+    if (wantsWebhook) {
+      const entered = await prompter.text({
+        message: "Webhook path",
+        placeholder: "/bluebubbles-webhook",
+        initialValue: existingWebhookPath || "/bluebubbles-webhook",
+        validate: (value) => {
+          const trimmed = String(value ?? "").trim();
+          if (!trimmed) return "Required";
+          if (!trimmed.startsWith("/")) return "Path must start with /";
+          return undefined;
+        },
+      });
+      webhookPath = String(entered).trim();
+    }
+
+    // Apply config
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          bluebubbles: {
+            ...next.channels?.bluebubbles,
+            enabled: true,
+            serverUrl,
+            password,
+            webhookPath,
+          },
+        },
+      };
+    } else {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          bluebubbles: {
+            ...next.channels?.bluebubbles,
+            enabled: true,
+            accounts: {
+              ...next.channels?.bluebubbles?.accounts,
+              [accountId]: {
+                ...next.channels?.bluebubbles?.accounts?.[accountId],
+                enabled: next.channels?.bluebubbles?.accounts?.[accountId]?.enabled ?? true,
+                serverUrl,
+                password,
+                webhookPath,
+              },
+            },
+          },
+        },
+      };
+    }
+
+    await prompter.note(
+      [
+        "Configure the webhook URL in BlueBubbles Server:",
+        "1. Open BlueBubbles Server → Settings → Webhooks",
+        "2. Add your Moltbot gateway URL + webhook path",
+        "   Example: https://your-gateway-host:3000/bluebubbles-webhook",
+        "3. Enable the webhook and save",
+        "",
+        `Docs: ${formatDocsLink("/channels/bluebubbles", "bluebubbles")}`,
+      ].join("\n"),
+      "BlueBubbles next steps",
+    );
+
+    return { cfg: next, accountId };
+  },
+  dmPolicy,
+  disable: (cfg) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      bluebubbles: { ...cfg.channels?.bluebubbles, enabled: false },
+    },
+  }),
+};

docker-compose/ez-assistant/extensions/bluebubbles/src/probe.ts

@@ -0,0 +1,127 @@
+import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
+
+export type BlueBubblesProbe = {
+  ok: boolean;
+  status?: number | null;
+  error?: string | null;
+};
+
+export type BlueBubblesServerInfo = {
+  os_version?: string;
+  server_version?: string;
+  private_api?: boolean;
+  helper_connected?: boolean;
+  proxy_service?: string;
+  detected_icloud?: string;
+  computer_id?: string;
+};
+
+/** Cache server info by account ID to avoid repeated API calls */
+const serverInfoCache = new Map<string, { info: BlueBubblesServerInfo; expires: number }>();
+const CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+function buildCacheKey(accountId?: string): string {
+  return accountId?.trim() || "default";
+}
+
+/**
+ * Fetch server info from BlueBubbles API and cache it.
+ * Returns cached result if available and not expired.
+ */
+export async function fetchBlueBubblesServerInfo(params: {
+  baseUrl?: string | null;
+  password?: string | null;
+  accountId?: string;
+  timeoutMs?: number;
+}): Promise<BlueBubblesServerInfo | null> {
+  const baseUrl = params.baseUrl?.trim();
+  const password = params.password?.trim();
+  if (!baseUrl || !password) return null;
+
+  const cacheKey = buildCacheKey(params.accountId);
+  const cached = serverInfoCache.get(cacheKey);
+  if (cached && cached.expires > Date.now()) {
+    return cached.info;
+  }
+
+  const url = buildBlueBubblesApiUrl({ baseUrl, path: "/api/v1/server/info", password });
+  try {
+    const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, params.timeoutMs ?? 5000);
+    if (!res.ok) return null;
+    const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
+    const data = payload?.data as BlueBubblesServerInfo | undefined;
+    if (data) {
+      serverInfoCache.set(cacheKey, { info: data, expires: Date.now() + CACHE_TTL_MS });
+    }
+    return data ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get cached server info synchronously (for use in listActions).
+ * Returns null if not cached or expired.
+ */
+export function getCachedBlueBubblesServerInfo(accountId?: string): BlueBubblesServerInfo | null {
+  const cacheKey = buildCacheKey(accountId);
+  const cached = serverInfoCache.get(cacheKey);
+  if (cached && cached.expires > Date.now()) {
+    return cached.info;
+  }
+  return null;
+}
+
+/**
+ * Parse macOS version string (e.g., "15.0.1" or "26.0") into major version number.
+ */
+export function parseMacOSMajorVersion(version?: string | null): number | null {
+  if (!version) return null;
+  const match = /^(\d+)/.exec(version.trim());
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+/**
+ * Check if the cached server info indicates macOS 26 or higher.
+ * Returns false if no cached info is available (fail open for action listing).
+ */
+export function isMacOS26OrHigher(accountId?: string): boolean {
+  const info = getCachedBlueBubblesServerInfo(accountId);
+  if (!info?.os_version) return false;
+  const major = parseMacOSMajorVersion(info.os_version);
+  return major !== null && major >= 26;
+}
+
+/** Clear the server info cache (for testing) */
+export function clearServerInfoCache(): void {
+  serverInfoCache.clear();
+}
+
+export async function probeBlueBubbles(params: {
+  baseUrl?: string | null;
+  password?: string | null;
+  timeoutMs?: number;
+}): Promise<BlueBubblesProbe> {
+  const baseUrl = params.baseUrl?.trim();
+  const password = params.password?.trim();
+  if (!baseUrl) return { ok: false, error: "serverUrl not configured" };
+  if (!password) return { ok: false, error: "password not configured" };
+  const url = buildBlueBubblesApiUrl({ baseUrl, path: "/api/v1/ping", password });
+  try {
+    const res = await blueBubblesFetchWithTimeout(
+      url,
+      { method: "GET" },
+      params.timeoutMs,
+    );
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return {
+      ok: false,
+      status: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/reactions.test.ts

@@ -0,0 +1,393 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import { sendBlueBubblesReaction } from "./reactions.js";
+
+vi.mock("./accounts.js", () => ({
+  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
+    const config = cfg?.channels?.bluebubbles ?? {};
+    return {
+      accountId: accountId ?? "default",
+      enabled: config.enabled !== false,
+      configured: Boolean(config.serverUrl && config.password),
+      config,
+    };
+  }),
+}));
+
+const mockFetch = vi.fn();
+
+describe("reactions", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("sendBlueBubblesReaction", () => {
+    it("throws when chatGuid is empty", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "",
+          messageGuid: "msg-123",
+          emoji: "love",
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        }),
+      ).rejects.toThrow("chatGuid");
+    });
+
+    it("throws when messageGuid is empty", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "",
+          emoji: "love",
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        }),
+      ).rejects.toThrow("messageGuid");
+    });
+
+    it("throws when emoji is empty", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "",
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        }),
+      ).rejects.toThrow("emoji or name");
+    });
+
+    it("throws when serverUrl is missing", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "love",
+          opts: {},
+        }),
+      ).rejects.toThrow("serverUrl is required");
+    });
+
+    it("throws when password is missing", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "love",
+          opts: {
+            serverUrl: "http://localhost:1234",
+          },
+        }),
+      ).rejects.toThrow("password is required");
+    });
+
+    it("throws for unsupported reaction type", async () => {
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "unsupported",
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        }),
+      ).rejects.toThrow("Unsupported BlueBubbles reaction");
+    });
+
+    describe("reaction type normalization", () => {
+      const testCases = [
+        { input: "love", expected: "love" },
+        { input: "like", expected: "like" },
+        { input: "dislike", expected: "dislike" },
+        { input: "laugh", expected: "laugh" },
+        { input: "emphasize", expected: "emphasize" },
+        { input: "question", expected: "question" },
+        { input: "heart", expected: "love" },
+        { input: "thumbs_up", expected: "like" },
+        { input: "thumbs-down", expected: "dislike" },
+        { input: "thumbs_down", expected: "dislike" },
+        { input: "haha", expected: "laugh" },
+        { input: "lol", expected: "laugh" },
+        { input: "emphasis", expected: "emphasize" },
+        { input: "exclaim", expected: "emphasize" },
+        { input: "❤️", expected: "love" },
+        { input: "❤", expected: "love" },
+        { input: "♥️", expected: "love" },
+        { input: "😍", expected: "love" },
+        { input: "👍", expected: "like" },
+        { input: "👎", expected: "dislike" },
+        { input: "😂", expected: "laugh" },
+        { input: "🤣", expected: "laugh" },
+        { input: "😆", expected: "laugh" },
+        { input: "‼️", expected: "emphasize" },
+        { input: "‼", expected: "emphasize" },
+        { input: "❗", expected: "emphasize" },
+        { input: "❓", expected: "question" },
+        { input: "❔", expected: "question" },
+        { input: "LOVE", expected: "love" },
+        { input: "Like", expected: "like" },
+      ];
+
+      for (const { input, expected } of testCases) {
+        it(`normalizes "${input}" to "${expected}"`, async () => {
+          mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: () => Promise.resolve(""),
+          });
+
+          await sendBlueBubblesReaction({
+            chatGuid: "chat-123",
+            messageGuid: "msg-123",
+            emoji: input,
+            opts: {
+              serverUrl: "http://localhost:1234",
+              password: "test",
+            },
+          });
+
+          const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+          expect(body.reaction).toBe(expected);
+        });
+      }
+    });
+
+    it("sends reaction successfully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "iMessage;-;+15551234567",
+        messageGuid: "msg-uuid-123",
+        emoji: "love",
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "test-password",
+        },
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/message/react"),
+        expect.objectContaining({
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.chatGuid).toBe("iMessage;-;+15551234567");
+      expect(body.selectedMessageGuid).toBe("msg-uuid-123");
+      expect(body.reaction).toBe("love");
+      expect(body.partIndex).toBe(0);
+    });
+
+    it("includes password in URL query", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "chat-123",
+        messageGuid: "msg-123",
+        emoji: "like",
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "my-react-password",
+        },
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("password=my-react-password");
+    });
+
+    it("sends reaction removal with dash prefix", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "chat-123",
+        messageGuid: "msg-123",
+        emoji: "love",
+        remove: true,
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        },
+      });
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.reaction).toBe("-love");
+    });
+
+    it("strips leading dash from emoji when remove flag is set", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "chat-123",
+        messageGuid: "msg-123",
+        emoji: "-love",
+        remove: true,
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        },
+      });
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.reaction).toBe("-love");
+    });
+
+    it("uses custom partIndex when provided", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "chat-123",
+        messageGuid: "msg-123",
+        emoji: "laugh",
+        partIndex: 3,
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        },
+      });
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.partIndex).toBe(3);
+    });
+
+    it("throws on non-ok response", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        text: () => Promise.resolve("Invalid reaction type"),
+      });
+
+      await expect(
+        sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "like",
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        }),
+      ).rejects.toThrow("reaction failed (400): Invalid reaction type");
+    });
+
+    it("resolves credentials from config", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "chat-123",
+        messageGuid: "msg-123",
+        emoji: "emphasize",
+        opts: {
+          cfg: {
+            channels: {
+              bluebubbles: {
+                serverUrl: "http://react-server:7777",
+                password: "react-pass",
+              },
+            },
+          },
+        },
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("react-server:7777");
+      expect(calledUrl).toContain("password=react-pass");
+    });
+
+    it("trims chatGuid and messageGuid", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve(""),
+      });
+
+      await sendBlueBubblesReaction({
+        chatGuid: "  chat-with-spaces  ",
+        messageGuid: "  msg-with-spaces  ",
+        emoji: "question",
+        opts: {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        },
+      });
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.chatGuid).toBe("chat-with-spaces");
+      expect(body.selectedMessageGuid).toBe("msg-with-spaces");
+    });
+
+    describe("reaction removal aliases", () => {
+      it("handles emoji-based removal", async () => {
+        mockFetch.mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(""),
+        });
+
+        await sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "👍",
+          remove: true,
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        });
+
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        expect(body.reaction).toBe("-like");
+      });
+
+      it("handles text alias removal", async () => {
+        mockFetch.mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(""),
+        });
+
+        await sendBlueBubblesReaction({
+          chatGuid: "chat-123",
+          messageGuid: "msg-123",
+          emoji: "haha",
+          remove: true,
+          opts: {
+            serverUrl: "http://localhost:1234",
+            password: "test",
+          },
+        });
+
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        expect(body.reaction).toBe("-laugh");
+      });
+    });
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/reactions.ts

@@ -0,0 +1,183 @@
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesReactionOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: MoltbotConfig;
+};
+
+const REACTION_TYPES = new Set([
+  "love",
+  "like",
+  "dislike",
+  "laugh",
+  "emphasize",
+  "question",
+]);
+
+const REACTION_ALIASES = new Map<string, string>([
+  // General
+  ["heart", "love"],
+  ["love", "love"],
+  ["❤", "love"],
+  ["❤️", "love"],
+  ["red_heart", "love"],
+  ["thumbs_up", "like"],
+  ["thumbsup", "like"],
+  ["thumbs-up", "like"],
+  ["thumbsup", "like"],
+  ["like", "like"],
+  ["thumb", "like"],
+  ["ok", "like"],
+  ["thumbs_down", "dislike"],
+  ["thumbsdown", "dislike"],
+  ["thumbs-down", "dislike"],
+  ["dislike", "dislike"],
+  ["boo", "dislike"],
+  ["no", "dislike"],
+  // Laugh
+  ["haha", "laugh"],
+  ["lol", "laugh"],
+  ["lmao", "laugh"],
+  ["rofl", "laugh"],
+  ["😂", "laugh"],
+  ["🤣", "laugh"],
+  ["xd", "laugh"],
+  ["laugh", "laugh"],
+  // Emphasize / exclaim
+  ["emphasis", "emphasize"],
+  ["emphasize", "emphasize"],
+  ["exclaim", "emphasize"],
+  ["!!", "emphasize"],
+  ["‼", "emphasize"],
+  ["‼️", "emphasize"],
+  ["❗", "emphasize"],
+  ["important", "emphasize"],
+  ["bang", "emphasize"],
+  // Question
+  ["question", "question"],
+  ["?", "question"],
+  ["❓", "question"],
+  ["❔", "question"],
+  ["ask", "question"],
+  // Apple/Messages names
+  ["loved", "love"],
+  ["liked", "like"],
+  ["disliked", "dislike"],
+  ["laughed", "laugh"],
+  ["emphasized", "emphasize"],
+  ["questioned", "question"],
+  // Colloquial / informal
+  ["fire", "love"],
+  ["🔥", "love"],
+  ["wow", "emphasize"],
+  ["!", "emphasize"],
+  // Edge: generic emoji name forms
+  ["heart_eyes", "love"],
+  ["smile", "laugh"],
+  ["smiley", "laugh"],
+  ["happy", "laugh"],
+  ["joy", "laugh"],
+]);
+
+const REACTION_EMOJIS = new Map<string, string>([
+  // Love
+  ["❤️", "love"],
+  ["❤", "love"],
+  ["♥️", "love"],
+  ["♥", "love"],
+  ["😍", "love"],
+  ["💕", "love"],
+  // Like
+  ["👍", "like"],
+  ["👌", "like"],
+  // Dislike
+  ["👎", "dislike"],
+  ["🙅", "dislike"],
+  // Laugh
+  ["😂", "laugh"],
+  ["🤣", "laugh"],
+  ["😆", "laugh"],
+  ["😁", "laugh"],
+  ["😹", "laugh"],
+  // Emphasize
+  ["‼️", "emphasize"],
+  ["‼", "emphasize"],
+  ["!!", "emphasize"],
+  ["❗", "emphasize"],
+  ["❕", "emphasize"],
+  ["!", "emphasize"],
+  // Question
+  ["❓", "question"],
+  ["❔", "question"],
+  ["?", "question"],
+]);
+
+function resolveAccount(params: BlueBubblesReactionOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export function normalizeBlueBubblesReactionInput(emoji: string, remove?: boolean): string {
+  const trimmed = emoji.trim();
+  if (!trimmed) throw new Error("BlueBubbles reaction requires an emoji or name.");
+  let raw = trimmed.toLowerCase();
+  if (raw.startsWith("-")) raw = raw.slice(1);
+  const aliased = REACTION_ALIASES.get(raw) ?? raw;
+  const mapped = REACTION_EMOJIS.get(trimmed) ?? REACTION_EMOJIS.get(raw) ?? aliased;
+  if (!REACTION_TYPES.has(mapped)) {
+    throw new Error(`Unsupported BlueBubbles reaction: ${trimmed}`);
+  }
+  return remove ? `-${mapped}` : mapped;
+}
+
+export async function sendBlueBubblesReaction(params: {
+  chatGuid: string;
+  messageGuid: string;
+  emoji: string;
+  remove?: boolean;
+  partIndex?: number;
+  opts?: BlueBubblesReactionOpts;
+}): Promise<void> {
+  const chatGuid = params.chatGuid.trim();
+  const messageGuid = params.messageGuid.trim();
+  if (!chatGuid) throw new Error("BlueBubbles reaction requires chatGuid.");
+  if (!messageGuid) throw new Error("BlueBubbles reaction requires messageGuid.");
+  const reaction = normalizeBlueBubblesReactionInput(params.emoji, params.remove);
+  const { baseUrl, password } = resolveAccount(params.opts ?? {});
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: "/api/v1/message/react",
+    password,
+  });
+  const payload = {
+    chatGuid,
+    selectedMessageGuid: messageGuid,
+    reaction,
+    partIndex: typeof params.partIndex === "number" ? params.partIndex : 0,
+  };
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    params.opts?.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`BlueBubbles reaction failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setBlueBubblesRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getBlueBubblesRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("BlueBubbles runtime not initialized");
+  }
+  return runtime;
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/send.test.ts

@@ -0,0 +1,809 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import { sendMessageBlueBubbles, resolveChatGuidForTarget } from "./send.js";
+import type { BlueBubblesSendTarget } from "./types.js";
+
+vi.mock("./accounts.js", () => ({
+  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
+    const config = cfg?.channels?.bluebubbles ?? {};
+    return {
+      accountId: accountId ?? "default",
+      enabled: config.enabled !== false,
+      configured: Boolean(config.serverUrl && config.password),
+      config,
+    };
+  }),
+}));
+
+const mockFetch = vi.fn();
+
+describe("send", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("resolveChatGuidForTarget", () => {
+    it("returns chatGuid directly for chat_guid target", async () => {
+      const target: BlueBubblesSendTarget = {
+        kind: "chat_guid",
+        chatGuid: "iMessage;-;+15551234567",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+      expect(result).toBe("iMessage;-;+15551234567");
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("queries chats to resolve chat_id target", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              { id: 123, guid: "iMessage;-;chat123", participants: [] },
+              { id: 456, guid: "iMessage;-;chat456", participants: [] },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = { kind: "chat_id", chatId: 456 };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;-;chat456");
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining("/api/v1/chat/query"),
+        expect.objectContaining({ method: "POST" }),
+      );
+    });
+
+    it("queries chats to resolve chat_identifier target", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                identifier: "chat123@group.imessage",
+                guid: "iMessage;-;chat123",
+                participants: [],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "chat_identifier",
+        chatIdentifier: "chat123@group.imessage",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;-;chat123");
+    });
+
+    it("matches chat_identifier against the 3rd component of chat GUID", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                guid: "iMessage;+;chat660250192681427962",
+                participants: [],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "chat_identifier",
+        chatIdentifier: "chat660250192681427962",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;+;chat660250192681427962");
+    });
+
+    it("resolves handle target by matching participant", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                guid: "iMessage;-;+15559999999",
+                participants: [{ address: "+15559999999" }],
+              },
+              {
+                guid: "iMessage;-;+15551234567",
+                participants: [{ address: "+15551234567" }],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "handle",
+        address: "+15551234567",
+        service: "imessage",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;-;+15551234567");
+    });
+
+    it("prefers direct chat guid when handle also appears in a group chat", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                guid: "iMessage;+;group-123",
+                participants: [{ address: "+15551234567" }, { address: "+15550001111" }],
+              },
+              {
+                guid: "iMessage;-;+15551234567",
+                participants: [{ address: "+15551234567" }],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "handle",
+        address: "+15551234567",
+        service: "imessage",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;-;+15551234567");
+    });
+
+    it("returns null when handle only exists in group chat (not DM)", async () => {
+      // This is the critical fix: if a phone number only exists as a participant in a group chat
+      // (no direct DM chat), we should NOT send to that group. Return null instead.
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;+;group-the-council",
+                  participants: [
+                    { address: "+12622102921" },
+                    { address: "+15550001111" },
+                    { address: "+15550002222" },
+                  ],
+                },
+              ],
+            }),
+        })
+        // Empty second page to stop pagination
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "handle",
+        address: "+12622102921",
+        service: "imessage",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      // Should return null, NOT the group chat GUID
+      expect(result).toBeNull();
+    });
+
+    it("returns null when chat not found", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ data: [] }),
+      });
+
+      const target: BlueBubblesSendTarget = { kind: "chat_id", chatId: 999 };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBeNull();
+    });
+
+    it("handles API error gracefully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+      });
+
+      const target: BlueBubblesSendTarget = { kind: "chat_id", chatId: 123 };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBeNull();
+    });
+
+    it("paginates through chats to find match", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: Array(500)
+                .fill(null)
+                .map((_, i) => ({
+                  id: i,
+                  guid: `chat-${i}`,
+                  participants: [],
+                })),
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [{ id: 555, guid: "found-chat", participants: [] }],
+            }),
+        });
+
+      const target: BlueBubblesSendTarget = { kind: "chat_id", chatId: 555 };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("found-chat");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("normalizes handle addresses for matching", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                guid: "iMessage;-;test@example.com",
+                participants: [{ address: "Test@Example.COM" }],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "handle",
+        address: "test@example.com",
+        service: "auto",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("iMessage;-;test@example.com");
+    });
+
+    it("extracts guid from various response formats", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                chatGuid: "format1-guid",
+                id: 100,
+                participants: [],
+              },
+            ],
+          }),
+      });
+
+      const target: BlueBubblesSendTarget = { kind: "chat_id", chatId: 100 };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      expect(result).toBe("format1-guid");
+    });
+  });
+
+  describe("sendMessageBlueBubbles", () => {
+    beforeEach(() => {
+      mockFetch.mockReset();
+    });
+
+    it("throws when text is empty", async () => {
+      await expect(
+        sendMessageBlueBubbles("+15551234567", "", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("requires text");
+    });
+
+    it("throws when text is whitespace only", async () => {
+      await expect(
+        sendMessageBlueBubbles("+15551234567", "   ", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("requires text");
+    });
+
+    it("throws when serverUrl is missing", async () => {
+      await expect(sendMessageBlueBubbles("+15551234567", "Hello", {})).rejects.toThrow(
+        "serverUrl is required",
+      );
+    });
+
+    it("throws when password is missing", async () => {
+      await expect(
+        sendMessageBlueBubbles("+15551234567", "Hello", {
+          serverUrl: "http://localhost:1234",
+        }),
+      ).rejects.toThrow("password is required");
+    });
+
+    it("throws when chatGuid cannot be resolved for non-handle targets", async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ data: [] }),
+      });
+
+      await expect(
+        sendMessageBlueBubbles("chat_id:999", "Hello", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("chatGuid not found");
+    });
+
+    it("sends message successfully", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { guid: "msg-uuid-123" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello world!", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("msg-uuid-123");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      const sendCall = mockFetch.mock.calls[1];
+      expect(sendCall[0]).toContain("/api/v1/message/text");
+      const body = JSON.parse(sendCall[1].body);
+      expect(body.chatGuid).toBe("iMessage;-;+15551234567");
+      expect(body.message).toBe("Hello world!");
+      expect(body.method).toBeUndefined();
+    });
+
+    it("creates a new chat when handle target is missing", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { guid: "new-msg-guid" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15550009999", "Hello new chat", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("new-msg-guid");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      const createCall = mockFetch.mock.calls[1];
+      expect(createCall[0]).toContain("/api/v1/chat/new");
+      const body = JSON.parse(createCall[1].body);
+      expect(body.addresses).toEqual(["+15550009999"]);
+      expect(body.message).toBe("Hello new chat");
+    });
+
+    it("throws when creating a new chat requires Private API", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        })
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 403,
+          text: () => Promise.resolve("Private API not enabled"),
+        });
+
+      await expect(
+        sendMessageBlueBubbles("+15550008888", "Hello", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("Private API must be enabled");
+    });
+
+    it("uses private-api when reply metadata is present", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { guid: "msg-uuid-124" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Replying", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+        replyToMessageGuid: "reply-guid-123",
+        replyToPartIndex: 1,
+      });
+
+      expect(result.messageId).toBe("msg-uuid-124");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      const sendCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(sendCall[1].body);
+      expect(body.method).toBe("private-api");
+      expect(body.selectedMessageGuid).toBe("reply-guid-123");
+      expect(body.partIndex).toBe(1);
+    });
+
+    it("normalizes effect names and uses private-api for effects", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { guid: "msg-uuid-125" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+        effectId: "invisible ink",
+      });
+
+      expect(result.messageId).toBe("msg-uuid-125");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      const sendCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(sendCall[1].body);
+      expect(body.method).toBe("private-api");
+      expect(body.effectId).toBe("com.apple.MobileSMS.expressivesend.invisibleink");
+    });
+
+    it("sends message with chat_guid target directly", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: () =>
+          Promise.resolve(
+            JSON.stringify({
+              data: { messageId: "direct-msg-123" },
+            }),
+          ),
+      });
+
+      const result = await sendMessageBlueBubbles(
+        "chat_guid:iMessage;-;direct-chat",
+        "Direct message",
+        {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        },
+      );
+
+      expect(result.messageId).toBe("direct-msg-123");
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("handles send failure", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 500,
+          text: () => Promise.resolve("Internal server error"),
+        });
+
+      await expect(
+        sendMessageBlueBubbles("+15551234567", "Hello", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("send failed (500)");
+    });
+
+    it("handles empty response body", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(""),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("ok");
+    });
+
+    it("handles invalid JSON response body", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve("not valid json"),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("ok");
+    });
+
+    it("extracts messageId from various response formats", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                id: "numeric-id-456",
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("numeric-id-456");
+    });
+
+    it("extracts messageGuid from response payload", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { messageGuid: "msg-guid-789" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("msg-guid-789");
+    });
+
+    it("resolves credentials from config", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(JSON.stringify({ data: { guid: "msg-123" } })),
+        });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        cfg: {
+          channels: {
+            bluebubbles: {
+              serverUrl: "http://config-server:5678",
+              password: "config-pass",
+            },
+          },
+        },
+      });
+
+      expect(result.messageId).toBe("msg-123");
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain("config-server:5678");
+    });
+
+    it("includes tempGuid in request payload", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;-;+15551234567",
+                  participants: [{ address: "+15551234567" }],
+                },
+              ],
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () => Promise.resolve(JSON.stringify({ data: { guid: "msg" } })),
+        });
+
+      await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      const sendCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(sendCall[1].body);
+      expect(body.tempGuid).toBeDefined();
+      expect(typeof body.tempGuid).toBe("string");
+      expect(body.tempGuid.length).toBeGreaterThan(0);
+    });
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/send.ts

@@ -0,0 +1,418 @@
+import crypto from "node:crypto";
+
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import {
+  extractHandleFromChatGuid,
+  normalizeBlueBubblesHandle,
+  parseBlueBubblesTarget,
+} from "./targets.js";
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import {
+  blueBubblesFetchWithTimeout,
+  buildBlueBubblesApiUrl,
+  type BlueBubblesSendTarget,
+} from "./types.js";
+
+export type BlueBubblesSendOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: MoltbotConfig;
+  /** Message GUID to reply to (reply threading) */
+  replyToMessageGuid?: string;
+  /** Part index for reply (default: 0) */
+  replyToPartIndex?: number;
+  /** Effect ID or short name for message effects (e.g., "slam", "balloons") */
+  effectId?: string;
+};
+
+export type BlueBubblesSendResult = {
+  messageId: string;
+};
+
+/** Maps short effect names to full Apple effect IDs */
+const EFFECT_MAP: Record<string, string> = {
+  // Bubble effects
+  slam: "com.apple.MobileSMS.expressivesend.impact",
+  loud: "com.apple.MobileSMS.expressivesend.loud",
+  gentle: "com.apple.MobileSMS.expressivesend.gentle",
+  invisible: "com.apple.MobileSMS.expressivesend.invisibleink",
+  "invisible-ink": "com.apple.MobileSMS.expressivesend.invisibleink",
+  "invisible ink": "com.apple.MobileSMS.expressivesend.invisibleink",
+  invisibleink: "com.apple.MobileSMS.expressivesend.invisibleink",
+  // Screen effects
+  echo: "com.apple.messages.effect.CKEchoEffect",
+  spotlight: "com.apple.messages.effect.CKSpotlightEffect",
+  balloons: "com.apple.messages.effect.CKHappyBirthdayEffect",
+  confetti: "com.apple.messages.effect.CKConfettiEffect",
+  love: "com.apple.messages.effect.CKHeartEffect",
+  heart: "com.apple.messages.effect.CKHeartEffect",
+  hearts: "com.apple.messages.effect.CKHeartEffect",
+  lasers: "com.apple.messages.effect.CKLasersEffect",
+  fireworks: "com.apple.messages.effect.CKFireworksEffect",
+  celebration: "com.apple.messages.effect.CKSparklesEffect",
+};
+
+function resolveEffectId(raw?: string): string | undefined {
+  if (!raw) return undefined;
+  const trimmed = raw.trim().toLowerCase();
+  if (EFFECT_MAP[trimmed]) return EFFECT_MAP[trimmed];
+  const normalized = trimmed.replace(/[\s_]+/g, "-");
+  if (EFFECT_MAP[normalized]) return EFFECT_MAP[normalized];
+  const compact = trimmed.replace(/[\s_-]+/g, "");
+  if (EFFECT_MAP[compact]) return EFFECT_MAP[compact];
+  return raw;
+}
+
+function resolveSendTarget(raw: string): BlueBubblesSendTarget {
+  const parsed = parseBlueBubblesTarget(raw);
+  if (parsed.kind === "handle") {
+    return {
+      kind: "handle",
+      address: normalizeBlueBubblesHandle(parsed.to),
+      service: parsed.service,
+    };
+  }
+  if (parsed.kind === "chat_id") {
+    return { kind: "chat_id", chatId: parsed.chatId };
+  }
+  if (parsed.kind === "chat_guid") {
+    return { kind: "chat_guid", chatGuid: parsed.chatGuid };
+  }
+  return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
+}
+
+function extractMessageId(payload: unknown): string {
+  if (!payload || typeof payload !== "object") return "unknown";
+  const record = payload as Record<string, unknown>;
+  const data =
+    record.data && typeof record.data === "object" ? (record.data as Record<string, unknown>) : null;
+  const candidates = [
+    record.messageId,
+    record.messageGuid,
+    record.message_guid,
+    record.guid,
+    record.id,
+    data?.messageId,
+    data?.messageGuid,
+    data?.message_guid,
+    data?.message_id,
+    data?.guid,
+    data?.id,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return String(candidate);
+  }
+  return "unknown";
+}
+
+type BlueBubblesChatRecord = Record<string, unknown>;
+
+function extractChatGuid(chat: BlueBubblesChatRecord): string | null {
+  const candidates = [
+    chat.chatGuid,
+    chat.guid,
+    chat.chat_guid,
+    chat.identifier,
+    chat.chatIdentifier,
+    chat.chat_identifier,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+function extractChatId(chat: BlueBubblesChatRecord): number | null {
+  const candidates = [chat.chatId, chat.id, chat.chat_id];
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
+  }
+  return null;
+}
+
+function extractChatIdentifierFromChatGuid(chatGuid: string): string | null {
+  const parts = chatGuid.split(";");
+  if (parts.length < 3) return null;
+  const identifier = parts[2]?.trim();
+  return identifier ? identifier : null;
+}
+
+function extractParticipantAddresses(chat: BlueBubblesChatRecord): string[] {
+  const raw =
+    (Array.isArray(chat.participants) ? chat.participants : null) ??
+    (Array.isArray(chat.handles) ? chat.handles : null) ??
+    (Array.isArray(chat.participantHandles) ? chat.participantHandles : null);
+  if (!raw) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry === "string") {
+      out.push(entry);
+      continue;
+    }
+    if (entry && typeof entry === "object") {
+      const record = entry as Record<string, unknown>;
+      const candidate =
+        (typeof record.address === "string" && record.address) ||
+        (typeof record.handle === "string" && record.handle) ||
+        (typeof record.id === "string" && record.id) ||
+        (typeof record.identifier === "string" && record.identifier);
+      if (candidate) out.push(candidate);
+    }
+  }
+  return out;
+}
+
+async function queryChats(params: {
+  baseUrl: string;
+  password: string;
+  timeoutMs?: number;
+  offset: number;
+  limit: number;
+}): Promise<BlueBubblesChatRecord[]> {
+  const url = buildBlueBubblesApiUrl({
+    baseUrl: params.baseUrl,
+    path: "/api/v1/chat/query",
+    password: params.password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        limit: params.limit,
+        offset: params.offset,
+        with: ["participants"],
+      }),
+    },
+    params.timeoutMs,
+  );
+  if (!res.ok) return [];
+  const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
+  const data = payload && typeof payload.data !== "undefined" ? (payload.data as unknown) : null;
+  return Array.isArray(data) ? (data as BlueBubblesChatRecord[]) : [];
+}
+
+export async function resolveChatGuidForTarget(params: {
+  baseUrl: string;
+  password: string;
+  timeoutMs?: number;
+  target: BlueBubblesSendTarget;
+}): Promise<string | null> {
+  if (params.target.kind === "chat_guid") return params.target.chatGuid;
+
+  const normalizedHandle =
+    params.target.kind === "handle" ? normalizeBlueBubblesHandle(params.target.address) : "";
+  const targetChatId = params.target.kind === "chat_id" ? params.target.chatId : null;
+  const targetChatIdentifier =
+    params.target.kind === "chat_identifier" ? params.target.chatIdentifier : null;
+
+  const limit = 500;
+  let participantMatch: string | null = null;
+  for (let offset = 0; offset < 5000; offset += limit) {
+    const chats = await queryChats({
+      baseUrl: params.baseUrl,
+      password: params.password,
+      timeoutMs: params.timeoutMs,
+      offset,
+      limit,
+    });
+    if (chats.length === 0) break;
+    for (const chat of chats) {
+      if (targetChatId != null) {
+        const chatId = extractChatId(chat);
+        if (chatId != null && chatId === targetChatId) {
+          return extractChatGuid(chat);
+        }
+      }
+      if (targetChatIdentifier) {
+        const guid = extractChatGuid(chat);
+        if (guid) {
+          // Back-compat: some callers might pass a full chat GUID.
+          if (guid === targetChatIdentifier) return guid;
+
+          // Primary match: BlueBubbles `chat_identifier:*` targets correspond to the
+          // third component of the chat GUID: `service;(+|-) ;identifier`.
+          const guidIdentifier = extractChatIdentifierFromChatGuid(guid);
+          if (guidIdentifier && guidIdentifier === targetChatIdentifier) return guid;
+        }
+
+        const identifier =
+          typeof chat.identifier === "string"
+            ? chat.identifier
+            : typeof chat.chatIdentifier === "string"
+              ? chat.chatIdentifier
+              : typeof chat.chat_identifier === "string"
+                ? chat.chat_identifier
+                : "";
+        if (identifier && identifier === targetChatIdentifier) return guid ?? extractChatGuid(chat);
+      }
+      if (normalizedHandle) {
+        const guid = extractChatGuid(chat);
+        const directHandle = guid ? extractHandleFromChatGuid(guid) : null;
+        if (directHandle && directHandle === normalizedHandle) {
+          return guid;
+        }
+        if (!participantMatch && guid) {
+          // Only consider DM chats (`;-;` separator) as participant matches.
+          // Group chats (`;+;` separator) should never match when searching by handle/phone.
+          // This prevents routing "send to +1234567890" to a group chat that contains that number.
+          const isDmChat = guid.includes(";-;");
+          if (isDmChat) {
+            const participants = extractParticipantAddresses(chat).map((entry) =>
+              normalizeBlueBubblesHandle(entry),
+            );
+            if (participants.includes(normalizedHandle)) {
+              participantMatch = guid;
+            }
+          }
+        }
+      }
+    }
+  }
+  return participantMatch;
+}
+
+/**
+ * Creates a new chat (DM) and optionally sends an initial message.
+ * Requires Private API to be enabled in BlueBubbles.
+ */
+async function createNewChatWithMessage(params: {
+  baseUrl: string;
+  password: string;
+  address: string;
+  message: string;
+  timeoutMs?: number;
+}): Promise<BlueBubblesSendResult> {
+  const url = buildBlueBubblesApiUrl({
+    baseUrl: params.baseUrl,
+    path: "/api/v1/chat/new",
+    password: params.password,
+  });
+  const payload = {
+    addresses: [params.address],
+    message: params.message,
+  };
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    params.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    // Check for Private API not enabled error
+    if (res.status === 400 || res.status === 403 || errorText.toLowerCase().includes("private api")) {
+      throw new Error(
+        `BlueBubbles send failed: Cannot create new chat - Private API must be enabled. Original error: ${errorText || res.status}`,
+      );
+    }
+    throw new Error(`BlueBubbles create chat failed (${res.status}): ${errorText || "unknown"}`);
+  }
+  const body = await res.text();
+  if (!body) return { messageId: "ok" };
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return { messageId: extractMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}
+
+export async function sendMessageBlueBubbles(
+  to: string,
+  text: string,
+  opts: BlueBubblesSendOpts = {},
+): Promise<BlueBubblesSendResult> {
+  const trimmedText = text ?? "";
+  if (!trimmedText.trim()) {
+    throw new Error("BlueBubbles send requires text");
+  }
+
+  const account = resolveBlueBubblesAccount({
+    cfg: opts.cfg ?? {},
+    accountId: opts.accountId,
+  });
+  const baseUrl = opts.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = opts.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+
+  const target = resolveSendTarget(to);
+  const chatGuid = await resolveChatGuidForTarget({
+    baseUrl,
+    password,
+    timeoutMs: opts.timeoutMs,
+    target,
+  });
+  if (!chatGuid) {
+    // If target is a phone number/handle and no existing chat found,
+    // auto-create a new DM chat using the /api/v1/chat/new endpoint
+    if (target.kind === "handle") {
+      return createNewChatWithMessage({
+        baseUrl,
+        password,
+        address: target.address,
+        message: trimmedText,
+        timeoutMs: opts.timeoutMs,
+      });
+    }
+    throw new Error(
+      "BlueBubbles send failed: chatGuid not found for target. Use a chat_guid target or ensure the chat exists.",
+    );
+  }
+  const effectId = resolveEffectId(opts.effectId);
+  const needsPrivateApi = Boolean(opts.replyToMessageGuid || effectId);
+  const payload: Record<string, unknown> = {
+    chatGuid,
+    tempGuid: crypto.randomUUID(),
+    message: trimmedText,
+  };
+  if (needsPrivateApi) {
+    payload.method = "private-api";
+  }
+
+  // Add reply threading support
+  if (opts.replyToMessageGuid) {
+    payload.selectedMessageGuid = opts.replyToMessageGuid;
+    payload.partIndex = typeof opts.replyToPartIndex === "number" ? opts.replyToPartIndex : 0;
+  }
+
+  // Add message effects support
+  if (effectId) {
+    payload.effectId = effectId;
+  }
+
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: "/api/v1/message/text",
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`BlueBubbles send failed (${res.status}): ${errorText || "unknown"}`);
+  }
+  const body = await res.text();
+  if (!body) return { messageId: "ok" };
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return { messageId: extractMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/targets.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  looksLikeBlueBubblesTargetId,
+  normalizeBlueBubblesMessagingTarget,
+  parseBlueBubblesTarget,
+  parseBlueBubblesAllowTarget,
+} from "./targets.js";
+
+describe("normalizeBlueBubblesMessagingTarget", () => {
+  it("normalizes chat_guid targets", () => {
+    expect(normalizeBlueBubblesMessagingTarget("chat_guid:ABC-123")).toBe("chat_guid:ABC-123");
+  });
+
+  it("normalizes group numeric targets to chat_id", () => {
+    expect(normalizeBlueBubblesMessagingTarget("group:123")).toBe("chat_id:123");
+  });
+
+  it("strips provider prefix and normalizes handles", () => {
+    expect(normalizeBlueBubblesMessagingTarget("bluebubbles:imessage:User@Example.com")).toBe(
+      "imessage:user@example.com",
+    );
+  });
+
+  it("extracts handle from DM chat_guid for cross-context matching", () => {
+    // DM format: service;-;handle
+    expect(normalizeBlueBubblesMessagingTarget("chat_guid:iMessage;-;+19257864429")).toBe(
+      "+19257864429",
+    );
+    expect(normalizeBlueBubblesMessagingTarget("chat_guid:SMS;-;+15551234567")).toBe(
+      "+15551234567",
+    );
+    // Email handles
+    expect(normalizeBlueBubblesMessagingTarget("chat_guid:iMessage;-;user@example.com")).toBe(
+      "user@example.com",
+    );
+  });
+
+  it("preserves group chat_guid format", () => {
+    // Group format: service;+;groupId
+    expect(normalizeBlueBubblesMessagingTarget("chat_guid:iMessage;+;chat123456789")).toBe(
+      "chat_guid:iMessage;+;chat123456789",
+    );
+  });
+
+  it("normalizes raw chat_guid values", () => {
+    expect(normalizeBlueBubblesMessagingTarget("iMessage;+;chat660250192681427962")).toBe(
+      "chat_guid:iMessage;+;chat660250192681427962",
+    );
+    expect(normalizeBlueBubblesMessagingTarget("iMessage;-;+19257864429")).toBe("+19257864429");
+  });
+
+  it("normalizes chat<digits> pattern to chat_identifier format", () => {
+    expect(normalizeBlueBubblesMessagingTarget("chat660250192681427962")).toBe(
+      "chat_identifier:chat660250192681427962",
+    );
+    expect(normalizeBlueBubblesMessagingTarget("chat123")).toBe("chat_identifier:chat123");
+    expect(normalizeBlueBubblesMessagingTarget("Chat456789")).toBe("chat_identifier:Chat456789");
+  });
+
+  it("normalizes UUID/hex chat identifiers", () => {
+    expect(normalizeBlueBubblesMessagingTarget("8b9c1a10536d4d86a336ea03ab7151cc")).toBe(
+      "chat_identifier:8b9c1a10536d4d86a336ea03ab7151cc",
+    );
+    expect(normalizeBlueBubblesMessagingTarget("1C2D3E4F-1234-5678-9ABC-DEF012345678")).toBe(
+      "chat_identifier:1C2D3E4F-1234-5678-9ABC-DEF012345678",
+    );
+  });
+});
+
+describe("looksLikeBlueBubblesTargetId", () => {
+  it("accepts chat targets", () => {
+    expect(looksLikeBlueBubblesTargetId("chat_guid:ABC-123")).toBe(true);
+  });
+
+  it("accepts email handles", () => {
+    expect(looksLikeBlueBubblesTargetId("user@example.com")).toBe(true);
+  });
+
+  it("accepts phone numbers with punctuation", () => {
+    expect(looksLikeBlueBubblesTargetId("+1 (555) 123-4567")).toBe(true);
+  });
+
+  it("accepts raw chat_guid values", () => {
+    expect(looksLikeBlueBubblesTargetId("iMessage;+;chat660250192681427962")).toBe(true);
+  });
+
+  it("accepts chat<digits> pattern as chat_id", () => {
+    expect(looksLikeBlueBubblesTargetId("chat660250192681427962")).toBe(true);
+    expect(looksLikeBlueBubblesTargetId("chat123")).toBe(true);
+    expect(looksLikeBlueBubblesTargetId("Chat456789")).toBe(true);
+  });
+
+  it("accepts UUID/hex chat identifiers", () => {
+    expect(looksLikeBlueBubblesTargetId("8b9c1a10536d4d86a336ea03ab7151cc")).toBe(true);
+    expect(looksLikeBlueBubblesTargetId("1C2D3E4F-1234-5678-9ABC-DEF012345678")).toBe(true);
+  });
+
+  it("rejects display names", () => {
+    expect(looksLikeBlueBubblesTargetId("Jane Doe")).toBe(false);
+  });
+});
+
+describe("parseBlueBubblesTarget", () => {
+  it("parses chat<digits> pattern as chat_identifier", () => {
+    expect(parseBlueBubblesTarget("chat660250192681427962")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat660250192681427962",
+    });
+    expect(parseBlueBubblesTarget("chat123")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat123",
+    });
+    expect(parseBlueBubblesTarget("Chat456789")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "Chat456789",
+    });
+  });
+
+  it("parses UUID/hex chat identifiers as chat_identifier", () => {
+    expect(parseBlueBubblesTarget("8b9c1a10536d4d86a336ea03ab7151cc")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "8b9c1a10536d4d86a336ea03ab7151cc",
+    });
+    expect(parseBlueBubblesTarget("1C2D3E4F-1234-5678-9ABC-DEF012345678")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "1C2D3E4F-1234-5678-9ABC-DEF012345678",
+    });
+  });
+
+  it("parses explicit chat_id: prefix", () => {
+    expect(parseBlueBubblesTarget("chat_id:123")).toEqual({ kind: "chat_id", chatId: 123 });
+  });
+
+  it("parses phone numbers as handles", () => {
+    expect(parseBlueBubblesTarget("+19257864429")).toEqual({
+      kind: "handle",
+      to: "+19257864429",
+      service: "auto",
+    });
+  });
+
+  it("parses raw chat_guid format", () => {
+    expect(parseBlueBubblesTarget("iMessage;+;chat660250192681427962")).toEqual({
+      kind: "chat_guid",
+      chatGuid: "iMessage;+;chat660250192681427962",
+    });
+  });
+});
+
+describe("parseBlueBubblesAllowTarget", () => {
+  it("parses chat<digits> pattern as chat_identifier", () => {
+    expect(parseBlueBubblesAllowTarget("chat660250192681427962")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat660250192681427962",
+    });
+    expect(parseBlueBubblesAllowTarget("chat123")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat123",
+    });
+  });
+
+  it("parses UUID/hex chat identifiers as chat_identifier", () => {
+    expect(parseBlueBubblesAllowTarget("8b9c1a10536d4d86a336ea03ab7151cc")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "8b9c1a10536d4d86a336ea03ab7151cc",
+    });
+    expect(parseBlueBubblesAllowTarget("1C2D3E4F-1234-5678-9ABC-DEF012345678")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "1C2D3E4F-1234-5678-9ABC-DEF012345678",
+    });
+  });
+
+  it("parses explicit chat_id: prefix", () => {
+    expect(parseBlueBubblesAllowTarget("chat_id:456")).toEqual({ kind: "chat_id", chatId: 456 });
+  });
+
+  it("parses phone numbers as handles", () => {
+    expect(parseBlueBubblesAllowTarget("+19257864429")).toEqual({
+      kind: "handle",
+      handle: "+19257864429",
+    });
+  });
+});

docker-compose/ez-assistant/extensions/bluebubbles/src/targets.ts

@@ -0,0 +1,323 @@
+export type BlueBubblesService = "imessage" | "sms" | "auto";
+
+export type BlueBubblesTarget =
+  | { kind: "chat_id"; chatId: number }
+  | { kind: "chat_guid"; chatGuid: string }
+  | { kind: "chat_identifier"; chatIdentifier: string }
+  | { kind: "handle"; to: string; service: BlueBubblesService };
+
+export type BlueBubblesAllowTarget =
+  | { kind: "chat_id"; chatId: number }
+  | { kind: "chat_guid"; chatGuid: string }
+  | { kind: "chat_identifier"; chatIdentifier: string }
+  | { kind: "handle"; handle: string };
+
+const CHAT_ID_PREFIXES = ["chat_id:", "chatid:", "chat:"];
+const CHAT_GUID_PREFIXES = ["chat_guid:", "chatguid:", "guid:"];
+const CHAT_IDENTIFIER_PREFIXES = ["chat_identifier:", "chatidentifier:", "chatident:"];
+const SERVICE_PREFIXES: Array<{ prefix: string; service: BlueBubblesService }> = [
+  { prefix: "imessage:", service: "imessage" },
+  { prefix: "sms:", service: "sms" },
+  { prefix: "auto:", service: "auto" },
+];
+const CHAT_IDENTIFIER_UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const CHAT_IDENTIFIER_HEX_RE = /^[0-9a-f]{24,64}$/i;
+
+function parseRawChatGuid(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const parts = trimmed.split(";");
+  if (parts.length !== 3) return null;
+  const service = parts[0]?.trim();
+  const separator = parts[1]?.trim();
+  const identifier = parts[2]?.trim();
+  if (!service || !identifier) return null;
+  if (separator !== "+" && separator !== "-") return null;
+  return `${service};${separator};${identifier}`;
+}
+
+function stripPrefix(value: string, prefix: string): string {
+  return value.slice(prefix.length).trim();
+}
+
+function stripBlueBubblesPrefix(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  if (!trimmed.toLowerCase().startsWith("bluebubbles:")) return trimmed;
+  return trimmed.slice("bluebubbles:".length).trim();
+}
+
+function looksLikeRawChatIdentifier(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  if (/^chat\d+$/i.test(trimmed)) return true;
+  return CHAT_IDENTIFIER_UUID_RE.test(trimmed) || CHAT_IDENTIFIER_HEX_RE.test(trimmed);
+}
+
+export function normalizeBlueBubblesHandle(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  const lowered = trimmed.toLowerCase();
+  if (lowered.startsWith("imessage:")) return normalizeBlueBubblesHandle(trimmed.slice(9));
+  if (lowered.startsWith("sms:")) return normalizeBlueBubblesHandle(trimmed.slice(4));
+  if (lowered.startsWith("auto:")) return normalizeBlueBubblesHandle(trimmed.slice(5));
+  if (trimmed.includes("@")) return trimmed.toLowerCase();
+  return trimmed.replace(/\s+/g, "");
+}
+
+/**
+ * Extracts the handle from a chat_guid if it's a DM (1:1 chat).
+ * BlueBubbles chat_guid format for DM: "service;-;handle" (e.g., "iMessage;-;+19257864429")
+ * Group chat format: "service;+;groupId" (has "+" instead of "-")
+ */
+export function extractHandleFromChatGuid(chatGuid: string): string | null {
+  const parts = chatGuid.split(";");
+  // DM format: service;-;handle (3 parts, middle is "-")
+  if (parts.length === 3 && parts[1] === "-") {
+    const handle = parts[2]?.trim();
+    if (handle) return normalizeBlueBubblesHandle(handle);
+  }
+  return null;
+}
+
+export function normalizeBlueBubblesMessagingTarget(raw: string): string | undefined {
+  let trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  trimmed = stripBlueBubblesPrefix(trimmed);
+  if (!trimmed) return undefined;
+  try {
+    const parsed = parseBlueBubblesTarget(trimmed);
+    if (parsed.kind === "chat_id") return `chat_id:${parsed.chatId}`;
+    if (parsed.kind === "chat_guid") {
+      // For DM chat_guids, normalize to just the handle for easier comparison.
+      // This allows "chat_guid:iMessage;-;+1234567890" to match "+1234567890".
+      const handle = extractHandleFromChatGuid(parsed.chatGuid);
+      if (handle) return handle;
+      // For group chats or unrecognized formats, keep the full chat_guid
+      return `chat_guid:${parsed.chatGuid}`;
+    }
+    if (parsed.kind === "chat_identifier") return `chat_identifier:${parsed.chatIdentifier}`;
+    const handle = normalizeBlueBubblesHandle(parsed.to);
+    if (!handle) return undefined;
+    return parsed.service === "auto" ? handle : `${parsed.service}:${handle}`;
+  } catch {
+    return trimmed;
+  }
+}
+
+export function looksLikeBlueBubblesTargetId(raw: string, normalized?: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return false;
+  const candidate = stripBlueBubblesPrefix(trimmed);
+  if (!candidate) return false;
+  if (parseRawChatGuid(candidate)) return true;
+  const lowered = candidate.toLowerCase();
+  if (/^(imessage|sms|auto):/.test(lowered)) return true;
+  if (
+    /^(chat_id|chatid|chat|chat_guid|chatguid|guid|chat_identifier|chatidentifier|chatident|group):/.test(
+      lowered,
+    )
+  ) {
+    return true;
+  }
+  // Recognize chat<digits> patterns (e.g., "chat660250192681427962") as chat IDs
+  if (/^chat\d+$/i.test(candidate)) return true;
+  if (looksLikeRawChatIdentifier(candidate)) return true;
+  if (candidate.includes("@")) return true;
+  const digitsOnly = candidate.replace(/[\s().-]/g, "");
+  if (/^\+?\d{3,}$/.test(digitsOnly)) return true;
+  if (normalized) {
+    const normalizedTrimmed = normalized.trim();
+    if (!normalizedTrimmed) return false;
+    const normalizedLower = normalizedTrimmed.toLowerCase();
+    if (
+      /^(imessage|sms|auto):/.test(normalizedLower) ||
+      /^(chat_id|chat_guid|chat_identifier):/.test(normalizedLower)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function parseBlueBubblesTarget(raw: string): BlueBubblesTarget {
+  const trimmed = stripBlueBubblesPrefix(raw);
+  if (!trimmed) throw new Error("BlueBubbles target is required");
+  const lower = trimmed.toLowerCase();
+
+  for (const { prefix, service } of SERVICE_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const remainder = stripPrefix(trimmed, prefix);
+      if (!remainder) throw new Error(`${prefix} target is required`);
+      const remainderLower = remainder.toLowerCase();
+      const isChatTarget =
+        CHAT_ID_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
+        CHAT_GUID_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
+        CHAT_IDENTIFIER_PREFIXES.some((p) => remainderLower.startsWith(p)) ||
+        remainderLower.startsWith("group:");
+      if (isChatTarget) {
+        return parseBlueBubblesTarget(remainder);
+      }
+      return { kind: "handle", to: remainder, service };
+    }
+  }
+
+  for (const prefix of CHAT_ID_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      const chatId = Number.parseInt(value, 10);
+      if (!Number.isFinite(chatId)) {
+        throw new Error(`Invalid chat_id: ${value}`);
+      }
+      return { kind: "chat_id", chatId };
+    }
+  }
+
+  for (const prefix of CHAT_GUID_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      if (!value) throw new Error("chat_guid is required");
+      return { kind: "chat_guid", chatGuid: value };
+    }
+  }
+
+  for (const prefix of CHAT_IDENTIFIER_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      if (!value) throw new Error("chat_identifier is required");
+      return { kind: "chat_identifier", chatIdentifier: value };
+    }
+  }
+
+  if (lower.startsWith("group:")) {
+    const value = stripPrefix(trimmed, "group:");
+    const chatId = Number.parseInt(value, 10);
+    if (Number.isFinite(chatId)) {
+      return { kind: "chat_id", chatId };
+    }
+    if (!value) throw new Error("group target is required");
+    return { kind: "chat_guid", chatGuid: value };
+  }
+
+  const rawChatGuid = parseRawChatGuid(trimmed);
+  if (rawChatGuid) {
+    return { kind: "chat_guid", chatGuid: rawChatGuid };
+  }
+
+  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_identifier
+  // These are BlueBubbles chat identifiers (the third part of a chat GUID), not numeric IDs
+  if (/^chat\d+$/i.test(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+
+  // Handle UUID/hex chat identifiers (e.g., "8b9c1a10536d4d86a336ea03ab7151cc")
+  if (looksLikeRawChatIdentifier(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+
+  return { kind: "handle", to: trimmed, service: "auto" };
+}
+
+export function parseBlueBubblesAllowTarget(raw: string): BlueBubblesAllowTarget {
+  const trimmed = raw.trim();
+  if (!trimmed) return { kind: "handle", handle: "" };
+  const lower = trimmed.toLowerCase();
+
+  for (const { prefix } of SERVICE_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const remainder = stripPrefix(trimmed, prefix);
+      if (!remainder) return { kind: "handle", handle: "" };
+      return parseBlueBubblesAllowTarget(remainder);
+    }
+  }
+
+  for (const prefix of CHAT_ID_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      const chatId = Number.parseInt(value, 10);
+      if (Number.isFinite(chatId)) return { kind: "chat_id", chatId };
+    }
+  }
+
+  for (const prefix of CHAT_GUID_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      if (value) return { kind: "chat_guid", chatGuid: value };
+    }
+  }
+
+  for (const prefix of CHAT_IDENTIFIER_PREFIXES) {
+    if (lower.startsWith(prefix)) {
+      const value = stripPrefix(trimmed, prefix);
+      if (value) return { kind: "chat_identifier", chatIdentifier: value };
+    }
+  }
+
+  if (lower.startsWith("group:")) {
+    const value = stripPrefix(trimmed, "group:");
+    const chatId = Number.parseInt(value, 10);
+    if (Number.isFinite(chatId)) return { kind: "chat_id", chatId };
+    if (value) return { kind: "chat_guid", chatGuid: value };
+  }
+
+  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_identifier
+  // These are BlueBubbles chat identifiers (the third part of a chat GUID), not numeric IDs
+  if (/^chat\d+$/i.test(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+
+  // Handle UUID/hex chat identifiers (e.g., "8b9c1a10536d4d86a336ea03ab7151cc")
+  if (looksLikeRawChatIdentifier(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+
+  return { kind: "handle", handle: normalizeBlueBubblesHandle(trimmed) };
+}
+
+export function isAllowedBlueBubblesSender(params: {
+  allowFrom: Array<string | number>;
+  sender: string;
+  chatId?: number | null;
+  chatGuid?: string | null;
+  chatIdentifier?: string | null;
+}): boolean {
+  const allowFrom = params.allowFrom.map((entry) => String(entry).trim());
+  if (allowFrom.length === 0) return true;
+  if (allowFrom.includes("*")) return true;
+
+  const senderNormalized = normalizeBlueBubblesHandle(params.sender);
+  const chatId = params.chatId ?? undefined;
+  const chatGuid = params.chatGuid?.trim();
+  const chatIdentifier = params.chatIdentifier?.trim();
+
+  for (const entry of allowFrom) {
+    if (!entry) continue;
+    const parsed = parseBlueBubblesAllowTarget(entry);
+    if (parsed.kind === "chat_id" && chatId !== undefined) {
+      if (parsed.chatId === chatId) return true;
+    } else if (parsed.kind === "chat_guid" && chatGuid) {
+      if (parsed.chatGuid === chatGuid) return true;
+    } else if (parsed.kind === "chat_identifier" && chatIdentifier) {
+      if (parsed.chatIdentifier === chatIdentifier) return true;
+    } else if (parsed.kind === "handle" && senderNormalized) {
+      if (parsed.handle === senderNormalized) return true;
+    }
+  }
+  return false;
+}
+
+export function formatBlueBubblesChatTarget(params: {
+  chatId?: number | null;
+  chatGuid?: string | null;
+  chatIdentifier?: string | null;
+}): string {
+  if (params.chatId && Number.isFinite(params.chatId)) {
+    return `chat_id:${params.chatId}`;
+  }
+  const guid = params.chatGuid?.trim();
+  if (guid) return `chat_guid:${guid}`;
+  const identifier = params.chatIdentifier?.trim();
+  if (identifier) return `chat_identifier:${identifier}`;
+  return "";
+}

docker-compose/ez-assistant/extensions/bluebubbles/src/types.ts

@@ -0,0 +1,127 @@
+export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
+export type GroupPolicy = "open" | "disabled" | "allowlist";
+
+export type BlueBubblesGroupConfig = {
+  /** If true, only respond in this group when mentioned. */
+  requireMention?: boolean;
+  /** Optional tool policy overrides for this group. */
+  tools?: { allow?: string[]; deny?: string[] };
+};
+
+export type BlueBubblesAccountConfig = {
+  /** Optional display name for this account (used in CLI/UI lists). */
+  name?: string;
+  /** Optional provider capability tags used for agent/runtime guidance. */
+  capabilities?: string[];
+  /** Allow channel-initiated config writes (default: true). */
+  configWrites?: boolean;
+  /** If false, do not start this BlueBubbles account. Default: true. */
+  enabled?: boolean;
+  /** Base URL for the BlueBubbles API. */
+  serverUrl?: string;
+  /** Password for BlueBubbles API authentication. */
+  password?: string;
+  /** Webhook path for the gateway HTTP server. */
+  webhookPath?: string;
+  /** Direct message access policy (default: pairing). */
+  dmPolicy?: DmPolicy;
+  allowFrom?: Array<string | number>;
+  /** Optional allowlist for group senders. */
+  groupAllowFrom?: Array<string | number>;
+  /** Group message handling policy. */
+  groupPolicy?: GroupPolicy;
+  /** Max group messages to keep as history context (0 disables). */
+  historyLimit?: number;
+  /** Max DM turns to keep as history context. */
+  dmHistoryLimit?: number;
+  /** Per-DM config overrides keyed by user ID. */
+  dms?: Record<string, unknown>;
+  /** Outbound text chunk size (chars). Default: 4000. */
+  textChunkLimit?: number;
+  /** Chunking mode: "newline" (default) splits on every newline; "length" splits by size. */
+  chunkMode?: "length" | "newline";
+  blockStreaming?: boolean;
+  /** Merge streamed block replies before sending. */
+  blockStreamingCoalesce?: Record<string, unknown>;
+  /** Max outbound media size in MB. */
+  mediaMaxMb?: number;
+  /** Send read receipts for incoming messages (default: true). */
+  sendReadReceipts?: boolean;
+  /** Per-group configuration keyed by chat GUID or identifier. */
+  groups?: Record<string, BlueBubblesGroupConfig>;
+};
+
+export type BlueBubblesActionConfig = {
+  reactions?: boolean;
+  edit?: boolean;
+  unsend?: boolean;
+  reply?: boolean;
+  sendWithEffect?: boolean;
+  renameGroup?: boolean;
+  addParticipant?: boolean;
+  removeParticipant?: boolean;
+  leaveGroup?: boolean;
+  sendAttachment?: boolean;
+};
+
+export type BlueBubblesConfig = {
+  /** Optional per-account BlueBubbles configuration (multi-account). */
+  accounts?: Record<string, BlueBubblesAccountConfig>;
+  /** Per-action tool gating (default: true for all). */
+  actions?: BlueBubblesActionConfig;
+} & BlueBubblesAccountConfig;
+
+export type BlueBubblesSendTarget =
+  | { kind: "chat_id"; chatId: number }
+  | { kind: "chat_guid"; chatGuid: string }
+  | { kind: "chat_identifier"; chatIdentifier: string }
+  | { kind: "handle"; address: string; service?: "imessage" | "sms" | "auto" };
+
+export type BlueBubblesAttachment = {
+  guid?: string;
+  uti?: string;
+  mimeType?: string;
+  transferName?: string;
+  totalBytes?: number;
+  height?: number;
+  width?: number;
+  originalROWID?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export function normalizeBlueBubblesServerUrl(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("BlueBubbles serverUrl is required");
+  }
+  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+  return withScheme.replace(/\/+$/, "");
+}
+
+export function buildBlueBubblesApiUrl(params: {
+  baseUrl: string;
+  path: string;
+  password?: string;
+}): string {
+  const normalized = normalizeBlueBubblesServerUrl(params.baseUrl);
+  const url = new URL(params.path, `${normalized}/`);
+  if (params.password) {
+    url.searchParams.set("password", params.password);
+  }
+  return url.toString();
+}
+
+export async function blueBubblesFetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}