Upload 553 files

extensions/bluebubbles/index.ts

@@ -0,0 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/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: OpenClawPluginApi) {
+    setBlueBubblesRuntime(api.runtime);
+    api.registerChannel({ plugin: bluebubblesPlugin });
+    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
+  },
+};
+
+export default plugin;

extensions/bluebubbles/openclaw.plugin.json

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

extensions/bluebubbles/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@openclaw/bluebubbles",
+  "version": "2026.1.30",
+  "description": "OpenClaw BlueBubbles channel plugin",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "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": "@openclaw/bluebubbles",
+      "localPath": "extensions/bluebubbles",
+      "defaultChoice": "npm"
+    }
+  }
+}

extensions/bluebubbles/src/accounts.ts

@@ -0,0 +1,88 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/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: OpenClawConfig): string[] {
+  const accounts = cfg.channels?.bluebubbles?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return [];
+  }
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listBlueBubblesAccountIds(cfg: OpenClawConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+  return ids.toSorted((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultBlueBubblesAccountId(cfg: OpenClawConfig): string {
+  const ids = listBlueBubblesAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: OpenClawConfig,
+  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: OpenClawConfig,
+  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: OpenClawConfig;
+  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: OpenClawConfig): ResolvedBlueBubblesAccount[] {
+  return listBlueBubblesAccountIds(cfg)
+    .map((accountId) => resolveBlueBubblesAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

extensions/bluebubbles/src/actions.test.ts

@@ -0,0 +1,650 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { bluebubblesMessageActions } from "./actions.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,
+    };
+  }),
+}));
+
+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: OpenClawConfig = {
+        channels: { bluebubbles: { enabled: false } },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).toEqual([]);
+    });
+
+    it("returns empty array when account is not configured", () => {
+      const cfg: OpenClawConfig = {
+        channels: { bluebubbles: { enabled: true } },
+      };
+      const actions = bluebubblesMessageActions.listActions({ cfg });
+      expect(actions).toEqual([]);
+    });
+
+    it("returns react action when enabled and configured", () => {
+      const cfg: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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: OpenClawConfig = {
+        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(),
+      );
+    });
+  });
+});

extensions/bluebubbles/src/actions.ts

@@ -0,0 +1,438 @@
+import {
+  BLUEBUBBLES_ACTION_NAMES,
+  BLUEBUBBLES_ACTIONS,
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelToolSend,
+} from "openclaw/plugin-sdk";
+import type { BlueBubblesSendTarget } from "./types.js";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { sendBlueBubblesAttachment } from "./attachments.js";
+import {
+  editBlueBubblesMessage,
+  unsendBlueBubblesMessage,
+  renameBlueBubblesChat,
+  setGroupIconBlueBubbles,
+  addBlueBubblesParticipant,
+  removeBlueBubblesParticipant,
+  leaveBlueBubblesChat,
+} from "./chat.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { isMacOS26OrHigher } from "./probe.js";
+import { sendBlueBubblesReaction } from "./reactions.js";
+import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
+import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.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 });
+    if (!account.enabled || !account.configured) {
+      return [];
+    }
+    const gate = createActionGate(cfg.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,
+      accountId: accountId ?? undefined,
+    });
+    const baseUrl = account.config.serverUrl?.trim();
+    const password = account.config.password?.trim();
+    const opts = { cfg: cfg, 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}.`);
+  },
+};

extensions/bluebubbles/src/attachments.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import type { BlueBubblesAttachment } from "./types.js";
+import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.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"');
+  });
+});

extensions/bluebubbles/src/attachments.ts

@@ -0,0 +1,300 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import crypto from "node:crypto";
+import path from "node:path";
+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?: OpenClawConfig;
+};
+
+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" };
+  }
+}

extensions/bluebubbles/src/channel.ts

@@ -0,0 +1,414 @@
+import type { ChannelAccountSnapshot, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  collectBlueBubblesStatusIssues,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  resolveBlueBubblesGroupRequireMention,
+  resolveBlueBubblesGroupToolPolicy,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk";
+import {
+  listBlueBubblesAccountIds,
+  type ResolvedBlueBubblesAccount,
+  resolveBlueBubblesAccount,
+  resolveDefaultBlueBubblesAccountId,
+} from "./accounts.js";
+import { bluebubblesMessageActions } from "./actions.js";
+import { BlueBubblesConfigSchema } from "./config-schema.js";
+import { sendBlueBubblesMedia } from "./media-send.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
+import { blueBubblesOnboardingAdapter } from "./onboarding.js";
+import { probeBlueBubbles, type BlueBubblesProbe } from "./probe.js";
+import { sendMessageBlueBubbles } from "./send.js";
+import {
+  extractHandleFromChatGuid,
+  looksLikeBlueBubblesTargetId,
+  normalizeBlueBubblesHandle,
+  normalizeBlueBubblesMessagingTarget,
+  parseBlueBubblesTarget,
+} from "./targets.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),
+    resolveAccount: (cfg, accountId) => resolveBlueBubblesAccount({ cfg: cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultBlueBubblesAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg,
+        sectionKey: "bluebubbles",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg,
+        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, 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.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,
+        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,
+        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 OpenClawConfig;
+      }
+      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 OpenClawConfig;
+    },
+  },
+  pairing: {
+    idLabel: "bluebubblesSenderId",
+    normalizeAllowEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
+    notifyApproval: async ({ cfg, id }) => {
+      await sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
+        cfg: cfg,
+      });
+    },
+  },
+  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,
+        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,
+        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,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+        webhookPath,
+      });
+    },
+  },
+};

extensions/bluebubbles/src/chat.test.ts

@@ -0,0 +1,461 @@
+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");
+    });
+  });
+});

extensions/bluebubbles/src/chat.ts

@@ -0,0 +1,378 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import crypto from "node:crypto";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesChatOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: OpenClawConfig;
+};
+
+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"}`);
+  }
+}

extensions/bluebubbles/src/config-schema.ts

@@ -0,0 +1,51 @@
+import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/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,
+});

extensions/bluebubbles/src/media-send.ts

@@ -0,0 +1,174 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveChannelMediaMaxBytes, type OpenClawConfig } from "openclaw/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: OpenClawConfig;
+  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;
+}

extensions/bluebubbles/src/monitor.test.ts

@@ -0,0 +1,2340 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { EventEmitter } from "node:events";
+import { removeAckReactionAfterReply, shouldAckReaction } from "openclaw/plugin-sdk";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedBlueBubblesAccount } from "./accounts.js";
+import {
+  handleBlueBubblesWebhookRequest,
+  registerBlueBubblesWebhookTarget,
+  resolveBlueBubblesMessageId,
+  _resetBlueBubblesShortIdState,
+} from "./monitor.js";
+import { setBlueBubblesRuntime } from "./runtime.js";
+
+// Mock dependencies
+vi.mock("./send.js", () => ({
+  resolveChatGuidForTarget: vi.fn().mockResolvedValue("iMessage;-;+15551234567"),
+  sendMessageBlueBubbles: vi.fn().mockResolvedValue({ messageId: "msg-123" }),
+}));
+
+vi.mock("./chat.js", () => ({
+  markBlueBubblesChatRead: vi.fn().mockResolvedValue(undefined),
+  sendBlueBubblesTyping: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("./attachments.js", () => ({
+  downloadBlueBubblesAttachment: vi.fn().mockResolvedValue({
+    buffer: Buffer.from("test"),
+    contentType: "image/jpeg",
+  }),
+}));
+
+vi.mock("./reactions.js", async () => {
+  const actual = await vi.importActual<typeof import("./reactions.js")>("./reactions.js");
+  return {
+    ...actual,
+    sendBlueBubblesReaction: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+// Mock runtime
+const mockEnqueueSystemEvent = vi.fn();
+const mockBuildPairingReply = vi.fn(() => "Pairing code: TESTCODE");
+const mockReadAllowFromStore = vi.fn().mockResolvedValue([]);
+const mockUpsertPairingRequest = vi.fn().mockResolvedValue({ code: "TESTCODE", created: true });
+const mockResolveAgentRoute = vi.fn(() => ({
+  agentId: "main",
+  accountId: "default",
+  sessionKey: "agent:main:bluebubbles:dm:+15551234567",
+}));
+const mockBuildMentionRegexes = vi.fn(() => [/\bbert\b/i]);
+const mockMatchesMentionPatterns = vi.fn((text: string, regexes: RegExp[]) =>
+  regexes.some((r) => r.test(text)),
+);
+const mockResolveRequireMention = vi.fn(() => false);
+const mockResolveGroupPolicy = vi.fn(() => "open");
+const mockDispatchReplyWithBufferedBlockDispatcher = vi.fn(async () => undefined);
+const mockHasControlCommand = vi.fn(() => false);
+const mockResolveCommandAuthorizedFromAuthorizers = vi.fn(() => false);
+const mockSaveMediaBuffer = vi.fn().mockResolvedValue({
+  path: "/tmp/test-media.jpg",
+  contentType: "image/jpeg",
+});
+const mockResolveStorePath = vi.fn(() => "/tmp/sessions.json");
+const mockReadSessionUpdatedAt = vi.fn(() => undefined);
+const mockResolveEnvelopeFormatOptions = vi.fn(() => ({
+  template: "channel+name+time",
+}));
+const mockFormatAgentEnvelope = vi.fn((opts: { body: string }) => opts.body);
+const mockChunkMarkdownText = vi.fn((text: string) => [text]);
+
+function createMockRuntime(): PluginRuntime {
+  return {
+    version: "1.0.0",
+    config: {
+      loadConfig: vi.fn(() => ({})) as unknown as PluginRuntime["config"]["loadConfig"],
+      writeConfigFile: vi.fn() as unknown as PluginRuntime["config"]["writeConfigFile"],
+    },
+    system: {
+      enqueueSystemEvent:
+        mockEnqueueSystemEvent as unknown as PluginRuntime["system"]["enqueueSystemEvent"],
+      runCommandWithTimeout: vi.fn() as unknown as PluginRuntime["system"]["runCommandWithTimeout"],
+    },
+    media: {
+      loadWebMedia: vi.fn() as unknown as PluginRuntime["media"]["loadWebMedia"],
+      detectMime: vi.fn() as unknown as PluginRuntime["media"]["detectMime"],
+      mediaKindFromMime: vi.fn() as unknown as PluginRuntime["media"]["mediaKindFromMime"],
+      isVoiceCompatibleAudio:
+        vi.fn() as unknown as PluginRuntime["media"]["isVoiceCompatibleAudio"],
+      getImageMetadata: vi.fn() as unknown as PluginRuntime["media"]["getImageMetadata"],
+      resizeToJpeg: vi.fn() as unknown as PluginRuntime["media"]["resizeToJpeg"],
+    },
+    tools: {
+      createMemoryGetTool: vi.fn() as unknown as PluginRuntime["tools"]["createMemoryGetTool"],
+      createMemorySearchTool:
+        vi.fn() as unknown as PluginRuntime["tools"]["createMemorySearchTool"],
+      registerMemoryCli: vi.fn() as unknown as PluginRuntime["tools"]["registerMemoryCli"],
+    },
+    channel: {
+      text: {
+        chunkMarkdownText:
+          mockChunkMarkdownText as unknown as PluginRuntime["channel"]["text"]["chunkMarkdownText"],
+        chunkText: vi.fn() as unknown as PluginRuntime["channel"]["text"]["chunkText"],
+        resolveTextChunkLimit: vi.fn(
+          () => 4000,
+        ) as unknown as PluginRuntime["channel"]["text"]["resolveTextChunkLimit"],
+        hasControlCommand:
+          mockHasControlCommand as unknown as PluginRuntime["channel"]["text"]["hasControlCommand"],
+        resolveMarkdownTableMode: vi.fn(
+          () => "code",
+        ) as unknown as PluginRuntime["channel"]["text"]["resolveMarkdownTableMode"],
+        convertMarkdownTables: vi.fn(
+          (text: string) => text,
+        ) as unknown as PluginRuntime["channel"]["text"]["convertMarkdownTables"],
+      },
+      reply: {
+        dispatchReplyWithBufferedBlockDispatcher:
+          mockDispatchReplyWithBufferedBlockDispatcher as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyWithBufferedBlockDispatcher"],
+        createReplyDispatcherWithTyping:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["createReplyDispatcherWithTyping"],
+        resolveEffectiveMessagesConfig:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["resolveEffectiveMessagesConfig"],
+        resolveHumanDelayConfig:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["resolveHumanDelayConfig"],
+        dispatchReplyFromConfig:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"],
+        finalizeInboundContext:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"],
+        formatAgentEnvelope:
+          mockFormatAgentEnvelope as unknown as PluginRuntime["channel"]["reply"]["formatAgentEnvelope"],
+        formatInboundEnvelope:
+          vi.fn() as unknown as PluginRuntime["channel"]["reply"]["formatInboundEnvelope"],
+        resolveEnvelopeFormatOptions:
+          mockResolveEnvelopeFormatOptions as unknown as PluginRuntime["channel"]["reply"]["resolveEnvelopeFormatOptions"],
+      },
+      routing: {
+        resolveAgentRoute:
+          mockResolveAgentRoute as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"],
+      },
+      pairing: {
+        buildPairingReply:
+          mockBuildPairingReply as unknown as PluginRuntime["channel"]["pairing"]["buildPairingReply"],
+        readAllowFromStore:
+          mockReadAllowFromStore as unknown as PluginRuntime["channel"]["pairing"]["readAllowFromStore"],
+        upsertPairingRequest:
+          mockUpsertPairingRequest as unknown as PluginRuntime["channel"]["pairing"]["upsertPairingRequest"],
+      },
+      media: {
+        fetchRemoteMedia:
+          vi.fn() as unknown as PluginRuntime["channel"]["media"]["fetchRemoteMedia"],
+        saveMediaBuffer:
+          mockSaveMediaBuffer as unknown as PluginRuntime["channel"]["media"]["saveMediaBuffer"],
+      },
+      session: {
+        resolveStorePath:
+          mockResolveStorePath as unknown as PluginRuntime["channel"]["session"]["resolveStorePath"],
+        readSessionUpdatedAt:
+          mockReadSessionUpdatedAt as unknown as PluginRuntime["channel"]["session"]["readSessionUpdatedAt"],
+        recordInboundSession:
+          vi.fn() as unknown as PluginRuntime["channel"]["session"]["recordInboundSession"],
+        recordSessionMetaFromInbound:
+          vi.fn() as unknown as PluginRuntime["channel"]["session"]["recordSessionMetaFromInbound"],
+        updateLastRoute:
+          vi.fn() as unknown as PluginRuntime["channel"]["session"]["updateLastRoute"],
+      },
+      mentions: {
+        buildMentionRegexes:
+          mockBuildMentionRegexes as unknown as PluginRuntime["channel"]["mentions"]["buildMentionRegexes"],
+        matchesMentionPatterns:
+          mockMatchesMentionPatterns as unknown as PluginRuntime["channel"]["mentions"]["matchesMentionPatterns"],
+      },
+      reactions: {
+        shouldAckReaction,
+        removeAckReactionAfterReply,
+      },
+      groups: {
+        resolveGroupPolicy:
+          mockResolveGroupPolicy as unknown as PluginRuntime["channel"]["groups"]["resolveGroupPolicy"],
+        resolveRequireMention:
+          mockResolveRequireMention as unknown as PluginRuntime["channel"]["groups"]["resolveRequireMention"],
+      },
+      debounce: {
+        // Create a pass-through debouncer that immediately calls onFlush
+        createInboundDebouncer: vi.fn(
+          (params: { onFlush: (items: unknown[]) => Promise<void> }) => ({
+            enqueue: async (item: unknown) => {
+              await params.onFlush([item]);
+            },
+            flushKey: vi.fn(),
+          }),
+        ) as unknown as PluginRuntime["channel"]["debounce"]["createInboundDebouncer"],
+        resolveInboundDebounceMs: vi.fn(
+          () => 0,
+        ) as unknown as PluginRuntime["channel"]["debounce"]["resolveInboundDebounceMs"],
+      },
+      commands: {
+        resolveCommandAuthorizedFromAuthorizers:
+          mockResolveCommandAuthorizedFromAuthorizers as unknown as PluginRuntime["channel"]["commands"]["resolveCommandAuthorizedFromAuthorizers"],
+        isControlCommandMessage:
+          vi.fn() as unknown as PluginRuntime["channel"]["commands"]["isControlCommandMessage"],
+        shouldComputeCommandAuthorized:
+          vi.fn() as unknown as PluginRuntime["channel"]["commands"]["shouldComputeCommandAuthorized"],
+        shouldHandleTextCommands:
+          vi.fn() as unknown as PluginRuntime["channel"]["commands"]["shouldHandleTextCommands"],
+      },
+      discord: {} as PluginRuntime["channel"]["discord"],
+      slack: {} as PluginRuntime["channel"]["slack"],
+      telegram: {} as PluginRuntime["channel"]["telegram"],
+      signal: {} as PluginRuntime["channel"]["signal"],
+      imessage: {} as PluginRuntime["channel"]["imessage"],
+      whatsapp: {} as PluginRuntime["channel"]["whatsapp"],
+    },
+    logging: {
+      shouldLogVerbose: vi.fn(
+        () => false,
+      ) as unknown as PluginRuntime["logging"]["shouldLogVerbose"],
+      getChildLogger: vi.fn(() => ({
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+      })) as unknown as PluginRuntime["logging"]["getChildLogger"],
+    },
+    state: {
+      resolveStateDir: vi.fn(
+        () => "/tmp/openclaw",
+      ) as unknown as PluginRuntime["state"]["resolveStateDir"],
+    },
+  };
+}
+
+function createMockAccount(
+  overrides: Partial<ResolvedBlueBubblesAccount["config"]> = {},
+): ResolvedBlueBubblesAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    configured: true,
+    config: {
+      serverUrl: "http://localhost:1234",
+      password: "test-password",
+      dmPolicy: "open",
+      groupPolicy: "open",
+      allowFrom: [],
+      groupAllowFrom: [],
+      ...overrides,
+    },
+  };
+}
+
+function createMockRequest(
+  method: string,
+  url: string,
+  body: unknown,
+  headers: Record<string, string> = {},
+): IncomingMessage {
+  const req = new EventEmitter() as IncomingMessage;
+  req.method = method;
+  req.url = url;
+  req.headers = headers;
+  (req as unknown as { socket: { remoteAddress: string } }).socket = { remoteAddress: "127.0.0.1" };
+
+  // Emit body data after a microtask
+  // oxlint-disable-next-line no-floating-promises
+  Promise.resolve().then(() => {
+    const bodyStr = typeof body === "string" ? body : JSON.stringify(body);
+    req.emit("data", Buffer.from(bodyStr));
+    req.emit("end");
+  });
+
+  return req;
+}
+
+function createMockResponse(): ServerResponse & { body: string; statusCode: number } {
+  const res = {
+    statusCode: 200,
+    body: "",
+    setHeader: vi.fn(),
+    end: vi.fn((data?: string) => {
+      res.body = data ?? "";
+    }),
+  } as unknown as ServerResponse & { body: string; statusCode: number };
+  return res;
+}
+
+const flushAsync = async () => {
+  for (let i = 0; i < 2; i += 1) {
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+};
+
+describe("BlueBubbles webhook monitor", () => {
+  let unregister: () => void;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset short ID state between tests for predictable behavior
+    _resetBlueBubblesShortIdState();
+    mockReadAllowFromStore.mockResolvedValue([]);
+    mockUpsertPairingRequest.mockResolvedValue({ code: "TESTCODE", created: true });
+    mockResolveRequireMention.mockReturnValue(false);
+    mockHasControlCommand.mockReturnValue(false);
+    mockResolveCommandAuthorizedFromAuthorizers.mockReturnValue(false);
+    mockBuildMentionRegexes.mockReturnValue([/\bbert\b/i]);
+
+    setBlueBubblesRuntime(createMockRuntime());
+  });
+
+  afterEach(() => {
+    unregister?.();
+  });
+
+  describe("webhook parsing + auth handling", () => {
+    it("rejects non-POST requests", async () => {
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const req = createMockRequest("GET", "/bluebubbles-webhook", {});
+      const res = createMockResponse();
+
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(405);
+    });
+
+    it("accepts POST requests with valid JSON payload", async () => {
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(200);
+      expect(res.body).toBe("ok");
+    });
+
+    it("rejects requests with invalid JSON", async () => {
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", "invalid json {{");
+      const res = createMockResponse();
+
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(400);
+    });
+
+    it("authenticates via password query parameter", async () => {
+      const account = createMockAccount({ password: "secret-token" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      // Mock non-localhost request
+      const req = createMockRequest("POST", "/bluebubbles-webhook?password=secret-token", {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+        },
+      });
+      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+        remoteAddress: "192.168.1.100",
+      };
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const res = createMockResponse();
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(200);
+    });
+
+    it("authenticates via x-password header", async () => {
+      const account = createMockAccount({ password: "secret-token" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      const req = createMockRequest(
+        "POST",
+        "/bluebubbles-webhook",
+        {
+          type: "new-message",
+          data: {
+            text: "hello",
+            handle: { address: "+15551234567" },
+            isGroup: false,
+            isFromMe: false,
+            guid: "msg-1",
+          },
+        },
+        { "x-password": "secret-token" },
+      );
+      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+        remoteAddress: "192.168.1.100",
+      };
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const res = createMockResponse();
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(200);
+    });
+
+    it("rejects unauthorized requests with wrong password", async () => {
+      const account = createMockAccount({ password: "secret-token" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook?password=wrong-token", {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+        },
+      });
+      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+        remoteAddress: "192.168.1.100",
+      };
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const res = createMockResponse();
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(401);
+    });
+
+    it("allows localhost requests without authentication", async () => {
+      const account = createMockAccount({ password: "secret-token" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+        },
+      });
+      // Localhost address
+      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+        remoteAddress: "127.0.0.1",
+      };
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const res = createMockResponse();
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(200);
+    });
+
+    it("ignores unregistered webhook paths", async () => {
+      const req = createMockRequest("POST", "/unregistered-path", {});
+      const res = createMockResponse();
+
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(false);
+    });
+
+    it("parses chatId when provided as a string (webhook variant)", async () => {
+      const { resolveChatGuidForTarget } = await import("./send.js");
+      vi.mocked(resolveChatGuidForTarget).mockClear();
+
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatId: "123",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(resolveChatGuidForTarget).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: { kind: "chat_id", chatId: 123 },
+        }),
+      );
+    });
+
+    it("extracts chatGuid from nested chat object fields (webhook variant)", async () => {
+      const { sendMessageBlueBubbles, resolveChatGuidForTarget } = await import("./send.js");
+      vi.mocked(sendMessageBlueBubbles).mockClear();
+      vi.mocked(resolveChatGuidForTarget).mockClear();
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async (params) => {
+        await params.dispatcherOptions.deliver({ text: "replying now" }, { kind: "final" });
+      });
+
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chat: { chatGuid: "iMessage;+;chat123456" },
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(resolveChatGuidForTarget).not.toHaveBeenCalled();
+      expect(sendMessageBlueBubbles).toHaveBeenCalledWith(
+        "chat_guid:iMessage;+;chat123456",
+        expect.any(String),
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe("DM pairing behavior vs allowFrom", () => {
+    it("allows DM from sender in allowFrom list", async () => {
+      const account = createMockAccount({
+        dmPolicy: "allowlist",
+        allowFrom: ["+15551234567"],
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from allowed sender",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+
+      // Wait for async processing
+      await flushAsync();
+
+      expect(res.statusCode).toBe(200);
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+
+    it("blocks DM from sender not in allowFrom when dmPolicy=allowlist", async () => {
+      const account = createMockAccount({
+        dmPolicy: "allowlist",
+        allowFrom: ["+15559999999"], // Different number
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from blocked sender",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(res.statusCode).toBe(200);
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+
+    it("triggers pairing flow for unknown sender when dmPolicy=pairing", async () => {
+      // Note: empty allowFrom = allow all. To trigger pairing, we need a non-empty
+      // allowlist that doesn't include the sender
+      const account = createMockAccount({
+        dmPolicy: "pairing",
+        allowFrom: ["+15559999999"], // Different number than sender
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockUpsertPairingRequest).toHaveBeenCalled();
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+
+    it("does not resend pairing reply when request already exists", async () => {
+      mockUpsertPairingRequest.mockResolvedValue({ code: "TESTCODE", created: false });
+
+      // Note: empty allowFrom = allow all. To trigger pairing, we need a non-empty
+      // allowlist that doesn't include the sender
+      const account = createMockAccount({
+        dmPolicy: "pairing",
+        allowFrom: ["+15559999999"], // Different number than sender
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello again",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-2",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockUpsertPairingRequest).toHaveBeenCalled();
+      // Should not send pairing reply since created=false
+      const { sendMessageBlueBubbles } = await import("./send.js");
+      expect(sendMessageBlueBubbles).not.toHaveBeenCalled();
+    });
+
+    it("allows all DMs when dmPolicy=open", async () => {
+      const account = createMockAccount({
+        dmPolicy: "open",
+        allowFrom: [],
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from anyone",
+          handle: { address: "+15559999999" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+
+    it("blocks all DMs when dmPolicy=disabled", async () => {
+      const account = createMockAccount({
+        dmPolicy: "disabled",
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("group message gating", () => {
+    it("allows group messages when groupPolicy=open and no allowlist", async () => {
+      const account = createMockAccount({
+        groupPolicy: "open",
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+
+    it("blocks group messages when groupPolicy=disabled", async () => {
+      const account = createMockAccount({
+        groupPolicy: "disabled",
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+
+    it("treats chat_guid groups as group even when isGroup=false", async () => {
+      const account = createMockAccount({
+        groupPolicy: "allowlist",
+        dmPolicy: "open",
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from group",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+
+    it("allows group messages from allowed chat_guid in groupAllowFrom", async () => {
+      const account = createMockAccount({
+        groupPolicy: "allowlist",
+        groupAllowFrom: ["chat_guid:iMessage;+;chat123456"],
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello from allowed group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+  });
+
+  describe("mention gating (group messages)", () => {
+    it("processes group message when mentioned and requireMention=true", async () => {
+      mockResolveRequireMention.mockReturnValue(true);
+      mockMatchesMentionPatterns.mockReturnValue(true);
+
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "bert, can you help me?",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.WasMentioned).toBe(true);
+    });
+
+    it("skips group message when not mentioned and requireMention=true", async () => {
+      mockResolveRequireMention.mockReturnValue(true);
+      mockMatchesMentionPatterns.mockReturnValue(false);
+
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello everyone",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+
+    it("processes group message without mention when requireMention=false", async () => {
+      mockResolveRequireMention.mockReturnValue(false);
+
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello everyone",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+  });
+
+  describe("group metadata", () => {
+    it("includes group subject + members in ctx", async () => {
+      const account = createMockAccount({ groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello group",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          chatName: "Family",
+          participants: [
+            { address: "+15551234567", displayName: "Alice" },
+            { address: "+15557654321", displayName: "Bob" },
+          ],
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.GroupSubject).toBe("Family");
+      expect(callArgs.ctx.GroupMembers).toBe("Alice (+15551234567), Bob (+15557654321)");
+    });
+  });
+
+  describe("inbound debouncing", () => {
+    it("coalesces text-only then attachment webhook events by messageId", async () => {
+      vi.useFakeTimers();
+      try {
+        const account = createMockAccount({ dmPolicy: "open" });
+        const config: OpenClawConfig = {};
+        const core = createMockRuntime();
+
+        // Use a timing-aware debouncer test double that respects debounceMs/buildKey/shouldDebounce.
+        core.channel.debounce.createInboundDebouncer = vi.fn((params: any) => {
+          type Item = any;
+          const buckets = new Map<
+            string,
+            { items: Item[]; timer: ReturnType<typeof setTimeout> | null }
+          >();
+
+          const flush = async (key: string) => {
+            const bucket = buckets.get(key);
+            if (!bucket) {
+              return;
+            }
+            if (bucket.timer) {
+              clearTimeout(bucket.timer);
+              bucket.timer = null;
+            }
+            const items = bucket.items;
+            bucket.items = [];
+            if (items.length > 0) {
+              try {
+                await params.onFlush(items);
+              } catch (err) {
+                params.onError?.(err);
+                throw err;
+              }
+            }
+          };
+
+          return {
+            enqueue: async (item: Item) => {
+              if (params.shouldDebounce && !params.shouldDebounce(item)) {
+                await params.onFlush([item]);
+                return;
+              }
+
+              const key = params.buildKey(item);
+              const existing = buckets.get(key);
+              const bucket = existing ?? { items: [], timer: null };
+              bucket.items.push(item);
+              if (bucket.timer) {
+                clearTimeout(bucket.timer);
+              }
+              bucket.timer = setTimeout(async () => {
+                await flush(key);
+              }, params.debounceMs);
+              buckets.set(key, bucket);
+            },
+            flushKey: vi.fn(async (key: string) => {
+              await flush(key);
+            }),
+          };
+        }) as unknown as PluginRuntime["channel"]["debounce"]["createInboundDebouncer"];
+
+        setBlueBubblesRuntime(core);
+
+        unregister = registerBlueBubblesWebhookTarget({
+          account,
+          config,
+          runtime: { log: vi.fn(), error: vi.fn() },
+          core,
+          path: "/bluebubbles-webhook",
+        });
+
+        const messageId = "race-msg-1";
+        const chatGuid = "iMessage;-;+15551234567";
+
+        const payloadA = {
+          type: "new-message",
+          data: {
+            text: "hello",
+            handle: { address: "+15551234567" },
+            isGroup: false,
+            isFromMe: false,
+            guid: messageId,
+            chatGuid,
+            date: Date.now(),
+          },
+        };
+
+        const payloadB = {
+          type: "new-message",
+          data: {
+            text: "hello",
+            handle: { address: "+15551234567" },
+            isGroup: false,
+            isFromMe: false,
+            guid: messageId,
+            chatGuid,
+            attachments: [
+              {
+                guid: "att-1",
+                mimeType: "image/jpeg",
+                totalBytes: 1024,
+              },
+            ],
+            date: Date.now(),
+          },
+        };
+
+        await handleBlueBubblesWebhookRequest(
+          createMockRequest("POST", "/bluebubbles-webhook", payloadA),
+          createMockResponse(),
+        );
+
+        // Simulate the real-world delay where the attachment-bearing webhook arrives shortly after.
+        await vi.advanceTimersByTimeAsync(300);
+
+        await handleBlueBubblesWebhookRequest(
+          createMockRequest("POST", "/bluebubbles-webhook", payloadB),
+          createMockResponse(),
+        );
+
+        // Not flushed yet; still within the debounce window.
+        expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+
+        // After the debounce window, the combined message should be processed exactly once.
+        await vi.advanceTimersByTimeAsync(600);
+
+        expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1);
+        const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+        expect(callArgs.ctx.MediaPaths).toEqual(["/tmp/test-media.jpg"]);
+        expect(callArgs.ctx.Body).toContain("hello");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  describe("reply metadata", () => {
+    it("surfaces reply fields in ctx when provided", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "replying now",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          replyTo: {
+            guid: "msg-0",
+            text: "original message",
+            handle: { address: "+15550000000", displayName: "Alice" },
+          },
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      // ReplyToId is the full UUID since it wasn't previously cached
+      expect(callArgs.ctx.ReplyToId).toBe("msg-0");
+      expect(callArgs.ctx.ReplyToBody).toBe("original message");
+      expect(callArgs.ctx.ReplyToSender).toBe("+15550000000");
+      // Body uses inline [[reply_to:N]] tag format
+      expect(callArgs.ctx.Body).toContain("[[reply_to:msg-0]]");
+    });
+
+    it("preserves part index prefixes in reply tags when short IDs are unavailable", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "replying now",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          replyTo: {
+            guid: "p:1/msg-0",
+            text: "original message",
+            handle: { address: "+15550000000", displayName: "Alice" },
+          },
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.ReplyToId).toBe("p:1/msg-0");
+      expect(callArgs.ctx.ReplyToIdFull).toBe("p:1/msg-0");
+      expect(callArgs.ctx.Body).toContain("[[reply_to:p:1/msg-0]]");
+    });
+
+    it("hydrates missing reply sender/body from the recent-message cache", async () => {
+      const account = createMockAccount({ dmPolicy: "open", groupPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const chatGuid = "iMessage;+;chat-reply-cache";
+
+      const originalPayload = {
+        type: "new-message",
+        data: {
+          text: "original message (cached)",
+          handle: { address: "+15550000000" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "cache-msg-0",
+          chatGuid,
+          date: Date.now(),
+        },
+      };
+
+      const originalReq = createMockRequest("POST", "/bluebubbles-webhook", originalPayload);
+      const originalRes = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(originalReq, originalRes);
+      await flushAsync();
+
+      // Only assert the reply message behavior below.
+      mockDispatchReplyWithBufferedBlockDispatcher.mockClear();
+
+      const replyPayload = {
+        type: "new-message",
+        data: {
+          text: "replying now",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "cache-msg-1",
+          chatGuid,
+          // Only the GUID is provided; sender/body must be hydrated.
+          replyToMessageGuid: "cache-msg-0",
+          date: Date.now(),
+        },
+      };
+
+      const replyReq = createMockRequest("POST", "/bluebubbles-webhook", replyPayload);
+      const replyRes = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(replyReq, replyRes);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      // ReplyToId uses short ID "1" (first cached message) for token savings
+      expect(callArgs.ctx.ReplyToId).toBe("1");
+      expect(callArgs.ctx.ReplyToIdFull).toBe("cache-msg-0");
+      expect(callArgs.ctx.ReplyToBody).toBe("original message (cached)");
+      expect(callArgs.ctx.ReplyToSender).toBe("+15550000000");
+      // Body uses inline [[reply_to:N]] tag format with short ID
+      expect(callArgs.ctx.Body).toContain("[[reply_to:1]]");
+    });
+
+    it("falls back to threadOriginatorGuid when reply metadata is absent", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "replying now",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          threadOriginatorGuid: "msg-0",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.ReplyToId).toBe("msg-0");
+    });
+  });
+
+  describe("tapback text parsing", () => {
+    it("does not rewrite tapback-like text without metadata", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "Loved this idea",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.RawBody).toBe("Loved this idea");
+      expect(callArgs.ctx.Body).toContain("Loved this idea");
+      expect(callArgs.ctx.Body).not.toContain("reacted with");
+    });
+
+    it("parses tapback text with custom emoji when metadata is present", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: 'Reacted 😅 to "nice one"',
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-2",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      expect(callArgs.ctx.RawBody).toBe("reacted with 😅");
+      expect(callArgs.ctx.Body).toContain("reacted with 😅");
+      expect(callArgs.ctx.Body).not.toContain("[[reply_to:");
+    });
+  });
+
+  describe("ack reactions", () => {
+    it("sends ack reaction when configured", async () => {
+      const { sendBlueBubblesReaction } = await import("./reactions.js");
+      vi.mocked(sendBlueBubblesReaction).mockClear();
+
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {
+        messages: {
+          ackReaction: "❤️",
+          ackReactionScope: "direct",
+        },
+      };
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(sendBlueBubblesReaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chatGuid: "iMessage;-;+15551234567",
+          messageGuid: "msg-1",
+          emoji: "❤️",
+          opts: expect.objectContaining({ accountId: "default" }),
+        }),
+      );
+    });
+  });
+
+  describe("command gating", () => {
+    it("allows control command to bypass mention gating when authorized", async () => {
+      mockResolveRequireMention.mockReturnValue(true);
+      mockMatchesMentionPatterns.mockReturnValue(false); // Not mentioned
+      mockHasControlCommand.mockReturnValue(true); // Has control command
+      mockResolveCommandAuthorizedFromAuthorizers.mockReturnValue(true); // Authorized
+
+      const account = createMockAccount({
+        groupPolicy: "open",
+        allowFrom: ["+15551234567"],
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "/status",
+          handle: { address: "+15551234567" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      // Should process even without mention because it's an authorized control command
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+    });
+
+    it("blocks control command from unauthorized sender in group", async () => {
+      mockHasControlCommand.mockReturnValue(true);
+      mockResolveCommandAuthorizedFromAuthorizers.mockReturnValue(false);
+
+      const account = createMockAccount({
+        groupPolicy: "open",
+        allowFrom: [], // No one authorized
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "/status",
+          handle: { address: "+15559999999" },
+          isGroup: true,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;+;chat123456",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("typing/read receipt toggles", () => {
+    it("marks chat as read when sendReadReceipts=true (default)", async () => {
+      const { markBlueBubblesChatRead } = await import("./chat.js");
+      vi.mocked(markBlueBubblesChatRead).mockClear();
+
+      const account = createMockAccount({
+        sendReadReceipts: true,
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(markBlueBubblesChatRead).toHaveBeenCalled();
+    });
+
+    it("does not mark chat as read when sendReadReceipts=false", async () => {
+      const { markBlueBubblesChatRead } = await import("./chat.js");
+      vi.mocked(markBlueBubblesChatRead).mockClear();
+
+      const account = createMockAccount({
+        sendReadReceipts: false,
+      });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(markBlueBubblesChatRead).not.toHaveBeenCalled();
+    });
+
+    it("sends typing indicator when processing message", async () => {
+      const { sendBlueBubblesTyping } = await import("./chat.js");
+      vi.mocked(sendBlueBubblesTyping).mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async (params) => {
+        await params.dispatcherOptions.onReplyStart?.();
+      });
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      // Should call typing start when reply flow triggers it.
+      expect(sendBlueBubblesTyping).toHaveBeenCalledWith(
+        expect.any(String),
+        true,
+        expect.any(Object),
+      );
+    });
+
+    it("stops typing on idle", async () => {
+      const { sendBlueBubblesTyping } = await import("./chat.js");
+      vi.mocked(sendBlueBubblesTyping).mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async (params) => {
+        await params.dispatcherOptions.onReplyStart?.();
+        await params.dispatcherOptions.deliver({ text: "replying now" }, { kind: "final" });
+        await params.dispatcherOptions.onIdle?.();
+      });
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(sendBlueBubblesTyping).toHaveBeenCalledWith(
+        expect.any(String),
+        false,
+        expect.any(Object),
+      );
+    });
+
+    it("stops typing when no reply is sent", async () => {
+      const { sendBlueBubblesTyping } = await import("./chat.js");
+      vi.mocked(sendBlueBubblesTyping).mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async () => undefined);
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(sendBlueBubblesTyping).toHaveBeenCalledWith(
+        expect.any(String),
+        false,
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe("outbound message ids", () => {
+    it("enqueues system event for outbound message id", async () => {
+      mockEnqueueSystemEvent.mockClear();
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async (params) => {
+        await params.dispatcherOptions.deliver({ text: "replying now" }, { kind: "final" });
+      });
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      // Outbound message ID uses short ID "2" (inbound msg-1 is "1", outbound msg-123 is "2")
+      expect(mockEnqueueSystemEvent).toHaveBeenCalledWith(
+        'Assistant sent "replying now" [message_id:2]',
+        expect.objectContaining({
+          sessionKey: "agent:main:bluebubbles:dm:+15551234567",
+        }),
+      );
+    });
+  });
+
+  describe("reaction events", () => {
+    it("enqueues system event for reaction added", async () => {
+      mockEnqueueSystemEvent.mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "message-reaction",
+        data: {
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          associatedMessageGuid: "msg-original-123",
+          associatedMessageType: 2000, // Heart reaction added
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockEnqueueSystemEvent).toHaveBeenCalledWith(
+        expect.stringContaining("reacted with ❤️ [[reply_to:"),
+        expect.any(Object),
+      );
+    });
+
+    it("enqueues system event for reaction removed", async () => {
+      mockEnqueueSystemEvent.mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "message-reaction",
+        data: {
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          associatedMessageGuid: "msg-original-123",
+          associatedMessageType: 3000, // Heart reaction removed
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockEnqueueSystemEvent).toHaveBeenCalledWith(
+        expect.stringContaining("removed ❤️ reaction [[reply_to:"),
+        expect.any(Object),
+      );
+    });
+
+    it("ignores reaction from self (fromMe=true)", async () => {
+      mockEnqueueSystemEvent.mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "message-reaction",
+        data: {
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: true, // From self
+          associatedMessageGuid: "msg-original-123",
+          associatedMessageType: 2000,
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockEnqueueSystemEvent).not.toHaveBeenCalled();
+    });
+
+    it("maps reaction types to correct emojis", async () => {
+      mockEnqueueSystemEvent.mockClear();
+
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      // Test thumbs up reaction (2001)
+      const payload = {
+        type: "message-reaction",
+        data: {
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          associatedMessageGuid: "msg-123",
+          associatedMessageType: 2001, // Thumbs up
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockEnqueueSystemEvent).toHaveBeenCalledWith(
+        expect.stringContaining("👍"),
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe("short message ID mapping", () => {
+    it("assigns sequential short IDs to messages", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "p:1/msg-uuid-12345",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalled();
+      const callArgs = mockDispatchReplyWithBufferedBlockDispatcher.mock.calls[0][0];
+      // MessageSid should be short ID "1" instead of full UUID
+      expect(callArgs.ctx.MessageSid).toBe("1");
+      expect(callArgs.ctx.MessageSidFull).toBe("p:1/msg-uuid-12345");
+    });
+
+    it("resolves short ID back to UUID", async () => {
+      const account = createMockAccount({ dmPolicy: "open" });
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "p:1/msg-uuid-12345",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      // The short ID "1" should resolve back to the full UUID
+      expect(resolveBlueBubblesMessageId("1")).toBe("p:1/msg-uuid-12345");
+    });
+
+    it("returns UUID unchanged when not in cache", () => {
+      expect(resolveBlueBubblesMessageId("msg-not-cached")).toBe("msg-not-cached");
+    });
+
+    it("returns short ID unchanged when numeric but not in cache", () => {
+      expect(resolveBlueBubblesMessageId("999")).toBe("999");
+    });
+
+    it("throws when numeric short ID is missing and requireKnownShortId is set", () => {
+      expect(() => resolveBlueBubblesMessageId("999", { requireKnownShortId: true })).toThrow(
+        /short message id/i,
+      );
+    });
+  });
+
+  describe("fromMe messages", () => {
+    it("ignores messages from self (fromMe=true)", async () => {
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "my own message",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: true,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await flushAsync();
+
+      expect(mockDispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    });
+  });
+});

extensions/bluebubbles/src/monitor.ts

@@ -0,0 +1,2469 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  logAckFailure,
+  logInboundDrop,
+  logTypingFailure,
+  resolveAckReaction,
+  resolveControlCommandGate,
+} from "openclaw/plugin-sdk";
+import type { ResolvedBlueBubblesAccount } from "./accounts.js";
+import type { BlueBubblesAccountConfig, BlueBubblesAttachment } from "./types.js";
+import { downloadBlueBubblesAttachment } from "./attachments.js";
+import { markBlueBubblesChatRead, sendBlueBubblesTyping } from "./chat.js";
+import { sendBlueBubblesMedia } from "./media-send.js";
+import { fetchBlueBubblesServerInfo } from "./probe.js";
+import { normalizeBlueBubblesReactionInput, sendBlueBubblesReaction } from "./reactions.js";
+import { getBlueBubblesRuntime } from "./runtime.js";
+import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
+import {
+  formatBlueBubblesChatTarget,
+  isAllowedBlueBubblesSender,
+  normalizeBlueBubblesHandle,
+} from "./targets.js";
+
+export type BlueBubblesRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type BlueBubblesMonitorOptions = {
+  account: ResolvedBlueBubblesAccount;
+  config: OpenClawConfig;
+  runtime: BlueBubblesRuntimeEnv;
+  abortSignal: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  webhookPath?: string;
+};
+
+const DEFAULT_WEBHOOK_PATH = "/bluebubbles-webhook";
+const DEFAULT_TEXT_LIMIT = 4000;
+const invalidAckReactions = new Set<string>();
+
+const REPLY_CACHE_MAX = 2000;
+const REPLY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+type BlueBubblesReplyCacheEntry = {
+  accountId: string;
+  messageId: string;
+  shortId: string;
+  chatGuid?: string;
+  chatIdentifier?: string;
+  chatId?: number;
+  senderLabel?: string;
+  body?: string;
+  timestamp: number;
+};
+
+// Best-effort cache for resolving reply context when BlueBubbles webhooks omit sender/body.
+const blueBubblesReplyCacheByMessageId = new Map<string, BlueBubblesReplyCacheEntry>();
+
+// Bidirectional maps for short ID ↔ message GUID resolution (token savings optimization)
+const blueBubblesShortIdToUuid = new Map<string, string>();
+const blueBubblesUuidToShortId = new Map<string, string>();
+let blueBubblesShortIdCounter = 0;
+
+function trimOrUndefined(value?: string | null): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function generateShortId(): string {
+  blueBubblesShortIdCounter += 1;
+  return String(blueBubblesShortIdCounter);
+}
+
+function rememberBlueBubblesReplyCache(
+  entry: Omit<BlueBubblesReplyCacheEntry, "shortId">,
+): BlueBubblesReplyCacheEntry {
+  const messageId = entry.messageId.trim();
+  if (!messageId) {
+    return { ...entry, shortId: "" };
+  }
+
+  // Check if we already have a short ID for this GUID
+  let shortId = blueBubblesUuidToShortId.get(messageId);
+  if (!shortId) {
+    shortId = generateShortId();
+    blueBubblesShortIdToUuid.set(shortId, messageId);
+    blueBubblesUuidToShortId.set(messageId, shortId);
+  }
+
+  const fullEntry: BlueBubblesReplyCacheEntry = { ...entry, messageId, shortId };
+
+  // Refresh insertion order.
+  blueBubblesReplyCacheByMessageId.delete(messageId);
+  blueBubblesReplyCacheByMessageId.set(messageId, fullEntry);
+
+  // Opportunistic prune.
+  const cutoff = Date.now() - REPLY_CACHE_TTL_MS;
+  for (const [key, value] of blueBubblesReplyCacheByMessageId) {
+    if (value.timestamp < cutoff) {
+      blueBubblesReplyCacheByMessageId.delete(key);
+      // Clean up short ID mappings for expired entries
+      if (value.shortId) {
+        blueBubblesShortIdToUuid.delete(value.shortId);
+        blueBubblesUuidToShortId.delete(key);
+      }
+      continue;
+    }
+    break;
+  }
+  while (blueBubblesReplyCacheByMessageId.size > REPLY_CACHE_MAX) {
+    const oldest = blueBubblesReplyCacheByMessageId.keys().next().value as string | undefined;
+    if (!oldest) {
+      break;
+    }
+    const oldEntry = blueBubblesReplyCacheByMessageId.get(oldest);
+    blueBubblesReplyCacheByMessageId.delete(oldest);
+    // Clean up short ID mappings for evicted entries
+    if (oldEntry?.shortId) {
+      blueBubblesShortIdToUuid.delete(oldEntry.shortId);
+      blueBubblesUuidToShortId.delete(oldest);
+    }
+  }
+
+  return fullEntry;
+}
+
+/**
+ * Resolves a short message ID (e.g., "1", "2") to a full BlueBubbles GUID.
+ * Returns the input unchanged if it's already a GUID or not found in the mapping.
+ */
+export function resolveBlueBubblesMessageId(
+  shortOrUuid: string,
+  opts?: { requireKnownShortId?: boolean },
+): string {
+  const trimmed = shortOrUuid.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+
+  // If it looks like a short ID (numeric), try to resolve it
+  if (/^\d+$/.test(trimmed)) {
+    const uuid = blueBubblesShortIdToUuid.get(trimmed);
+    if (uuid) {
+      return uuid;
+    }
+    if (opts?.requireKnownShortId) {
+      throw new Error(
+        `BlueBubbles short message id "${trimmed}" is no longer available. Use MessageSidFull.`,
+      );
+    }
+  }
+
+  // Return as-is (either already a UUID or not found)
+  return trimmed;
+}
+
+/**
+ * Resets the short ID state. Only use in tests.
+ * @internal
+ */
+export function _resetBlueBubblesShortIdState(): void {
+  blueBubblesShortIdToUuid.clear();
+  blueBubblesUuidToShortId.clear();
+  blueBubblesReplyCacheByMessageId.clear();
+  blueBubblesShortIdCounter = 0;
+}
+
+/**
+ * Gets the short ID for a message GUID, if one exists.
+ */
+function getShortIdForUuid(uuid: string): string | undefined {
+  return blueBubblesUuidToShortId.get(uuid.trim());
+}
+
+function resolveReplyContextFromCache(params: {
+  accountId: string;
+  replyToId: string;
+  chatGuid?: string;
+  chatIdentifier?: string;
+  chatId?: number;
+}): BlueBubblesReplyCacheEntry | null {
+  const replyToId = params.replyToId.trim();
+  if (!replyToId) {
+    return null;
+  }
+
+  const cached = blueBubblesReplyCacheByMessageId.get(replyToId);
+  if (!cached) {
+    return null;
+  }
+  if (cached.accountId !== params.accountId) {
+    return null;
+  }
+
+  const cutoff = Date.now() - REPLY_CACHE_TTL_MS;
+  if (cached.timestamp < cutoff) {
+    blueBubblesReplyCacheByMessageId.delete(replyToId);
+    return null;
+  }
+
+  const chatGuid = trimOrUndefined(params.chatGuid);
+  const chatIdentifier = trimOrUndefined(params.chatIdentifier);
+  const cachedChatGuid = trimOrUndefined(cached.chatGuid);
+  const cachedChatIdentifier = trimOrUndefined(cached.chatIdentifier);
+  const chatId = typeof params.chatId === "number" ? params.chatId : undefined;
+  const cachedChatId = typeof cached.chatId === "number" ? cached.chatId : undefined;
+
+  // Avoid cross-chat collisions if we have identifiers.
+  if (chatGuid && cachedChatGuid && chatGuid !== cachedChatGuid) {
+    return null;
+  }
+  if (
+    !chatGuid &&
+    chatIdentifier &&
+    cachedChatIdentifier &&
+    chatIdentifier !== cachedChatIdentifier
+  ) {
+    return null;
+  }
+  if (!chatGuid && !chatIdentifier && chatId && cachedChatId && chatId !== cachedChatId) {
+    return null;
+  }
+
+  return cached;
+}
+
+type BlueBubblesCoreRuntime = ReturnType<typeof getBlueBubblesRuntime>;
+
+function logVerbose(
+  core: BlueBubblesCoreRuntime,
+  runtime: BlueBubblesRuntimeEnv,
+  message: string,
+): void {
+  if (core.logging.shouldLogVerbose()) {
+    runtime.log?.(`[bluebubbles] ${message}`);
+  }
+}
+
+function logGroupAllowlistHint(params: {
+  runtime: BlueBubblesRuntimeEnv;
+  reason: string;
+  entry: string | null;
+  chatName?: string;
+  accountId?: string;
+}): void {
+  const log = params.runtime.log ?? console.log;
+  const nameHint = params.chatName ? ` (group name: ${params.chatName})` : "";
+  const accountHint = params.accountId
+    ? ` (or channels.bluebubbles.accounts.${params.accountId}.groupAllowFrom)`
+    : "";
+  if (params.entry) {
+    log(
+      `[bluebubbles] group message blocked (${params.reason}). Allow this group by adding ` +
+        `"${params.entry}" to channels.bluebubbles.groupAllowFrom${nameHint}.`,
+    );
+    log(
+      `[bluebubbles] add to config: channels.bluebubbles.groupAllowFrom=["${params.entry}"]${accountHint}.`,
+    );
+    return;
+  }
+  log(
+    `[bluebubbles] group message blocked (${params.reason}). Allow groups by setting ` +
+      `channels.bluebubbles.groupPolicy="open" or adding a group id to ` +
+      `channels.bluebubbles.groupAllowFrom${accountHint}${nameHint}.`,
+  );
+}
+
+type WebhookTarget = {
+  account: ResolvedBlueBubblesAccount;
+  config: OpenClawConfig;
+  runtime: BlueBubblesRuntimeEnv;
+  core: BlueBubblesCoreRuntime;
+  path: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+/**
+ * Entry type for debouncing inbound messages.
+ * Captures the normalized message and its target for later combined processing.
+ */
+type BlueBubblesDebounceEntry = {
+  message: NormalizedWebhookMessage;
+  target: WebhookTarget;
+};
+
+/**
+ * Default debounce window for inbound message coalescing (ms).
+ * This helps combine URL text + link preview balloon messages that BlueBubbles
+ * sends as separate webhook events when no explicit inbound debounce config exists.
+ */
+const DEFAULT_INBOUND_DEBOUNCE_MS = 500;
+
+/**
+ * Combines multiple debounced messages into a single message for processing.
+ * Used when multiple webhook events arrive within the debounce window.
+ */
+function combineDebounceEntries(entries: BlueBubblesDebounceEntry[]): NormalizedWebhookMessage {
+  if (entries.length === 0) {
+    throw new Error("Cannot combine empty entries");
+  }
+  if (entries.length === 1) {
+    return entries[0].message;
+  }
+
+  // Use the first message as the base (typically the text message)
+  const first = entries[0].message;
+
+  // Combine text from all entries, filtering out duplicates and empty strings
+  const seenTexts = new Set<string>();
+  const textParts: string[] = [];
+
+  for (const entry of entries) {
+    const text = entry.message.text.trim();
+    if (!text) {
+      continue;
+    }
+    // Skip duplicate text (URL might be in both text message and balloon)
+    const normalizedText = text.toLowerCase();
+    if (seenTexts.has(normalizedText)) {
+      continue;
+    }
+    seenTexts.add(normalizedText);
+    textParts.push(text);
+  }
+
+  // Merge attachments from all entries
+  const allAttachments = entries.flatMap((e) => e.message.attachments ?? []);
+
+  // Use the latest timestamp
+  const timestamps = entries
+    .map((e) => e.message.timestamp)
+    .filter((t): t is number => typeof t === "number");
+  const latestTimestamp = timestamps.length > 0 ? Math.max(...timestamps) : first.timestamp;
+
+  // Collect all message IDs for reference
+  const messageIds = entries
+    .map((e) => e.message.messageId)
+    .filter((id): id is string => Boolean(id));
+
+  // Prefer reply context from any entry that has it
+  const entryWithReply = entries.find((e) => e.message.replyToId);
+
+  return {
+    ...first,
+    text: textParts.join(" "),
+    attachments: allAttachments.length > 0 ? allAttachments : first.attachments,
+    timestamp: latestTimestamp,
+    // Use first message's ID as primary (for reply reference), but we've coalesced others
+    messageId: messageIds[0] ?? first.messageId,
+    // Preserve reply context if present
+    replyToId: entryWithReply?.message.replyToId ?? first.replyToId,
+    replyToBody: entryWithReply?.message.replyToBody ?? first.replyToBody,
+    replyToSender: entryWithReply?.message.replyToSender ?? first.replyToSender,
+    // Clear balloonBundleId since we've combined (the combined message is no longer just a balloon)
+    balloonBundleId: undefined,
+  };
+}
+
+const webhookTargets = new Map<string, WebhookTarget[]>();
+
+/**
+ * Maps webhook targets to their inbound debouncers.
+ * Each target gets its own debouncer keyed by a unique identifier.
+ */
+const targetDebouncers = new Map<
+  WebhookTarget,
+  ReturnType<BlueBubblesCoreRuntime["channel"]["debounce"]["createInboundDebouncer"]>
+>();
+
+function resolveBlueBubblesDebounceMs(
+  config: OpenClawConfig,
+  core: BlueBubblesCoreRuntime,
+): number {
+  const inbound = config.messages?.inbound;
+  const hasExplicitDebounce =
+    typeof inbound?.debounceMs === "number" || typeof inbound?.byChannel?.bluebubbles === "number";
+  if (!hasExplicitDebounce) {
+    return DEFAULT_INBOUND_DEBOUNCE_MS;
+  }
+  return core.channel.debounce.resolveInboundDebounceMs({ cfg: config, channel: "bluebubbles" });
+}
+
+/**
+ * Creates or retrieves a debouncer for a webhook target.
+ */
+function getOrCreateDebouncer(target: WebhookTarget) {
+  const existing = targetDebouncers.get(target);
+  if (existing) {
+    return existing;
+  }
+
+  const { account, config, runtime, core } = target;
+
+  const debouncer = core.channel.debounce.createInboundDebouncer<BlueBubblesDebounceEntry>({
+    debounceMs: resolveBlueBubblesDebounceMs(config, core),
+    buildKey: (entry) => {
+      const msg = entry.message;
+      // Prefer stable, shared identifiers to coalesce rapid-fire webhook events for the
+      // same message (e.g., text-only then text+attachment).
+      //
+      // For balloons (URL previews, stickers, etc), BlueBubbles often uses a different
+      // messageId than the originating text. When present, key by associatedMessageGuid
+      // to keep text + balloon coalescing working.
+      const balloonBundleId = msg.balloonBundleId?.trim();
+      const associatedMessageGuid = msg.associatedMessageGuid?.trim();
+      if (balloonBundleId && associatedMessageGuid) {
+        return `bluebubbles:${account.accountId}:balloon:${associatedMessageGuid}`;
+      }
+
+      const messageId = msg.messageId?.trim();
+      if (messageId) {
+        return `bluebubbles:${account.accountId}:msg:${messageId}`;
+      }
+
+      const chatKey =
+        msg.chatGuid?.trim() ??
+        msg.chatIdentifier?.trim() ??
+        (msg.chatId ? String(msg.chatId) : "dm");
+      return `bluebubbles:${account.accountId}:${chatKey}:${msg.senderId}`;
+    },
+    shouldDebounce: (entry) => {
+      const msg = entry.message;
+      // Skip debouncing for from-me messages (they're just cached, not processed)
+      if (msg.fromMe) {
+        return false;
+      }
+      // Skip debouncing for control commands - process immediately
+      if (core.channel.text.hasControlCommand(msg.text, config)) {
+        return false;
+      }
+      // Debounce all other messages to coalesce rapid-fire webhook events
+      // (e.g., text+image arriving as separate webhooks for the same messageId)
+      return true;
+    },
+    onFlush: async (entries) => {
+      if (entries.length === 0) {
+        return;
+      }
+
+      // Use target from first entry (all entries have same target due to key structure)
+      const flushTarget = entries[0].target;
+
+      if (entries.length === 1) {
+        // Single message - process normally
+        await processMessage(entries[0].message, flushTarget);
+        return;
+      }
+
+      // Multiple messages - combine and process
+      const combined = combineDebounceEntries(entries);
+
+      if (core.logging.shouldLogVerbose()) {
+        const count = entries.length;
+        const preview = combined.text.slice(0, 50);
+        runtime.log?.(
+          `[bluebubbles] coalesced ${count} messages: "${preview}${combined.text.length > 50 ? "..." : ""}"`,
+        );
+      }
+
+      await processMessage(combined, flushTarget);
+    },
+    onError: (err) => {
+      runtime.error?.(`[${account.accountId}] [bluebubbles] debounce flush failed: ${String(err)}`);
+    },
+  });
+
+  targetDebouncers.set(target, debouncer);
+  return debouncer;
+}
+
+/**
+ * Removes a debouncer for a target (called during unregistration).
+ */
+function removeDebouncer(target: WebhookTarget): void {
+  targetDebouncers.delete(target);
+}
+
+function normalizeWebhookPath(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (withSlash.length > 1 && withSlash.endsWith("/")) {
+    return withSlash.slice(0, -1);
+  }
+  return withSlash;
+}
+
+export function registerBlueBubblesWebhookTarget(target: WebhookTarget): () => void {
+  const key = normalizeWebhookPath(target.path);
+  const normalizedTarget = { ...target, path: key };
+  const existing = webhookTargets.get(key) ?? [];
+  const next = [...existing, normalizedTarget];
+  webhookTargets.set(key, next);
+  return () => {
+    const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
+    if (updated.length > 0) {
+      webhookTargets.set(key, updated);
+    } else {
+      webhookTargets.delete(key);
+    }
+    // Clean up debouncer when target is unregistered
+    removeDebouncer(normalizedTarget);
+  };
+}
+
+async function readJsonBody(req: IncomingMessage, maxBytes: number) {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  return await new Promise<{ ok: boolean; value?: unknown; error?: string }>((resolve) => {
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        resolve({ ok: false, error: "payload too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        const raw = Buffer.concat(chunks).toString("utf8");
+        if (!raw.trim()) {
+          resolve({ ok: false, error: "empty payload" });
+          return;
+        }
+        try {
+          resolve({ ok: true, value: JSON.parse(raw) as unknown });
+          return;
+        } catch {
+          const params = new URLSearchParams(raw);
+          const payload = params.get("payload") ?? params.get("data") ?? params.get("message");
+          if (payload) {
+            resolve({ ok: true, value: JSON.parse(payload) as unknown });
+            return;
+          }
+          throw new Error("invalid json");
+        }
+      } catch (err) {
+        resolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+      }
+    });
+    req.on("error", (err) => {
+      resolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    });
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function readString(record: Record<string, unknown> | null, key: string): string | undefined {
+  if (!record) {
+    return undefined;
+  }
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readNumber(record: Record<string, unknown> | null, key: string): number | undefined {
+  if (!record) {
+    return undefined;
+  }
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function readBoolean(record: Record<string, unknown> | null, key: string): boolean | undefined {
+  if (!record) {
+    return undefined;
+  }
+  const value = record[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function extractAttachments(message: Record<string, unknown>): BlueBubblesAttachment[] {
+  const raw = message["attachments"];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const out: BlueBubblesAttachment[] = [];
+  for (const entry of raw) {
+    const record = asRecord(entry);
+    if (!record) {
+      continue;
+    }
+    out.push({
+      guid: readString(record, "guid"),
+      uti: readString(record, "uti"),
+      mimeType: readString(record, "mimeType") ?? readString(record, "mime_type"),
+      transferName: readString(record, "transferName") ?? readString(record, "transfer_name"),
+      totalBytes: readNumberLike(record, "totalBytes") ?? readNumberLike(record, "total_bytes"),
+      height: readNumberLike(record, "height"),
+      width: readNumberLike(record, "width"),
+      originalROWID: readNumberLike(record, "originalROWID") ?? readNumberLike(record, "rowid"),
+    });
+  }
+  return out;
+}
+
+function buildAttachmentPlaceholder(attachments: BlueBubblesAttachment[]): string {
+  if (attachments.length === 0) {
+    return "";
+  }
+  const mimeTypes = attachments.map((entry) => entry.mimeType ?? "");
+  const allImages = mimeTypes.every((entry) => entry.startsWith("image/"));
+  const allVideos = mimeTypes.every((entry) => entry.startsWith("video/"));
+  const allAudio = mimeTypes.every((entry) => entry.startsWith("audio/"));
+  const tag = allImages
+    ? "<media:image>"
+    : allVideos
+      ? "<media:video>"
+      : allAudio
+        ? "<media:audio>"
+        : "<media:attachment>";
+  const label = allImages ? "image" : allVideos ? "video" : allAudio ? "audio" : "file";
+  const suffix = attachments.length === 1 ? label : `${label}s`;
+  return `${tag} (${attachments.length} ${suffix})`;
+}
+
+function buildMessagePlaceholder(message: NormalizedWebhookMessage): string {
+  const attachmentPlaceholder = buildAttachmentPlaceholder(message.attachments ?? []);
+  if (attachmentPlaceholder) {
+    return attachmentPlaceholder;
+  }
+  if (message.balloonBundleId) {
+    return "<media:sticker>";
+  }
+  return "";
+}
+
+// Returns inline reply tag like "[[reply_to:4]]" for prepending to message body
+function formatReplyTag(message: { replyToId?: string; replyToShortId?: string }): string | null {
+  // Prefer short ID
+  const rawId = message.replyToShortId || message.replyToId;
+  if (!rawId) {
+    return null;
+  }
+  return `[[reply_to:${rawId}]]`;
+}
+
+function readNumberLike(record: Record<string, unknown> | null, key: string): number | undefined {
+  if (!record) {
+    return undefined;
+  }
+  const value = record[key];
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
+function extractReplyMetadata(message: Record<string, unknown>): {
+  replyToId?: string;
+  replyToBody?: string;
+  replyToSender?: string;
+} {
+  const replyRaw =
+    message["replyTo"] ??
+    message["reply_to"] ??
+    message["replyToMessage"] ??
+    message["reply_to_message"] ??
+    message["repliedMessage"] ??
+    message["quotedMessage"] ??
+    message["associatedMessage"] ??
+    message["reply"];
+  const replyRecord = asRecord(replyRaw);
+  const replyHandle =
+    asRecord(replyRecord?.["handle"]) ?? asRecord(replyRecord?.["sender"]) ?? null;
+  const replySenderRaw =
+    readString(replyHandle, "address") ??
+    readString(replyHandle, "handle") ??
+    readString(replyHandle, "id") ??
+    readString(replyRecord, "senderId") ??
+    readString(replyRecord, "sender") ??
+    readString(replyRecord, "from");
+  const normalizedSender = replySenderRaw
+    ? normalizeBlueBubblesHandle(replySenderRaw) || replySenderRaw.trim()
+    : undefined;
+
+  const replyToBody =
+    readString(replyRecord, "text") ??
+    readString(replyRecord, "body") ??
+    readString(replyRecord, "message") ??
+    readString(replyRecord, "subject") ??
+    undefined;
+
+  const directReplyId =
+    readString(message, "replyToMessageGuid") ??
+    readString(message, "replyToGuid") ??
+    readString(message, "replyGuid") ??
+    readString(message, "selectedMessageGuid") ??
+    readString(message, "selectedMessageId") ??
+    readString(message, "replyToMessageId") ??
+    readString(message, "replyId") ??
+    readString(replyRecord, "guid") ??
+    readString(replyRecord, "id") ??
+    readString(replyRecord, "messageId");
+
+  const associatedType =
+    readNumberLike(message, "associatedMessageType") ??
+    readNumberLike(message, "associated_message_type");
+  const associatedGuid =
+    readString(message, "associatedMessageGuid") ??
+    readString(message, "associated_message_guid") ??
+    readString(message, "associatedMessageId");
+  const isReactionAssociation =
+    typeof associatedType === "number" && REACTION_TYPE_MAP.has(associatedType);
+
+  const replyToId = directReplyId ?? (!isReactionAssociation ? associatedGuid : undefined);
+  const threadOriginatorGuid = readString(message, "threadOriginatorGuid");
+  const messageGuid = readString(message, "guid");
+  const fallbackReplyId =
+    !replyToId && threadOriginatorGuid && threadOriginatorGuid !== messageGuid
+      ? threadOriginatorGuid
+      : undefined;
+
+  return {
+    replyToId: (replyToId ?? fallbackReplyId)?.trim() || undefined,
+    replyToBody: replyToBody?.trim() || undefined,
+    replyToSender: normalizedSender || undefined,
+  };
+}
+
+function readFirstChatRecord(message: Record<string, unknown>): Record<string, unknown> | null {
+  const chats = message["chats"];
+  if (!Array.isArray(chats) || chats.length === 0) {
+    return null;
+  }
+  const first = chats[0];
+  return asRecord(first);
+}
+
+function normalizeParticipantEntry(entry: unknown): BlueBubblesParticipant | null {
+  if (typeof entry === "string" || typeof entry === "number") {
+    const raw = String(entry).trim();
+    if (!raw) {
+      return null;
+    }
+    const normalized = normalizeBlueBubblesHandle(raw) || raw;
+    return normalized ? { id: normalized } : null;
+  }
+  const record = asRecord(entry);
+  if (!record) {
+    return null;
+  }
+  const nestedHandle =
+    asRecord(record["handle"]) ?? asRecord(record["sender"]) ?? asRecord(record["contact"]) ?? null;
+  const idRaw =
+    readString(record, "address") ??
+    readString(record, "handle") ??
+    readString(record, "id") ??
+    readString(record, "phoneNumber") ??
+    readString(record, "phone_number") ??
+    readString(record, "email") ??
+    readString(nestedHandle, "address") ??
+    readString(nestedHandle, "handle") ??
+    readString(nestedHandle, "id");
+  const nameRaw =
+    readString(record, "displayName") ??
+    readString(record, "name") ??
+    readString(record, "title") ??
+    readString(nestedHandle, "displayName") ??
+    readString(nestedHandle, "name");
+  const normalizedId = idRaw ? normalizeBlueBubblesHandle(idRaw) || idRaw.trim() : "";
+  if (!normalizedId) {
+    return null;
+  }
+  const name = nameRaw?.trim() || undefined;
+  return { id: normalizedId, name };
+}
+
+function normalizeParticipantList(raw: unknown): BlueBubblesParticipant[] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return [];
+  }
+  const seen = new Set<string>();
+  const output: BlueBubblesParticipant[] = [];
+  for (const entry of raw) {
+    const normalized = normalizeParticipantEntry(entry);
+    if (!normalized?.id) {
+      continue;
+    }
+    const key = normalized.id.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    output.push(normalized);
+  }
+  return output;
+}
+
+function formatGroupMembers(params: {
+  participants?: BlueBubblesParticipant[];
+  fallback?: BlueBubblesParticipant;
+}): string | undefined {
+  const seen = new Set<string>();
+  const ordered: BlueBubblesParticipant[] = [];
+  for (const entry of params.participants ?? []) {
+    if (!entry?.id) {
+      continue;
+    }
+    const key = entry.id.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    ordered.push(entry);
+  }
+  if (ordered.length === 0 && params.fallback?.id) {
+    ordered.push(params.fallback);
+  }
+  if (ordered.length === 0) {
+    return undefined;
+  }
+  return ordered.map((entry) => (entry.name ? `${entry.name} (${entry.id})` : entry.id)).join(", ");
+}
+
+function resolveGroupFlagFromChatGuid(chatGuid?: string | null): boolean | undefined {
+  const guid = chatGuid?.trim();
+  if (!guid) {
+    return undefined;
+  }
+  const parts = guid.split(";");
+  if (parts.length >= 3) {
+    if (parts[1] === "+") {
+      return true;
+    }
+    if (parts[1] === "-") {
+      return false;
+    }
+  }
+  if (guid.includes(";+;")) {
+    return true;
+  }
+  if (guid.includes(";-;")) {
+    return false;
+  }
+  return undefined;
+}
+
+function extractChatIdentifierFromChatGuid(chatGuid?: string | null): string | undefined {
+  const guid = chatGuid?.trim();
+  if (!guid) {
+    return undefined;
+  }
+  const parts = guid.split(";");
+  if (parts.length < 3) {
+    return undefined;
+  }
+  const identifier = parts[2]?.trim();
+  return identifier || undefined;
+}
+
+function formatGroupAllowlistEntry(params: {
+  chatGuid?: string;
+  chatId?: number;
+  chatIdentifier?: string;
+}): string | null {
+  const guid = params.chatGuid?.trim();
+  if (guid) {
+    return `chat_guid:${guid}`;
+  }
+  const chatId = params.chatId;
+  if (typeof chatId === "number" && Number.isFinite(chatId)) {
+    return `chat_id:${chatId}`;
+  }
+  const identifier = params.chatIdentifier?.trim();
+  if (identifier) {
+    return `chat_identifier:${identifier}`;
+  }
+  return null;
+}
+
+type BlueBubblesParticipant = {
+  id: string;
+  name?: string;
+};
+
+type NormalizedWebhookMessage = {
+  text: string;
+  senderId: string;
+  senderName?: string;
+  messageId?: string;
+  timestamp?: number;
+  isGroup: boolean;
+  chatId?: number;
+  chatGuid?: string;
+  chatIdentifier?: string;
+  chatName?: string;
+  fromMe?: boolean;
+  attachments?: BlueBubblesAttachment[];
+  balloonBundleId?: string;
+  associatedMessageGuid?: string;
+  associatedMessageType?: number;
+  associatedMessageEmoji?: string;
+  isTapback?: boolean;
+  participants?: BlueBubblesParticipant[];
+  replyToId?: string;
+  replyToBody?: string;
+  replyToSender?: string;
+};
+
+type NormalizedWebhookReaction = {
+  action: "added" | "removed";
+  emoji: string;
+  senderId: string;
+  senderName?: string;
+  messageId: string;
+  timestamp?: number;
+  isGroup: boolean;
+  chatId?: number;
+  chatGuid?: string;
+  chatIdentifier?: string;
+  chatName?: string;
+  fromMe?: boolean;
+};
+
+const REACTION_TYPE_MAP = new Map<number, { emoji: string; action: "added" | "removed" }>([
+  [2000, { emoji: "❤️", action: "added" }],
+  [2001, { emoji: "👍", action: "added" }],
+  [2002, { emoji: "👎", action: "added" }],
+  [2003, { emoji: "😂", action: "added" }],
+  [2004, { emoji: "‼️", action: "added" }],
+  [2005, { emoji: "❓", action: "added" }],
+  [3000, { emoji: "❤️", action: "removed" }],
+  [3001, { emoji: "👍", action: "removed" }],
+  [3002, { emoji: "��", action: "removed" }],
+  [3003, { emoji: "😂", action: "removed" }],
+  [3004, { emoji: "‼️", action: "removed" }],
+  [3005, { emoji: "❓", action: "removed" }],
+]);
+
+// Maps tapback text patterns (e.g., "Loved", "Liked") to emoji + action
+const TAPBACK_TEXT_MAP = new Map<string, { emoji: string; action: "added" | "removed" }>([
+  ["loved", { emoji: "❤️", action: "added" }],
+  ["liked", { emoji: "👍", action: "added" }],
+  ["disliked", { emoji: "👎", action: "added" }],
+  ["laughed at", { emoji: "😂", action: "added" }],
+  ["emphasized", { emoji: "‼️", action: "added" }],
+  ["questioned", { emoji: "❓", action: "added" }],
+  // Removal patterns (e.g., "Removed a heart from")
+  ["removed a heart from", { emoji: "❤️", action: "removed" }],
+  ["removed a like from", { emoji: "👍", action: "removed" }],
+  ["removed a dislike from", { emoji: "👎", action: "removed" }],
+  ["removed a laugh from", { emoji: "😂", action: "removed" }],
+  ["removed an emphasis from", { emoji: "‼️", action: "removed" }],
+  ["removed a question from", { emoji: "❓", action: "removed" }],
+]);
+
+const TAPBACK_EMOJI_REGEX =
+  /(?:\p{Regional_Indicator}{2})|(?:[0-9#*]\uFE0F?\u20E3)|(?:\p{Extended_Pictographic}(?:\uFE0F|\uFE0E)?(?:\p{Emoji_Modifier})?(?:\u200D\p{Extended_Pictographic}(?:\uFE0F|\uFE0E)?(?:\p{Emoji_Modifier})?)*)/u;
+
+function extractFirstEmoji(text: string): string | null {
+  const match = text.match(TAPBACK_EMOJI_REGEX);
+  return match ? match[0] : null;
+}
+
+function extractQuotedTapbackText(text: string): string | null {
+  const match = text.match(/[“"]([^”"]+)[”"]/s);
+  return match ? match[1] : null;
+}
+
+function isTapbackAssociatedType(type: number | undefined): boolean {
+  return typeof type === "number" && Number.isFinite(type) && type >= 2000 && type < 4000;
+}
+
+function resolveTapbackActionHint(type: number | undefined): "added" | "removed" | undefined {
+  if (typeof type !== "number" || !Number.isFinite(type)) {
+    return undefined;
+  }
+  if (type >= 3000 && type < 4000) {
+    return "removed";
+  }
+  if (type >= 2000 && type < 3000) {
+    return "added";
+  }
+  return undefined;
+}
+
+function resolveTapbackContext(message: NormalizedWebhookMessage): {
+  emojiHint?: string;
+  actionHint?: "added" | "removed";
+  replyToId?: string;
+} | null {
+  const associatedType = message.associatedMessageType;
+  const hasTapbackType = isTapbackAssociatedType(associatedType);
+  const hasTapbackMarker = Boolean(message.associatedMessageEmoji) || Boolean(message.isTapback);
+  if (!hasTapbackType && !hasTapbackMarker) {
+    return null;
+  }
+  const replyToId = message.associatedMessageGuid?.trim() || message.replyToId?.trim() || undefined;
+  const actionHint = resolveTapbackActionHint(associatedType);
+  const emojiHint =
+    message.associatedMessageEmoji?.trim() || REACTION_TYPE_MAP.get(associatedType ?? -1)?.emoji;
+  return { emojiHint, actionHint, replyToId };
+}
+
+// Detects tapback text patterns like 'Loved "message"' and converts to structured format
+function parseTapbackText(params: {
+  text: string;
+  emojiHint?: string;
+  actionHint?: "added" | "removed";
+  requireQuoted?: boolean;
+}): {
+  emoji: string;
+  action: "added" | "removed";
+  quotedText: string;
+} | null {
+  const trimmed = params.text.trim();
+  const lower = trimmed.toLowerCase();
+  if (!trimmed) {
+    return null;
+  }
+
+  for (const [pattern, { emoji, action }] of TAPBACK_TEXT_MAP) {
+    if (lower.startsWith(pattern)) {
+      // Extract quoted text if present (e.g., 'Loved "hello"' -> "hello")
+      const afterPattern = trimmed.slice(pattern.length).trim();
+      if (params.requireQuoted) {
+        const strictMatch = afterPattern.match(/^[“"](.+)[”"]$/s);
+        if (!strictMatch) {
+          return null;
+        }
+        return { emoji, action, quotedText: strictMatch[1] };
+      }
+      const quotedText =
+        extractQuotedTapbackText(afterPattern) ?? extractQuotedTapbackText(trimmed) ?? afterPattern;
+      return { emoji, action, quotedText };
+    }
+  }
+
+  if (lower.startsWith("reacted")) {
+    const emoji = extractFirstEmoji(trimmed) ?? params.emojiHint;
+    if (!emoji) {
+      return null;
+    }
+    const quotedText = extractQuotedTapbackText(trimmed);
+    if (params.requireQuoted && !quotedText) {
+      return null;
+    }
+    const fallback = trimmed.slice("reacted".length).trim();
+    return { emoji, action: params.actionHint ?? "added", quotedText: quotedText ?? fallback };
+  }
+
+  if (lower.startsWith("removed")) {
+    const emoji = extractFirstEmoji(trimmed) ?? params.emojiHint;
+    if (!emoji) {
+      return null;
+    }
+    const quotedText = extractQuotedTapbackText(trimmed);
+    if (params.requireQuoted && !quotedText) {
+      return null;
+    }
+    const fallback = trimmed.slice("removed".length).trim();
+    return { emoji, action: params.actionHint ?? "removed", quotedText: quotedText ?? fallback };
+  }
+  return null;
+}
+
+function maskSecret(value: string): string {
+  if (value.length <= 6) {
+    return "***";
+  }
+  return `${value.slice(0, 2)}***${value.slice(-2)}`;
+}
+
+function resolveBlueBubblesAckReaction(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  core: BlueBubblesCoreRuntime;
+  runtime: BlueBubblesRuntimeEnv;
+}): string | null {
+  const raw = resolveAckReaction(params.cfg, params.agentId).trim();
+  if (!raw) {
+    return null;
+  }
+  try {
+    normalizeBlueBubblesReactionInput(raw);
+    return raw;
+  } catch {
+    const key = raw.toLowerCase();
+    if (!invalidAckReactions.has(key)) {
+      invalidAckReactions.add(key);
+      logVerbose(
+        params.core,
+        params.runtime,
+        `ack reaction skipped (unsupported for BlueBubbles): ${raw}`,
+      );
+    }
+    return null;
+  }
+}
+
+function extractMessagePayload(payload: Record<string, unknown>): Record<string, unknown> | null {
+  const dataRaw = payload.data ?? payload.payload ?? payload.event;
+  const data =
+    asRecord(dataRaw) ??
+    (typeof dataRaw === "string" ? (asRecord(JSON.parse(dataRaw)) ?? null) : null);
+  const messageRaw = payload.message ?? data?.message ?? data;
+  const message =
+    asRecord(messageRaw) ??
+    (typeof messageRaw === "string" ? (asRecord(JSON.parse(messageRaw)) ?? null) : null);
+  if (!message) {
+    return null;
+  }
+  return message;
+}
+
+function normalizeWebhookMessage(
+  payload: Record<string, unknown>,
+): NormalizedWebhookMessage | null {
+  const message = extractMessagePayload(payload);
+  if (!message) {
+    return null;
+  }
+
+  const text =
+    readString(message, "text") ??
+    readString(message, "body") ??
+    readString(message, "subject") ??
+    "";
+
+  const handleValue = message.handle ?? message.sender;
+  const handle =
+    asRecord(handleValue) ?? (typeof handleValue === "string" ? { address: handleValue } : null);
+  const senderId =
+    readString(handle, "address") ??
+    readString(handle, "handle") ??
+    readString(handle, "id") ??
+    readString(message, "senderId") ??
+    readString(message, "sender") ??
+    readString(message, "from") ??
+    "";
+
+  const senderName =
+    readString(handle, "displayName") ??
+    readString(handle, "name") ??
+    readString(message, "senderName") ??
+    undefined;
+
+  const chat = asRecord(message.chat) ?? asRecord(message.conversation) ?? null;
+  const chatFromList = readFirstChatRecord(message);
+  const chatGuid =
+    readString(message, "chatGuid") ??
+    readString(message, "chat_guid") ??
+    readString(chat, "chatGuid") ??
+    readString(chat, "chat_guid") ??
+    readString(chat, "guid") ??
+    readString(chatFromList, "chatGuid") ??
+    readString(chatFromList, "chat_guid") ??
+    readString(chatFromList, "guid");
+  const chatIdentifier =
+    readString(message, "chatIdentifier") ??
+    readString(message, "chat_identifier") ??
+    readString(chat, "chatIdentifier") ??
+    readString(chat, "chat_identifier") ??
+    readString(chat, "identifier") ??
+    readString(chatFromList, "chatIdentifier") ??
+    readString(chatFromList, "chat_identifier") ??
+    readString(chatFromList, "identifier") ??
+    extractChatIdentifierFromChatGuid(chatGuid);
+  const chatId =
+    readNumberLike(message, "chatId") ??
+    readNumberLike(message, "chat_id") ??
+    readNumberLike(chat, "chatId") ??
+    readNumberLike(chat, "chat_id") ??
+    readNumberLike(chat, "id") ??
+    readNumberLike(chatFromList, "chatId") ??
+    readNumberLike(chatFromList, "chat_id") ??
+    readNumberLike(chatFromList, "id");
+  const chatName =
+    readString(message, "chatName") ??
+    readString(chat, "displayName") ??
+    readString(chat, "name") ??
+    readString(chatFromList, "displayName") ??
+    readString(chatFromList, "name") ??
+    undefined;
+
+  const chatParticipants = chat ? chat["participants"] : undefined;
+  const messageParticipants = message["participants"];
+  const chatsParticipants = chatFromList ? chatFromList["participants"] : undefined;
+  const participants = Array.isArray(chatParticipants)
+    ? chatParticipants
+    : Array.isArray(messageParticipants)
+      ? messageParticipants
+      : Array.isArray(chatsParticipants)
+        ? chatsParticipants
+        : [];
+  const normalizedParticipants = normalizeParticipantList(participants);
+  const participantsCount = participants.length;
+  const groupFromChatGuid = resolveGroupFlagFromChatGuid(chatGuid);
+  const explicitIsGroup =
+    readBoolean(message, "isGroup") ??
+    readBoolean(message, "is_group") ??
+    readBoolean(chat, "isGroup") ??
+    readBoolean(message, "group");
+  const isGroup =
+    typeof groupFromChatGuid === "boolean"
+      ? groupFromChatGuid
+      : (explicitIsGroup ?? participantsCount > 2);
+
+  const fromMe = readBoolean(message, "isFromMe") ?? readBoolean(message, "is_from_me");
+  const messageId =
+    readString(message, "guid") ??
+    readString(message, "id") ??
+    readString(message, "messageId") ??
+    undefined;
+  const balloonBundleId = readString(message, "balloonBundleId");
+  const associatedMessageGuid =
+    readString(message, "associatedMessageGuid") ??
+    readString(message, "associated_message_guid") ??
+    readString(message, "associatedMessageId") ??
+    undefined;
+  const associatedMessageType =
+    readNumberLike(message, "associatedMessageType") ??
+    readNumberLike(message, "associated_message_type");
+  const associatedMessageEmoji =
+    readString(message, "associatedMessageEmoji") ??
+    readString(message, "associated_message_emoji") ??
+    readString(message, "reactionEmoji") ??
+    readString(message, "reaction_emoji") ??
+    undefined;
+  const isTapback =
+    readBoolean(message, "isTapback") ??
+    readBoolean(message, "is_tapback") ??
+    readBoolean(message, "tapback") ??
+    undefined;
+
+  const timestampRaw =
+    readNumber(message, "date") ??
+    readNumber(message, "dateCreated") ??
+    readNumber(message, "timestamp");
+  const timestamp =
+    typeof timestampRaw === "number"
+      ? timestampRaw > 1_000_000_000_000
+        ? timestampRaw
+        : timestampRaw * 1000
+      : undefined;
+
+  const normalizedSender = normalizeBlueBubblesHandle(senderId);
+  if (!normalizedSender) {
+    return null;
+  }
+  const replyMetadata = extractReplyMetadata(message);
+
+  return {
+    text,
+    senderId: normalizedSender,
+    senderName,
+    messageId,
+    timestamp,
+    isGroup,
+    chatId,
+    chatGuid,
+    chatIdentifier,
+    chatName,
+    fromMe,
+    attachments: extractAttachments(message),
+    balloonBundleId,
+    associatedMessageGuid,
+    associatedMessageType,
+    associatedMessageEmoji,
+    isTapback,
+    participants: normalizedParticipants,
+    replyToId: replyMetadata.replyToId,
+    replyToBody: replyMetadata.replyToBody,
+    replyToSender: replyMetadata.replyToSender,
+  };
+}
+
+function normalizeWebhookReaction(
+  payload: Record<string, unknown>,
+): NormalizedWebhookReaction | null {
+  const message = extractMessagePayload(payload);
+  if (!message) {
+    return null;
+  }
+
+  const associatedGuid =
+    readString(message, "associatedMessageGuid") ??
+    readString(message, "associated_message_guid") ??
+    readString(message, "associatedMessageId");
+  const associatedType =
+    readNumberLike(message, "associatedMessageType") ??
+    readNumberLike(message, "associated_message_type");
+  if (!associatedGuid || associatedType === undefined) {
+    return null;
+  }
+
+  const mapping = REACTION_TYPE_MAP.get(associatedType);
+  const associatedEmoji =
+    readString(message, "associatedMessageEmoji") ??
+    readString(message, "associated_message_emoji") ??
+    readString(message, "reactionEmoji") ??
+    readString(message, "reaction_emoji");
+  const emoji = (associatedEmoji?.trim() || mapping?.emoji) ?? `reaction:${associatedType}`;
+  const action = mapping?.action ?? resolveTapbackActionHint(associatedType) ?? "added";
+
+  const handleValue = message.handle ?? message.sender;
+  const handle =
+    asRecord(handleValue) ?? (typeof handleValue === "string" ? { address: handleValue } : null);
+  const senderId =
+    readString(handle, "address") ??
+    readString(handle, "handle") ??
+    readString(handle, "id") ??
+    readString(message, "senderId") ??
+    readString(message, "sender") ??
+    readString(message, "from") ??
+    "";
+  const senderName =
+    readString(handle, "displayName") ??
+    readString(handle, "name") ??
+    readString(message, "senderName") ??
+    undefined;
+
+  const chat = asRecord(message.chat) ?? asRecord(message.conversation) ?? null;
+  const chatFromList = readFirstChatRecord(message);
+  const chatGuid =
+    readString(message, "chatGuid") ??
+    readString(message, "chat_guid") ??
+    readString(chat, "chatGuid") ??
+    readString(chat, "chat_guid") ??
+    readString(chat, "guid") ??
+    readString(chatFromList, "chatGuid") ??
+    readString(chatFromList, "chat_guid") ??
+    readString(chatFromList, "guid");
+  const chatIdentifier =
+    readString(message, "chatIdentifier") ??
+    readString(message, "chat_identifier") ??
+    readString(chat, "chatIdentifier") ??
+    readString(chat, "chat_identifier") ??
+    readString(chat, "identifier") ??
+    readString(chatFromList, "chatIdentifier") ??
+    readString(chatFromList, "chat_identifier") ??
+    readString(chatFromList, "identifier") ??
+    extractChatIdentifierFromChatGuid(chatGuid);
+  const chatId =
+    readNumberLike(message, "chatId") ??
+    readNumberLike(message, "chat_id") ??
+    readNumberLike(chat, "chatId") ??
+    readNumberLike(chat, "chat_id") ??
+    readNumberLike(chat, "id") ??
+    readNumberLike(chatFromList, "chatId") ??
+    readNumberLike(chatFromList, "chat_id") ??
+    readNumberLike(chatFromList, "id");
+  const chatName =
+    readString(message, "chatName") ??
+    readString(chat, "displayName") ??
+    readString(chat, "name") ??
+    readString(chatFromList, "displayName") ??
+    readString(chatFromList, "name") ??
+    undefined;
+
+  const chatParticipants = chat ? chat["participants"] : undefined;
+  const messageParticipants = message["participants"];
+  const chatsParticipants = chatFromList ? chatFromList["participants"] : undefined;
+  const participants = Array.isArray(chatParticipants)
+    ? chatParticipants
+    : Array.isArray(messageParticipants)
+      ? messageParticipants
+      : Array.isArray(chatsParticipants)
+        ? chatsParticipants
+        : [];
+  const participantsCount = participants.length;
+  const groupFromChatGuid = resolveGroupFlagFromChatGuid(chatGuid);
+  const explicitIsGroup =
+    readBoolean(message, "isGroup") ??
+    readBoolean(message, "is_group") ??
+    readBoolean(chat, "isGroup") ??
+    readBoolean(message, "group");
+  const isGroup =
+    typeof groupFromChatGuid === "boolean"
+      ? groupFromChatGuid
+      : (explicitIsGroup ?? participantsCount > 2);
+
+  const fromMe = readBoolean(message, "isFromMe") ?? readBoolean(message, "is_from_me");
+  const timestampRaw =
+    readNumberLike(message, "date") ??
+    readNumberLike(message, "dateCreated") ??
+    readNumberLike(message, "timestamp");
+  const timestamp =
+    typeof timestampRaw === "number"
+      ? timestampRaw > 1_000_000_000_000
+        ? timestampRaw
+        : timestampRaw * 1000
+      : undefined;
+
+  const normalizedSender = normalizeBlueBubblesHandle(senderId);
+  if (!normalizedSender) {
+    return null;
+  }
+
+  return {
+    action,
+    emoji,
+    senderId: normalizedSender,
+    senderName,
+    messageId: associatedGuid,
+    timestamp,
+    isGroup,
+    chatId,
+    chatGuid,
+    chatIdentifier,
+    chatName,
+    fromMe,
+  };
+}
+
+export async function handleBlueBubblesWebhookRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const path = normalizeWebhookPath(url.pathname);
+  const targets = webhookTargets.get(path);
+  if (!targets || targets.length === 0) {
+    return false;
+  }
+
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    res.setHeader("Allow", "POST");
+    res.end("Method Not Allowed");
+    return true;
+  }
+
+  const body = await readJsonBody(req, 1024 * 1024);
+  if (!body.ok) {
+    res.statusCode = body.error === "payload too large" ? 413 : 400;
+    res.end(body.error ?? "invalid payload");
+    console.warn(`[bluebubbles] webhook rejected: ${body.error ?? "invalid payload"}`);
+    return true;
+  }
+
+  const payload = asRecord(body.value) ?? {};
+  const firstTarget = targets[0];
+  if (firstTarget) {
+    logVerbose(
+      firstTarget.core,
+      firstTarget.runtime,
+      `webhook received path=${path} keys=${Object.keys(payload).join(",") || "none"}`,
+    );
+  }
+  const eventTypeRaw = payload.type;
+  const eventType = typeof eventTypeRaw === "string" ? eventTypeRaw.trim() : "";
+  const allowedEventTypes = new Set([
+    "new-message",
+    "updated-message",
+    "message-reaction",
+    "reaction",
+  ]);
+  if (eventType && !allowedEventTypes.has(eventType)) {
+    res.statusCode = 200;
+    res.end("ok");
+    if (firstTarget) {
+      logVerbose(firstTarget.core, firstTarget.runtime, `webhook ignored type=${eventType}`);
+    }
+    return true;
+  }
+  const reaction = normalizeWebhookReaction(payload);
+  if (
+    (eventType === "updated-message" ||
+      eventType === "message-reaction" ||
+      eventType === "reaction") &&
+    !reaction
+  ) {
+    res.statusCode = 200;
+    res.end("ok");
+    if (firstTarget) {
+      logVerbose(
+        firstTarget.core,
+        firstTarget.runtime,
+        `webhook ignored ${eventType || "event"} without reaction`,
+      );
+    }
+    return true;
+  }
+  const message = reaction ? null : normalizeWebhookMessage(payload);
+  if (!message && !reaction) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    console.warn("[bluebubbles] webhook rejected: unable to parse message payload");
+    return true;
+  }
+
+  const matching = targets.filter((target) => {
+    const token = target.account.config.password?.trim();
+    if (!token) {
+      return true;
+    }
+    const guidParam = url.searchParams.get("guid") ?? url.searchParams.get("password");
+    const headerToken =
+      req.headers["x-guid"] ??
+      req.headers["x-password"] ??
+      req.headers["x-bluebubbles-guid"] ??
+      req.headers["authorization"];
+    const guid = (Array.isArray(headerToken) ? headerToken[0] : headerToken) ?? guidParam ?? "";
+    if (guid && guid.trim() === token) {
+      return true;
+    }
+    const remote = req.socket?.remoteAddress ?? "";
+    if (remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1") {
+      return true;
+    }
+    return false;
+  });
+
+  if (matching.length === 0) {
+    res.statusCode = 401;
+    res.end("unauthorized");
+    console.warn(
+      `[bluebubbles] webhook rejected: unauthorized guid=${maskSecret(url.searchParams.get("guid") ?? url.searchParams.get("password") ?? "")}`,
+    );
+    return true;
+  }
+
+  for (const target of matching) {
+    target.statusSink?.({ lastInboundAt: Date.now() });
+    if (reaction) {
+      processReaction(reaction, target).catch((err) => {
+        target.runtime.error?.(
+          `[${target.account.accountId}] BlueBubbles reaction failed: ${String(err)}`,
+        );
+      });
+    } else if (message) {
+      // Route messages through debouncer to coalesce rapid-fire events
+      // (e.g., text message + URL balloon arriving as separate webhooks)
+      const debouncer = getOrCreateDebouncer(target);
+      debouncer.enqueue({ message, target }).catch((err) => {
+        target.runtime.error?.(
+          `[${target.account.accountId}] BlueBubbles webhook failed: ${String(err)}`,
+        );
+      });
+    }
+  }
+
+  res.statusCode = 200;
+  res.end("ok");
+  if (reaction) {
+    if (firstTarget) {
+      logVerbose(
+        firstTarget.core,
+        firstTarget.runtime,
+        `webhook accepted reaction sender=${reaction.senderId} msg=${reaction.messageId} action=${reaction.action}`,
+      );
+    }
+  } else if (message) {
+    if (firstTarget) {
+      logVerbose(
+        firstTarget.core,
+        firstTarget.runtime,
+        `webhook accepted sender=${message.senderId} group=${message.isGroup} chatGuid=${message.chatGuid ?? ""} chatId=${message.chatId ?? ""}`,
+      );
+    }
+  }
+  return true;
+}
+
+async function processMessage(
+  message: NormalizedWebhookMessage,
+  target: WebhookTarget,
+): Promise<void> {
+  const { account, config, runtime, core, statusSink } = target;
+
+  const groupFlag = resolveGroupFlagFromChatGuid(message.chatGuid);
+  const isGroup = typeof groupFlag === "boolean" ? groupFlag : message.isGroup;
+
+  const text = message.text.trim();
+  const attachments = message.attachments ?? [];
+  const placeholder = buildMessagePlaceholder(message);
+  // Check if text is a tapback pattern (e.g., 'Loved "hello"') and transform to emoji format
+  // For tapbacks, we'll append [[reply_to:N]] at the end; for regular messages, prepend it
+  const tapbackContext = resolveTapbackContext(message);
+  const tapbackParsed = parseTapbackText({
+    text,
+    emojiHint: tapbackContext?.emojiHint,
+    actionHint: tapbackContext?.actionHint,
+    requireQuoted: !tapbackContext,
+  });
+  const isTapbackMessage = Boolean(tapbackParsed);
+  const rawBody = tapbackParsed
+    ? tapbackParsed.action === "removed"
+      ? `removed ${tapbackParsed.emoji} reaction`
+      : `reacted with ${tapbackParsed.emoji}`
+    : text || placeholder;
+
+  const cacheMessageId = message.messageId?.trim();
+  let messageShortId: string | undefined;
+  const cacheInboundMessage = () => {
+    if (!cacheMessageId) {
+      return;
+    }
+    const cacheEntry = rememberBlueBubblesReplyCache({
+      accountId: account.accountId,
+      messageId: cacheMessageId,
+      chatGuid: message.chatGuid,
+      chatIdentifier: message.chatIdentifier,
+      chatId: message.chatId,
+      senderLabel: message.fromMe ? "me" : message.senderId,
+      body: rawBody,
+      timestamp: message.timestamp ?? Date.now(),
+    });
+    messageShortId = cacheEntry.shortId;
+  };
+
+  if (message.fromMe) {
+    // Cache from-me messages so reply context can resolve sender/body.
+    cacheInboundMessage();
+    return;
+  }
+
+  if (!rawBody) {
+    logVerbose(core, runtime, `drop: empty text sender=${message.senderId}`);
+    return;
+  }
+  logVerbose(
+    core,
+    runtime,
+    `msg sender=${message.senderId} group=${isGroup} textLen=${text.length} attachments=${attachments.length} chatGuid=${message.chatGuid ?? ""} chatId=${message.chatId ?? ""}`,
+  );
+
+  const dmPolicy = account.config.dmPolicy ?? "pairing";
+  const groupPolicy = account.config.groupPolicy ?? "allowlist";
+  const configAllowFrom = (account.config.allowFrom ?? []).map((entry) => String(entry));
+  const configGroupAllowFrom = (account.config.groupAllowFrom ?? []).map((entry) => String(entry));
+  const storeAllowFrom = await core.channel.pairing
+    .readAllowFromStore("bluebubbles")
+    .catch(() => []);
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom]
+    .map((entry) => String(entry).trim())
+    .filter(Boolean);
+  const effectiveGroupAllowFrom = [
+    ...(configGroupAllowFrom.length > 0 ? configGroupAllowFrom : configAllowFrom),
+    ...storeAllowFrom,
+  ]
+    .map((entry) => String(entry).trim())
+    .filter(Boolean);
+  const groupAllowEntry = formatGroupAllowlistEntry({
+    chatGuid: message.chatGuid,
+    chatId: message.chatId ?? undefined,
+    chatIdentifier: message.chatIdentifier ?? undefined,
+  });
+  const groupName = message.chatName?.trim() || undefined;
+
+  if (isGroup) {
+    if (groupPolicy === "disabled") {
+      logVerbose(core, runtime, "Blocked BlueBubbles group message (groupPolicy=disabled)");
+      logGroupAllowlistHint({
+        runtime,
+        reason: "groupPolicy=disabled",
+        entry: groupAllowEntry,
+        chatName: groupName,
+        accountId: account.accountId,
+      });
+      return;
+    }
+    if (groupPolicy === "allowlist") {
+      if (effectiveGroupAllowFrom.length === 0) {
+        logVerbose(core, runtime, "Blocked BlueBubbles group message (no allowlist)");
+        logGroupAllowlistHint({
+          runtime,
+          reason: "groupPolicy=allowlist (empty allowlist)",
+          entry: groupAllowEntry,
+          chatName: groupName,
+          accountId: account.accountId,
+        });
+        return;
+      }
+      const allowed = isAllowedBlueBubblesSender({
+        allowFrom: effectiveGroupAllowFrom,
+        sender: message.senderId,
+        chatId: message.chatId ?? undefined,
+        chatGuid: message.chatGuid ?? undefined,
+        chatIdentifier: message.chatIdentifier ?? undefined,
+      });
+      if (!allowed) {
+        logVerbose(
+          core,
+          runtime,
+          `Blocked BlueBubbles sender ${message.senderId} (not in groupAllowFrom)`,
+        );
+        logVerbose(
+          core,
+          runtime,
+          `drop: group sender not allowed sender=${message.senderId} allowFrom=${effectiveGroupAllowFrom.join(",")}`,
+        );
+        logGroupAllowlistHint({
+          runtime,
+          reason: "groupPolicy=allowlist (not allowlisted)",
+          entry: groupAllowEntry,
+          chatName: groupName,
+          accountId: account.accountId,
+        });
+        return;
+      }
+    }
+  } else {
+    if (dmPolicy === "disabled") {
+      logVerbose(core, runtime, `Blocked BlueBubbles DM from ${message.senderId}`);
+      logVerbose(core, runtime, `drop: dmPolicy disabled sender=${message.senderId}`);
+      return;
+    }
+    if (dmPolicy !== "open") {
+      const allowed = isAllowedBlueBubblesSender({
+        allowFrom: effectiveAllowFrom,
+        sender: message.senderId,
+        chatId: message.chatId ?? undefined,
+        chatGuid: message.chatGuid ?? undefined,
+        chatIdentifier: message.chatIdentifier ?? undefined,
+      });
+      if (!allowed) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: "bluebubbles",
+            id: message.senderId,
+            meta: { name: message.senderName },
+          });
+          runtime.log?.(
+            `[bluebubbles] pairing request sender=${message.senderId} created=${created}`,
+          );
+          if (created) {
+            logVerbose(core, runtime, `bluebubbles pairing request sender=${message.senderId}`);
+            try {
+              await sendMessageBlueBubbles(
+                message.senderId,
+                core.channel.pairing.buildPairingReply({
+                  channel: "bluebubbles",
+                  idLine: `Your BlueBubbles sender id: ${message.senderId}`,
+                  code,
+                }),
+                { cfg: config, accountId: account.accountId },
+              );
+              statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              logVerbose(
+                core,
+                runtime,
+                `bluebubbles pairing reply failed for ${message.senderId}: ${String(err)}`,
+              );
+              runtime.error?.(
+                `[bluebubbles] pairing reply failed sender=${message.senderId}: ${String(err)}`,
+              );
+            }
+          }
+        } else {
+          logVerbose(
+            core,
+            runtime,
+            `Blocked unauthorized BlueBubbles sender ${message.senderId} (dmPolicy=${dmPolicy})`,
+          );
+          logVerbose(
+            core,
+            runtime,
+            `drop: dm sender not allowed sender=${message.senderId} allowFrom=${effectiveAllowFrom.join(",")}`,
+          );
+        }
+        return;
+      }
+    }
+  }
+
+  const chatId = message.chatId ?? undefined;
+  const chatGuid = message.chatGuid ?? undefined;
+  const chatIdentifier = message.chatIdentifier ?? undefined;
+  const peerId = isGroup
+    ? (chatGuid ?? chatIdentifier ?? (chatId ? String(chatId) : "group"))
+    : message.senderId;
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "bluebubbles",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: peerId,
+    },
+  });
+
+  // Mention gating for group chats (parity with iMessage/WhatsApp)
+  const messageText = text;
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(config, route.agentId);
+  const wasMentioned = isGroup
+    ? core.channel.mentions.matchesMentionPatterns(messageText, mentionRegexes)
+    : true;
+  const canDetectMention = mentionRegexes.length > 0;
+  const requireMention = core.channel.groups.resolveRequireMention({
+    cfg: config,
+    channel: "bluebubbles",
+    groupId: peerId,
+    accountId: account.accountId,
+  });
+
+  // Command gating (parity with iMessage/WhatsApp)
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const hasControlCmd = core.channel.text.hasControlCommand(messageText, config);
+  const ownerAllowedForCommands =
+    effectiveAllowFrom.length > 0
+      ? isAllowedBlueBubblesSender({
+          allowFrom: effectiveAllowFrom,
+          sender: message.senderId,
+          chatId: message.chatId ?? undefined,
+          chatGuid: message.chatGuid ?? undefined,
+          chatIdentifier: message.chatIdentifier ?? undefined,
+        })
+      : false;
+  const groupAllowedForCommands =
+    effectiveGroupAllowFrom.length > 0
+      ? isAllowedBlueBubblesSender({
+          allowFrom: effectiveGroupAllowFrom,
+          sender: message.senderId,
+          chatId: message.chatId ?? undefined,
+          chatGuid: message.chatGuid ?? undefined,
+          chatIdentifier: message.chatIdentifier ?? undefined,
+        })
+      : false;
+  const dmAuthorized = dmPolicy === "open" || ownerAllowedForCommands;
+  const commandGate = resolveControlCommandGate({
+    useAccessGroups,
+    authorizers: [
+      { configured: effectiveAllowFrom.length > 0, allowed: ownerAllowedForCommands },
+      { configured: effectiveGroupAllowFrom.length > 0, allowed: groupAllowedForCommands },
+    ],
+    allowTextCommands: true,
+    hasControlCommand: hasControlCmd,
+  });
+  const commandAuthorized = isGroup ? commandGate.commandAuthorized : dmAuthorized;
+
+  // Block control commands from unauthorized senders in groups
+  if (isGroup && commandGate.shouldBlock) {
+    logInboundDrop({
+      log: (msg) => logVerbose(core, runtime, msg),
+      channel: "bluebubbles",
+      reason: "control command (unauthorized)",
+      target: message.senderId,
+    });
+    return;
+  }
+
+  // Allow control commands to bypass mention gating when authorized (parity with iMessage)
+  const shouldBypassMention =
+    isGroup && requireMention && !wasMentioned && commandAuthorized && hasControlCmd;
+  const effectiveWasMentioned = wasMentioned || shouldBypassMention;
+
+  // Skip group messages that require mention but weren't mentioned
+  if (isGroup && requireMention && canDetectMention && !wasMentioned && !shouldBypassMention) {
+    logVerbose(core, runtime, `bluebubbles: skipping group message (no mention)`);
+    return;
+  }
+
+  // Cache allowed inbound messages so later replies can resolve sender/body without
+  // surfacing dropped content (allowlist/mention/command gating).
+  cacheInboundMessage();
+
+  const baseUrl = account.config.serverUrl?.trim();
+  const password = account.config.password?.trim();
+  const maxBytes =
+    account.config.mediaMaxMb && account.config.mediaMaxMb > 0
+      ? account.config.mediaMaxMb * 1024 * 1024
+      : 8 * 1024 * 1024;
+
+  let mediaUrls: string[] = [];
+  let mediaPaths: string[] = [];
+  let mediaTypes: string[] = [];
+  if (attachments.length > 0) {
+    if (!baseUrl || !password) {
+      logVerbose(core, runtime, "attachment download skipped (missing serverUrl/password)");
+    } else {
+      for (const attachment of attachments) {
+        if (!attachment.guid) {
+          continue;
+        }
+        if (attachment.totalBytes && attachment.totalBytes > maxBytes) {
+          logVerbose(
+            core,
+            runtime,
+            `attachment too large guid=${attachment.guid} bytes=${attachment.totalBytes}`,
+          );
+          continue;
+        }
+        try {
+          const downloaded = await downloadBlueBubblesAttachment(attachment, {
+            cfg: config,
+            accountId: account.accountId,
+            maxBytes,
+          });
+          const saved = await core.channel.media.saveMediaBuffer(
+            downloaded.buffer,
+            downloaded.contentType,
+            "inbound",
+            maxBytes,
+          );
+          mediaPaths.push(saved.path);
+          mediaUrls.push(saved.path);
+          if (saved.contentType) {
+            mediaTypes.push(saved.contentType);
+          }
+        } catch (err) {
+          logVerbose(
+            core,
+            runtime,
+            `attachment download failed guid=${attachment.guid} err=${String(err)}`,
+          );
+        }
+      }
+    }
+  }
+  let replyToId = message.replyToId;
+  let replyToBody = message.replyToBody;
+  let replyToSender = message.replyToSender;
+  let replyToShortId: string | undefined;
+
+  if (isTapbackMessage && tapbackContext?.replyToId) {
+    replyToId = tapbackContext.replyToId;
+  }
+
+  if (replyToId) {
+    const cached = resolveReplyContextFromCache({
+      accountId: account.accountId,
+      replyToId,
+      chatGuid: message.chatGuid,
+      chatIdentifier: message.chatIdentifier,
+      chatId: message.chatId,
+    });
+    if (cached) {
+      if (!replyToBody && cached.body) {
+        replyToBody = cached.body;
+      }
+      if (!replyToSender && cached.senderLabel) {
+        replyToSender = cached.senderLabel;
+      }
+      replyToShortId = cached.shortId;
+      if (core.logging.shouldLogVerbose()) {
+        const preview = (cached.body ?? "").replace(/\s+/g, " ").slice(0, 120);
+        logVerbose(
+          core,
+          runtime,
+          `reply-context cache hit replyToId=${replyToId} sender=${replyToSender ?? ""} body="${preview}"`,
+        );
+      }
+    }
+  }
+
+  // If no cached short ID, try to get one from the UUID directly
+  if (replyToId && !replyToShortId) {
+    replyToShortId = getShortIdForUuid(replyToId);
+  }
+
+  // Use inline [[reply_to:N]] tag format
+  // For tapbacks/reactions: append at end (e.g., "reacted with ❤️ [[reply_to:4]]")
+  // For regular replies: prepend at start (e.g., "[[reply_to:4]] Awesome")
+  const replyTag = formatReplyTag({ replyToId, replyToShortId });
+  const baseBody = replyTag
+    ? isTapbackMessage
+      ? `${rawBody} ${replyTag}`
+      : `${replyTag} ${rawBody}`
+    : rawBody;
+  const fromLabel = isGroup ? undefined : message.senderName || `user:${message.senderId}`;
+  const groupSubject = isGroup ? message.chatName?.trim() || undefined : undefined;
+  const groupMembers = isGroup
+    ? formatGroupMembers({
+        participants: message.participants,
+        fallback: message.senderId ? { id: message.senderId, name: message.senderName } : undefined,
+      })
+    : undefined;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "BlueBubbles",
+    from: fromLabel,
+    timestamp: message.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: baseBody,
+  });
+  let chatGuidForActions = chatGuid;
+  if (!chatGuidForActions && baseUrl && password) {
+    const target =
+      isGroup && (chatId || chatIdentifier)
+        ? chatId
+          ? ({ kind: "chat_id", chatId } as const)
+          : ({ kind: "chat_identifier", chatIdentifier: chatIdentifier ?? "" } as const)
+        : ({ kind: "handle", address: message.senderId } as const);
+    if (target.kind !== "chat_identifier" || target.chatIdentifier) {
+      chatGuidForActions =
+        (await resolveChatGuidForTarget({
+          baseUrl,
+          password,
+          target,
+        })) ?? undefined;
+    }
+  }
+
+  const ackReactionScope = config.messages?.ackReactionScope ?? "group-mentions";
+  const removeAckAfterReply = config.messages?.removeAckAfterReply ?? false;
+  const ackReactionValue = resolveBlueBubblesAckReaction({
+    cfg: config,
+    agentId: route.agentId,
+    core,
+    runtime,
+  });
+  const shouldAckReaction = () =>
+    Boolean(
+      ackReactionValue &&
+      core.channel.reactions.shouldAckReaction({
+        scope: ackReactionScope,
+        isDirect: !isGroup,
+        isGroup,
+        isMentionableGroup: isGroup,
+        requireMention: Boolean(requireMention),
+        canDetectMention,
+        effectiveWasMentioned,
+        shouldBypassMention,
+      }),
+    );
+  const ackMessageId = message.messageId?.trim() || "";
+  const ackReactionPromise =
+    shouldAckReaction() && ackMessageId && chatGuidForActions && ackReactionValue
+      ? sendBlueBubblesReaction({
+          chatGuid: chatGuidForActions,
+          messageGuid: ackMessageId,
+          emoji: ackReactionValue,
+          opts: { cfg: config, accountId: account.accountId },
+        }).then(
+          () => true,
+          (err) => {
+            logVerbose(
+              core,
+              runtime,
+              `ack reaction failed chatGuid=${chatGuidForActions} msg=${ackMessageId}: ${String(err)}`,
+            );
+            return false;
+          },
+        )
+      : null;
+
+  // Respect sendReadReceipts config (parity with WhatsApp)
+  const sendReadReceipts = account.config.sendReadReceipts !== false;
+  if (chatGuidForActions && baseUrl && password && sendReadReceipts) {
+    try {
+      await markBlueBubblesChatRead(chatGuidForActions, {
+        cfg: config,
+        accountId: account.accountId,
+      });
+      logVerbose(core, runtime, `marked read chatGuid=${chatGuidForActions}`);
+    } catch (err) {
+      runtime.error?.(`[bluebubbles] mark read failed: ${String(err)}`);
+    }
+  } else if (!sendReadReceipts) {
+    logVerbose(core, runtime, "mark read skipped (sendReadReceipts=false)");
+  } else {
+    logVerbose(core, runtime, "mark read skipped (missing chatGuid or credentials)");
+  }
+
+  const outboundTarget = isGroup
+    ? formatBlueBubblesChatTarget({
+        chatId,
+        chatGuid: chatGuidForActions ?? chatGuid,
+        chatIdentifier,
+      }) || peerId
+    : chatGuidForActions
+      ? formatBlueBubblesChatTarget({ chatGuid: chatGuidForActions })
+      : message.senderId;
+
+  const maybeEnqueueOutboundMessageId = (messageId?: string, snippet?: string) => {
+    const trimmed = messageId?.trim();
+    if (!trimmed || trimmed === "ok" || trimmed === "unknown") {
+      return;
+    }
+    // Cache outbound message to get short ID
+    const cacheEntry = rememberBlueBubblesReplyCache({
+      accountId: account.accountId,
+      messageId: trimmed,
+      chatGuid: chatGuidForActions ?? chatGuid,
+      chatIdentifier,
+      chatId,
+      senderLabel: "me",
+      body: snippet ?? "",
+      timestamp: Date.now(),
+    });
+    const displayId = cacheEntry.shortId || trimmed;
+    const preview = snippet ? ` "${snippet.slice(0, 12)}${snippet.length > 12 ? "…" : ""}"` : "";
+    core.system.enqueueSystemEvent(`Assistant sent${preview} [message_id:${displayId}]`, {
+      sessionKey: route.sessionKey,
+      contextKey: `bluebubbles:outbound:${outboundTarget}:${trimmed}`,
+    });
+  };
+
+  const ctxPayload = {
+    Body: body,
+    BodyForAgent: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    BodyForCommands: rawBody,
+    MediaUrl: mediaUrls[0],
+    MediaUrls: mediaUrls.length > 0 ? mediaUrls : undefined,
+    MediaPath: mediaPaths[0],
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaType: mediaTypes[0],
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+    From: isGroup ? `group:${peerId}` : `bluebubbles:${message.senderId}`,
+    To: `bluebubbles:${outboundTarget}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    // Use short ID for token savings (agent can use this to reference the message)
+    ReplyToId: replyToShortId || replyToId,
+    ReplyToIdFull: replyToId,
+    ReplyToBody: replyToBody,
+    ReplyToSender: replyToSender,
+    GroupSubject: groupSubject,
+    GroupMembers: groupMembers,
+    SenderName: message.senderName || undefined,
+    SenderId: message.senderId,
+    Provider: "bluebubbles",
+    Surface: "bluebubbles",
+    // Use short ID for token savings (agent can use this to reference the message)
+    MessageSid: messageShortId || message.messageId,
+    MessageSidFull: message.messageId,
+    Timestamp: message.timestamp,
+    OriginatingChannel: "bluebubbles",
+    OriginatingTo: `bluebubbles:${outboundTarget}`,
+    WasMentioned: effectiveWasMentioned,
+    CommandAuthorized: commandAuthorized,
+  };
+
+  let sentMessage = false;
+  try {
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg: config,
+      dispatcherOptions: {
+        deliver: async (payload) => {
+          const rawReplyToId =
+            typeof payload.replyToId === "string" ? payload.replyToId.trim() : "";
+          // Resolve short ID (e.g., "5") to full UUID
+          const replyToMessageGuid = rawReplyToId
+            ? resolveBlueBubblesMessageId(rawReplyToId, { requireKnownShortId: true })
+            : "";
+          const mediaList = payload.mediaUrls?.length
+            ? payload.mediaUrls
+            : payload.mediaUrl
+              ? [payload.mediaUrl]
+              : [];
+          if (mediaList.length > 0) {
+            const tableMode = core.channel.text.resolveMarkdownTableMode({
+              cfg: config,
+              channel: "bluebubbles",
+              accountId: account.accountId,
+            });
+            const text = core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
+            let first = true;
+            for (const mediaUrl of mediaList) {
+              const caption = first ? text : undefined;
+              first = false;
+              const result = await sendBlueBubblesMedia({
+                cfg: config,
+                to: outboundTarget,
+                mediaUrl,
+                caption: caption ?? undefined,
+                replyToId: replyToMessageGuid || null,
+                accountId: account.accountId,
+              });
+              const cachedBody = (caption ?? "").trim() || "<media:attachment>";
+              maybeEnqueueOutboundMessageId(result.messageId, cachedBody);
+              sentMessage = true;
+              statusSink?.({ lastOutboundAt: Date.now() });
+            }
+            return;
+          }
+
+          const textLimit =
+            account.config.textChunkLimit && account.config.textChunkLimit > 0
+              ? account.config.textChunkLimit
+              : DEFAULT_TEXT_LIMIT;
+          const chunkMode = account.config.chunkMode ?? "length";
+          const tableMode = core.channel.text.resolveMarkdownTableMode({
+            cfg: config,
+            channel: "bluebubbles",
+            accountId: account.accountId,
+          });
+          const text = core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
+          const chunks =
+            chunkMode === "newline"
+              ? core.channel.text.chunkTextWithMode(text, textLimit, chunkMode)
+              : core.channel.text.chunkMarkdownText(text, textLimit);
+          if (!chunks.length && text) {
+            chunks.push(text);
+          }
+          if (!chunks.length) {
+            return;
+          }
+          for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            const result = await sendMessageBlueBubbles(outboundTarget, chunk, {
+              cfg: config,
+              accountId: account.accountId,
+              replyToMessageGuid: replyToMessageGuid || undefined,
+            });
+            maybeEnqueueOutboundMessageId(result.messageId, chunk);
+            sentMessage = true;
+            statusSink?.({ lastOutboundAt: Date.now() });
+            // In newline mode, restart typing after each chunk if more chunks remain
+            // Small delay allows the Apple API to finish clearing the typing state from message send
+            if (chunkMode === "newline" && i < chunks.length - 1 && chatGuidForActions) {
+              await new Promise((r) => setTimeout(r, 150));
+              sendBlueBubblesTyping(chatGuidForActions, true, {
+                cfg: config,
+                accountId: account.accountId,
+              }).catch(() => {
+                // Ignore typing errors
+              });
+            }
+          }
+        },
+        onReplyStart: async () => {
+          if (!chatGuidForActions) {
+            return;
+          }
+          if (!baseUrl || !password) {
+            return;
+          }
+          logVerbose(core, runtime, `typing start chatGuid=${chatGuidForActions}`);
+          try {
+            await sendBlueBubblesTyping(chatGuidForActions, true, {
+              cfg: config,
+              accountId: account.accountId,
+            });
+          } catch (err) {
+            runtime.error?.(`[bluebubbles] typing start failed: ${String(err)}`);
+          }
+        },
+        onIdle: async () => {
+          if (!chatGuidForActions) {
+            return;
+          }
+          if (!baseUrl || !password) {
+            return;
+          }
+          try {
+            await sendBlueBubblesTyping(chatGuidForActions, false, {
+              cfg: config,
+              accountId: account.accountId,
+            });
+          } catch (err) {
+            logVerbose(core, runtime, `typing stop failed: ${String(err)}`);
+          }
+        },
+        onError: (err, info) => {
+          runtime.error?.(`BlueBubbles ${info.kind} reply failed: ${String(err)}`);
+        },
+      },
+      replyOptions: {
+        disableBlockStreaming:
+          typeof account.config.blockStreaming === "boolean"
+            ? !account.config.blockStreaming
+            : undefined,
+      },
+    });
+  } finally {
+    if (sentMessage && chatGuidForActions && ackMessageId) {
+      core.channel.reactions.removeAckReactionAfterReply({
+        removeAfterReply: removeAckAfterReply,
+        ackReactionPromise,
+        ackReactionValue: ackReactionValue ?? null,
+        remove: () =>
+          sendBlueBubblesReaction({
+            chatGuid: chatGuidForActions,
+            messageGuid: ackMessageId,
+            emoji: ackReactionValue ?? "",
+            remove: true,
+            opts: { cfg: config, accountId: account.accountId },
+          }),
+        onError: (err) => {
+          logAckFailure({
+            log: (msg) => logVerbose(core, runtime, msg),
+            channel: "bluebubbles",
+            target: `${chatGuidForActions}/${ackMessageId}`,
+            error: err,
+          });
+        },
+      });
+    }
+    if (chatGuidForActions && baseUrl && password && !sentMessage) {
+      // Stop typing indicator when no message was sent (e.g., NO_REPLY)
+      sendBlueBubblesTyping(chatGuidForActions, false, {
+        cfg: config,
+        accountId: account.accountId,
+      }).catch((err) => {
+        logTypingFailure({
+          log: (msg) => logVerbose(core, runtime, msg),
+          channel: "bluebubbles",
+          action: "stop",
+          target: chatGuidForActions,
+          error: err,
+        });
+      });
+    }
+  }
+}
+
+async function processReaction(
+  reaction: NormalizedWebhookReaction,
+  target: WebhookTarget,
+): Promise<void> {
+  const { account, config, runtime, core } = target;
+  if (reaction.fromMe) {
+    return;
+  }
+
+  const dmPolicy = account.config.dmPolicy ?? "pairing";
+  const groupPolicy = account.config.groupPolicy ?? "allowlist";
+  const configAllowFrom = (account.config.allowFrom ?? []).map((entry) => String(entry));
+  const configGroupAllowFrom = (account.config.groupAllowFrom ?? []).map((entry) => String(entry));
+  const storeAllowFrom = await core.channel.pairing
+    .readAllowFromStore("bluebubbles")
+    .catch(() => []);
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom]
+    .map((entry) => String(entry).trim())
+    .filter(Boolean);
+  const effectiveGroupAllowFrom = [
+    ...(configGroupAllowFrom.length > 0 ? configGroupAllowFrom : configAllowFrom),
+    ...storeAllowFrom,
+  ]
+    .map((entry) => String(entry).trim())
+    .filter(Boolean);
+
+  if (reaction.isGroup) {
+    if (groupPolicy === "disabled") {
+      return;
+    }
+    if (groupPolicy === "allowlist") {
+      if (effectiveGroupAllowFrom.length === 0) {
+        return;
+      }
+      const allowed = isAllowedBlueBubblesSender({
+        allowFrom: effectiveGroupAllowFrom,
+        sender: reaction.senderId,
+        chatId: reaction.chatId ?? undefined,
+        chatGuid: reaction.chatGuid ?? undefined,
+        chatIdentifier: reaction.chatIdentifier ?? undefined,
+      });
+      if (!allowed) {
+        return;
+      }
+    }
+  } else {
+    if (dmPolicy === "disabled") {
+      return;
+    }
+    if (dmPolicy !== "open") {
+      const allowed = isAllowedBlueBubblesSender({
+        allowFrom: effectiveAllowFrom,
+        sender: reaction.senderId,
+        chatId: reaction.chatId ?? undefined,
+        chatGuid: reaction.chatGuid ?? undefined,
+        chatIdentifier: reaction.chatIdentifier ?? undefined,
+      });
+      if (!allowed) {
+        return;
+      }
+    }
+  }
+
+  const chatId = reaction.chatId ?? undefined;
+  const chatGuid = reaction.chatGuid ?? undefined;
+  const chatIdentifier = reaction.chatIdentifier ?? undefined;
+  const peerId = reaction.isGroup
+    ? (chatGuid ?? chatIdentifier ?? (chatId ? String(chatId) : "group"))
+    : reaction.senderId;
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "bluebubbles",
+    accountId: account.accountId,
+    peer: {
+      kind: reaction.isGroup ? "group" : "dm",
+      id: peerId,
+    },
+  });
+
+  const senderLabel = reaction.senderName || reaction.senderId;
+  const chatLabel = reaction.isGroup ? ` in group:${peerId}` : "";
+  // Use short ID for token savings
+  const messageDisplayId = getShortIdForUuid(reaction.messageId) || reaction.messageId;
+  // Format: "Tyler reacted with ❤️ [[reply_to:5]]" or "Tyler removed ❤️ reaction [[reply_to:5]]"
+  const text =
+    reaction.action === "removed"
+      ? `${senderLabel} removed ${reaction.emoji} reaction [[reply_to:${messageDisplayId}]]${chatLabel}`
+      : `${senderLabel} reacted with ${reaction.emoji} [[reply_to:${messageDisplayId}]]${chatLabel}`;
+  core.system.enqueueSystemEvent(text, {
+    sessionKey: route.sessionKey,
+    contextKey: `bluebubbles:reaction:${reaction.action}:${peerId}:${reaction.messageId}:${reaction.senderId}:${reaction.emoji}`,
+  });
+  logVerbose(core, runtime, `reaction event enqueued: ${text}`);
+}
+
+export async function monitorBlueBubblesProvider(
+  options: BlueBubblesMonitorOptions,
+): Promise<void> {
+  const { account, config, runtime, abortSignal, statusSink } = options;
+  const core = getBlueBubblesRuntime();
+  const path = options.webhookPath?.trim() || DEFAULT_WEBHOOK_PATH;
+
+  // Fetch and cache server info (for macOS version detection in action gating)
+  const serverInfo = await fetchBlueBubblesServerInfo({
+    baseUrl: account.baseUrl,
+    password: account.config.password,
+    accountId: account.accountId,
+    timeoutMs: 5000,
+  }).catch(() => null);
+  if (serverInfo?.os_version) {
+    runtime.log?.(`[${account.accountId}] BlueBubbles server macOS ${serverInfo.os_version}`);
+  }
+
+  const unregister = registerBlueBubblesWebhookTarget({
+    account,
+    config,
+    runtime,
+    core,
+    path,
+    statusSink,
+  });
+
+  return await new Promise((resolve) => {
+    const stop = () => {
+      unregister();
+      resolve();
+    };
+
+    if (abortSignal?.aborted) {
+      stop();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", stop, { once: true });
+    runtime.log?.(
+      `[${account.accountId}] BlueBubbles webhook listening on ${normalizeWebhookPath(path)}`,
+    );
+  });
+}
+
+export function resolveWebhookPathFromConfig(config?: BlueBubblesAccountConfig): string {
+  const raw = config?.webhookPath?.trim();
+  if (raw) {
+    return normalizeWebhookPath(raw);
+  }
+  return DEFAULT_WEBHOOK_PATH;
+}

extensions/bluebubbles/src/onboarding.ts

@@ -0,0 +1,352 @@
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  OpenClawConfig,
+  DmPolicy,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  addWildcardAllowFrom,
+  formatDocsLink,
+  normalizeAccountId,
+  promptAccountId,
+} from "openclaw/plugin-sdk";
+import {
+  listBlueBubblesAccountIds,
+  resolveBlueBubblesAccount,
+  resolveDefaultBlueBubblesAccountId,
+} from "./accounts.js";
+import { parseBlueBubblesAllowTarget } from "./targets.js";
+import { normalizeBlueBubblesServerUrl } from "./types.js";
+
+const channel = "bluebubbles" as const;
+
+function setBlueBubblesDmPolicy(cfg: OpenClawConfig, dmPolicy: DmPolicy): OpenClawConfig {
+  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: OpenClawConfig,
+  accountId: string,
+  allowFrom: string[],
+): OpenClawConfig {
+  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: OpenClawConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<OpenClawConfig> {
+  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 OpenClaw 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 },
+    },
+  }),
+};

extensions/bluebubbles/src/probe.ts

@@ -0,0 +1,135 @@
+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),
+    };
+  }
+}

extensions/bluebubbles/src/reactions.test.ts

@@ -0,0 +1,392 @@
+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");
+      });
+    });
+  });
+});

extensions/bluebubbles/src/reactions.ts

@@ -0,0 +1,188 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesReactionOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: OpenClawConfig;
+};
+
+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"}`);
+  }
+}

extensions/bluebubbles/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/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;
+}

extensions/bluebubbles/src/send.test.ts

@@ -0,0 +1,808 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import type { BlueBubblesSendTarget } from "./types.js";
+import { sendMessageBlueBubbles, resolveChatGuidForTarget } from "./send.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);
+    });
+  });
+});

extensions/bluebubbles/src/send.ts

@@ -0,0 +1,467 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import crypto from "node:crypto";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import {
+  extractHandleFromChatGuid,
+  normalizeBlueBubblesHandle,
+  parseBlueBubblesTarget,
+} from "./targets.js";
+import {
+  blueBubblesFetchWithTimeout,
+  buildBlueBubblesApiUrl,
+  type BlueBubblesSendTarget,
+} from "./types.js";
+
+export type BlueBubblesSendOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: OpenClawConfig;
+  /** 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" };
+  }
+}

extensions/bluebubbles/src/targets.test.ts

@@ -0,0 +1,183 @@
+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",
+    });
+  });
+});

extensions/bluebubbles/src/targets.ts

@@ -0,0 +1,422 @@
+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 "";
+}

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);
+  }
+}

extensions/copilot-proxy/README.md

@@ -0,0 +1,24 @@
+# Copilot Proxy (OpenClaw plugin)
+
+Provider plugin for the **Copilot Proxy** VS Code extension.
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```bash
+openclaw plugins enable copilot-proxy
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+openclaw models auth login --provider copilot-proxy --set-default
+```
+
+## Notes
+
+- Copilot Proxy must be running in VS Code.
+- Base URL must include `/v1`.

extensions/copilot-proxy/index.ts

@@ -0,0 +1,148 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+const DEFAULT_BASE_URL = "http://localhost:3000/v1";
+const DEFAULT_API_KEY = "n/a";
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 8192;
+const DEFAULT_MODEL_IDS = [
+  "gpt-5.2",
+  "gpt-5.2-codex",
+  "gpt-5.1",
+  "gpt-5.1-codex",
+  "gpt-5.1-codex-max",
+  "gpt-5-mini",
+  "claude-opus-4.5",
+  "claude-sonnet-4.5",
+  "claude-haiku-4.5",
+  "gemini-3-pro",
+  "gemini-3-flash",
+  "grok-code-fast-1",
+] as const;
+
+function normalizeBaseUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return DEFAULT_BASE_URL;
+  }
+  let normalized = trimmed;
+  while (normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (!normalized.endsWith("/v1")) {
+    normalized = `${normalized}/v1`;
+  }
+  return normalized;
+}
+
+function validateBaseUrl(value: string): string | undefined {
+  const normalized = normalizeBaseUrl(value);
+  try {
+    new URL(normalized);
+  } catch {
+    return "Enter a valid URL";
+  }
+  return undefined;
+}
+
+function parseModelIds(input: string): string[] {
+  const parsed = input
+    .split(/[\n,]/)
+    .map((model) => model.trim())
+    .filter(Boolean);
+  return Array.from(new Set(parsed));
+}
+
+function buildModelDefinition(modelId: string) {
+  return {
+    id: modelId,
+    name: modelId,
+    api: "openai-completions",
+    reasoning: false,
+    input: ["text", "image"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: DEFAULT_CONTEXT_WINDOW,
+    maxTokens: DEFAULT_MAX_TOKENS,
+  };
+}
+
+const copilotProxyPlugin = {
+  id: "copilot-proxy",
+  name: "Copilot Proxy",
+  description: "Local Copilot Proxy (VS Code LM) provider plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api) {
+    api.registerProvider({
+      id: "copilot-proxy",
+      label: "Copilot Proxy",
+      docsPath: "/providers/models",
+      auth: [
+        {
+          id: "local",
+          label: "Local proxy",
+          hint: "Configure base URL + models for the Copilot Proxy server",
+          kind: "custom",
+          run: async (ctx) => {
+            const baseUrlInput = await ctx.prompter.text({
+              message: "Copilot Proxy base URL",
+              initialValue: DEFAULT_BASE_URL,
+              validate: validateBaseUrl,
+            });
+
+            const modelInput = await ctx.prompter.text({
+              message: "Model IDs (comma-separated)",
+              initialValue: DEFAULT_MODEL_IDS.join(", "),
+              validate: (value) =>
+                parseModelIds(value).length > 0 ? undefined : "Enter at least one model id",
+            });
+
+            const baseUrl = normalizeBaseUrl(baseUrlInput);
+            const modelIds = parseModelIds(modelInput);
+            const defaultModelId = modelIds[0] ?? DEFAULT_MODEL_IDS[0];
+            const defaultModelRef = `copilot-proxy/${defaultModelId}`;
+
+            return {
+              profiles: [
+                {
+                  profileId: "copilot-proxy:local",
+                  credential: {
+                    type: "token",
+                    provider: "copilot-proxy",
+                    token: DEFAULT_API_KEY,
+                  },
+                },
+              ],
+              configPatch: {
+                models: {
+                  providers: {
+                    "copilot-proxy": {
+                      baseUrl,
+                      apiKey: DEFAULT_API_KEY,
+                      api: "openai-completions",
+                      authHeader: false,
+                      models: modelIds.map((modelId) => buildModelDefinition(modelId)),
+                    },
+                  },
+                },
+                agents: {
+                  defaults: {
+                    models: Object.fromEntries(
+                      modelIds.map((modelId) => [`copilot-proxy/${modelId}`, {}]),
+                    ),
+                  },
+                },
+              },
+              defaultModel: defaultModelRef,
+              notes: [
+                "Start the Copilot Proxy VS Code extension before using these models.",
+                "Copilot Proxy serves /v1/chat/completions; base URL must include /v1.",
+                "Model availability depends on your Copilot plan; edit models.providers.copilot-proxy if needed.",
+              ],
+            };
+          },
+        },
+      ],
+    });
+  },
+};
+
+export default copilotProxyPlugin;

extensions/copilot-proxy/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "copilot-proxy",
+  "providers": ["copilot-proxy"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/copilot-proxy/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@openclaw/copilot-proxy",
+  "version": "2026.1.30",
+  "description": "OpenClaw Copilot Proxy provider plugin",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/diagnostics-otel/index.ts

@@ -0,0 +1,15 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { createDiagnosticsOtelService } from "./src/service.js";
+
+const plugin = {
+  id: "diagnostics-otel",
+  name: "Diagnostics OpenTelemetry",
+  description: "Export diagnostics events to OpenTelemetry",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    api.registerService(createDiagnosticsOtelService());
+  },
+};
+
+export default plugin;

extensions/diagnostics-otel/openclaw.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "diagnostics-otel",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/diagnostics-otel/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@openclaw/diagnostics-otel",
+  "version": "2026.1.30",
+  "description": "OpenClaw diagnostics OpenTelemetry exporter",
+  "type": "module",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.211.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.211.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.211.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
+    "@opentelemetry/resources": "^2.5.0",
+    "@opentelemetry/sdk-logs": "^0.211.0",
+    "@opentelemetry/sdk-metrics": "^2.5.0",
+    "@opentelemetry/sdk-node": "^0.211.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.0",
+    "@opentelemetry/semantic-conventions": "^1.39.0"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/diagnostics-otel/src/service.test.ts

@@ -0,0 +1,226 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const registerLogTransportMock = vi.hoisted(() => vi.fn());
+
+const telemetryState = vi.hoisted(() => {
+  const counters = new Map<string, { add: ReturnType<typeof vi.fn> }>();
+  const histograms = new Map<string, { record: ReturnType<typeof vi.fn> }>();
+  const tracer = {
+    startSpan: vi.fn((_name: string, _opts?: unknown) => ({
+      end: vi.fn(),
+      setStatus: vi.fn(),
+    })),
+  };
+  const meter = {
+    createCounter: vi.fn((name: string) => {
+      const counter = { add: vi.fn() };
+      counters.set(name, counter);
+      return counter;
+    }),
+    createHistogram: vi.fn((name: string) => {
+      const histogram = { record: vi.fn() };
+      histograms.set(name, histogram);
+      return histogram;
+    }),
+  };
+  return { counters, histograms, tracer, meter };
+});
+
+const sdkStart = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const sdkShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const logEmit = vi.hoisted(() => vi.fn());
+const logShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+
+vi.mock("@opentelemetry/api", () => ({
+  metrics: {
+    getMeter: () => telemetryState.meter,
+  },
+  trace: {
+    getTracer: () => telemetryState.tracer,
+  },
+  SpanStatusCode: {
+    ERROR: 2,
+  },
+}));
+
+vi.mock("@opentelemetry/sdk-node", () => ({
+  NodeSDK: class {
+    start = sdkStart;
+    shutdown = sdkShutdown;
+  },
+}));
+
+vi.mock("@opentelemetry/exporter-metrics-otlp-http", () => ({
+  OTLPMetricExporter: class {},
+}));
+
+vi.mock("@opentelemetry/exporter-trace-otlp-http", () => ({
+  OTLPTraceExporter: class {},
+}));
+
+vi.mock("@opentelemetry/exporter-logs-otlp-http", () => ({
+  OTLPLogExporter: class {},
+}));
+
+vi.mock("@opentelemetry/sdk-logs", () => ({
+  BatchLogRecordProcessor: class {},
+  LoggerProvider: class {
+    addLogRecordProcessor = vi.fn();
+    getLogger = vi.fn(() => ({
+      emit: logEmit,
+    }));
+    shutdown = logShutdown;
+  },
+}));
+
+vi.mock("@opentelemetry/sdk-metrics", () => ({
+  PeriodicExportingMetricReader: class {},
+}));
+
+vi.mock("@opentelemetry/sdk-trace-base", () => ({
+  ParentBasedSampler: class {},
+  TraceIdRatioBasedSampler: class {},
+}));
+
+vi.mock("@opentelemetry/resources", () => ({
+  Resource: class {
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(_value?: unknown) {}
+  },
+}));
+
+vi.mock("@opentelemetry/semantic-conventions", () => ({
+  SemanticResourceAttributes: {
+    SERVICE_NAME: "service.name",
+  },
+}));
+
+vi.mock("openclaw/plugin-sdk", async () => {
+  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk")>("openclaw/plugin-sdk");
+  return {
+    ...actual,
+    registerLogTransport: registerLogTransportMock,
+  };
+});
+
+import { emitDiagnosticEvent } from "openclaw/plugin-sdk";
+import { createDiagnosticsOtelService } from "./service.js";
+
+describe("diagnostics-otel service", () => {
+  beforeEach(() => {
+    telemetryState.counters.clear();
+    telemetryState.histograms.clear();
+    telemetryState.tracer.startSpan.mockClear();
+    telemetryState.meter.createCounter.mockClear();
+    telemetryState.meter.createHistogram.mockClear();
+    sdkStart.mockClear();
+    sdkShutdown.mockClear();
+    logEmit.mockClear();
+    logShutdown.mockClear();
+    registerLogTransportMock.mockReset();
+  });
+
+  test("records message-flow metrics and spans", async () => {
+    const registeredTransports: Array<(logObj: Record<string, unknown>) => void> = [];
+    const stopTransport = vi.fn();
+    registerLogTransportMock.mockImplementation((transport) => {
+      registeredTransports.push(transport);
+      return stopTransport;
+    });
+
+    const service = createDiagnosticsOtelService();
+    await service.start({
+      config: {
+        diagnostics: {
+          enabled: true,
+          otel: {
+            enabled: true,
+            endpoint: "http://otel-collector:4318",
+            protocol: "http/protobuf",
+            traces: true,
+            metrics: true,
+            logs: true,
+          },
+        },
+      },
+      logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+      },
+    });
+
+    emitDiagnosticEvent({
+      type: "webhook.received",
+      channel: "telegram",
+      updateType: "telegram-post",
+    });
+    emitDiagnosticEvent({
+      type: "webhook.processed",
+      channel: "telegram",
+      updateType: "telegram-post",
+      durationMs: 120,
+    });
+    emitDiagnosticEvent({
+      type: "message.queued",
+      channel: "telegram",
+      source: "telegram",
+      queueDepth: 2,
+    });
+    emitDiagnosticEvent({
+      type: "message.processed",
+      channel: "telegram",
+      outcome: "completed",
+      durationMs: 55,
+    });
+    emitDiagnosticEvent({
+      type: "queue.lane.dequeue",
+      lane: "main",
+      queueSize: 3,
+      waitMs: 10,
+    });
+    emitDiagnosticEvent({
+      type: "session.stuck",
+      state: "processing",
+      ageMs: 125_000,
+    });
+    emitDiagnosticEvent({
+      type: "run.attempt",
+      runId: "run-1",
+      attempt: 2,
+    });
+
+    expect(telemetryState.counters.get("openclaw.webhook.received")?.add).toHaveBeenCalled();
+    expect(
+      telemetryState.histograms.get("openclaw.webhook.duration_ms")?.record,
+    ).toHaveBeenCalled();
+    expect(telemetryState.counters.get("openclaw.message.queued")?.add).toHaveBeenCalled();
+    expect(telemetryState.counters.get("openclaw.message.processed")?.add).toHaveBeenCalled();
+    expect(
+      telemetryState.histograms.get("openclaw.message.duration_ms")?.record,
+    ).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("openclaw.queue.wait_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("openclaw.session.stuck")?.add).toHaveBeenCalled();
+    expect(
+      telemetryState.histograms.get("openclaw.session.stuck_age_ms")?.record,
+    ).toHaveBeenCalled();
+    expect(telemetryState.counters.get("openclaw.run.attempt")?.add).toHaveBeenCalled();
+
+    const spanNames = telemetryState.tracer.startSpan.mock.calls.map((call) => call[0]);
+    expect(spanNames).toContain("openclaw.webhook.processed");
+    expect(spanNames).toContain("openclaw.message.processed");
+    expect(spanNames).toContain("openclaw.session.stuck");
+
+    expect(registerLogTransportMock).toHaveBeenCalledTimes(1);
+    expect(registeredTransports).toHaveLength(1);
+    registeredTransports[0]?.({
+      0: '{"subsystem":"diagnostic"}',
+      1: "hello",
+      _meta: { logLevelName: "INFO", date: new Date() },
+    });
+    expect(logEmit).toHaveBeenCalled();
+
+    await service.stop?.();
+  });
+});

extensions/diagnostics-otel/src/service.ts

@@ -0,0 +1,635 @@
+import type { SeverityNumber } from "@opentelemetry/api-logs";
+import type { DiagnosticEventPayload, OpenClawPluginService } from "openclaw/plugin-sdk";
+import { metrics, trace, SpanStatusCode } from "@opentelemetry/api";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { onDiagnosticEvent, registerLogTransport } from "openclaw/plugin-sdk";
+
+const DEFAULT_SERVICE_NAME = "openclaw";
+
+function normalizeEndpoint(endpoint?: string): string | undefined {
+  const trimmed = endpoint?.trim();
+  return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
+}
+
+function resolveOtelUrl(endpoint: string | undefined, path: string): string | undefined {
+  if (!endpoint) {
+    return undefined;
+  }
+  if (endpoint.includes("/v1/")) {
+    return endpoint;
+  }
+  return `${endpoint}/${path}`;
+}
+
+function resolveSampleRate(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  if (value < 0 || value > 1) {
+    return undefined;
+  }
+  return value;
+}
+
+export function createDiagnosticsOtelService(): OpenClawPluginService {
+  let sdk: NodeSDK | null = null;
+  let logProvider: LoggerProvider | null = null;
+  let stopLogTransport: (() => void) | null = null;
+  let unsubscribe: (() => void) | null = null;
+
+  return {
+    id: "diagnostics-otel",
+    async start(ctx) {
+      const cfg = ctx.config.diagnostics;
+      const otel = cfg?.otel;
+      if (!cfg?.enabled || !otel?.enabled) {
+        return;
+      }
+
+      const protocol = otel.protocol ?? process.env.OTEL_EXPORTER_OTLP_PROTOCOL ?? "http/protobuf";
+      if (protocol !== "http/protobuf") {
+        ctx.logger.warn(`diagnostics-otel: unsupported protocol ${protocol}`);
+        return;
+      }
+
+      const endpoint = normalizeEndpoint(otel.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+      const headers = otel.headers ?? undefined;
+      const serviceName =
+        otel.serviceName?.trim() || process.env.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
+      const sampleRate = resolveSampleRate(otel.sampleRate);
+
+      const tracesEnabled = otel.traces !== false;
+      const metricsEnabled = otel.metrics !== false;
+      const logsEnabled = otel.logs === true;
+      if (!tracesEnabled && !metricsEnabled && !logsEnabled) {
+        return;
+      }
+
+      const resource = new Resource({
+        [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+      });
+
+      const traceUrl = resolveOtelUrl(endpoint, "v1/traces");
+      const metricUrl = resolveOtelUrl(endpoint, "v1/metrics");
+      const logUrl = resolveOtelUrl(endpoint, "v1/logs");
+      const traceExporter = tracesEnabled
+        ? new OTLPTraceExporter({
+            ...(traceUrl ? { url: traceUrl } : {}),
+            ...(headers ? { headers } : {}),
+          })
+        : undefined;
+
+      const metricExporter = metricsEnabled
+        ? new OTLPMetricExporter({
+            ...(metricUrl ? { url: metricUrl } : {}),
+            ...(headers ? { headers } : {}),
+          })
+        : undefined;
+
+      const metricReader = metricExporter
+        ? new PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            ...(typeof otel.flushIntervalMs === "number"
+              ? { exportIntervalMillis: Math.max(1000, otel.flushIntervalMs) }
+              : {}),
+          })
+        : undefined;
+
+      if (tracesEnabled || metricsEnabled) {
+        sdk = new NodeSDK({
+          resource,
+          ...(traceExporter ? { traceExporter } : {}),
+          ...(metricReader ? { metricReader } : {}),
+          ...(sampleRate !== undefined
+            ? {
+                sampler: new ParentBasedSampler({
+                  root: new TraceIdRatioBasedSampler(sampleRate),
+                }),
+              }
+            : {}),
+        });
+
+        sdk.start();
+      }
+
+      const logSeverityMap: Record<string, SeverityNumber> = {
+        TRACE: 1 as SeverityNumber,
+        DEBUG: 5 as SeverityNumber,
+        INFO: 9 as SeverityNumber,
+        WARN: 13 as SeverityNumber,
+        ERROR: 17 as SeverityNumber,
+        FATAL: 21 as SeverityNumber,
+      };
+
+      const meter = metrics.getMeter("openclaw");
+      const tracer = trace.getTracer("openclaw");
+
+      const tokensCounter = meter.createCounter("openclaw.tokens", {
+        unit: "1",
+        description: "Token usage by type",
+      });
+      const costCounter = meter.createCounter("openclaw.cost.usd", {
+        unit: "1",
+        description: "Estimated model cost (USD)",
+      });
+      const durationHistogram = meter.createHistogram("openclaw.run.duration_ms", {
+        unit: "ms",
+        description: "Agent run duration",
+      });
+      const contextHistogram = meter.createHistogram("openclaw.context.tokens", {
+        unit: "1",
+        description: "Context window size and usage",
+      });
+      const webhookReceivedCounter = meter.createCounter("openclaw.webhook.received", {
+        unit: "1",
+        description: "Webhook requests received",
+      });
+      const webhookErrorCounter = meter.createCounter("openclaw.webhook.error", {
+        unit: "1",
+        description: "Webhook processing errors",
+      });
+      const webhookDurationHistogram = meter.createHistogram("openclaw.webhook.duration_ms", {
+        unit: "ms",
+        description: "Webhook processing duration",
+      });
+      const messageQueuedCounter = meter.createCounter("openclaw.message.queued", {
+        unit: "1",
+        description: "Messages queued for processing",
+      });
+      const messageProcessedCounter = meter.createCounter("openclaw.message.processed", {
+        unit: "1",
+        description: "Messages processed by outcome",
+      });
+      const messageDurationHistogram = meter.createHistogram("openclaw.message.duration_ms", {
+        unit: "ms",
+        description: "Message processing duration",
+      });
+      const queueDepthHistogram = meter.createHistogram("openclaw.queue.depth", {
+        unit: "1",
+        description: "Queue depth on enqueue/dequeue",
+      });
+      const queueWaitHistogram = meter.createHistogram("openclaw.queue.wait_ms", {
+        unit: "ms",
+        description: "Queue wait time before execution",
+      });
+      const laneEnqueueCounter = meter.createCounter("openclaw.queue.lane.enqueue", {
+        unit: "1",
+        description: "Command queue lane enqueue events",
+      });
+      const laneDequeueCounter = meter.createCounter("openclaw.queue.lane.dequeue", {
+        unit: "1",
+        description: "Command queue lane dequeue events",
+      });
+      const sessionStateCounter = meter.createCounter("openclaw.session.state", {
+        unit: "1",
+        description: "Session state transitions",
+      });
+      const sessionStuckCounter = meter.createCounter("openclaw.session.stuck", {
+        unit: "1",
+        description: "Sessions stuck in processing",
+      });
+      const sessionStuckAgeHistogram = meter.createHistogram("openclaw.session.stuck_age_ms", {
+        unit: "ms",
+        description: "Age of stuck sessions",
+      });
+      const runAttemptCounter = meter.createCounter("openclaw.run.attempt", {
+        unit: "1",
+        description: "Run attempts",
+      });
+
+      if (logsEnabled) {
+        const logExporter = new OTLPLogExporter({
+          ...(logUrl ? { url: logUrl } : {}),
+          ...(headers ? { headers } : {}),
+        });
+        logProvider = new LoggerProvider({ resource });
+        logProvider.addLogRecordProcessor(
+          new BatchLogRecordProcessor(
+            logExporter,
+            typeof otel.flushIntervalMs === "number"
+              ? { scheduledDelayMillis: Math.max(1000, otel.flushIntervalMs) }
+              : {},
+          ),
+        );
+        const otelLogger = logProvider.getLogger("openclaw");
+
+        stopLogTransport = registerLogTransport((logObj) => {
+          const safeStringify = (value: unknown) => {
+            try {
+              return JSON.stringify(value);
+            } catch {
+              return String(value);
+            }
+          };
+          const meta = (logObj as Record<string, unknown>)._meta as
+            | {
+                logLevelName?: string;
+                date?: Date;
+                name?: string;
+                parentNames?: string[];
+                path?: {
+                  filePath?: string;
+                  fileLine?: string;
+                  fileColumn?: string;
+                  filePathWithLine?: string;
+                  method?: string;
+                };
+              }
+            | undefined;
+          const logLevelName = meta?.logLevelName ?? "INFO";
+          const severityNumber = logSeverityMap[logLevelName] ?? (9 as SeverityNumber);
+
+          const numericArgs = Object.entries(logObj)
+            .filter(([key]) => /^\d+$/.test(key))
+            .toSorted((a, b) => Number(a[0]) - Number(b[0]))
+            .map(([, value]) => value);
+
+          let bindings: Record<string, unknown> | undefined;
+          if (typeof numericArgs[0] === "string" && numericArgs[0].trim().startsWith("{")) {
+            try {
+              const parsed = JSON.parse(numericArgs[0]);
+              if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                bindings = parsed as Record<string, unknown>;
+                numericArgs.shift();
+              }
+            } catch {
+              // ignore malformed json bindings
+            }
+          }
+
+          let message = "";
+          if (numericArgs.length > 0 && typeof numericArgs[numericArgs.length - 1] === "string") {
+            message = String(numericArgs.pop());
+          } else if (numericArgs.length === 1) {
+            message = safeStringify(numericArgs[0]);
+            numericArgs.length = 0;
+          }
+          if (!message) {
+            message = "log";
+          }
+
+          const attributes: Record<string, string | number | boolean> = {
+            "openclaw.log.level": logLevelName,
+          };
+          if (meta?.name) {
+            attributes["openclaw.logger"] = meta.name;
+          }
+          if (meta?.parentNames?.length) {
+            attributes["openclaw.logger.parents"] = meta.parentNames.join(".");
+          }
+          if (bindings) {
+            for (const [key, value] of Object.entries(bindings)) {
+              if (
+                typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean"
+              ) {
+                attributes[`openclaw.${key}`] = value;
+              } else if (value != null) {
+                attributes[`openclaw.${key}`] = safeStringify(value);
+              }
+            }
+          }
+          if (numericArgs.length > 0) {
+            attributes["openclaw.log.args"] = safeStringify(numericArgs);
+          }
+          if (meta?.path?.filePath) {
+            attributes["code.filepath"] = meta.path.filePath;
+          }
+          if (meta?.path?.fileLine) {
+            attributes["code.lineno"] = Number(meta.path.fileLine);
+          }
+          if (meta?.path?.method) {
+            attributes["code.function"] = meta.path.method;
+          }
+          if (meta?.path?.filePathWithLine) {
+            attributes["openclaw.code.location"] = meta.path.filePathWithLine;
+          }
+
+          otelLogger.emit({
+            body: message,
+            severityText: logLevelName,
+            severityNumber,
+            attributes,
+            timestamp: meta?.date ?? new Date(),
+          });
+        });
+      }
+
+      const spanWithDuration = (
+        name: string,
+        attributes: Record<string, string | number>,
+        durationMs?: number,
+      ) => {
+        const startTime =
+          typeof durationMs === "number" ? Date.now() - Math.max(0, durationMs) : undefined;
+        const span = tracer.startSpan(name, {
+          attributes,
+          ...(startTime ? { startTime } : {}),
+        });
+        return span;
+      };
+
+      const recordModelUsage = (evt: Extract<DiagnosticEventPayload, { type: "model.usage" }>) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.provider": evt.provider ?? "unknown",
+          "openclaw.model": evt.model ?? "unknown",
+        };
+
+        const usage = evt.usage;
+        if (usage.input) {
+          tokensCounter.add(usage.input, { ...attrs, "openclaw.token": "input" });
+        }
+        if (usage.output) {
+          tokensCounter.add(usage.output, { ...attrs, "openclaw.token": "output" });
+        }
+        if (usage.cacheRead) {
+          tokensCounter.add(usage.cacheRead, { ...attrs, "openclaw.token": "cache_read" });
+        }
+        if (usage.cacheWrite) {
+          tokensCounter.add(usage.cacheWrite, { ...attrs, "openclaw.token": "cache_write" });
+        }
+        if (usage.promptTokens) {
+          tokensCounter.add(usage.promptTokens, { ...attrs, "openclaw.token": "prompt" });
+        }
+        if (usage.total) {
+          tokensCounter.add(usage.total, { ...attrs, "openclaw.token": "total" });
+        }
+
+        if (evt.costUsd) {
+          costCounter.add(evt.costUsd, attrs);
+        }
+        if (evt.durationMs) {
+          durationHistogram.record(evt.durationMs, attrs);
+        }
+        if (evt.context?.limit) {
+          contextHistogram.record(evt.context.limit, {
+            ...attrs,
+            "openclaw.context": "limit",
+          });
+        }
+        if (evt.context?.used) {
+          contextHistogram.record(evt.context.used, {
+            ...attrs,
+            "openclaw.context": "used",
+          });
+        }
+
+        if (!tracesEnabled) {
+          return;
+        }
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "openclaw.sessionKey": evt.sessionKey ?? "",
+          "openclaw.sessionId": evt.sessionId ?? "",
+          "openclaw.tokens.input": usage.input ?? 0,
+          "openclaw.tokens.output": usage.output ?? 0,
+          "openclaw.tokens.cache_read": usage.cacheRead ?? 0,
+          "openclaw.tokens.cache_write": usage.cacheWrite ?? 0,
+          "openclaw.tokens.total": usage.total ?? 0,
+        };
+
+        const span = spanWithDuration("openclaw.model.usage", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookReceived = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.received" }>,
+      ) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.webhook": evt.updateType ?? "unknown",
+        };
+        webhookReceivedCounter.add(1, attrs);
+      };
+
+      const recordWebhookProcessed = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.processed" }>,
+      ) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.webhook": evt.updateType ?? "unknown",
+        };
+        if (typeof evt.durationMs === "number") {
+          webhookDurationHistogram.record(evt.durationMs, attrs);
+        }
+        if (!tracesEnabled) {
+          return;
+        }
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.chatId !== undefined) {
+          spanAttrs["openclaw.chatId"] = String(evt.chatId);
+        }
+        const span = spanWithDuration("openclaw.webhook.processed", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookError = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.error" }>,
+      ) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.webhook": evt.updateType ?? "unknown",
+        };
+        webhookErrorCounter.add(1, attrs);
+        if (!tracesEnabled) {
+          return;
+        }
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "openclaw.error": evt.error,
+        };
+        if (evt.chatId !== undefined) {
+          spanAttrs["openclaw.chatId"] = String(evt.chatId);
+        }
+        const span = tracer.startSpan("openclaw.webhook.error", {
+          attributes: spanAttrs,
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: evt.error });
+        span.end();
+      };
+
+      const recordMessageQueued = (
+        evt: Extract<DiagnosticEventPayload, { type: "message.queued" }>,
+      ) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.source": evt.source ?? "unknown",
+        };
+        messageQueuedCounter.add(1, attrs);
+        if (typeof evt.queueDepth === "number") {
+          queueDepthHistogram.record(evt.queueDepth, attrs);
+        }
+      };
+
+      const recordMessageProcessed = (
+        evt: Extract<DiagnosticEventPayload, { type: "message.processed" }>,
+      ) => {
+        const attrs = {
+          "openclaw.channel": evt.channel ?? "unknown",
+          "openclaw.outcome": evt.outcome ?? "unknown",
+        };
+        messageProcessedCounter.add(1, attrs);
+        if (typeof evt.durationMs === "number") {
+          messageDurationHistogram.record(evt.durationMs, attrs);
+        }
+        if (!tracesEnabled) {
+          return;
+        }
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.sessionKey) {
+          spanAttrs["openclaw.sessionKey"] = evt.sessionKey;
+        }
+        if (evt.sessionId) {
+          spanAttrs["openclaw.sessionId"] = evt.sessionId;
+        }
+        if (evt.chatId !== undefined) {
+          spanAttrs["openclaw.chatId"] = String(evt.chatId);
+        }
+        if (evt.messageId !== undefined) {
+          spanAttrs["openclaw.messageId"] = String(evt.messageId);
+        }
+        if (evt.reason) {
+          spanAttrs["openclaw.reason"] = evt.reason;
+        }
+        const span = spanWithDuration("openclaw.message.processed", spanAttrs, evt.durationMs);
+        if (evt.outcome === "error") {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: evt.error });
+        }
+        span.end();
+      };
+
+      const recordLaneEnqueue = (
+        evt: Extract<DiagnosticEventPayload, { type: "queue.lane.enqueue" }>,
+      ) => {
+        const attrs = { "openclaw.lane": evt.lane };
+        laneEnqueueCounter.add(1, attrs);
+        queueDepthHistogram.record(evt.queueSize, attrs);
+      };
+
+      const recordLaneDequeue = (
+        evt: Extract<DiagnosticEventPayload, { type: "queue.lane.dequeue" }>,
+      ) => {
+        const attrs = { "openclaw.lane": evt.lane };
+        laneDequeueCounter.add(1, attrs);
+        queueDepthHistogram.record(evt.queueSize, attrs);
+        if (typeof evt.waitMs === "number") {
+          queueWaitHistogram.record(evt.waitMs, attrs);
+        }
+      };
+
+      const recordSessionState = (
+        evt: Extract<DiagnosticEventPayload, { type: "session.state" }>,
+      ) => {
+        const attrs: Record<string, string> = { "openclaw.state": evt.state };
+        if (evt.reason) {
+          attrs["openclaw.reason"] = evt.reason;
+        }
+        sessionStateCounter.add(1, attrs);
+      };
+
+      const recordSessionStuck = (
+        evt: Extract<DiagnosticEventPayload, { type: "session.stuck" }>,
+      ) => {
+        const attrs: Record<string, string> = { "openclaw.state": evt.state };
+        sessionStuckCounter.add(1, attrs);
+        if (typeof evt.ageMs === "number") {
+          sessionStuckAgeHistogram.record(evt.ageMs, attrs);
+        }
+        if (!tracesEnabled) {
+          return;
+        }
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.sessionKey) {
+          spanAttrs["openclaw.sessionKey"] = evt.sessionKey;
+        }
+        if (evt.sessionId) {
+          spanAttrs["openclaw.sessionId"] = evt.sessionId;
+        }
+        spanAttrs["openclaw.queueDepth"] = evt.queueDepth ?? 0;
+        spanAttrs["openclaw.ageMs"] = evt.ageMs;
+        const span = tracer.startSpan("openclaw.session.stuck", { attributes: spanAttrs });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: "session stuck" });
+        span.end();
+      };
+
+      const recordRunAttempt = (evt: Extract<DiagnosticEventPayload, { type: "run.attempt" }>) => {
+        runAttemptCounter.add(1, { "openclaw.attempt": evt.attempt });
+      };
+
+      const recordHeartbeat = (
+        evt: Extract<DiagnosticEventPayload, { type: "diagnostic.heartbeat" }>,
+      ) => {
+        queueDepthHistogram.record(evt.queued, { "openclaw.channel": "heartbeat" });
+      };
+
+      unsubscribe = onDiagnosticEvent((evt: DiagnosticEventPayload) => {
+        switch (evt.type) {
+          case "model.usage":
+            recordModelUsage(evt);
+            return;
+          case "webhook.received":
+            recordWebhookReceived(evt);
+            return;
+          case "webhook.processed":
+            recordWebhookProcessed(evt);
+            return;
+          case "webhook.error":
+            recordWebhookError(evt);
+            return;
+          case "message.queued":
+            recordMessageQueued(evt);
+            return;
+          case "message.processed":
+            recordMessageProcessed(evt);
+            return;
+          case "queue.lane.enqueue":
+            recordLaneEnqueue(evt);
+            return;
+          case "queue.lane.dequeue":
+            recordLaneDequeue(evt);
+            return;
+          case "session.state":
+            recordSessionState(evt);
+            return;
+          case "session.stuck":
+            recordSessionStuck(evt);
+            return;
+          case "run.attempt":
+            recordRunAttempt(evt);
+            return;
+          case "diagnostic.heartbeat":
+            recordHeartbeat(evt);
+            return;
+        }
+      });
+
+      if (logsEnabled) {
+        ctx.logger.info("diagnostics-otel: logs exporter enabled (OTLP/HTTP)");
+      }
+    },
+    async stop() {
+      unsubscribe?.();
+      unsubscribe = null;
+      stopLogTransport?.();
+      stopLogTransport = null;
+      if (logProvider) {
+        await logProvider.shutdown().catch(() => undefined);
+        logProvider = null;
+      }
+      if (sdk) {
+        await sdk.shutdown().catch(() => undefined);
+        sdk = null;
+      }
+    },
+  } satisfies OpenClawPluginService;
+}

extensions/discord/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { discordPlugin } from "./src/channel.js";
+import { setDiscordRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "discord",
+  name: "Discord",
+  description: "Discord channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setDiscordRuntime(api.runtime);
+    api.registerChannel({ plugin: discordPlugin });
+  },
+};
+
+export default plugin;

extensions/discord/openclaw.plugin.json

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

extensions/discord/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@openclaw/discord",
+  "version": "2026.1.30",
+  "description": "OpenClaw Discord channel plugin",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/discord/src/channel.ts

@@ -0,0 +1,422 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  collectDiscordAuditChannelIds,
+  collectDiscordStatusIssues,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  discordOnboardingAdapter,
+  DiscordConfigSchema,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  listDiscordAccountIds,
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryPeersFromConfig,
+  looksLikeDiscordTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeDiscordMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  resolveDiscordAccount,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordGroupRequireMention,
+  resolveDiscordGroupToolPolicy,
+  setAccountEnabledInConfigSection,
+  type ChannelMessageActionAdapter,
+  type ChannelPlugin,
+  type ResolvedDiscordAccount,
+} from "openclaw/plugin-sdk";
+import { getDiscordRuntime } from "./runtime.js";
+
+const meta = getChatChannelMeta("discord");
+
+const discordMessageActions: ChannelMessageActionAdapter = {
+  listActions: (ctx) => getDiscordRuntime().channel.discord.messageActions.listActions(ctx),
+  extractToolSend: (ctx) => getDiscordRuntime().channel.discord.messageActions.extractToolSend(ctx),
+  handleAction: async (ctx) =>
+    await getDiscordRuntime().channel.discord.messageActions.handleAction(ctx),
+};
+
+export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
+  id: "discord",
+  meta: {
+    ...meta,
+  },
+  onboarding: discordOnboardingAdapter,
+  pairing: {
+    idLabel: "discordUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(discord|user):/i, ""),
+    notifyApproval: async ({ id }) => {
+      await getDiscordRuntime().channel.discord.sendMessageDiscord(
+        `user:${id}`,
+        PAIRING_APPROVED_MESSAGE,
+      );
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel", "thread"],
+    polls: true,
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.discord"] },
+  configSchema: buildChannelConfigSchema(DiscordConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listDiscordAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveDiscordAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultDiscordAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "discord",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "discord",
+        accountId,
+        clearBaseFields: ["token", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.token?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.token?.trim()),
+      tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveDiscordAccount({ cfg, accountId }).config.dm?.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.discord?.accounts?.[resolvedAccountId]);
+      const allowFromPath = useAccountPath
+        ? `channels.discord.accounts.${resolvedAccountId}.dm.`
+        : "channels.discord.dm.";
+      return {
+        policy: account.config.dm?.policy ?? "pairing",
+        allowFrom: account.config.dm?.allowFrom ?? [],
+        allowFromPath,
+        approveHint: formatPairingApproveHint("discord"),
+        normalizeEntry: (raw) => raw.replace(/^(discord|user):/i, "").replace(/^<@!?(\d+)>$/, "$1"),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+      const guildEntries = account.config.guilds ?? {};
+      const guildsConfigured = Object.keys(guildEntries).length > 0;
+      const channelAllowlistConfigured = guildsConfigured;
+
+      if (groupPolicy === "open") {
+        if (channelAllowlistConfigured) {
+          warnings.push(
+            `- Discord guilds: groupPolicy="open" allows any channel not explicitly denied to trigger (mention-gated). Set channels.discord.groupPolicy="allowlist" and configure channels.discord.guilds.<id>.channels.`,
+          );
+        } else {
+          warnings.push(
+            `- Discord guilds: groupPolicy="open" with no guild/channel allowlist; any channel can trigger (mention-gated). Set channels.discord.groupPolicy="allowlist" and configure channels.discord.guilds.<id>.channels.`,
+          );
+        }
+      }
+
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveDiscordGroupRequireMention,
+    resolveToolPolicy: resolveDiscordGroupToolPolicy,
+  },
+  mentions: {
+    stripPatterns: () => ["<@!?\\d+>"],
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.discord?.replyToMode ?? "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeDiscordMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeDiscordTargetId,
+      hint: "<channelId|user:ID|channel:ID>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async (params) => listDiscordDirectoryPeersFromConfig(params),
+    listGroups: async (params) => listDiscordDirectoryGroupsFromConfig(params),
+    listPeersLive: async (params) =>
+      getDiscordRuntime().channel.discord.listDirectoryPeersLive(params),
+    listGroupsLive: async (params) =>
+      getDiscordRuntime().channel.discord.listDirectoryGroupsLive(params),
+  },
+  resolver: {
+    resolveTargets: async ({ cfg, accountId, inputs, kind }) => {
+      const account = resolveDiscordAccount({ cfg, accountId });
+      const token = account.token?.trim();
+      if (!token) {
+        return inputs.map((input) => ({
+          input,
+          resolved: false,
+          note: "missing Discord token",
+        }));
+      }
+      if (kind === "group") {
+        const resolved = await getDiscordRuntime().channel.discord.resolveChannelAllowlist({
+          token,
+          entries: inputs,
+        });
+        return resolved.map((entry) => ({
+          input: entry.input,
+          resolved: entry.resolved,
+          id: entry.channelId ?? entry.guildId,
+          name:
+            entry.channelName ??
+            entry.guildName ??
+            (entry.guildId && !entry.channelId ? entry.guildId : undefined),
+          note: entry.note,
+        }));
+      }
+      const resolved = await getDiscordRuntime().channel.discord.resolveUserAllowlist({
+        token,
+        entries: inputs,
+      });
+      return resolved.map((entry) => ({
+        input: entry.input,
+        resolved: entry.resolved,
+        id: entry.id,
+        name: entry.name,
+        note: entry.note,
+      }));
+    },
+  },
+  actions: discordMessageActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "discord",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "DISCORD_BOT_TOKEN can only be used for the default account.";
+      }
+      if (!input.useEnv && !input.token) {
+        return "Discord requires token (or --use-env).";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "discord",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "discord",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            discord: {
+              ...next.channels?.discord,
+              enabled: true,
+              ...(input.useEnv ? {} : input.token ? { token: input.token } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          discord: {
+            ...next.channels?.discord,
+            enabled: true,
+            accounts: {
+              ...next.channels?.discord?.accounts,
+              [accountId]: {
+                ...next.channels?.discord?.accounts?.[accountId],
+                enabled: true,
+                ...(input.token ? { token: input.token } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: null,
+    textChunkLimit: 2000,
+    pollMaxOptions: 10,
+    sendText: async ({ to, text, accountId, deps, replyToId }) => {
+      const send = deps?.sendDiscord ?? getDiscordRuntime().channel.discord.sendMessageDiscord;
+      const result = await send(to, text, {
+        verbose: false,
+        replyTo: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "discord", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId }) => {
+      const send = deps?.sendDiscord ?? getDiscordRuntime().channel.discord.sendMessageDiscord;
+      const result = await send(to, text, {
+        verbose: false,
+        mediaUrl,
+        replyTo: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "discord", ...result };
+    },
+    sendPoll: async ({ to, poll, accountId }) =>
+      await getDiscordRuntime().channel.discord.sendPollDiscord(to, poll, {
+        accountId: accountId ?? undefined,
+      }),
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: collectDiscordStatusIssues,
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      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 }) =>
+      getDiscordRuntime().channel.discord.probeDiscord(account.token, timeoutMs, {
+        includeApplication: true,
+      }),
+    auditAccount: async ({ account, timeoutMs, cfg }) => {
+      const { channelIds, unresolvedChannels } = collectDiscordAuditChannelIds({
+        cfg,
+        accountId: account.accountId,
+      });
+      if (!channelIds.length && unresolvedChannels === 0) {
+        return undefined;
+      }
+      const botToken = account.token?.trim();
+      if (!botToken) {
+        return {
+          ok: unresolvedChannels === 0,
+          checkedChannels: 0,
+          unresolvedChannels,
+          channels: [],
+          elapsedMs: 0,
+        };
+      }
+      const audit = await getDiscordRuntime().channel.discord.auditChannelPermissions({
+        token: botToken,
+        accountId: account.accountId,
+        channelIds,
+        timeoutMs,
+      });
+      return { ...audit, unresolvedChannels };
+    },
+    buildAccountSnapshot: ({ account, runtime, probe, audit }) => {
+      const configured = Boolean(account.token?.trim());
+      const app = runtime?.application ?? (probe as { application?: unknown })?.application;
+      const bot = runtime?.bot ?? (probe as { bot?: unknown })?.bot;
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured,
+        tokenSource: account.tokenSource,
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        application: app ?? undefined,
+        bot: bot ?? undefined,
+        probe,
+        audit,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const token = account.token.trim();
+      let discordBotLabel = "";
+      try {
+        const probe = await getDiscordRuntime().channel.discord.probeDiscord(token, 2500, {
+          includeApplication: true,
+        });
+        const username = probe.ok ? probe.bot?.username?.trim() : null;
+        if (username) {
+          discordBotLabel = ` (@${username})`;
+        }
+        ctx.setStatus({
+          accountId: account.accountId,
+          bot: probe.bot,
+          application: probe.application,
+        });
+        const messageContent = probe.application?.intents?.messageContent;
+        if (messageContent === "disabled") {
+          ctx.log?.warn(
+            `[${account.accountId}] Discord Message Content Intent is disabled; bot may not respond to channel messages. Enable it in Discord Dev Portal (Bot → Privileged Gateway Intents) or require mentions.`,
+          );
+        } else if (messageContent === "limited") {
+          ctx.log?.info(
+            `[${account.accountId}] Discord Message Content Intent is limited; bots under 100 servers can use it without verification.`,
+          );
+        }
+      } catch (err) {
+        if (getDiscordRuntime().logging.shouldLogVerbose()) {
+          ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`);
+        }
+      }
+      ctx.log?.info(`[${account.accountId}] starting provider${discordBotLabel}`);
+      return getDiscordRuntime().channel.discord.monitorDiscordProvider({
+        token,
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+        historyLimit: account.config.historyLimit,
+      });
+    },
+  },
+};

extensions/discord/src/runtime.ts

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

extensions/google-antigravity-auth/README.md

@@ -0,0 +1,24 @@
+# Google Antigravity Auth (OpenClaw plugin)
+
+OAuth provider plugin for **Google Antigravity** (Cloud Code Assist).
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```bash
+openclaw plugins enable google-antigravity-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+openclaw models auth login --provider google-antigravity --set-default
+```
+
+## Notes
+
+- Antigravity uses Google Cloud project quotas.
+- If requests fail, ensure Gemini for Google Cloud is enabled.

extensions/google-antigravity-auth/index.ts

@@ -0,0 +1,461 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+// OAuth constants - decoded from pi-ai's base64 encoded values to stay in sync
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ==",
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const DEFAULT_PROJECT_ID = "rising-fact-p41fc";
+const DEFAULT_MODEL = "google-antigravity/claude-opus-4-5-thinking";
+
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+
+const CODE_ASSIST_ENDPOINTS = [
+  "https://cloudcode-pa.googleapis.com",
+  "https://daily-cloudcode-pa.sandbox.googleapis.com",
+];
+
+const RESPONSE_PAGE = `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>OpenClaw Antigravity OAuth</title>
+  </head>
+  <body>
+    <main>
+      <h1>Authentication complete</h1>
+      <p>You can return to the terminal.</p>
+    </main>
+  </body>
+</html>`;
+
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+function isWSL(): boolean {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  try {
+    const release = readFileSync("/proc/version", "utf8").toLowerCase();
+    return release.includes("microsoft") || release.includes("wsl");
+  } catch {
+    return false;
+  }
+}
+
+function isWSL2(): boolean {
+  if (!isWSL()) {
+    return false;
+  }
+  try {
+    const version = readFileSync("/proc/version", "utf8").toLowerCase();
+    return version.includes("wsl2") || version.includes("microsoft-standard");
+  } catch {
+    return false;
+  }
+}
+
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2();
+}
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+
+function parseCallbackInput(input: string): { code: string; state: string } | { error: string } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { error: "No input provided" };
+  }
+
+  try {
+    const url = new URL(trimmed);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (!code) {
+      return { error: "Missing 'code' parameter in URL" };
+    }
+    if (!state) {
+      return { error: "Missing 'state' parameter in URL" };
+    }
+    return { code, state };
+  } catch {
+    return { error: "Paste the full redirect URL (not just the code)." };
+  }
+}
+
+async function startCallbackServer(params: { timeoutMs: number }) {
+  const redirect = new URL(REDIRECT_URI);
+  const port = redirect.port ? Number(redirect.port) : 51121;
+
+  let settled = false;
+  let resolveCallback: (url: URL) => void;
+  let rejectCallback: (err: Error) => void;
+
+  const callbackPromise = new Promise<URL>((resolve, reject) => {
+    resolveCallback = (url) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(url);
+    };
+    rejectCallback = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      reject(err);
+    };
+  });
+
+  const timeout = setTimeout(() => {
+    rejectCallback(new Error("Timed out waiting for OAuth callback"));
+  }, params.timeoutMs);
+  timeout.unref?.();
+
+  const server = createServer((request, response) => {
+    if (!request.url) {
+      response.writeHead(400, { "Content-Type": "text/plain" });
+      response.end("Missing URL");
+      return;
+    }
+
+    const url = new URL(request.url, `${redirect.protocol}//${redirect.host}`);
+    if (url.pathname !== redirect.pathname) {
+      response.writeHead(404, { "Content-Type": "text/plain" });
+      response.end("Not found");
+      return;
+    }
+
+    response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    response.end(RESPONSE_PAGE);
+    resolveCallback(url);
+
+    setImmediate(() => {
+      server.close();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (err: Error) => {
+      server.off("error", onError);
+      reject(err);
+    };
+    server.once("error", onError);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+
+  return {
+    waitForCallback: () => callbackPromise,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+}
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed: ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+
+  const access = data.access_token?.trim();
+  const refresh = data.refresh_token?.trim();
+  const expiresIn = data.expires_in ?? 0;
+
+  if (!access) {
+    throw new Error("Token exchange returned no access_token");
+  }
+  if (!refresh) {
+    throw new Error("Token exchange returned no refresh_token");
+  }
+
+  const expires = Date.now() + expiresIn * 1000 - 5 * 60 * 1000;
+  return { access, refresh, expires };
+}
+
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  try {
+    const response = await fetch("https://www.googleapis.com/oauth2/v1/userinfo?alt=json", {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+      return undefined;
+    }
+    const data = (await response.json()) as { email?: string };
+    return data.email;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  for (const endpoint of CODE_ASSIST_ENDPOINTS) {
+    try {
+      const response = await fetch(`${endpoint}/v1internal:loadCodeAssist`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          metadata: {
+            ideType: "IDE_UNSPECIFIED",
+            platform: "PLATFORM_UNSPECIFIED",
+            pluginType: "GEMINI",
+          },
+        }),
+      });
+
+      if (!response.ok) {
+        continue;
+      }
+      const data = (await response.json()) as {
+        cloudaicompanionProject?: string | { id?: string };
+      };
+
+      if (typeof data.cloudaicompanionProject === "string") {
+        return data.cloudaicompanionProject;
+      }
+      if (
+        data.cloudaicompanionProject &&
+        typeof data.cloudaicompanionProject === "object" &&
+        data.cloudaicompanionProject.id
+      ) {
+        return data.cloudaicompanionProject.id;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return DEFAULT_PROJECT_ID;
+}
+
+async function loginAntigravity(params: {
+  isRemote: boolean;
+  openUrl: (url: string) => Promise<void>;
+  prompt: (message: string) => Promise<string>;
+  note: (message: string, title?: string) => Promise<void>;
+  log: (message: string) => void;
+  progress: { update: (msg: string) => void; stop: (msg?: string) => void };
+}): Promise<{
+  access: string;
+  refresh: string;
+  expires: number;
+  email?: string;
+  projectId: string;
+}> {
+  const { verifier, challenge } = generatePkce();
+  const state = randomBytes(16).toString("hex");
+  const authUrl = buildAuthUrl({ challenge, state });
+
+  let callbackServer: Awaited<ReturnType<typeof startCallbackServer>> | null = null;
+  const needsManual = shouldUseManualOAuthFlow(params.isRemote);
+  if (!needsManual) {
+    try {
+      callbackServer = await startCallbackServer({ timeoutMs: 5 * 60 * 1000 });
+    } catch {
+      callbackServer = null;
+    }
+  }
+
+  if (!callbackServer) {
+    await params.note(
+      [
+        "Open the URL in your local browser.",
+        "After signing in, copy the full redirect URL and paste it back here.",
+        "",
+        `Auth URL: ${authUrl}`,
+        `Redirect URI: ${REDIRECT_URI}`,
+      ].join("\n"),
+      "Google Antigravity OAuth",
+    );
+    // Output raw URL below the box for easy copying (fixes #1772)
+    params.log("");
+    params.log("Copy this URL:");
+    params.log(authUrl);
+    params.log("");
+  }
+
+  if (!needsManual) {
+    params.progress.update("Opening Google sign-in…");
+    try {
+      await params.openUrl(authUrl);
+    } catch {
+      // ignore
+    }
+  }
+
+  let code = "";
+  let returnedState = "";
+
+  if (callbackServer) {
+    params.progress.update("Waiting for OAuth callback…");
+    const callback = await callbackServer.waitForCallback();
+    code = callback.searchParams.get("code") ?? "";
+    returnedState = callback.searchParams.get("state") ?? "";
+    await callbackServer.close();
+  } else {
+    params.progress.update("Waiting for redirect URL…");
+    const input = await params.prompt("Paste the redirect URL: ");
+    const parsed = parseCallbackInput(input);
+    if ("error" in parsed) {
+      throw new Error(parsed.error);
+    }
+    code = parsed.code;
+    returnedState = parsed.state;
+  }
+
+  if (!code) {
+    throw new Error("Missing OAuth code");
+  }
+  if (returnedState !== state) {
+    throw new Error("OAuth state mismatch. Please try again.");
+  }
+
+  params.progress.update("Exchanging code for tokens…");
+  const tokens = await exchangeCode({ code, verifier });
+  const email = await fetchUserEmail(tokens.access);
+  const projectId = await fetchProjectId(tokens.access);
+
+  params.progress.stop("Antigravity OAuth complete");
+  return { ...tokens, email, projectId };
+}
+
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx) => {
+            const spin = ctx.prompter.progress("Starting Antigravity OAuth…");
+            try {
+              const result = await loginAntigravity({
+                isRemote: ctx.isRemote,
+                openUrl: ctx.openUrl,
+                prompt: async (message) => String(await ctx.prompter.text({ message })),
+                note: ctx.prompter.note,
+                log: (message) => ctx.runtime.log(message),
+                progress: spin,
+              });
+
+              const profileId = `google-antigravity:${result.email ?? "default"}`;
+              return {
+                profiles: [
+                  {
+                    profileId,
+                    credential: {
+                      type: "oauth",
+                      provider: "google-antigravity",
+                      access: result.access,
+                      refresh: result.refresh,
+                      expires: result.expires,
+                      email: result.email,
+                      projectId: result.projectId,
+                    },
+                  },
+                ],
+                configPatch: {
+                  agents: {
+                    defaults: {
+                      models: {
+                        [DEFAULT_MODEL]: {},
+                      },
+                    },
+                  },
+                },
+                defaultModel: DEFAULT_MODEL,
+                notes: [
+                  "Antigravity uses Google Cloud project quotas.",
+                  "Enable Gemini for Google Cloud on your project if requests fail.",
+                ],
+              };
+            } catch (err) {
+              spin.stop("Antigravity OAuth failed");
+              throw err;
+            }
+          },
+        },
+      ],
+    });
+  },
+};
+
+export default antigravityPlugin;

extensions/google-antigravity-auth/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "google-antigravity-auth",
+  "providers": ["google-antigravity"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/google-antigravity-auth/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@openclaw/google-antigravity-auth",
+  "version": "2026.1.30",
+  "description": "OpenClaw Google Antigravity OAuth provider plugin",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/google-gemini-cli-auth/README.md

@@ -0,0 +1,35 @@
+# Google Gemini CLI Auth (OpenClaw plugin)
+
+OAuth provider plugin for **Gemini CLI** (Google Code Assist).
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```bash
+openclaw plugins enable google-gemini-cli-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+openclaw models auth login --provider google-gemini-cli --set-default
+```
+
+## Requirements
+
+Requires the Gemini CLI to be installed (credentials are extracted automatically):
+
+```bash
+brew install gemini-cli
+# or: npm install -g @google/gemini-cli
+```
+
+## Env vars (optional)
+
+Override auto-detected credentials with:
+
+- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID` / `GEMINI_CLI_OAUTH_CLIENT_ID`
+- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET` / `GEMINI_CLI_OAUTH_CLIENT_SECRET`

extensions/google-gemini-cli-auth/index.ts

@@ -0,0 +1,88 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { loginGeminiCliOAuth } from "./oauth.js";
+
+const PROVIDER_ID = "google-gemini-cli";
+const PROVIDER_LABEL = "Gemini CLI OAuth";
+const DEFAULT_MODEL = "google-gemini-cli/gemini-3-pro-preview";
+const ENV_VARS = [
+  "OPENCLAW_GEMINI_OAUTH_CLIENT_ID",
+  "OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET",
+  "GEMINI_CLI_OAUTH_CLIENT_ID",
+  "GEMINI_CLI_OAUTH_CLIENT_SECRET",
+];
+
+const geminiCliPlugin = {
+  id: "google-gemini-cli-auth",
+  name: "Google Gemini CLI Auth",
+  description: "OAuth flow for Gemini CLI (Google Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api) {
+    api.registerProvider({
+      id: PROVIDER_ID,
+      label: PROVIDER_LABEL,
+      docsPath: "/providers/models",
+      aliases: ["gemini-cli"],
+      envVars: ENV_VARS,
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx) => {
+            const spin = ctx.prompter.progress("Starting Gemini CLI OAuth…");
+            try {
+              const result = await loginGeminiCliOAuth({
+                isRemote: ctx.isRemote,
+                openUrl: ctx.openUrl,
+                log: (msg) => ctx.runtime.log(msg),
+                note: ctx.prompter.note,
+                prompt: async (message) => String(await ctx.prompter.text({ message })),
+                progress: spin,
+              });
+
+              spin.stop("Gemini CLI OAuth complete");
+              const profileId = `google-gemini-cli:${result.email ?? "default"}`;
+              return {
+                profiles: [
+                  {
+                    profileId,
+                    credential: {
+                      type: "oauth",
+                      provider: PROVIDER_ID,
+                      access: result.access,
+                      refresh: result.refresh,
+                      expires: result.expires,
+                      email: result.email,
+                      projectId: result.projectId,
+                    },
+                  },
+                ],
+                configPatch: {
+                  agents: {
+                    defaults: {
+                      models: {
+                        [DEFAULT_MODEL]: {},
+                      },
+                    },
+                  },
+                },
+                defaultModel: DEFAULT_MODEL,
+                notes: ["If requests fail, set GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID."],
+              };
+            } catch (err) {
+              spin.stop("Gemini CLI OAuth failed");
+              await ctx.prompter.note(
+                "Trouble with OAuth? Ensure your Google account has Gemini CLI access.",
+                "OAuth help",
+              );
+              throw err;
+            }
+          },
+        },
+      ],
+    });
+  },
+};
+
+export default geminiCliPlugin;

extensions/google-gemini-cli-auth/oauth.test.ts

@@ -0,0 +1,240 @@
+import { join, parse } from "node:path";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+// Mock fs module before importing the module under test
+const mockExistsSync = vi.fn();
+const mockReadFileSync = vi.fn();
+const mockRealpathSync = vi.fn();
+const mockReaddirSync = vi.fn();
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    existsSync: (...args: Parameters<typeof actual.existsSync>) => mockExistsSync(...args),
+    readFileSync: (...args: Parameters<typeof actual.readFileSync>) => mockReadFileSync(...args),
+    realpathSync: (...args: Parameters<typeof actual.realpathSync>) => mockRealpathSync(...args),
+    readdirSync: (...args: Parameters<typeof actual.readdirSync>) => mockReaddirSync(...args),
+  };
+});
+
+describe("extractGeminiCliCredentials", () => {
+  const normalizePath = (value: string) =>
+    value.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+  const rootDir = parse(process.cwd()).root || "/";
+  const FAKE_CLIENT_ID = "123456789-abcdef.apps.googleusercontent.com";
+  const FAKE_CLIENT_SECRET = "GOCSPX-FakeSecretValue123";
+  const FAKE_OAUTH2_CONTENT = `
+    const clientId = "${FAKE_CLIENT_ID}";
+    const clientSecret = "${FAKE_CLIENT_SECRET}";
+  `;
+
+  let originalPath: string | undefined;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    originalPath = process.env.PATH;
+  });
+
+  afterEach(() => {
+    process.env.PATH = originalPath;
+  });
+
+  it("returns null when gemini binary is not in PATH", async () => {
+    process.env.PATH = "/nonexistent";
+    mockExistsSync.mockReturnValue(false);
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("extracts credentials from oauth2.js in known path", async () => {
+    const fakeBinDir = join(rootDir, "fake", "bin");
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeResolvedPath = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "dist",
+      "index.js",
+    );
+    const fakeOauth2Path = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "node_modules",
+      "@google",
+      "gemini-cli-core",
+      "dist",
+      "src",
+      "code_assist",
+      "oauth2.js",
+    );
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      const normalized = normalizePath(p);
+      if (normalized === normalizePath(fakeGeminiPath)) {
+        return true;
+      }
+      if (normalized === normalizePath(fakeOauth2Path)) {
+        return true;
+      }
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockReturnValue(FAKE_OAUTH2_CONTENT);
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    const result = extractGeminiCliCredentials();
+
+    expect(result).toEqual({
+      clientId: FAKE_CLIENT_ID,
+      clientSecret: FAKE_CLIENT_SECRET,
+    });
+  });
+
+  it("returns null when oauth2.js cannot be found", async () => {
+    const fakeBinDir = join(rootDir, "fake", "bin");
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeResolvedPath = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "dist",
+      "index.js",
+    );
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation(
+      (p: string) => normalizePath(p) === normalizePath(fakeGeminiPath),
+    );
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReaddirSync.mockReturnValue([]); // Empty directory for recursive search
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("returns null when oauth2.js lacks credentials", async () => {
+    const fakeBinDir = join(rootDir, "fake", "bin");
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeResolvedPath = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "dist",
+      "index.js",
+    );
+    const fakeOauth2Path = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "node_modules",
+      "@google",
+      "gemini-cli-core",
+      "dist",
+      "src",
+      "code_assist",
+      "oauth2.js",
+    );
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      const normalized = normalizePath(p);
+      if (normalized === normalizePath(fakeGeminiPath)) {
+        return true;
+      }
+      if (normalized === normalizePath(fakeOauth2Path)) {
+        return true;
+      }
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockReturnValue("// no credentials here");
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("caches credentials after first extraction", async () => {
+    const fakeBinDir = join(rootDir, "fake", "bin");
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeResolvedPath = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "dist",
+      "index.js",
+    );
+    const fakeOauth2Path = join(
+      rootDir,
+      "fake",
+      "lib",
+      "node_modules",
+      "@google",
+      "gemini-cli",
+      "node_modules",
+      "@google",
+      "gemini-cli-core",
+      "dist",
+      "src",
+      "code_assist",
+      "oauth2.js",
+    );
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      const normalized = normalizePath(p);
+      if (normalized === normalizePath(fakeGeminiPath)) {
+        return true;
+      }
+      if (normalized === normalizePath(fakeOauth2Path)) {
+        return true;
+      }
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockReturnValue(FAKE_OAUTH2_CONTENT);
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+
+    // First call
+    const result1 = extractGeminiCliCredentials();
+    expect(result1).not.toBeNull();
+
+    // Second call should use cache (readFileSync not called again)
+    const readCount = mockReadFileSync.mock.calls.length;
+    const result2 = extractGeminiCliCredentials();
+    expect(result2).toEqual(result1);
+    expect(mockReadFileSync.mock.calls.length).toBe(readCount);
+  });
+});

extensions/google-gemini-cli-auth/oauth.ts

@@ -0,0 +1,662 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { createServer } from "node:http";
+import { delimiter, dirname, join } from "node:path";
+
+const CLIENT_ID_KEYS = ["OPENCLAW_GEMINI_OAUTH_CLIENT_ID", "GEMINI_CLI_OAUTH_CLIENT_ID"];
+const CLIENT_SECRET_KEYS = [
+  "OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET",
+  "GEMINI_CLI_OAUTH_CLIENT_SECRET",
+];
+const REDIRECT_URI = "http://localhost:8085/oauth2callback";
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const USERINFO_URL = "https://www.googleapis.com/oauth2/v1/userinfo?alt=json";
+const CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+];
+
+const TIER_FREE = "free-tier";
+const TIER_LEGACY = "legacy-tier";
+const TIER_STANDARD = "standard-tier";
+
+export type GeminiCliOAuthCredentials = {
+  access: string;
+  refresh: string;
+  expires: number;
+  email?: string;
+  projectId: string;
+};
+
+export type GeminiCliOAuthContext = {
+  isRemote: boolean;
+  openUrl: (url: string) => Promise<void>;
+  log: (msg: string) => void;
+  note: (message: string, title?: string) => Promise<void>;
+  prompt: (message: string) => Promise<string>;
+  progress: { update: (msg: string) => void; stop: (msg?: string) => void };
+};
+
+function resolveEnv(keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = process.env[key]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+let cachedGeminiCliCredentials: { clientId: string; clientSecret: string } | null = null;
+
+/** @internal */
+export function clearCredentialsCache(): void {
+  cachedGeminiCliCredentials = null;
+}
+
+/** Extracts OAuth credentials from the installed Gemini CLI's bundled oauth2.js. */
+export function extractGeminiCliCredentials(): { clientId: string; clientSecret: string } | null {
+  if (cachedGeminiCliCredentials) {
+    return cachedGeminiCliCredentials;
+  }
+
+  try {
+    const geminiPath = findInPath("gemini");
+    if (!geminiPath) {
+      return null;
+    }
+
+    const resolvedPath = realpathSync(geminiPath);
+    const geminiCliDir = dirname(dirname(resolvedPath));
+
+    const searchPaths = [
+      join(
+        geminiCliDir,
+        "node_modules",
+        "@google",
+        "gemini-cli-core",
+        "dist",
+        "src",
+        "code_assist",
+        "oauth2.js",
+      ),
+      join(
+        geminiCliDir,
+        "node_modules",
+        "@google",
+        "gemini-cli-core",
+        "dist",
+        "code_assist",
+        "oauth2.js",
+      ),
+    ];
+
+    let content: string | null = null;
+    for (const p of searchPaths) {
+      if (existsSync(p)) {
+        content = readFileSync(p, "utf8");
+        break;
+      }
+    }
+    if (!content) {
+      const found = findFile(geminiCliDir, "oauth2.js", 10);
+      if (found) {
+        content = readFileSync(found, "utf8");
+      }
+    }
+    if (!content) {
+      return null;
+    }
+
+    const idMatch = content.match(/(\d+-[a-z0-9]+\.apps\.googleusercontent\.com)/);
+    const secretMatch = content.match(/(GOCSPX-[A-Za-z0-9_-]+)/);
+    if (idMatch && secretMatch) {
+      cachedGeminiCliCredentials = { clientId: idMatch[1], clientSecret: secretMatch[1] };
+      return cachedGeminiCliCredentials;
+    }
+  } catch {
+    // Gemini CLI not installed or extraction failed
+  }
+  return null;
+}
+
+function findInPath(name: string): string | null {
+  const exts = process.platform === "win32" ? [".cmd", ".bat", ".exe", ""] : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    for (const ext of exts) {
+      const p = join(dir, name + ext);
+      if (existsSync(p)) {
+        return p;
+      }
+    }
+  }
+  return null;
+}
+
+function findFile(dir: string, name: string, depth: number): string | null {
+  if (depth <= 0) {
+    return null;
+  }
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isFile() && e.name === name) {
+        return p;
+      }
+      if (e.isDirectory() && !e.name.startsWith(".")) {
+        const found = findFile(p, name, depth - 1);
+        if (found) {
+          return found;
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function resolveOAuthClientConfig(): { clientId: string; clientSecret?: string } {
+  // 1. Check env vars first (user override)
+  const envClientId = resolveEnv(CLIENT_ID_KEYS);
+  const envClientSecret = resolveEnv(CLIENT_SECRET_KEYS);
+  if (envClientId) {
+    return { clientId: envClientId, clientSecret: envClientSecret };
+  }
+
+  // 2. Try to extract from installed Gemini CLI
+  const extracted = extractGeminiCliCredentials();
+  if (extracted) {
+    return extracted;
+  }
+
+  // 3. No credentials available
+  throw new Error(
+    "Gemini CLI not found. Install it first: brew install gemini-cli (or npm install -g @google/gemini-cli), or set GEMINI_CLI_OAUTH_CLIENT_ID.",
+  );
+}
+
+function isWSL(): boolean {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  try {
+    const release = readFileSync("/proc/version", "utf8").toLowerCase();
+    return release.includes("microsoft") || release.includes("wsl");
+  } catch {
+    return false;
+  }
+}
+
+function isWSL2(): boolean {
+  if (!isWSL()) {
+    return false;
+  }
+  try {
+    const version = readFileSync("/proc/version", "utf8").toLowerCase();
+    return version.includes("wsl2") || version.includes("microsoft-standard");
+  } catch {
+    return false;
+  }
+}
+
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2();
+}
+
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+function buildAuthUrl(challenge: string, verifier: string): string {
+  const { clientId } = resolveOAuthClientConfig();
+  const params = new URLSearchParams({
+    client_id: clientId,
+    response_type: "code",
+    redirect_uri: REDIRECT_URI,
+    scope: SCOPES.join(" "),
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state: verifier,
+    access_type: "offline",
+    prompt: "consent",
+  });
+  return `${AUTH_URL}?${params.toString()}`;
+}
+
+function parseCallbackInput(
+  input: string,
+  expectedState: string,
+): { code: string; state: string } | { error: string } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { error: "No input provided" };
+  }
+
+  try {
+    const url = new URL(trimmed);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state") ?? expectedState;
+    if (!code) {
+      return { error: "Missing 'code' parameter in URL" };
+    }
+    if (!state) {
+      return { error: "Missing 'state' parameter. Paste the full URL." };
+    }
+    return { code, state };
+  } catch {
+    if (!expectedState) {
+      return { error: "Paste the full redirect URL, not just the code." };
+    }
+    return { code: trimmed, state: expectedState };
+  }
+}
+
+async function waitForLocalCallback(params: {
+  expectedState: string;
+  timeoutMs: number;
+  onProgress?: (message: string) => void;
+}): Promise<{ code: string; state: string }> {
+  const port = 8085;
+  const hostname = "localhost";
+  const expectedPath = "/oauth2callback";
+
+  return new Promise<{ code: string; state: string }>((resolve, reject) => {
+    let timeout: NodeJS.Timeout | null = null;
+    const server = createServer((req, res) => {
+      try {
+        const requestUrl = new URL(req.url ?? "/", `http://${hostname}:${port}`);
+        if (requestUrl.pathname !== expectedPath) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "text/plain");
+          res.end("Not found");
+          return;
+        }
+
+        const error = requestUrl.searchParams.get("error");
+        const code = requestUrl.searchParams.get("code")?.trim();
+        const state = requestUrl.searchParams.get("state")?.trim();
+
+        if (error) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "text/plain");
+          res.end(`Authentication failed: ${error}`);
+          finish(new Error(`OAuth error: ${error}`));
+          return;
+        }
+
+        if (!code || !state) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "text/plain");
+          res.end("Missing code or state");
+          finish(new Error("Missing OAuth code or state"));
+          return;
+        }
+
+        if (state !== params.expectedState) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "text/plain");
+          res.end("Invalid state");
+          finish(new Error("OAuth state mismatch"));
+          return;
+        }
+
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(
+          "<!doctype html><html><head><meta charset='utf-8'/></head>" +
+            "<body><h2>Gemini CLI OAuth complete</h2>" +
+            "<p>You can close this window and return to OpenClaw.</p></body></html>",
+        );
+
+        finish(undefined, { code, state });
+      } catch (err) {
+        finish(err instanceof Error ? err : new Error("OAuth callback failed"));
+      }
+    });
+
+    const finish = (err?: Error, result?: { code: string; state: string }) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      try {
+        server.close();
+      } catch {
+        // ignore close errors
+      }
+      if (err) {
+        reject(err);
+      } else if (result) {
+        resolve(result);
+      }
+    };
+
+    server.once("error", (err) => {
+      finish(err instanceof Error ? err : new Error("OAuth callback server error"));
+    });
+
+    server.listen(port, hostname, () => {
+      params.onProgress?.(`Waiting for OAuth callback on ${REDIRECT_URI}…`);
+    });
+
+    timeout = setTimeout(() => {
+      finish(new Error("OAuth callback timeout"));
+    }, params.timeoutMs);
+  });
+}
+
+async function exchangeCodeForTokens(
+  code: string,
+  verifier: string,
+): Promise<GeminiCliOAuthCredentials> {
+  const { clientId, clientSecret } = resolveOAuthClientConfig();
+  const body = new URLSearchParams({
+    client_id: clientId,
+    code,
+    grant_type: "authorization_code",
+    redirect_uri: REDIRECT_URI,
+    code_verifier: verifier,
+  });
+  if (clientSecret) {
+    body.set("client_secret", clientSecret);
+  }
+
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token exchange failed: ${errorText}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  };
+
+  if (!data.refresh_token) {
+    throw new Error("No refresh token received. Please try again.");
+  }
+
+  const email = await getUserEmail(data.access_token);
+  const projectId = await discoverProject(data.access_token);
+  const expiresAt = Date.now() + data.expires_in * 1000 - 5 * 60 * 1000;
+
+  return {
+    refresh: data.refresh_token,
+    access: data.access_token,
+    expires: expiresAt,
+    projectId,
+    email,
+  };
+}
+
+async function getUserEmail(accessToken: string): Promise<string | undefined> {
+  try {
+    const response = await fetch(USERINFO_URL, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (response.ok) {
+      const data = (await response.json()) as { email?: string };
+      return data.email;
+    }
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+async function discoverProject(accessToken: string): Promise<string> {
+  const envProject = process.env.GOOGLE_CLOUD_PROJECT || process.env.GOOGLE_CLOUD_PROJECT_ID;
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "gl-node/openclaw",
+  };
+
+  const loadBody = {
+    cloudaicompanionProject: envProject,
+    metadata: {
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+      duetProject: envProject,
+    },
+  };
+
+  let data: {
+    currentTier?: { id?: string };
+    cloudaicompanionProject?: string | { id?: string };
+    allowedTiers?: Array<{ id?: string; isDefault?: boolean }>;
+  } = {};
+
+  try {
+    const response = await fetch(`${CODE_ASSIST_ENDPOINT}/v1internal:loadCodeAssist`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(loadBody),
+    });
+
+    if (!response.ok) {
+      const errorPayload = await response.json().catch(() => null);
+      if (isVpcScAffected(errorPayload)) {
+        data = { currentTier: { id: TIER_STANDARD } };
+      } else {
+        throw new Error(`loadCodeAssist failed: ${response.status} ${response.statusText}`);
+      }
+    } else {
+      data = (await response.json()) as typeof data;
+    }
+  } catch (err) {
+    if (err instanceof Error) {
+      throw err;
+    }
+    throw new Error("loadCodeAssist failed", { cause: err });
+  }
+
+  if (data.currentTier) {
+    const project = data.cloudaicompanionProject;
+    if (typeof project === "string" && project) {
+      return project;
+    }
+    if (typeof project === "object" && project?.id) {
+      return project.id;
+    }
+    if (envProject) {
+      return envProject;
+    }
+    throw new Error(
+      "This account requires GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID to be set.",
+    );
+  }
+
+  const tier = getDefaultTier(data.allowedTiers);
+  const tierId = tier?.id || TIER_FREE;
+  if (tierId !== TIER_FREE && !envProject) {
+    throw new Error(
+      "This account requires GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID to be set.",
+    );
+  }
+
+  const onboardBody: Record<string, unknown> = {
+    tierId,
+    metadata: {
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    },
+  };
+  if (tierId !== TIER_FREE && envProject) {
+    onboardBody.cloudaicompanionProject = envProject;
+    (onboardBody.metadata as Record<string, unknown>).duetProject = envProject;
+  }
+
+  const onboardResponse = await fetch(`${CODE_ASSIST_ENDPOINT}/v1internal:onboardUser`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(onboardBody),
+  });
+
+  if (!onboardResponse.ok) {
+    throw new Error(`onboardUser failed: ${onboardResponse.status} ${onboardResponse.statusText}`);
+  }
+
+  let lro = (await onboardResponse.json()) as {
+    done?: boolean;
+    name?: string;
+    response?: { cloudaicompanionProject?: { id?: string } };
+  };
+
+  if (!lro.done && lro.name) {
+    lro = await pollOperation(lro.name, headers);
+  }
+
+  const projectId = lro.response?.cloudaicompanionProject?.id;
+  if (projectId) {
+    return projectId;
+  }
+  if (envProject) {
+    return envProject;
+  }
+
+  throw new Error(
+    "Could not discover or provision a Google Cloud project. Set GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID.",
+  );
+}
+
+function isVpcScAffected(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+  const error = (payload as { error?: unknown }).error;
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const details = (error as { details?: unknown[] }).details;
+  if (!Array.isArray(details)) {
+    return false;
+  }
+  return details.some(
+    (item) =>
+      typeof item === "object" &&
+      item &&
+      (item as { reason?: string }).reason === "SECURITY_POLICY_VIOLATED",
+  );
+}
+
+function getDefaultTier(
+  allowedTiers?: Array<{ id?: string; isDefault?: boolean }>,
+): { id?: string } | undefined {
+  if (!allowedTiers?.length) {
+    return { id: TIER_LEGACY };
+  }
+  return allowedTiers.find((tier) => tier.isDefault) ?? { id: TIER_LEGACY };
+}
+
+async function pollOperation(
+  operationName: string,
+  headers: Record<string, string>,
+): Promise<{ done?: boolean; response?: { cloudaicompanionProject?: { id?: string } } }> {
+  for (let attempt = 0; attempt < 24; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+    const response = await fetch(`${CODE_ASSIST_ENDPOINT}/v1internal/${operationName}`, {
+      headers,
+    });
+    if (!response.ok) {
+      continue;
+    }
+    const data = (await response.json()) as {
+      done?: boolean;
+      response?: { cloudaicompanionProject?: { id?: string } };
+    };
+    if (data.done) {
+      return data;
+    }
+  }
+  throw new Error("Operation polling timeout");
+}
+
+export async function loginGeminiCliOAuth(
+  ctx: GeminiCliOAuthContext,
+): Promise<GeminiCliOAuthCredentials> {
+  const needsManual = shouldUseManualOAuthFlow(ctx.isRemote);
+  await ctx.note(
+    needsManual
+      ? [
+          "You are running in a remote/VPS environment.",
+          "A URL will be shown for you to open in your LOCAL browser.",
+          "After signing in, copy the redirect URL and paste it back here.",
+        ].join("\n")
+      : [
+          "Browser will open for Google authentication.",
+          "Sign in with your Google account for Gemini CLI access.",
+          "The callback will be captured automatically on localhost:8085.",
+        ].join("\n"),
+    "Gemini CLI OAuth",
+  );
+
+  const { verifier, challenge } = generatePkce();
+  const authUrl = buildAuthUrl(challenge, verifier);
+
+  if (needsManual) {
+    ctx.progress.update("OAuth URL ready");
+    ctx.log(`\nOpen this URL in your LOCAL browser:\n\n${authUrl}\n`);
+    ctx.progress.update("Waiting for you to paste the callback URL...");
+    const callbackInput = await ctx.prompt("Paste the redirect URL here: ");
+    const parsed = parseCallbackInput(callbackInput, verifier);
+    if ("error" in parsed) {
+      throw new Error(parsed.error);
+    }
+    if (parsed.state !== verifier) {
+      throw new Error("OAuth state mismatch - please try again");
+    }
+    ctx.progress.update("Exchanging authorization code for tokens...");
+    return exchangeCodeForTokens(parsed.code, verifier);
+  }
+
+  ctx.progress.update("Complete sign-in in browser...");
+  try {
+    await ctx.openUrl(authUrl);
+  } catch {
+    ctx.log(`\nOpen this URL in your browser:\n\n${authUrl}\n`);
+  }
+
+  try {
+    const { code } = await waitForLocalCallback({
+      expectedState: verifier,
+      timeoutMs: 5 * 60 * 1000,
+      onProgress: (msg) => ctx.progress.update(msg),
+    });
+    ctx.progress.update("Exchanging authorization code for tokens...");
+    return await exchangeCodeForTokens(code, verifier);
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      (err.message.includes("EADDRINUSE") ||
+        err.message.includes("port") ||
+        err.message.includes("listen"))
+    ) {
+      ctx.progress.update("Local callback server failed. Switching to manual mode...");
+      ctx.log(`\nOpen this URL in your LOCAL browser:\n\n${authUrl}\n`);
+      const callbackInput = await ctx.prompt("Paste the redirect URL here: ");
+      const parsed = parseCallbackInput(callbackInput, verifier);
+      if ("error" in parsed) {
+        throw new Error(parsed.error, { cause: err });
+      }
+      if (parsed.state !== verifier) {
+        throw new Error("OAuth state mismatch - please try again", { cause: err });
+      }
+      ctx.progress.update("Exchanging authorization code for tokens...");
+      return exchangeCodeForTokens(parsed.code, verifier);
+    }
+    throw err;
+  }
+}

extensions/google-gemini-cli-auth/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "google-gemini-cli-auth",
+  "providers": ["google-gemini-cli"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/google-gemini-cli-auth/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@openclaw/google-gemini-cli-auth",
+  "version": "2026.1.30",
+  "description": "OpenClaw Gemini CLI OAuth provider plugin",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/googlechat/index.ts

@@ -0,0 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { googlechatDock, googlechatPlugin } from "./src/channel.js";
+import { handleGoogleChatWebhookRequest } from "./src/monitor.js";
+import { setGoogleChatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "googlechat",
+  name: "Google Chat",
+  description: "OpenClaw Google Chat channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setGoogleChatRuntime(api.runtime);
+    api.registerChannel({ plugin: googlechatPlugin, dock: googlechatDock });
+    api.registerHttpHandler(handleGoogleChatWebhookRequest);
+  },
+};
+
+export default plugin;