Add ez-assistant and kerberos service folders

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docker-compose/ez-assistant/extensions/copilot-proxy/README.md

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

docker-compose/ez-assistant/extensions/copilot-proxy/clawdbot.plugin.json

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

docker-compose/ez-assistant/extensions/copilot-proxy/index.ts

@@ -0,0 +1,142 @@
+import { emptyPluginConfigSchema } from "clawdbot/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;

docker-compose/ez-assistant/extensions/copilot-proxy/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/copilot-proxy",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Copilot Proxy provider plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

docker-compose/ez-assistant/extensions/diagnostics-otel/clawdbot.plugin.json

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

docker-compose/ez-assistant/extensions/diagnostics-otel/index.ts

@@ -0,0 +1,16 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/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: MoltbotPluginApi) {
+    api.registerService(createDiagnosticsOtelService());
+  },
+};
+
+export default plugin;

docker-compose/ez-assistant/extensions/diagnostics-otel/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@moltbot/diagnostics-otel",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot diagnostics OpenTelemetry exporter",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "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"
+  }
+}

docker-compose/ez-assistant/extensions/diagnostics-otel/src/service.test.ts

@@ -0,0 +1,220 @@
+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("clawdbot/plugin-sdk", async () => {
+  const actual = await vi.importActual<typeof import("clawdbot/plugin-sdk")>("clawdbot/plugin-sdk");
+  return {
+    ...actual,
+    registerLogTransport: registerLogTransportMock,
+  };
+});
+
+import { createDiagnosticsOtelService } from "./service.js";
+import { emitDiagnosticEvent } from "clawdbot/plugin-sdk";
+
+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("moltbot.webhook.received")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("moltbot.webhook.duration_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("moltbot.message.queued")?.add).toHaveBeenCalled();
+    expect(telemetryState.counters.get("moltbot.message.processed")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("moltbot.message.duration_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("moltbot.queue.wait_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("moltbot.session.stuck")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("moltbot.session.stuck_age_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("moltbot.run.attempt")?.add).toHaveBeenCalled();
+
+    const spanNames = telemetryState.tracer.startSpan.mock.calls.map((call) => call[0]);
+    expect(spanNames).toContain("moltbot.webhook.processed");
+    expect(spanNames).toContain("moltbot.message.processed");
+    expect(spanNames).toContain("moltbot.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?.();
+  });
+});

docker-compose/ez-assistant/extensions/diagnostics-otel/src/service.ts

@@ -0,0 +1,566 @@
+import { metrics, trace, SpanStatusCode } from "@opentelemetry/api";
+import type { SeverityNumber } from "@opentelemetry/api-logs";
+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 type { MoltbotPluginService, DiagnosticEventPayload } from "clawdbot/plugin-sdk";
+import { onDiagnosticEvent, registerLogTransport } from "clawdbot/plugin-sdk";
+
+const DEFAULT_SERVICE_NAME = "moltbot";
+
+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(): MoltbotPluginService {
+  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),
+                }),
+              }
+            : {}),
+        });
+
+        await 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("moltbot");
+      const tracer = trace.getTracer("moltbot");
+
+      const tokensCounter = meter.createCounter("moltbot.tokens", {
+        unit: "1",
+        description: "Token usage by type",
+      });
+      const costCounter = meter.createCounter("moltbot.cost.usd", {
+        unit: "1",
+        description: "Estimated model cost (USD)",
+      });
+      const durationHistogram = meter.createHistogram("moltbot.run.duration_ms", {
+        unit: "ms",
+        description: "Agent run duration",
+      });
+      const contextHistogram = meter.createHistogram("moltbot.context.tokens", {
+        unit: "1",
+        description: "Context window size and usage",
+      });
+      const webhookReceivedCounter = meter.createCounter("moltbot.webhook.received", {
+        unit: "1",
+        description: "Webhook requests received",
+      });
+      const webhookErrorCounter = meter.createCounter("moltbot.webhook.error", {
+        unit: "1",
+        description: "Webhook processing errors",
+      });
+      const webhookDurationHistogram = meter.createHistogram("moltbot.webhook.duration_ms", {
+        unit: "ms",
+        description: "Webhook processing duration",
+      });
+      const messageQueuedCounter = meter.createCounter("moltbot.message.queued", {
+        unit: "1",
+        description: "Messages queued for processing",
+      });
+      const messageProcessedCounter = meter.createCounter("moltbot.message.processed", {
+        unit: "1",
+        description: "Messages processed by outcome",
+      });
+      const messageDurationHistogram = meter.createHistogram("moltbot.message.duration_ms", {
+        unit: "ms",
+        description: "Message processing duration",
+      });
+      const queueDepthHistogram = meter.createHistogram("moltbot.queue.depth", {
+        unit: "1",
+        description: "Queue depth on enqueue/dequeue",
+      });
+      const queueWaitHistogram = meter.createHistogram("moltbot.queue.wait_ms", {
+        unit: "ms",
+        description: "Queue wait time before execution",
+      });
+      const laneEnqueueCounter = meter.createCounter("moltbot.queue.lane.enqueue", {
+        unit: "1",
+        description: "Command queue lane enqueue events",
+      });
+      const laneDequeueCounter = meter.createCounter("moltbot.queue.lane.dequeue", {
+        unit: "1",
+        description: "Command queue lane dequeue events",
+      });
+      const sessionStateCounter = meter.createCounter("moltbot.session.state", {
+        unit: "1",
+        description: "Session state transitions",
+      });
+      const sessionStuckCounter = meter.createCounter("moltbot.session.stuck", {
+        unit: "1",
+        description: "Sessions stuck in processing",
+      });
+      const sessionStuckAgeHistogram = meter.createHistogram("moltbot.session.stuck_age_ms", {
+        unit: "ms",
+        description: "Age of stuck sessions",
+      });
+      const runAttemptCounter = meter.createCounter("moltbot.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("moltbot");
+
+        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))
+            .sort((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> = {
+            "moltbot.log.level": logLevelName,
+          };
+          if (meta?.name) attributes["moltbot.logger"] = meta.name;
+          if (meta?.parentNames?.length) {
+            attributes["moltbot.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[`moltbot.${key}`] = value;
+              } else if (value != null) {
+                attributes[`moltbot.${key}`] = safeStringify(value);
+              }
+            }
+          }
+          if (numericArgs.length > 0) {
+            attributes["moltbot.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["moltbot.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 = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.provider": evt.provider ?? "unknown",
+          "moltbot.model": evt.model ?? "unknown",
+        };
+
+        const usage = evt.usage;
+        if (usage.input) tokensCounter.add(usage.input, { ...attrs, "moltbot.token": "input" });
+        if (usage.output) tokensCounter.add(usage.output, { ...attrs, "moltbot.token": "output" });
+        if (usage.cacheRead)
+          tokensCounter.add(usage.cacheRead, { ...attrs, "moltbot.token": "cache_read" });
+        if (usage.cacheWrite)
+          tokensCounter.add(usage.cacheWrite, { ...attrs, "moltbot.token": "cache_write" });
+        if (usage.promptTokens)
+          tokensCounter.add(usage.promptTokens, { ...attrs, "moltbot.token": "prompt" });
+        if (usage.total) tokensCounter.add(usage.total, { ...attrs, "moltbot.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,
+            "moltbot.context": "limit",
+          });
+        if (evt.context?.used)
+          contextHistogram.record(evt.context.used, {
+            ...attrs,
+            "moltbot.context": "used",
+          });
+
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "moltbot.sessionKey": evt.sessionKey ?? "",
+          "moltbot.sessionId": evt.sessionId ?? "",
+          "moltbot.tokens.input": usage.input ?? 0,
+          "moltbot.tokens.output": usage.output ?? 0,
+          "moltbot.tokens.cache_read": usage.cacheRead ?? 0,
+          "moltbot.tokens.cache_write": usage.cacheWrite ?? 0,
+          "moltbot.tokens.total": usage.total ?? 0,
+        };
+
+        const span = spanWithDuration("moltbot.model.usage", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookReceived = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.received" }>,
+      ) => {
+        const attrs = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.webhook": evt.updateType ?? "unknown",
+        };
+        webhookReceivedCounter.add(1, attrs);
+      };
+
+      const recordWebhookProcessed = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.processed" }>,
+      ) => {
+        const attrs = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.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["moltbot.chatId"] = String(evt.chatId);
+        const span = spanWithDuration("moltbot.webhook.processed", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookError = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.error" }>,
+      ) => {
+        const attrs = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.webhook": evt.updateType ?? "unknown",
+        };
+        webhookErrorCounter.add(1, attrs);
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "moltbot.error": evt.error,
+        };
+        if (evt.chatId !== undefined) spanAttrs["moltbot.chatId"] = String(evt.chatId);
+        const span = tracer.startSpan("moltbot.webhook.error", {
+          attributes: spanAttrs,
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: evt.error });
+        span.end();
+      };
+
+      const recordMessageQueued = (
+        evt: Extract<DiagnosticEventPayload, { type: "message.queued" }>,
+      ) => {
+        const attrs = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.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 = {
+          "moltbot.channel": evt.channel ?? "unknown",
+          "moltbot.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["moltbot.sessionKey"] = evt.sessionKey;
+        if (evt.sessionId) spanAttrs["moltbot.sessionId"] = evt.sessionId;
+        if (evt.chatId !== undefined) spanAttrs["moltbot.chatId"] = String(evt.chatId);
+        if (evt.messageId !== undefined) spanAttrs["moltbot.messageId"] = String(evt.messageId);
+        if (evt.reason) spanAttrs["moltbot.reason"] = evt.reason;
+        const span = spanWithDuration("moltbot.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 = { "moltbot.lane": evt.lane };
+        laneEnqueueCounter.add(1, attrs);
+        queueDepthHistogram.record(evt.queueSize, attrs);
+      };
+
+      const recordLaneDequeue = (
+        evt: Extract<DiagnosticEventPayload, { type: "queue.lane.dequeue" }>,
+      ) => {
+        const attrs = { "moltbot.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> = { "moltbot.state": evt.state };
+        if (evt.reason) attrs["moltbot.reason"] = evt.reason;
+        sessionStateCounter.add(1, attrs);
+      };
+
+      const recordSessionStuck = (
+        evt: Extract<DiagnosticEventPayload, { type: "session.stuck" }>,
+      ) => {
+        const attrs: Record<string, string> = { "moltbot.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["moltbot.sessionKey"] = evt.sessionKey;
+        if (evt.sessionId) spanAttrs["moltbot.sessionId"] = evt.sessionId;
+        spanAttrs["moltbot.queueDepth"] = evt.queueDepth ?? 0;
+        spanAttrs["moltbot.ageMs"] = evt.ageMs;
+        const span = tracer.startSpan("moltbot.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, { "moltbot.attempt": evt.attempt });
+      };
+
+      const recordHeartbeat = (
+        evt: Extract<DiagnosticEventPayload, { type: "diagnostic.heartbeat" }>,
+      ) => {
+        queueDepthHistogram.record(evt.queued, { "moltbot.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 MoltbotPluginService;
+}

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

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

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

@@ -0,0 +1,18 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/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: MoltbotPluginApi) {
+    setDiscordRuntime(api.runtime);
+    api.registerChannel({ plugin: discordPlugin });
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/discord",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Discord channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

docker-compose/ez-assistant/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 "clawdbot/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,
+      });
+    },
+  },
+};

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

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

docker-compose/ez-assistant/extensions/google-antigravity-auth/README.md

@@ -0,0 +1,24 @@
+# Google Antigravity Auth (Clawdbot plugin)
+
+OAuth provider plugin for **Google Antigravity** (Cloud Code Assist).
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```bash
+clawdbot plugins enable google-antigravity-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+clawdbot 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.

docker-compose/ez-assistant/extensions/google-antigravity-auth/clawdbot.plugin.json

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

docker-compose/ez-assistant/extensions/google-antigravity-auth/index.ts

@@ -0,0 +1,437 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { emptyPluginConfigSchema } from "clawdbot/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>Moltbot 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;

docker-compose/ez-assistant/extensions/google-antigravity-auth/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/google-antigravity-auth",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Google Antigravity OAuth provider plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/README.md

@@ -0,0 +1,35 @@
+# Google Gemini CLI Auth (Clawdbot plugin)
+
+OAuth provider plugin for **Gemini CLI** (Google Code Assist).
+
+## Enable
+
+Bundled plugins are disabled by default. Enable this one:
+
+```bash
+clawdbot plugins enable google-gemini-cli-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+clawdbot 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:
+
+- `CLAWDBOT_GEMINI_OAUTH_CLIENT_ID` / `GEMINI_CLI_OAUTH_CLIENT_ID`
+- `CLAWDBOT_GEMINI_OAUTH_CLIENT_SECRET` / `GEMINI_CLI_OAUTH_CLIENT_SECRET`

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/clawdbot.plugin.json

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

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/index.ts

@@ -0,0 +1,91 @@
+import { emptyPluginConfigSchema } from "clawdbot/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 = [
+  "CLAWDBOT_GEMINI_OAUTH_CLIENT_ID",
+  "CLAWDBOT_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;

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/oauth.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { join, parse } from "node:path";
+
+// 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);
+  });
+});

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/oauth.ts

@@ -0,0 +1,580 @@
+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 = ["CLAWDBOT_GEMINI_OAUTH_CLIENT_ID", "GEMINI_CLI_OAUTH_CLIENT_ID"];
+const CLIENT_SECRET_KEYS = [
+  "CLAWDBOT_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 Moltbot.</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/moltbot",
+  };
+
+  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");
+  }
+
+  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);
+      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);
+    }
+    throw err;
+  }
+}

docker-compose/ez-assistant/extensions/google-gemini-cli-auth/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/google-gemini-cli-auth",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Gemini CLI OAuth provider plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

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

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

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

@@ -0,0 +1,20 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/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: "Moltbot Google Chat channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: MoltbotPluginApi) {
+    setGoogleChatRuntime(api.runtime);
+    api.registerChannel({ plugin: googlechatPlugin, dock: googlechatDock });
+    api.registerHttpHandler(handleGoogleChatWebhookRequest);
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,39 @@
+{
+  "name": "@moltbot/googlechat",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Google Chat channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "googlechat",
+      "label": "Google Chat",
+      "selectionLabel": "Google Chat (Chat API)",
+      "detailLabel": "Google Chat",
+      "docsPath": "/channels/googlechat",
+      "docsLabel": "googlechat",
+      "blurb": "Google Workspace Chat app via HTTP webhooks.",
+      "aliases": [
+        "gchat",
+        "google-chat"
+      ],
+      "order": 55
+    },
+    "install": {
+      "npmSpec": "@moltbot/googlechat",
+      "localPath": "extensions/googlechat",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "google-auth-library": "^10.5.0"
+  },
+  "devDependencies": {
+    "moltbot": "workspace:*"
+  },
+  "peerDependencies": {
+    "moltbot": ">=2026.1.26"
+  }
+}

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

@@ -0,0 +1,133 @@
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import type { GoogleChatAccountConfig, GoogleChatConfig } from "./types.config.js";
+
+export type GoogleChatCredentialSource = "file" | "inline" | "env" | "none";
+
+export type ResolvedGoogleChatAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  config: GoogleChatAccountConfig;
+  credentialSource: GoogleChatCredentialSource;
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+};
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+
+function listConfiguredAccountIds(cfg: MoltbotConfig): string[] {
+  const accounts = (cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listGoogleChatAccountIds(cfg: MoltbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultGoogleChatAccountId(cfg: MoltbotConfig): string {
+  const channel = cfg.channels?.["googlechat"] as GoogleChatConfig | undefined;
+  if (channel?.defaultAccount?.trim()) return channel.defaultAccount.trim();
+  const ids = listGoogleChatAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: MoltbotConfig,
+  accountId: string,
+): GoogleChatAccountConfig | undefined {
+  const accounts = (cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as GoogleChatAccountConfig | undefined;
+}
+
+function mergeGoogleChatAccountConfig(
+  cfg: MoltbotConfig,
+  accountId: string,
+): GoogleChatAccountConfig {
+  const raw = (cfg.channels?.["googlechat"] ?? {}) as GoogleChatConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account } as GoogleChatAccountConfig;
+}
+
+function parseServiceAccount(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object") return value as Record<string, unknown>;
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCredentialsFromConfig(params: {
+  accountId: string;
+  account: GoogleChatAccountConfig;
+}): {
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+  source: GoogleChatCredentialSource;
+} {
+  const { account, accountId } = params;
+  const inline = parseServiceAccount(account.serviceAccount);
+  if (inline) {
+    return { credentials: inline, source: "inline" };
+  }
+
+  const file = account.serviceAccountFile?.trim();
+  if (file) {
+    return { credentialsFile: file, source: "file" };
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envJson = process.env[ENV_SERVICE_ACCOUNT];
+    const envInline = parseServiceAccount(envJson);
+    if (envInline) {
+      return { credentials: envInline, source: "env" };
+    }
+    const envFile = process.env[ENV_SERVICE_ACCOUNT_FILE]?.trim();
+    if (envFile) {
+      return { credentialsFile: envFile, source: "env" };
+    }
+  }
+
+  return { source: "none" };
+}
+
+export function resolveGoogleChatAccount(params: {
+  cfg: MoltbotConfig;
+  accountId?: string | null;
+}): ResolvedGoogleChatAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled =
+    (params.cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.enabled !== false;
+  const merged = mergeGoogleChatAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const credentials = resolveCredentialsFromConfig({ accountId, account: merged });
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    config: merged,
+    credentialSource: credentials.source,
+    credentials: credentials.credentials,
+    credentialsFile: credentials.credentialsFile,
+  };
+}
+
+export function listEnabledGoogleChatAccounts(cfg: MoltbotConfig): ResolvedGoogleChatAccount[] {
+  return listGoogleChatAccountIds(cfg)
+    .map((accountId) => resolveGoogleChatAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

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

@@ -0,0 +1,162 @@
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  MoltbotConfig,
+} from "clawdbot/plugin-sdk";
+import {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "clawdbot/plugin-sdk";
+
+import { listEnabledGoogleChatAccounts, resolveGoogleChatAccount } from "./accounts.js";
+import {
+  createGoogleChatReaction,
+  deleteGoogleChatReaction,
+  listGoogleChatReactions,
+  sendGoogleChatMessage,
+  uploadGoogleChatAttachment,
+} from "./api.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import { resolveGoogleChatOutboundSpace } from "./targets.js";
+
+const providerId = "googlechat";
+
+function listEnabledAccounts(cfg: MoltbotConfig) {
+  return listEnabledGoogleChatAccounts(cfg).filter(
+    (account) => account.enabled && account.credentialSource !== "none",
+  );
+}
+
+function isReactionsEnabled(accounts: ReturnType<typeof listEnabledAccounts>, cfg: MoltbotConfig) {
+  for (const account of accounts) {
+    const gate = createActionGate(
+      (account.config.actions ?? (cfg.channels?.["googlechat"] as { actions?: unknown })?.actions) as Record<
+        string,
+        boolean | undefined
+      >,
+    );
+    if (gate("reactions")) return true;
+  }
+  return false;
+}
+
+function resolveAppUserNames(account: { config: { botUser?: string | null } }) {
+  return new Set(["users/app", account.config.botUser?.trim()].filter(Boolean) as string[]);
+}
+
+export const googlechatMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const accounts = listEnabledAccounts(cfg as MoltbotConfig);
+    if (accounts.length === 0) return [];
+    const actions = new Set<ChannelMessageActionName>([]);
+    actions.add("send");
+    if (isReactionsEnabled(accounts, cfg as MoltbotConfig)) {
+      actions.add("react");
+      actions.add("reactions");
+    }
+    return Array.from(actions);
+  },
+  extractToolSend: ({ args }) => {
+    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 }) => {
+    const account = resolveGoogleChatAccount({
+      cfg: cfg as MoltbotConfig,
+      accountId,
+    });
+    if (account.credentialSource === "none") {
+      throw new Error("Google Chat credentials are missing.");
+    }
+
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+      const threadId = readStringParam(params, "threadId") ?? readStringParam(params, "replyTo");
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+
+      if (mediaUrl) {
+        const core = getGoogleChatRuntime();
+        const maxBytes = (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+        const loaded = await core.channel.media.fetchRemoteMedia(mediaUrl, { maxBytes });
+        const upload = await uploadGoogleChatAttachment({
+          account,
+          space,
+          filename: loaded.filename ?? "attachment",
+          buffer: loaded.buffer,
+          contentType: loaded.contentType,
+        });
+        await sendGoogleChatMessage({
+          account,
+          space,
+          text: content,
+          thread: threadId ?? undefined,
+          attachments: upload.attachmentUploadToken
+            ? [{ attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename }]
+            : undefined,
+        });
+        return jsonResult({ ok: true, to: space });
+      }
+
+      await sendGoogleChatMessage({
+        account,
+        space,
+        text: content,
+        thread: threadId ?? undefined,
+      });
+      return jsonResult({ ok: true, to: space });
+    }
+
+    if (action === "react") {
+      const messageName = readStringParam(params, "messageId", { required: true });
+      const { emoji, remove, isEmpty } = readReactionParams(params, {
+        removeErrorMessage: "Emoji is required to remove a Google Chat reaction.",
+      });
+      if (remove || isEmpty) {
+        const reactions = await listGoogleChatReactions({ account, messageName });
+        const appUsers = resolveAppUserNames(account);
+        const toRemove = reactions.filter((reaction) => {
+          const userName = reaction.user?.name?.trim();
+          if (appUsers.size > 0 && !appUsers.has(userName ?? "")) return false;
+          if (emoji) return reaction.emoji?.unicode === emoji;
+          return true;
+        });
+        for (const reaction of toRemove) {
+          if (!reaction.name) continue;
+          await deleteGoogleChatReaction({ account, reactionName: reaction.name });
+        }
+        return jsonResult({ ok: true, removed: toRemove.length });
+      }
+      const reaction = await createGoogleChatReaction({
+        account,
+        messageName,
+        emoji,
+      });
+      return jsonResult({ ok: true, reaction });
+    }
+
+    if (action === "reactions") {
+      const messageName = readStringParam(params, "messageId", { required: true });
+      const limit = readNumberParam(params, "limit", { integer: true });
+      const reactions = await listGoogleChatReactions({
+        account,
+        messageName,
+        limit: limit ?? undefined,
+      });
+      return jsonResult({ ok: true, reactions });
+    }
+
+    throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+  },
+};

docker-compose/ez-assistant/extensions/googlechat/src/api.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { downloadGoogleChatMedia } from "./api.js";
+
+vi.mock("./auth.js", () => ({
+  getGoogleChatAccessToken: vi.fn().mockResolvedValue("token"),
+}));
+
+const account = {
+  accountId: "default",
+  enabled: true,
+  credentialSource: "inline",
+  config: {},
+} as ResolvedGoogleChatAccount;
+
+describe("downloadGoogleChatMedia", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("rejects when content-length exceeds max bytes", async () => {
+    const body = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+        controller.close();
+      },
+    });
+    const response = new Response(body, {
+      status: 200,
+      headers: { "content-length": "50", "content-type": "application/octet-stream" },
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response));
+
+    await expect(
+      downloadGoogleChatMedia({ account, resourceName: "media/123", maxBytes: 10 }),
+    ).rejects.toThrow(/max bytes/i);
+  });
+
+  it("rejects when streamed payload exceeds max bytes", async () => {
+    const chunks = [new Uint8Array(6), new Uint8Array(6)];
+    let index = 0;
+    const body = new ReadableStream({
+      pull(controller) {
+        if (index < chunks.length) {
+          controller.enqueue(chunks[index++]);
+        } else {
+          controller.close();
+        }
+      },
+    });
+    const response = new Response(body, {
+      status: 200,
+      headers: { "content-type": "application/octet-stream" },
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response));
+
+    await expect(
+      downloadGoogleChatMedia({ account, resourceName: "media/123", maxBytes: 10 }),
+    ).rejects.toThrow(/max bytes/i);
+  });
+});

docker-compose/ez-assistant/extensions/googlechat/src/api.ts

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { getGoogleChatAccessToken } from "./auth.js";
+import type { GoogleChatReaction } from "./types.js";
+
+const CHAT_API_BASE = "https://chat.googleapis.com/v1";
+const CHAT_UPLOAD_BASE = "https://chat.googleapis.com/upload/v1";
+
+async function fetchJson<T>(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init: RequestInit,
+): Promise<T> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+async function fetchOk(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init: RequestInit,
+): Promise<void> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+}
+
+async function fetchBuffer(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init?: RequestInit,
+  options?: { maxBytes?: number },
+): Promise<{ buffer: Buffer; contentType?: string }> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init?.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+  const maxBytes = options?.maxBytes;
+  const lengthHeader = res.headers.get("content-length");
+  if (maxBytes && lengthHeader) {
+    const length = Number(lengthHeader);
+    if (Number.isFinite(length) && length > maxBytes) {
+      throw new Error(`Google Chat media exceeds max bytes (${maxBytes})`);
+    }
+  }
+  if (!maxBytes || !res.body) {
+    const buffer = Buffer.from(await res.arrayBuffer());
+    const contentType = res.headers.get("content-type") ?? undefined;
+    return { buffer, contentType };
+  }
+  const reader = res.body.getReader();
+  const chunks: Buffer[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.length;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`Google Chat media exceeds max bytes (${maxBytes})`);
+    }
+    chunks.push(Buffer.from(value));
+  }
+  const buffer = Buffer.concat(chunks, total);
+  const contentType = res.headers.get("content-type") ?? undefined;
+  return { buffer, contentType };
+}
+
+export async function sendGoogleChatMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  space: string;
+  text?: string;
+  thread?: string;
+  attachments?: Array<{ attachmentUploadToken: string; contentName?: string }>;
+}): Promise<{ messageName?: string } | null> {
+  const { account, space, text, thread, attachments } = params;
+  const body: Record<string, unknown> = {};
+  if (text) body.text = text;
+  if (thread) body.thread = { name: thread };
+  if (attachments && attachments.length > 0) {
+    body.attachment = attachments.map((item) => ({
+      attachmentDataRef: { attachmentUploadToken: item.attachmentUploadToken },
+      ...(item.contentName ? { contentName: item.contentName } : {}),
+    }));
+  }
+  const url = `${CHAT_API_BASE}/${space}/messages`;
+  const result = await fetchJson<{ name?: string }>(account, url, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return result ? { messageName: result.name } : null;
+}
+
+export async function updateGoogleChatMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+  text: string;
+}): Promise<{ messageName?: string }> {
+  const { account, messageName, text } = params;
+  const url = `${CHAT_API_BASE}/${messageName}?updateMask=text`;
+  const result = await fetchJson<{ name?: string }>(account, url, {
+    method: "PATCH",
+    body: JSON.stringify({ text }),
+  });
+  return { messageName: result.name };
+}
+
+export async function deleteGoogleChatMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+}): Promise<void> {
+  const { account, messageName } = params;
+  const url = `${CHAT_API_BASE}/${messageName}`;
+  await fetchOk(account, url, { method: "DELETE" });
+}
+
+export async function uploadGoogleChatAttachment(params: {
+  account: ResolvedGoogleChatAccount;
+  space: string;
+  filename: string;
+  buffer: Buffer;
+  contentType?: string;
+}): Promise<{ attachmentUploadToken?: string }> {
+  const { account, space, filename, buffer, contentType } = params;
+  const boundary = `moltbot-${crypto.randomUUID()}`;
+  const metadata = JSON.stringify({ filename });
+  const header = `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n`;
+  const mediaHeader = `--${boundary}\r\nContent-Type: ${contentType ?? "application/octet-stream"}\r\n\r\n`;
+  const footer = `\r\n--${boundary}--\r\n`;
+  const body = Buffer.concat([
+    Buffer.from(header, "utf8"),
+    Buffer.from(mediaHeader, "utf8"),
+    buffer,
+    Buffer.from(footer, "utf8"),
+  ]);
+
+  const token = await getGoogleChatAccessToken(account);
+  const url = `${CHAT_UPLOAD_BASE}/${space}/attachments:upload?uploadType=multipart`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": `multipart/related; boundary=${boundary}`,
+    },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat upload ${res.status}: ${text || res.statusText}`);
+  }
+  const payload = (await res.json()) as {
+    attachmentDataRef?: { attachmentUploadToken?: string };
+  };
+  return { attachmentUploadToken: payload.attachmentDataRef?.attachmentUploadToken };
+}
+
+export async function downloadGoogleChatMedia(params: {
+  account: ResolvedGoogleChatAccount;
+  resourceName: string;
+  maxBytes?: number;
+}): Promise<{ buffer: Buffer; contentType?: string }> {
+  const { account, resourceName, maxBytes } = params;
+  const url = `${CHAT_API_BASE}/media/${resourceName}?alt=media`;
+  return await fetchBuffer(account, url, undefined, { maxBytes });
+}
+
+export async function createGoogleChatReaction(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+  emoji: string;
+}): Promise<GoogleChatReaction> {
+  const { account, messageName, emoji } = params;
+  const url = `${CHAT_API_BASE}/${messageName}/reactions`;
+  return await fetchJson<GoogleChatReaction>(account, url, {
+    method: "POST",
+    body: JSON.stringify({ emoji: { unicode: emoji } }),
+  });
+}
+
+export async function listGoogleChatReactions(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+  limit?: number;
+}): Promise<GoogleChatReaction[]> {
+  const { account, messageName, limit } = params;
+  const url = new URL(`${CHAT_API_BASE}/${messageName}/reactions`);
+  if (limit && limit > 0) url.searchParams.set("pageSize", String(limit));
+  const result = await fetchJson<{ reactions?: GoogleChatReaction[] }>(account, url.toString(), {
+    method: "GET",
+  });
+  return result.reactions ?? [];
+}
+
+export async function deleteGoogleChatReaction(params: {
+  account: ResolvedGoogleChatAccount;
+  reactionName: string;
+}): Promise<void> {
+  const { account, reactionName } = params;
+  const url = `${CHAT_API_BASE}/${reactionName}`;
+  await fetchOk(account, url, { method: "DELETE" });
+}
+
+export async function findGoogleChatDirectMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  userName: string;
+}): Promise<{ name?: string; displayName?: string } | null> {
+  const { account, userName } = params;
+  const url = new URL(`${CHAT_API_BASE}/spaces:findDirectMessage`);
+  url.searchParams.set("name", userName);
+  return await fetchJson<{ name?: string; displayName?: string }>(account, url.toString(), {
+    method: "GET",
+  });
+}
+
+export async function probeGoogleChat(account: ResolvedGoogleChatAccount): Promise<{
+  ok: boolean;
+  status?: number;
+  error?: string;
+}> {
+  try {
+    const url = new URL(`${CHAT_API_BASE}/spaces`);
+    url.searchParams.set("pageSize", "1");
+    await fetchJson<Record<string, unknown>>(account, url.toString(), { method: "GET" });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

docker-compose/ez-assistant/extensions/googlechat/src/auth.ts

@@ -0,0 +1,113 @@
+import { GoogleAuth, OAuth2Client } from "google-auth-library";
+
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+
+const CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";
+const CHAT_ISSUER = "chat@system.gserviceaccount.com";
+// Google Workspace Add-ons use a different service account pattern
+const ADDON_ISSUER_PATTERN = /^service-\d+@gcp-sa-gsuiteaddons\.iam\.gserviceaccount\.com$/;
+const CHAT_CERTS_URL =
+  "https://www.googleapis.com/service_accounts/v1/metadata/x509/chat@system.gserviceaccount.com";
+
+const authCache = new Map<string, { key: string; auth: GoogleAuth }>();
+const verifyClient = new OAuth2Client();
+
+let cachedCerts: { fetchedAt: number; certs: Record<string, string> } | null = null;
+
+function buildAuthKey(account: ResolvedGoogleChatAccount): string {
+  if (account.credentialsFile) return `file:${account.credentialsFile}`;
+  if (account.credentials) return `inline:${JSON.stringify(account.credentials)}`;
+  return "none";
+}
+
+function getAuthInstance(account: ResolvedGoogleChatAccount): GoogleAuth {
+  const key = buildAuthKey(account);
+  const cached = authCache.get(account.accountId);
+  if (cached && cached.key === key) return cached.auth;
+
+  if (account.credentialsFile) {
+    const auth = new GoogleAuth({ keyFile: account.credentialsFile, scopes: [CHAT_SCOPE] });
+    authCache.set(account.accountId, { key, auth });
+    return auth;
+  }
+
+  if (account.credentials) {
+    const auth = new GoogleAuth({ credentials: account.credentials, scopes: [CHAT_SCOPE] });
+    authCache.set(account.accountId, { key, auth });
+    return auth;
+  }
+
+  const auth = new GoogleAuth({ scopes: [CHAT_SCOPE] });
+  authCache.set(account.accountId, { key, auth });
+  return auth;
+}
+
+export async function getGoogleChatAccessToken(
+  account: ResolvedGoogleChatAccount,
+): Promise<string> {
+  const auth = getAuthInstance(account);
+  const client = await auth.getClient();
+  const access = await client.getAccessToken();
+  const token = typeof access === "string" ? access : access?.token;
+  if (!token) {
+    throw new Error("Missing Google Chat access token");
+  }
+  return token;
+}
+
+async function fetchChatCerts(): Promise<Record<string, string>> {
+  const now = Date.now();
+  if (cachedCerts && now - cachedCerts.fetchedAt < 10 * 60 * 1000) {
+    return cachedCerts.certs;
+  }
+  const res = await fetch(CHAT_CERTS_URL);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch Chat certs (${res.status})`);
+  }
+  const certs = (await res.json()) as Record<string, string>;
+  cachedCerts = { fetchedAt: now, certs };
+  return certs;
+}
+
+export type GoogleChatAudienceType = "app-url" | "project-number";
+
+export async function verifyGoogleChatRequest(params: {
+  bearer?: string | null;
+  audienceType?: GoogleChatAudienceType | null;
+  audience?: string | null;
+}): Promise<{ ok: boolean; reason?: string }> {
+  const bearer = params.bearer?.trim();
+  if (!bearer) return { ok: false, reason: "missing token" };
+  const audience = params.audience?.trim();
+  if (!audience) return { ok: false, reason: "missing audience" };
+  const audienceType = params.audienceType ?? null;
+
+  if (audienceType === "app-url") {
+    try {
+      const ticket = await verifyClient.verifyIdToken({
+        idToken: bearer,
+        audience,
+      });
+      const payload = ticket.getPayload();
+      const email = payload?.email ?? "";
+      const ok = payload?.email_verified && (email === CHAT_ISSUER || ADDON_ISSUER_PATTERN.test(email));
+      return ok ? { ok: true } : { ok: false, reason: `invalid issuer: ${email}` };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  if (audienceType === "project-number") {
+    try {
+      const certs = await fetchChatCerts();
+      await verifyClient.verifySignedJwtWithCertsAsync(bearer, certs, audience, [CHAT_ISSUER]);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  return { ok: false, reason: "unsupported audience type" };
+}
+
+export const GOOGLE_CHAT_SCOPE = CHAT_SCOPE;

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

@@ -0,0 +1,580 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  migrateBaseNameToDefaultAccount,
+  missingTargetError,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  resolveGoogleChatGroupRequireMention,
+  setAccountEnabledInConfigSection,
+  type ChannelDock,
+  type ChannelMessageActionAdapter,
+  type ChannelPlugin,
+  type MoltbotConfig,
+} from "clawdbot/plugin-sdk";
+import { GoogleChatConfigSchema } from "clawdbot/plugin-sdk";
+
+import {
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+  type ResolvedGoogleChatAccount,
+} from "./accounts.js";
+import { googlechatMessageActions } from "./actions.js";
+import { sendGoogleChatMessage, uploadGoogleChatAttachment, probeGoogleChat } from "./api.js";
+import { googlechatOnboardingAdapter } from "./onboarding.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import { resolveGoogleChatWebhookPath, startGoogleChatMonitor } from "./monitor.js";
+import {
+  isGoogleChatSpaceTarget,
+  isGoogleChatUserTarget,
+  normalizeGoogleChatTarget,
+  resolveGoogleChatOutboundSpace,
+} from "./targets.js";
+
+const meta = getChatChannelMeta("googlechat");
+
+const formatAllowFromEntry = (entry: string) =>
+  entry
+    .trim()
+    .replace(/^(googlechat|google-chat|gchat):/i, "")
+    .replace(/^user:/i, "")
+    .replace(/^users\//i, "")
+    .toLowerCase();
+
+export const googlechatDock: ChannelDock = {
+  id: "googlechat",
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    reactions: true,
+    media: true,
+    threads: true,
+    blockStreaming: true,
+  },
+  outbound: { textChunkLimit: 4000 },
+  config: {
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveGoogleChatAccount({ cfg: cfg as MoltbotConfig, accountId }).config.dm?.allowFrom ??
+        []
+      ).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry))
+        .filter(Boolean)
+        .map(formatAllowFromEntry),
+  },
+  groups: {
+    resolveRequireMention: resolveGoogleChatGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.["googlechat"]?.replyToMode ?? "off",
+    buildToolContext: ({ context, hasRepliedRef }) => {
+      const threadId = context.MessageThreadId ?? context.ReplyToId;
+      return {
+        currentChannelId: context.To?.trim() || undefined,
+        currentThreadTs: threadId != null ? String(threadId) : undefined,
+        hasRepliedRef,
+      };
+    },
+  },
+};
+
+const googlechatActions: ChannelMessageActionAdapter = {
+  listActions: (ctx) => googlechatMessageActions.listActions?.(ctx) ?? [],
+  extractToolSend: (ctx) => googlechatMessageActions.extractToolSend?.(ctx) ?? null,
+  handleAction: async (ctx) => {
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Google Chat actions are not available.");
+    }
+    return await googlechatMessageActions.handleAction(ctx);
+  },
+};
+
+export const googlechatPlugin: ChannelPlugin<ResolvedGoogleChatAccount> = {
+  id: "googlechat",
+  meta: { ...meta },
+  onboarding: googlechatOnboardingAdapter,
+  pairing: {
+    idLabel: "googlechatUserId",
+    normalizeAllowEntry: (entry) => formatAllowFromEntry(entry),
+    notifyApproval: async ({ cfg, id }) => {
+      const account = resolveGoogleChatAccount({ cfg: cfg as MoltbotConfig });
+      if (account.credentialSource === "none") return;
+      const user = normalizeGoogleChatTarget(id) ?? id;
+      const target = isGoogleChatUserTarget(user) ? user : `users/${user}`;
+      const space = await resolveGoogleChatOutboundSpace({ account, target });
+      await sendGoogleChatMessage({
+        account,
+        space,
+        text: PAIRING_APPROVED_MESSAGE,
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.googlechat"] },
+  configSchema: buildChannelConfigSchema(GoogleChatConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listGoogleChatAccountIds(cfg as MoltbotConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveGoogleChatAccount({ cfg: cfg as MoltbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultGoogleChatAccountId(cfg as MoltbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as MoltbotConfig,
+        sectionKey: "googlechat",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as MoltbotConfig,
+        sectionKey: "googlechat",
+        accountId,
+        clearBaseFields: [
+          "serviceAccount",
+          "serviceAccountFile",
+          "audienceType",
+          "audience",
+          "webhookPath",
+          "webhookUrl",
+          "botUser",
+          "name",
+        ],
+      }),
+    isConfigured: (account) => account.credentialSource !== "none",
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.credentialSource !== "none",
+      credentialSource: account.credentialSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveGoogleChatAccount({
+        cfg: cfg as MoltbotConfig,
+        accountId,
+      }).config.dm?.allowFrom ?? []
+      ).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry))
+        .filter(Boolean)
+        .map(formatAllowFromEntry),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(
+        (cfg as MoltbotConfig).channels?.["googlechat"]?.accounts?.[resolvedAccountId],
+      );
+      const allowFromPath = useAccountPath
+        ? `channels.googlechat.accounts.${resolvedAccountId}.dm.`
+        : "channels.googlechat.dm.";
+      return {
+        policy: account.config.dm?.policy ?? "pairing",
+        allowFrom: account.config.dm?.allowFrom ?? [],
+        allowFromPath,
+        approveHint: formatPairingApproveHint("googlechat"),
+        normalizeEntry: (raw) => formatAllowFromEntry(raw),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy === "open") {
+        warnings.push(
+          `- Google Chat spaces: groupPolicy="open" allows any space to trigger (mention-gated). Set channels.googlechat.groupPolicy="allowlist" and configure channels.googlechat.groups.`,
+        );
+      }
+      if (account.config.dm?.policy === "open") {
+        warnings.push(
+          `- Google Chat DMs are open to anyone. Set channels.googlechat.dm.policy="pairing" or "allowlist".`,
+        );
+      }
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveGoogleChatGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.["googlechat"]?.replyToMode ?? "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeGoogleChatTarget,
+    targetResolver: {
+      looksLikeId: (raw, normalized) => {
+        const value = normalized ?? raw.trim();
+        return isGoogleChatSpaceTarget(value) || isGoogleChatUserTarget(value);
+      },
+      hint: "<spaces/{space}|users/{user}>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as MoltbotConfig,
+        accountId,
+      });
+      const q = query?.trim().toLowerCase() || "";
+      const allowFrom = account.config.dm?.allowFrom ?? [];
+      const peers = Array.from(
+        new Set(
+          allowFrom
+            .map((entry) => String(entry).trim())
+            .filter((entry) => Boolean(entry) && entry !== "*")
+            .map((entry) => normalizeGoogleChatTarget(entry) ?? entry),
+        ),
+      )
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "user", id }) as const);
+      return peers;
+    },
+    listGroups: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as MoltbotConfig,
+        accountId,
+      });
+      const groups = account.config.groups ?? {};
+      const q = query?.trim().toLowerCase() || "";
+      const entries = Object.keys(groups)
+        .filter((key) => key && key !== "*")
+        .filter((key) => (q ? key.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "group", id }) as const);
+      return entries;
+    },
+  },
+  resolver: {
+    resolveTargets: async ({ inputs, kind }) => {
+      const resolved = inputs.map((input) => {
+        const normalized = normalizeGoogleChatTarget(input);
+        if (!normalized) {
+          return { input, resolved: false, note: "empty target" };
+        }
+        if (kind === "user" && isGoogleChatUserTarget(normalized)) {
+          return { input, resolved: true, id: normalized };
+        }
+        if (kind === "group" && isGoogleChatSpaceTarget(normalized)) {
+          return { input, resolved: true, id: normalized };
+        }
+        return {
+          input,
+          resolved: false,
+          note: "use spaces/{space} or users/{user}",
+        };
+      });
+      return resolved;
+    },
+  },
+  actions: googlechatActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as MoltbotConfig,
+        channelKey: "googlechat",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "GOOGLE_CHAT_SERVICE_ACCOUNT env vars can only be used for the default account.";
+      }
+      if (!input.useEnv && !input.token && !input.tokenFile) {
+        return "Google Chat requires --token (service account JSON) or --token-file.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as MoltbotConfig,
+        channelKey: "googlechat",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig as MoltbotConfig,
+              channelKey: "googlechat",
+            })
+          : namedConfig;
+      const patch = input.useEnv
+        ? {}
+        : input.tokenFile
+          ? { serviceAccountFile: input.tokenFile }
+          : input.token
+            ? { serviceAccount: input.token }
+            : {};
+      const audienceType = input.audienceType?.trim();
+      const audience = input.audience?.trim();
+      const webhookPath = input.webhookPath?.trim();
+      const webhookUrl = input.webhookUrl?.trim();
+      const configPatch = {
+        ...patch,
+        ...(audienceType ? { audienceType } : {}),
+        ...(audience ? { audience } : {}),
+        ...(webhookPath ? { webhookPath } : {}),
+        ...(webhookUrl ? { webhookUrl } : {}),
+      };
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            "googlechat": {
+              ...(next.channels?.["googlechat"] ?? {}),
+              enabled: true,
+              ...configPatch,
+            },
+          },
+        } as MoltbotConfig;
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          "googlechat": {
+            ...(next.channels?.["googlechat"] ?? {}),
+            enabled: true,
+            accounts: {
+              ...(next.channels?.["googlechat"]?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.["googlechat"]?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                ...configPatch,
+              },
+            },
+          },
+        },
+      } as MoltbotConfig;
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) =>
+      getGoogleChatRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 4000,
+    resolveTarget: ({ to, allowFrom, mode }) => {
+      const trimmed = to?.trim() ?? "";
+      const allowListRaw = (allowFrom ?? []).map((entry) => String(entry).trim()).filter(Boolean);
+      const allowList = allowListRaw
+        .filter((entry) => entry !== "*")
+        .map((entry) => normalizeGoogleChatTarget(entry))
+        .filter((entry): entry is string => Boolean(entry));
+
+      if (trimmed) {
+        const normalized = normalizeGoogleChatTarget(trimmed);
+        if (!normalized) {
+          if ((mode === "implicit" || mode === "heartbeat") && allowList.length > 0) {
+            return { ok: true, to: allowList[0] };
+          }
+          return {
+            ok: false,
+            error: missingTargetError(
+              "Google Chat",
+              "<spaces/{space}|users/{user}> or channels.googlechat.dm.allowFrom[0]",
+            ),
+          };
+        }
+        return { ok: true, to: normalized };
+      }
+
+      if (allowList.length > 0) {
+        return { ok: true, to: allowList[0] };
+      }
+      return {
+        ok: false,
+        error: missingTargetError(
+          "Google Chat",
+          "<spaces/{space}|users/{user}> or channels.googlechat.dm.allowFrom[0]",
+        ),
+      };
+    },
+    sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as MoltbotConfig,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread = (threadId ?? replyToId ?? undefined) as string | undefined;
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+      });
+      return {
+        channel: "googlechat",
+        messageId: result?.messageName ?? "",
+        chatId: space,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId, replyToId, threadId }) => {
+      if (!mediaUrl) {
+        throw new Error("Google Chat mediaUrl is required.");
+      }
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as MoltbotConfig,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread = (threadId ?? replyToId ?? undefined) as string | undefined;
+      const runtime = getGoogleChatRuntime();
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg: cfg as MoltbotConfig,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          (cfg.channels?.["googlechat"] as { accounts?: Record<string, { mediaMaxMb?: number }>; mediaMaxMb?: number } | undefined)
+            ?.accounts?.[accountId]?.mediaMaxMb ??
+          (cfg.channels?.["googlechat"] as { mediaMaxMb?: number } | undefined)?.mediaMaxMb,
+        accountId,
+      });
+      const loaded = await runtime.channel.media.fetchRemoteMedia(mediaUrl, {
+        maxBytes: maxBytes ?? (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      });
+      const upload = await uploadGoogleChatAttachment({
+        account,
+        space,
+        filename: loaded.filename ?? "attachment",
+        buffer: loaded.buffer,
+        contentType: loaded.contentType,
+      });
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+        attachments: upload.attachmentUploadToken
+          ? [{ attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename }]
+          : undefined,
+      });
+      return {
+        channel: "googlechat",
+        messageId: result?.messageName ?? "",
+        chatId: space,
+      };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((entry) => {
+        const accountId = String(entry.accountId ?? DEFAULT_ACCOUNT_ID);
+        const enabled = entry.enabled !== false;
+        const configured = entry.configured === true;
+        if (!enabled || !configured) return [];
+        const issues = [];
+        if (!entry.audience) {
+          issues.push({
+            channel: "googlechat",
+            accountId,
+            kind: "config",
+            message: "Google Chat audience is missing (set channels.googlechat.audience).",
+            fix: "Set channels.googlechat.audienceType and channels.googlechat.audience.",
+          });
+        }
+        if (!entry.audienceType) {
+          issues.push({
+            channel: "googlechat",
+            accountId,
+            kind: "config",
+            message: "Google Chat audienceType is missing (app-url or project-number).",
+            fix: "Set channels.googlechat.audienceType and channels.googlechat.audience.",
+          });
+        }
+        return issues;
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      credentialSource: snapshot.credentialSource ?? "none",
+      audienceType: snapshot.audienceType ?? null,
+      audience: snapshot.audience ?? null,
+      webhookPath: snapshot.webhookPath ?? null,
+      webhookUrl: snapshot.webhookUrl ?? 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 }) => probeGoogleChat(account),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.credentialSource !== "none",
+      credentialSource: account.credentialSource,
+      audienceType: account.config.audienceType,
+      audience: account.config.audience,
+      webhookPath: account.config.webhookPath,
+      webhookUrl: account.config.webhookUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      dmPolicy: account.config.dm?.policy ?? "pairing",
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.log?.info(`[${account.accountId}] starting Google Chat webhook`);
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        lastStartAt: Date.now(),
+        webhookPath: resolveGoogleChatWebhookPath({ account }),
+        audienceType: account.config.audienceType,
+        audience: account.config.audience,
+      });
+      const unregister = await startGoogleChatMonitor({
+        account,
+        config: ctx.cfg as MoltbotConfig,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        webhookPath: account.config.webhookPath,
+        webhookUrl: account.config.webhookUrl,
+        statusSink: (patch) => ctx.setStatus({ accountId: account.accountId, ...patch }),
+      });
+      return () => {
+        unregister?.();
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          lastStopAt: Date.now(),
+        });
+      };
+    },
+  },
+};

docker-compose/ez-assistant/extensions/googlechat/src/monitor.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { isSenderAllowed } from "./monitor.js";
+
+describe("isSenderAllowed", () => {
+  it("matches allowlist entries with users/<email>", () => {
+    expect(
+      isSenderAllowed("users/123", "Jane@Example.com", ["users/jane@example.com"]),
+    ).toBe(true);
+  });
+
+  it("matches allowlist entries with raw email", () => {
+    expect(isSenderAllowed("users/123", "Jane@Example.com", ["jane@example.com"])).toBe(
+      true,
+    );
+  });
+
+  it("still matches user id entries", () => {
+    expect(isSenderAllowed("users/abc", "jane@example.com", ["users/abc"])).toBe(true);
+  });
+
+  it("rejects non-matching emails", () => {
+    expect(isSenderAllowed("users/123", "jane@example.com", ["users/other@example.com"])).toBe(
+      false,
+    );
+  });
+});

docker-compose/ez-assistant/extensions/googlechat/src/monitor.ts

@@ -0,0 +1,900 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import { resolveMentionGatingWithBypass } from "clawdbot/plugin-sdk";
+
+import {
+  type ResolvedGoogleChatAccount
+} from "./accounts.js";
+import {
+  downloadGoogleChatMedia,
+  deleteGoogleChatMessage,
+  sendGoogleChatMessage,
+  updateGoogleChatMessage,
+} from "./api.js";
+import { verifyGoogleChatRequest, type GoogleChatAudienceType } from "./auth.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import type {
+  GoogleChatAnnotation,
+  GoogleChatAttachment,
+  GoogleChatEvent,
+  GoogleChatSpace,
+  GoogleChatMessage,
+  GoogleChatUser,
+} from "./types.js";
+
+export type GoogleChatRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type GoogleChatMonitorOptions = {
+  account: ResolvedGoogleChatAccount;
+  config: MoltbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  abortSignal: AbortSignal;
+  webhookPath?: string;
+  webhookUrl?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+type GoogleChatCoreRuntime = ReturnType<typeof getGoogleChatRuntime>;
+
+type WebhookTarget = {
+  account: ResolvedGoogleChatAccount;
+  config: MoltbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  path: string;
+  audienceType?: GoogleChatAudienceType;
+  audience?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  mediaMaxMb: number;
+};
+
+const webhookTargets = new Map<string, WebhookTarget[]>();
+
+function logVerbose(core: GoogleChatCoreRuntime, runtime: GoogleChatRuntimeEnv, message: string) {
+  if (core.logging.shouldLogVerbose()) {
+    runtime.log?.(`[googlechat] ${message}`);
+  }
+}
+
+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;
+}
+
+function resolveWebhookPath(webhookPath?: string, webhookUrl?: string): string | null {
+  const trimmedPath = webhookPath?.trim();
+  if (trimmedPath) return normalizeWebhookPath(trimmedPath);
+  if (webhookUrl?.trim()) {
+    try {
+      const parsed = new URL(webhookUrl);
+      return normalizeWebhookPath(parsed.pathname || "/");
+    } catch {
+      return null;
+    }
+  }
+  return "/googlechat";
+}
+
+async function readJsonBody(req: IncomingMessage, maxBytes: number) {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  return await new Promise<{ ok: boolean; value?: unknown; error?: string }>((resolve) => {
+    let resolved = false;
+    const doResolve = (value: { ok: boolean; value?: unknown; error?: string }) => {
+      if (resolved) return;
+      resolved = true;
+      req.removeAllListeners();
+      resolve(value);
+    };
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        doResolve({ 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()) {
+          doResolve({ ok: false, error: "empty payload" });
+          return;
+        }
+        doResolve({ ok: true, value: JSON.parse(raw) as unknown });
+      } catch (err) {
+        doResolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+      }
+    });
+    req.on("error", (err) => {
+      doResolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    });
+  });
+}
+
+export function registerGoogleChatWebhookTarget(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);
+    }
+  };
+}
+
+function normalizeAudienceType(value?: string | null): GoogleChatAudienceType | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "app-url" || normalized === "app_url" || normalized === "app") {
+    return "app-url";
+  }
+  if (normalized === "project-number" || normalized === "project_number" || normalized === "project") {
+    return "project-number";
+  }
+  return undefined;
+}
+
+export async function handleGoogleChatWebhookRequest(
+  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 authHeader = String(req.headers.authorization ?? "");
+  const bearer = authHeader.toLowerCase().startsWith("bearer ")
+    ? authHeader.slice("bearer ".length)
+    : "";
+
+  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");
+    return true;
+  }
+
+  let raw = body.value;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  // Transform Google Workspace Add-on format to standard Chat API format
+  const rawObj = raw as {
+    commonEventObject?: { hostApp?: string };
+    chat?: {
+      messagePayload?: { space?: GoogleChatSpace; message?: GoogleChatMessage };
+      user?: GoogleChatUser;
+      eventTime?: string;
+    };
+    authorizationEventObject?: { systemIdToken?: string };
+  };
+
+  if (rawObj.commonEventObject?.hostApp === "CHAT" && rawObj.chat?.messagePayload) {
+    const chat = rawObj.chat;
+    const messagePayload = chat.messagePayload;
+    raw = {
+      type: "MESSAGE",
+      space: messagePayload?.space,
+      message: messagePayload?.message,
+      user: chat.user,
+      eventTime: chat.eventTime,
+    };
+    
+    // For Add-ons, the bearer token may be in authorizationEventObject.systemIdToken
+    const systemIdToken = rawObj.authorizationEventObject?.systemIdToken;
+    if (!bearer && systemIdToken) {
+      Object.assign(req.headers, { authorization: `Bearer ${systemIdToken}` });
+    }
+  }
+
+  const event = raw as GoogleChatEvent;
+  const eventType = event.type ?? (raw as { eventType?: string }).eventType;
+  if (typeof eventType !== "string") {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  if (!event.space || typeof event.space !== "object" || Array.isArray(event.space)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  if (eventType === "MESSAGE") {
+    if (!event.message || typeof event.message !== "object" || Array.isArray(event.message)) {
+      res.statusCode = 400;
+      res.end("invalid payload");
+      return true;
+    }
+  }
+
+  // Re-extract bearer in case it was updated from Add-on format
+  const authHeaderNow = String(req.headers.authorization ?? "");
+  const effectiveBearer = authHeaderNow.toLowerCase().startsWith("bearer ")
+    ? authHeaderNow.slice("bearer ".length)
+    : bearer;
+
+  let selected: WebhookTarget | undefined;
+  for (const target of targets) {
+    const audienceType = target.audienceType;
+    const audience = target.audience;
+    const verification = await verifyGoogleChatRequest({
+      bearer: effectiveBearer,
+      audienceType,
+      audience,
+    });
+    if (verification.ok) {
+      selected = target;
+      break;
+    }
+  }
+
+  if (!selected) {
+    res.statusCode = 401;
+    res.end("unauthorized");
+    return true;
+  }
+
+  selected.statusSink?.({ lastInboundAt: Date.now() });
+  processGoogleChatEvent(event, selected).catch((err) => {
+    selected?.runtime.error?.(
+      `[${selected.account.accountId}] Google Chat webhook failed: ${String(err)}`,
+    );
+  });
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end("{}");
+  return true;
+}
+
+async function processGoogleChatEvent(event: GoogleChatEvent, target: WebhookTarget) {
+  const eventType = event.type ?? (event as { eventType?: string }).eventType;
+  if (eventType !== "MESSAGE") return;
+  if (!event.message || !event.space) return;
+
+  await processMessageWithPipeline({
+    event,
+    account: target.account,
+    config: target.config,
+    runtime: target.runtime,
+    core: target.core,
+    statusSink: target.statusSink,
+    mediaMaxMb: target.mediaMaxMb,
+  });
+}
+
+function normalizeUserId(raw?: string | null): string {
+  const trimmed = raw?.trim() ?? "";
+  if (!trimmed) return "";
+  return trimmed.replace(/^users\//i, "").toLowerCase();
+}
+
+export function isSenderAllowed(
+  senderId: string,
+  senderEmail: string | undefined,
+  allowFrom: string[],
+) {
+  if (allowFrom.includes("*")) return true;
+  const normalizedSenderId = normalizeUserId(senderId);
+  const normalizedEmail = senderEmail?.trim().toLowerCase() ?? "";
+  return allowFrom.some((entry) => {
+    const normalized = String(entry).trim().toLowerCase();
+    if (!normalized) return false;
+    if (normalized === normalizedSenderId) return true;
+    if (normalizedEmail && normalized === normalizedEmail) return true;
+    if (normalizedEmail && normalized.replace(/^users\//i, "") === normalizedEmail) return true;
+    if (normalized.replace(/^users\//i, "") === normalizedSenderId) return true;
+    if (normalized.replace(/^(googlechat|google-chat|gchat):/i, "") === normalizedSenderId) {
+      return true;
+    }
+    return false;
+  });
+}
+
+function resolveGroupConfig(params: {
+  groupId: string;
+  groupName?: string | null;
+  groups?: Record<string, { requireMention?: boolean; allow?: boolean; enabled?: boolean; users?: Array<string | number>; systemPrompt?: string }>;
+}) {
+  const { groupId, groupName, groups } = params;
+  const entries = groups ?? {};
+  const keys = Object.keys(entries);
+  if (keys.length === 0) {
+    return { entry: undefined, allowlistConfigured: false };
+  }
+  const normalizedName = groupName?.trim().toLowerCase();
+  const candidates = [groupId, groupName ?? "", normalizedName ?? ""].filter(Boolean);
+  let entry = candidates.map((candidate) => entries[candidate]).find(Boolean);
+  if (!entry && normalizedName) {
+    entry = entries[normalizedName];
+  }
+  const fallback = entries["*"];
+  return { entry: entry ?? fallback, allowlistConfigured: true, fallback };
+}
+
+function extractMentionInfo(annotations: GoogleChatAnnotation[], botUser?: string | null) {
+  const mentionAnnotations = annotations.filter((entry) => entry.type === "USER_MENTION");
+  const hasAnyMention = mentionAnnotations.length > 0;
+  const botTargets = new Set(["users/app", botUser?.trim()].filter(Boolean) as string[]);
+  const wasMentioned = mentionAnnotations.some((entry) => {
+    const userName = entry.userMention?.user?.name;
+    if (!userName) return false;
+    if (botTargets.has(userName)) return true;
+    return normalizeUserId(userName) === "app";
+  });
+  return { hasAnyMention, wasMentioned };
+}
+
+/**
+ * Resolve bot display name with fallback chain:
+ * 1. Account config name
+ * 2. Agent name from config
+ * 3. "Moltbot" as generic fallback
+ */
+function resolveBotDisplayName(params: {
+  accountName?: string;
+  agentId: string;
+  config: MoltbotConfig;
+}): string {
+  const { accountName, agentId, config } = params;
+  if (accountName?.trim()) return accountName.trim();
+  const agent = config.agents?.list?.find((a) => a.id === agentId);
+  if (agent?.name?.trim()) return agent.name.trim();
+  return "Moltbot";
+}
+
+async function processMessageWithPipeline(params: {
+  event: GoogleChatEvent;
+  account: ResolvedGoogleChatAccount;
+  config: MoltbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  mediaMaxMb: number;
+}): Promise<void> {
+  const { event, account, config, runtime, core, statusSink, mediaMaxMb } = params;
+  const space = event.space;
+  const message = event.message;
+  if (!space || !message) return;
+
+  const spaceId = space.name ?? "";
+  if (!spaceId) return;
+  const spaceType = (space.type ?? "").toUpperCase();
+  const isGroup = spaceType !== "DM";
+  const sender = message.sender ?? event.user;
+  const senderId = sender?.name ?? "";
+  const senderName = sender?.displayName ?? "";
+  const senderEmail = sender?.email ?? undefined;
+
+  const allowBots = account.config.allowBots === true;
+  if (!allowBots) {
+    if (sender?.type?.toUpperCase() === "BOT") {
+      logVerbose(core, runtime, `skip bot-authored message (${senderId || "unknown"})`);
+      return;
+    }
+    if (senderId === "users/app") {
+      logVerbose(core, runtime, "skip app-authored message");
+      return;
+    }
+  }
+
+  const messageText = (message.argumentText ?? message.text ?? "").trim();
+  const attachments = message.attachment ?? [];
+  const hasMedia = attachments.length > 0;
+  const rawBody = messageText || (hasMedia ? "<media:attachment>" : "");
+  if (!rawBody) return;
+
+  const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
+  const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+  const groupConfigResolved = resolveGroupConfig({
+    groupId: spaceId,
+    groupName: space.displayName ?? null,
+    groups: account.config.groups ?? undefined,
+  });
+  const groupEntry = groupConfigResolved.entry;
+  const groupUsers = groupEntry?.users ?? account.config.groupAllowFrom ?? [];
+  let effectiveWasMentioned: boolean | undefined;
+
+  if (isGroup) {
+    if (groupPolicy === "disabled") {
+      logVerbose(core, runtime, `drop group message (groupPolicy=disabled, space=${spaceId})`);
+      return;
+    }
+    const groupAllowlistConfigured = groupConfigResolved.allowlistConfigured;
+    const groupAllowed =
+      Boolean(groupEntry) || Boolean((account.config.groups ?? {})["*"]);
+    if (groupPolicy === "allowlist") {
+      if (!groupAllowlistConfigured) {
+        logVerbose(
+          core,
+          runtime,
+          `drop group message (groupPolicy=allowlist, no allowlist, space=${spaceId})`,
+        );
+        return;
+      }
+      if (!groupAllowed) {
+        logVerbose(core, runtime, `drop group message (not allowlisted, space=${spaceId})`);
+        return;
+      }
+    }
+    if (groupEntry?.enabled === false || groupEntry?.allow === false) {
+      logVerbose(core, runtime, `drop group message (space disabled, space=${spaceId})`);
+      return;
+    }
+
+    if (groupUsers.length > 0) {
+      const ok = isSenderAllowed(senderId, senderEmail, groupUsers.map((v) => String(v)));
+      if (!ok) {
+        logVerbose(core, runtime, `drop group message (sender not allowed, ${senderId})`);
+        return;
+      }
+    }
+  }
+
+  const dmPolicy = account.config.dm?.policy ?? "pairing";
+  const configAllowFrom = (account.config.dm?.allowFrom ?? []).map((v) => String(v));
+  const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, config);
+  const storeAllowFrom =
+    !isGroup && (dmPolicy !== "open" || shouldComputeAuth)
+      ? await core.channel.pairing.readAllowFromStore("googlechat").catch(() => [])
+      : [];
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+  const commandAllowFrom = isGroup ? groupUsers.map((v) => String(v)) : effectiveAllowFrom;
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = isSenderAllowed(senderId, senderEmail, commandAllowFrom);
+  const commandAuthorized = shouldComputeAuth
+    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [
+          { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
+        ],
+      })
+    : undefined;
+
+  if (isGroup) {
+    const requireMention = groupEntry?.requireMention ?? account.config.requireMention ?? true;
+    const annotations = message.annotations ?? [];
+    const mentionInfo = extractMentionInfo(annotations, account.config.botUser);
+    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+      cfg: config,
+      surface: "googlechat",
+    });
+    const mentionGate = resolveMentionGatingWithBypass({
+      isGroup: true,
+      requireMention,
+      canDetectMention: true,
+      wasMentioned: mentionInfo.wasMentioned,
+      implicitMention: false,
+      hasAnyMention: mentionInfo.hasAnyMention,
+      allowTextCommands,
+      hasControlCommand: core.channel.text.hasControlCommand(rawBody, config),
+      commandAuthorized: commandAuthorized === true,
+    });
+    effectiveWasMentioned = mentionGate.effectiveWasMentioned;
+    if (mentionGate.shouldSkip) {
+      logVerbose(core, runtime, `drop group message (mention required, space=${spaceId})`);
+      return;
+    }
+  }
+
+  if (!isGroup) {
+    if (dmPolicy === "disabled" || account.config.dm?.enabled === false) {
+      logVerbose(core, runtime, `Blocked Google Chat DM from ${senderId} (dmPolicy=disabled)`);
+      return;
+    }
+
+    if (dmPolicy !== "open") {
+      const allowed = senderAllowedForCommands;
+      if (!allowed) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: "googlechat",
+            id: senderId,
+            meta: { name: senderName || undefined, email: senderEmail },
+          });
+          if (created) {
+            logVerbose(core, runtime, `googlechat pairing request sender=${senderId}`);
+            try {
+              await sendGoogleChatMessage({
+                account,
+                space: spaceId,
+                text: core.channel.pairing.buildPairingReply({
+                  channel: "googlechat",
+                  idLine: `Your Google Chat user id: ${senderId}`,
+                  code,
+                }),
+              });
+              statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              logVerbose(core, runtime, `pairing reply failed for ${senderId}: ${String(err)}`);
+            }
+          }
+        } else {
+          logVerbose(
+            core,
+            runtime,
+            `Blocked unauthorized Google Chat sender ${senderId} (dmPolicy=${dmPolicy})`,
+          );
+        }
+        return;
+      }
+    }
+  }
+
+  if (
+    isGroup &&
+    core.channel.commands.isControlCommandMessage(rawBody, config) &&
+    commandAuthorized !== true
+  ) {
+    logVerbose(core, runtime, `googlechat: drop control command from ${senderId}`);
+    return;
+  }
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "googlechat",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: spaceId,
+    },
+  });
+
+  let mediaPath: string | undefined;
+  let mediaType: string | undefined;
+  if (attachments.length > 0) {
+    const first = attachments[0];
+    const attachmentData = await downloadAttachment(first, account, mediaMaxMb, core);
+    if (attachmentData) {
+      mediaPath = attachmentData.path;
+      mediaType = attachmentData.contentType;
+    }
+  }
+
+  const fromLabel = isGroup
+    ? space.displayName || `space:${spaceId}`
+    : senderName || `user:${senderId}`;
+  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: "Google Chat",
+    from: fromLabel,
+    timestamp: event.eventTime ? Date.parse(event.eventTime) : undefined,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const groupSystemPrompt = groupConfigResolved.entry?.systemPrompt?.trim() || undefined;
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `googlechat:${senderId}`,
+    To: `googlechat:${spaceId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "channel" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: senderName || undefined,
+    SenderId: senderId,
+    SenderUsername: senderEmail,
+    WasMentioned: isGroup ? effectiveWasMentioned : undefined,
+    CommandAuthorized: commandAuthorized,
+    Provider: "googlechat",
+    Surface: "googlechat",
+    MessageSid: message.name,
+    MessageSidFull: message.name,
+    ReplyToId: message.thread?.name,
+    ReplyToIdFull: message.thread?.name,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath,
+    GroupSpace: isGroup ? space.displayName ?? undefined : undefined,
+    GroupSystemPrompt: isGroup ? groupSystemPrompt : undefined,
+    OriginatingChannel: "googlechat",
+    OriginatingTo: `googlechat:${spaceId}`,
+  });
+
+  void core.channel.session
+    .recordSessionMetaFromInbound({
+      storePath,
+      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      ctx: ctxPayload,
+    })
+    .catch((err) => {
+      runtime.error?.(`googlechat: failed updating session meta: ${String(err)}`);
+    });
+
+  // Typing indicator setup
+  // Note: Reaction mode requires user OAuth, not available with service account auth.
+  // If reaction is configured, we fall back to message mode with a warning.
+  let typingIndicator = account.config.typingIndicator ?? "message";
+  if (typingIndicator === "reaction") {
+    runtime.error?.(
+      `[${account.accountId}] typingIndicator="reaction" requires user OAuth (not supported with service account). Falling back to "message" mode.`,
+    );
+    typingIndicator = "message";
+  }
+  let typingMessageName: string | undefined;
+
+  // Start typing indicator (message mode only, reaction mode not supported with app auth)
+  if (typingIndicator === "message") {
+    try {
+      const botName = resolveBotDisplayName({
+        accountName: account.config.name,
+        agentId: route.agentId,
+        config,
+      });
+      const result = await sendGoogleChatMessage({
+        account,
+        space: spaceId,
+        text: `_${botName} is typing..._`,
+        thread: message.thread?.name,
+      });
+      typingMessageName = result?.messageName;
+    } catch (err) {
+      runtime.error?.(`Failed sending typing message: ${String(err)}`);
+    }
+  }
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        await deliverGoogleChatReply({
+          payload,
+          account,
+          spaceId,
+          runtime,
+          core,
+          config,
+          statusSink,
+          typingMessageName,
+        });
+        // Only use typing message for first delivery
+        typingMessageName = undefined;
+      },
+      onError: (err, info) => {
+        runtime.error?.(
+          `[${account.accountId}] Google Chat ${info.kind} reply failed: ${String(err)}`,
+        );
+      },
+    },
+  });
+}
+
+async function downloadAttachment(
+  attachment: GoogleChatAttachment,
+  account: ResolvedGoogleChatAccount,
+  mediaMaxMb: number,
+  core: GoogleChatCoreRuntime,
+): Promise<{ path: string; contentType?: string } | null> {
+  const resourceName = attachment.attachmentDataRef?.resourceName;
+  if (!resourceName) return null;
+  const maxBytes = Math.max(1, mediaMaxMb) * 1024 * 1024;
+  const downloaded = await downloadGoogleChatMedia({ account, resourceName, maxBytes });
+  const saved = await core.channel.media.saveMediaBuffer(
+    downloaded.buffer,
+    downloaded.contentType ?? attachment.contentType,
+    "inbound",
+    maxBytes,
+    attachment.contentName,
+  );
+  return { path: saved.path, contentType: saved.contentType };
+}
+
+async function deliverGoogleChatReply(params: {
+  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string; replyToId?: string };
+  account: ResolvedGoogleChatAccount;
+  spaceId: string;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  config: MoltbotConfig;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  typingMessageName?: string;
+}): Promise<void> {
+  const { payload, account, spaceId, runtime, core, config, statusSink, typingMessageName } = params;
+  const mediaList = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : payload.mediaUrl
+      ? [payload.mediaUrl]
+      : [];
+
+  if (mediaList.length > 0) {
+    let suppressCaption = false;
+    if (typingMessageName) {
+      try {
+        await deleteGoogleChatMessage({
+          account,
+          messageName: typingMessageName,
+        });
+      } catch (err) {
+        runtime.error?.(`Google Chat typing cleanup failed: ${String(err)}`);
+        const fallbackText = payload.text?.trim()
+          ? payload.text
+          : mediaList.length > 1
+            ? "Sent attachments."
+            : "Sent attachment.";
+        try {
+          await updateGoogleChatMessage({
+            account,
+            messageName: typingMessageName,
+            text: fallbackText,
+          });
+          suppressCaption = Boolean(payload.text?.trim());
+        } catch (updateErr) {
+          runtime.error?.(`Google Chat typing update failed: ${String(updateErr)}`);
+        }
+      }
+    }
+    let first = true;
+    for (const mediaUrl of mediaList) {
+      const caption = first && !suppressCaption ? payload.text : undefined;
+      first = false;
+      try {
+        const loaded = await core.channel.media.fetchRemoteMedia(mediaUrl, {
+          maxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+        });
+        const upload = await uploadAttachmentForReply({
+          account,
+          spaceId,
+          buffer: loaded.buffer,
+          contentType: loaded.contentType,
+          filename: loaded.filename ?? "attachment",
+        });
+        if (!upload.attachmentUploadToken) {
+          throw new Error("missing attachment upload token");
+        }
+        await sendGoogleChatMessage({
+          account,
+          space: spaceId,
+          text: caption,
+          thread: payload.replyToId,
+          attachments: [
+            { attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename },
+          ],
+        });
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error?.(`Google Chat attachment send failed: ${String(err)}`);
+      }
+    }
+    return;
+  }
+
+  if (payload.text) {
+    const chunkLimit = account.config.textChunkLimit ?? 4000;
+    const chunkMode = core.channel.text.resolveChunkMode(
+      config,
+      "googlechat",
+      account.accountId,
+    );
+    const chunks = core.channel.text.chunkMarkdownTextWithMode(
+      payload.text,
+      chunkLimit,
+      chunkMode,
+    );
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
+      try {
+        // Edit typing message with first chunk if available
+        if (i === 0 && typingMessageName) {
+          await updateGoogleChatMessage({
+            account,
+            messageName: typingMessageName,
+            text: chunk,
+          });
+        } else {
+          await sendGoogleChatMessage({
+            account,
+            space: spaceId,
+            text: chunk,
+            thread: payload.replyToId,
+          });
+        }
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error?.(`Google Chat message send failed: ${String(err)}`);
+      }
+    }
+  }
+}
+
+async function uploadAttachmentForReply(params: {
+  account: ResolvedGoogleChatAccount;
+  spaceId: string;
+  buffer: Buffer;
+  contentType?: string;
+  filename: string;
+}) {
+  const { account, spaceId, buffer, contentType, filename } = params;
+  const { uploadGoogleChatAttachment } = await import("./api.js");
+  return await uploadGoogleChatAttachment({
+    account,
+    space: spaceId,
+    filename,
+    buffer,
+    contentType,
+  });
+}
+
+export function monitorGoogleChatProvider(options: GoogleChatMonitorOptions): () => void {
+  const core = getGoogleChatRuntime();
+  const webhookPath = resolveWebhookPath(options.webhookPath, options.webhookUrl);
+  if (!webhookPath) {
+    options.runtime.error?.(`[${options.account.accountId}] invalid webhook path`);
+    return () => {};
+  }
+
+  const audienceType = normalizeAudienceType(options.account.config.audienceType);
+  const audience = options.account.config.audience?.trim();
+  const mediaMaxMb = options.account.config.mediaMaxMb ?? 20;
+
+  const unregister = registerGoogleChatWebhookTarget({
+    account: options.account,
+    config: options.config,
+    runtime: options.runtime,
+    core,
+    path: webhookPath,
+    audienceType,
+    audience,
+    statusSink: options.statusSink,
+    mediaMaxMb,
+  });
+
+  return unregister;
+}
+
+export async function startGoogleChatMonitor(params: GoogleChatMonitorOptions): Promise<() => void> {
+  return monitorGoogleChatProvider(params);
+}
+
+export function resolveGoogleChatWebhookPath(params: {
+  account: ResolvedGoogleChatAccount;
+}): string {
+  return resolveWebhookPath(
+    params.account.config.webhookPath,
+    params.account.config.webhookUrl,
+  ) ?? "/googlechat";
+}
+
+export function computeGoogleChatMediaMaxMb(params: { account: ResolvedGoogleChatAccount }) {
+  return params.account.config.mediaMaxMb ?? 20;
+}

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

@@ -0,0 +1,278 @@
+import type { MoltbotConfig, DmPolicy } from "clawdbot/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  formatDocsLink,
+  promptAccountId,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type WizardPrompter,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  migrateBaseNameToDefaultAccount,
+} from "clawdbot/plugin-sdk";
+
+import {
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+} from "./accounts.js";
+
+const channel = "googlechat" as const;
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+
+function setGoogleChatDmPolicy(cfg: MoltbotConfig, policy: DmPolicy) {
+  const allowFrom =
+    policy === "open"
+      ? addWildcardAllowFrom(cfg.channels?.["googlechat"]?.dm?.allowFrom)
+      : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "googlechat": {
+        ...(cfg.channels?.["googlechat"] ?? {}),
+        dm: {
+          ...(cfg.channels?.["googlechat"]?.dm ?? {}),
+          policy,
+          ...(allowFrom ? { allowFrom } : {}),
+        },
+      },
+    },
+  };
+}
+
+function parseAllowFromInput(raw: string): string[] {
+  return raw
+    .split(/[\n,;]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+async function promptAllowFrom(params: {
+  cfg: MoltbotConfig;
+  prompter: WizardPrompter;
+}): Promise<MoltbotConfig> {
+  const current = params.cfg.channels?.["googlechat"]?.dm?.allowFrom ?? [];
+  const entry = await params.prompter.text({
+    message: "Google Chat allowFrom (user id or email)",
+    placeholder: "users/123456789, name@example.com",
+    initialValue: current[0] ? String(current[0]) : undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  const parts = parseAllowFromInput(String(entry));
+  const unique = [...new Set(parts)];
+  return {
+    ...params.cfg,
+    channels: {
+      ...params.cfg.channels,
+      "googlechat": {
+        ...(params.cfg.channels?.["googlechat"] ?? {}),
+        enabled: true,
+        dm: {
+          ...(params.cfg.channels?.["googlechat"]?.dm ?? {}),
+          policy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    },
+  };
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Google Chat",
+  channel,
+  policyKey: "channels.googlechat.dm.policy",
+  allowFromKey: "channels.googlechat.dm.allowFrom",
+  getCurrent: (cfg) => cfg.channels?.["googlechat"]?.dm?.policy ?? "pairing",
+  setPolicy: (cfg, policy) => setGoogleChatDmPolicy(cfg, policy),
+  promptAllowFrom,
+};
+
+function applyAccountConfig(params: {
+  cfg: MoltbotConfig;
+  accountId: string;
+  patch: Record<string, unknown>;
+}): MoltbotConfig {
+  const { cfg, accountId, patch } = params;
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "googlechat": {
+          ...(cfg.channels?.["googlechat"] ?? {}),
+          enabled: true,
+          ...patch,
+        },
+      },
+    };
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "googlechat": {
+        ...(cfg.channels?.["googlechat"] ?? {}),
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.["googlechat"]?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.["googlechat"]?.accounts?.[accountId] ?? {}),
+            enabled: true,
+            ...patch,
+          },
+        },
+      },
+    },
+  };
+}
+
+async function promptCredentials(params: {
+  cfg: MoltbotConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<MoltbotConfig> {
+  const { cfg, prompter, accountId } = params;
+  const envReady =
+    accountId === DEFAULT_ACCOUNT_ID &&
+    (Boolean(process.env[ENV_SERVICE_ACCOUNT]) ||
+      Boolean(process.env[ENV_SERVICE_ACCOUNT_FILE]));
+  if (envReady) {
+    const useEnv = await prompter.confirm({
+      message: "Use GOOGLE_CHAT_SERVICE_ACCOUNT env vars?",
+      initialValue: true,
+    });
+    if (useEnv) {
+      return applyAccountConfig({ cfg, accountId, patch: {} });
+    }
+  }
+
+  const method = await prompter.select({
+    message: "Google Chat auth method",
+    options: [
+      { value: "file", label: "Service account JSON file" },
+      { value: "inline", label: "Paste service account JSON" },
+    ],
+    initialValue: "file",
+  });
+
+  if (method === "file") {
+    const path = await prompter.text({
+      message: "Service account JSON path",
+      placeholder: "/path/to/service-account.json",
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+    return applyAccountConfig({
+      cfg,
+      accountId,
+      patch: { serviceAccountFile: String(path).trim() },
+    });
+  }
+
+  const json = await prompter.text({
+    message: "Service account JSON (single line)",
+    placeholder: "{\"type\":\"service_account\", ... }",
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  return applyAccountConfig({
+    cfg,
+    accountId,
+    patch: { serviceAccount: String(json).trim() },
+  });
+}
+
+async function promptAudience(params: {
+  cfg: MoltbotConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<MoltbotConfig> {
+  const account = resolveGoogleChatAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const currentType = account.config.audienceType ?? "app-url";
+  const currentAudience = account.config.audience ?? "";
+  const audienceType = (await params.prompter.select({
+    message: "Webhook audience type",
+    options: [
+      { value: "app-url", label: "App URL (recommended)" },
+      { value: "project-number", label: "Project number" },
+    ],
+    initialValue: currentType === "project-number" ? "project-number" : "app-url",
+  })) as "app-url" | "project-number";
+  const audience = await params.prompter.text({
+    message: audienceType === "project-number" ? "Project number" : "App URL",
+    placeholder: audienceType === "project-number" ? "1234567890" : "https://your.host/googlechat",
+    initialValue: currentAudience || undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  return applyAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    patch: { audienceType, audience: String(audience).trim() },
+  });
+}
+
+async function noteGoogleChatSetup(prompter: WizardPrompter) {
+  await prompter.note(
+    [
+      "Google Chat apps use service-account auth and an HTTPS webhook.",
+      "Set the Chat API scopes in your service account and configure the Chat app URL.",
+      "Webhook verification requires audience type + audience value.",
+      `Docs: ${formatDocsLink("/channels/googlechat", "channels/googlechat")}`,
+    ].join("\n"),
+    "Google Chat setup",
+  );
+}
+
+export const googlechatOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  dmPolicy,
+  getStatus: async ({ cfg }) => {
+    const configured = listGoogleChatAccountIds(cfg).some(
+      (accountId) => resolveGoogleChatAccount({ cfg, accountId }).credentialSource !== "none",
+    );
+    return {
+      channel,
+      configured,
+      statusLines: [
+        `Google Chat: ${configured ? "configured" : "needs service account"}`,
+      ],
+      selectionHint: configured ? "configured" : "needs auth",
+    };
+  },
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+  }) => {
+    const override = accountOverrides["googlechat"]?.trim();
+    const defaultAccountId = resolveDefaultGoogleChatAccountId(cfg);
+    let accountId = override ? normalizeAccountId(override) : defaultAccountId;
+    if (shouldPromptAccountIds && !override) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Google Chat",
+        currentId: accountId,
+        listAccountIds: listGoogleChatAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+    await noteGoogleChatSetup(prompter);
+    next = await promptCredentials({ cfg: next, prompter, accountId });
+    next = await promptAudience({ cfg: next, prompter, accountId });
+
+    const namedConfig = migrateBaseNameToDefaultAccount({
+      cfg: next,
+      channelKey: "googlechat",
+    });
+
+    return { cfg: namedConfig, accountId };
+  },
+};

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

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

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  isGoogleChatSpaceTarget,
+  isGoogleChatUserTarget,
+  normalizeGoogleChatTarget,
+} from "./targets.js";
+
+describe("normalizeGoogleChatTarget", () => {
+  it("normalizes provider prefixes", () => {
+    expect(normalizeGoogleChatTarget("googlechat:users/123")).toBe("users/123");
+    expect(normalizeGoogleChatTarget("google-chat:spaces/AAA")).toBe("spaces/AAA");
+    expect(normalizeGoogleChatTarget("gchat:user:User@Example.com")).toBe(
+      "users/user@example.com",
+    );
+  });
+
+  it("normalizes email targets to users/<email>", () => {
+    expect(normalizeGoogleChatTarget("User@Example.com")).toBe("users/user@example.com");
+    expect(normalizeGoogleChatTarget("users/User@Example.com")).toBe("users/user@example.com");
+  });
+
+  it("preserves space targets", () => {
+    expect(normalizeGoogleChatTarget("space:spaces/BBB")).toBe("spaces/BBB");
+    expect(normalizeGoogleChatTarget("spaces/CCC")).toBe("spaces/CCC");
+  });
+});
+
+describe("target helpers", () => {
+  it("detects user and space targets", () => {
+    expect(isGoogleChatUserTarget("users/abc")).toBe(true);
+    expect(isGoogleChatSpaceTarget("spaces/abc")).toBe(true);
+    expect(isGoogleChatUserTarget("spaces/abc")).toBe(false);
+  });
+});

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

@@ -0,0 +1,55 @@
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { findGoogleChatDirectMessage } from "./api.js";
+
+export function normalizeGoogleChatTarget(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  const withoutPrefix = trimmed.replace(/^(googlechat|google-chat|gchat):/i, "");
+  const normalized = withoutPrefix
+    .replace(/^user:(users\/)?/i, "users/")
+    .replace(/^space:(spaces\/)?/i, "spaces/");
+  if (isGoogleChatUserTarget(normalized)) {
+    const suffix = normalized.slice("users/".length);
+    return suffix.includes("@") ? `users/${suffix.toLowerCase()}` : normalized;
+  }
+  if (isGoogleChatSpaceTarget(normalized)) return normalized;
+  if (normalized.includes("@")) return `users/${normalized.toLowerCase()}`;
+  return normalized;
+}
+
+export function isGoogleChatUserTarget(value: string): boolean {
+  return value.toLowerCase().startsWith("users/");
+}
+
+export function isGoogleChatSpaceTarget(value: string): boolean {
+  return value.toLowerCase().startsWith("spaces/");
+}
+
+function stripMessageSuffix(target: string): string {
+  const index = target.indexOf("/messages/");
+  if (index === -1) return target;
+  return target.slice(0, index);
+}
+
+export async function resolveGoogleChatOutboundSpace(params: {
+  account: ResolvedGoogleChatAccount;
+  target: string;
+}): Promise<string> {
+  const normalized = normalizeGoogleChatTarget(params.target);
+  if (!normalized) {
+    throw new Error("Missing Google Chat target.");
+  }
+  const base = stripMessageSuffix(normalized);
+  if (isGoogleChatSpaceTarget(base)) return base;
+  if (isGoogleChatUserTarget(base)) {
+    const dm = await findGoogleChatDirectMessage({
+      account: params.account,
+      userName: base,
+    });
+    if (!dm?.name) {
+      throw new Error(`No Google Chat DM found for ${base}`);
+    }
+    return dm.name;
+  }
+  return base;
+}

docker-compose/ez-assistant/extensions/googlechat/src/types.config.ts

@@ -0,0 +1,3 @@
+import type { GoogleChatAccountConfig, GoogleChatConfig } from "clawdbot/plugin-sdk";
+
+export type { GoogleChatAccountConfig, GoogleChatConfig };

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

@@ -0,0 +1,73 @@
+export type GoogleChatSpace = {
+  name?: string;
+  displayName?: string;
+  type?: string;
+};
+
+export type GoogleChatUser = {
+  name?: string;
+  displayName?: string;
+  email?: string;
+  type?: string;
+};
+
+export type GoogleChatThread = {
+  name?: string;
+  threadKey?: string;
+};
+
+export type GoogleChatAttachmentDataRef = {
+  resourceName?: string;
+  attachmentUploadToken?: string;
+};
+
+export type GoogleChatAttachment = {
+  name?: string;
+  contentName?: string;
+  contentType?: string;
+  thumbnailUri?: string;
+  downloadUri?: string;
+  source?: string;
+  attachmentDataRef?: GoogleChatAttachmentDataRef;
+  driveDataRef?: Record<string, unknown>;
+};
+
+export type GoogleChatUserMention = {
+  user?: GoogleChatUser;
+  type?: string;
+};
+
+export type GoogleChatAnnotation = {
+  type?: string;
+  startIndex?: number;
+  length?: number;
+  userMention?: GoogleChatUserMention;
+  slashCommand?: Record<string, unknown>;
+  richLinkMetadata?: Record<string, unknown>;
+  customEmojiMetadata?: Record<string, unknown>;
+};
+
+export type GoogleChatMessage = {
+  name?: string;
+  text?: string;
+  argumentText?: string;
+  sender?: GoogleChatUser;
+  thread?: GoogleChatThread;
+  attachment?: GoogleChatAttachment[];
+  annotations?: GoogleChatAnnotation[];
+};
+
+export type GoogleChatEvent = {
+  type?: string;
+  eventType?: string;
+  eventTime?: string;
+  space?: GoogleChatSpace;
+  user?: GoogleChatUser;
+  message?: GoogleChatMessage;
+};
+
+export type GoogleChatReaction = {
+  name?: string;
+  user?: GoogleChatUser;
+  emoji?: { unicode?: string };
+};

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

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

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

@@ -0,0 +1,18 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { imessagePlugin } from "./src/channel.js";
+import { setIMessageRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "imessage",
+  name: "iMessage",
+  description: "iMessage channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: MoltbotPluginApi) {
+    setIMessageRuntime(api.runtime);
+    api.registerChannel({ plugin: imessagePlugin });
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/imessage",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot iMessage channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

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

@@ -0,0 +1,294 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  imessageOnboardingAdapter,
+  IMessageConfigSchema,
+  listIMessageAccountIds,
+  looksLikeIMessageTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeIMessageMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  resolveDefaultIMessageAccountId,
+  resolveIMessageAccount,
+  resolveIMessageGroupRequireMention,
+  resolveIMessageGroupToolPolicy,
+  setAccountEnabledInConfigSection,
+  type ChannelPlugin,
+  type ResolvedIMessageAccount,
+} from "clawdbot/plugin-sdk";
+
+import { getIMessageRuntime } from "./runtime.js";
+
+const meta = getChatChannelMeta("imessage");
+
+export const imessagePlugin: ChannelPlugin<ResolvedIMessageAccount> = {
+  id: "imessage",
+  meta: {
+    ...meta,
+    aliases: ["imsg"],
+    showConfigured: false,
+  },
+  onboarding: imessageOnboardingAdapter,
+  pairing: {
+    idLabel: "imessageSenderId",
+    notifyApproval: async ({ id }) => {
+      await getIMessageRuntime().channel.imessage.sendMessageIMessage(
+        id,
+        PAIRING_APPROVED_MESSAGE,
+      );
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+  },
+  reload: { configPrefixes: ["channels.imessage"] },
+  configSchema: buildChannelConfigSchema(IMessageConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listIMessageAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveIMessageAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultIMessageAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "imessage",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "imessage",
+        accountId,
+        clearBaseFields: ["cliPath", "dbPath", "service", "region", "name"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveIMessageAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((entry) => String(entry).trim()).filter(Boolean),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.imessage?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.imessage.accounts.${resolvedAccountId}.`
+        : "channels.imessage.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("imessage"),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- iMessage groups: groupPolicy="open" allows any member to trigger the bot. Set channels.imessage.groupPolicy="allowlist" + channels.imessage.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveIMessageGroupRequireMention,
+    resolveToolPolicy: resolveIMessageGroupToolPolicy,
+  },
+  messaging: {
+    normalizeTarget: normalizeIMessageMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeIMessageTargetId,
+      hint: "<handle|chat_id:ID>",
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "imessage",
+        accountId,
+        name,
+      }),
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "imessage",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "imessage",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            imessage: {
+              ...next.channels?.imessage,
+              enabled: true,
+              ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+              ...(input.dbPath ? { dbPath: input.dbPath } : {}),
+              ...(input.service ? { service: input.service } : {}),
+              ...(input.region ? { region: input.region } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          imessage: {
+            ...next.channels?.imessage,
+            enabled: true,
+            accounts: {
+              ...next.channels?.imessage?.accounts,
+              [accountId]: {
+                ...next.channels?.imessage?.accounts?.[accountId],
+                enabled: true,
+                ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+                ...(input.dbPath ? { dbPath: input.dbPath } : {}),
+                ...(input.service ? { service: input.service } : {}),
+                ...(input.region ? { region: input.region } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getIMessageRuntime().channel.text.chunkText(text, limit),
+    chunkerMode: "text",
+    textChunkLimit: 4000,
+    sendText: async ({ cfg, to, text, accountId, deps }) => {
+      const send = deps?.sendIMessage ?? getIMessageRuntime().channel.imessage.sendMessageIMessage;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.imessage?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "imessage", ...result };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId, deps }) => {
+      const send = deps?.sendIMessage ?? getIMessageRuntime().channel.imessage.sendMessageIMessage;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.imessage?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        mediaUrl,
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "imessage", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      cliPath: null,
+      dbPath: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "imessage",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      cliPath: snapshot.cliPath ?? null,
+      dbPath: snapshot.dbPath ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ timeoutMs }) =>
+      getIMessageRuntime().channel.imessage.probeIMessage(timeoutMs),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      cliPath: runtime?.cliPath ?? account.config.cliPath ?? null,
+      dbPath: runtime?.dbPath ?? account.config.dbPath ?? null,
+      probe,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+    resolveAccountState: ({ enabled }) => (enabled ? "enabled" : "disabled"),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const cliPath = account.config.cliPath?.trim() || "imsg";
+      const dbPath = account.config.dbPath?.trim();
+      ctx.setStatus({
+        accountId: account.accountId,
+        cliPath,
+        dbPath: dbPath ?? null,
+      });
+      ctx.log?.info(
+        `[${account.accountId}] starting provider (${cliPath}${dbPath ? ` db=${dbPath}` : ""})`,
+      );
+      return getIMessageRuntime().channel.imessage.monitorIMessageProvider({
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+      });
+    },
+  },
+};

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

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

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

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

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

@@ -0,0 +1,20 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { linePlugin } from "./src/channel.js";
+import { registerLineCardCommand } from "./src/card-command.js";
+import { setLineRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "line",
+  name: "LINE",
+  description: "LINE Messaging API channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: MoltbotPluginApi) {
+    setLineRuntime(api.runtime);
+    api.registerChannel({ plugin: linePlugin });
+    registerLineCardCommand(api);
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,29 @@
+{
+  "name": "@moltbot/line",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot LINE channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "line",
+      "label": "LINE",
+      "selectionLabel": "LINE (Messaging API)",
+      "docsPath": "/channels/line",
+      "docsLabel": "line",
+      "blurb": "LINE Messaging API bot for Japan/Taiwan/Thailand markets.",
+      "order": 75,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@moltbot/line",
+      "localPath": "extensions/line",
+      "defaultChoice": "npm"
+    }
+  },
+  "devDependencies": {
+    "moltbot": "workspace:*"
+  }
+}

docker-compose/ez-assistant/extensions/line/src/card-command.ts

@@ -0,0 +1,338 @@
+import type { MoltbotPluginApi, LineChannelData, ReplyPayload } from "clawdbot/plugin-sdk";
+import {
+  createActionCard,
+  createImageCard,
+  createInfoCard,
+  createListCard,
+  createReceiptCard,
+  type CardAction,
+  type ListItem,
+} from "clawdbot/plugin-sdk";
+
+const CARD_USAGE = `Usage: /card <type> "title" "body" [options]
+
+Types:
+  info "Title" "Body" ["Footer"]
+  image "Title" "Caption" --url <image-url>
+  action "Title" "Body" --actions "Btn1|url1,Btn2|text2"
+  list "Title" "Item1|Desc1,Item2|Desc2"
+  receipt "Title" "Item1:$10,Item2:$20" --total "$30"
+  confirm "Question?" --yes "Yes|data" --no "No|data"
+  buttons "Title" "Text" --actions "Btn1|url1,Btn2|data2"
+
+Examples:
+  /card info "Welcome" "Thanks for joining!"
+  /card image "Product" "Check it out" --url https://example.com/img.jpg
+  /card action "Menu" "Choose an option" --actions "Order|/order,Help|/help"`;
+
+function buildLineReply(lineData: LineChannelData): ReplyPayload {
+  return {
+    channelData: {
+      line: lineData,
+    },
+  };
+}
+
+/**
+ * Parse action string format: "Label|data,Label2|data2"
+ * Data can be a URL (uri action) or plain text (message action) or key=value (postback)
+ */
+function parseActions(actionsStr: string | undefined): CardAction[] {
+  if (!actionsStr) return [];
+
+  const results: CardAction[] = [];
+
+  for (const part of actionsStr.split(",")) {
+    const [label, data] = part
+      .trim()
+      .split("|")
+      .map((s) => s.trim());
+    if (!label) continue;
+
+    const actionData = data || label;
+
+    if (actionData.startsWith("http://") || actionData.startsWith("https://")) {
+      results.push({
+        label,
+        action: { type: "uri", label: label.slice(0, 20), uri: actionData },
+      });
+    } else if (actionData.includes("=")) {
+      results.push({
+        label,
+        action: {
+          type: "postback",
+          label: label.slice(0, 20),
+          data: actionData.slice(0, 300),
+          displayText: label,
+        },
+      });
+    } else {
+      results.push({
+        label,
+        action: { type: "message", label: label.slice(0, 20), text: actionData },
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Parse list items format: "Item1|Subtitle1,Item2|Subtitle2"
+ */
+function parseListItems(itemsStr: string): ListItem[] {
+  return itemsStr
+    .split(",")
+    .map((part) => {
+      const [title, subtitle] = part
+        .trim()
+        .split("|")
+        .map((s) => s.trim());
+      return { title: title || "", subtitle };
+    })
+    .filter((item) => item.title);
+}
+
+/**
+ * Parse receipt items format: "Item1:$10,Item2:$20"
+ */
+function parseReceiptItems(itemsStr: string): Array<{ name: string; value: string }> {
+  return itemsStr
+    .split(",")
+    .map((part) => {
+      const colonIndex = part.lastIndexOf(":");
+      if (colonIndex === -1) {
+        return { name: part.trim(), value: "" };
+      }
+      return {
+        name: part.slice(0, colonIndex).trim(),
+        value: part.slice(colonIndex + 1).trim(),
+      };
+    })
+    .filter((item) => item.name);
+}
+
+/**
+ * Parse quoted arguments from command string
+ * Supports: /card type "arg1" "arg2" "arg3" --flag value
+ */
+function parseCardArgs(argsStr: string): {
+  type: string;
+  args: string[];
+  flags: Record<string, string>;
+} {
+  const result: { type: string; args: string[]; flags: Record<string, string> } = {
+    type: "",
+    args: [],
+    flags: {},
+  };
+
+  // Extract type (first word)
+  const typeMatch = argsStr.match(/^(\w+)/);
+  if (typeMatch) {
+    result.type = typeMatch[1].toLowerCase();
+    argsStr = argsStr.slice(typeMatch[0].length).trim();
+  }
+
+  // Extract quoted arguments
+  const quotedRegex = /"([^"]*?)"/g;
+  let match;
+  while ((match = quotedRegex.exec(argsStr)) !== null) {
+    result.args.push(match[1]);
+  }
+
+  // Extract flags (--key value or --key "value")
+  const flagRegex = /--(\w+)\s+(?:"([^"]*?)"|(\S+))/g;
+  while ((match = flagRegex.exec(argsStr)) !== null) {
+    result.flags[match[1]] = match[2] ?? match[3];
+  }
+
+  return result;
+}
+
+export function registerLineCardCommand(api: MoltbotPluginApi): void {
+  api.registerCommand({
+    name: "card",
+    description: "Send a rich card message (LINE).",
+    acceptsArgs: true,
+    requireAuth: false,
+    handler: async (ctx) => {
+      const argsStr = ctx.args?.trim() ?? "";
+      if (!argsStr) return { text: CARD_USAGE };
+
+      const parsed = parseCardArgs(argsStr);
+      const { type, args, flags } = parsed;
+
+      if (!type) return { text: CARD_USAGE };
+
+      // Only LINE supports rich cards; fallback to text elsewhere.
+      if (ctx.channel !== "line") {
+        const fallbackText = args.join(" - ");
+        return { text: `[${type} card] ${fallbackText}`.trim() };
+      }
+
+      try {
+        switch (type) {
+          case "info": {
+            const [title = "Info", body = "", footer] = args;
+            const bubble = createInfoCard(title, body, footer);
+            return buildLineReply({
+              flexMessage: {
+                altText: `${title}: ${body}`.slice(0, 400),
+                contents: bubble,
+              },
+            });
+          }
+
+          case "image": {
+            const [title = "Image", caption = ""] = args;
+            const imageUrl = flags.url || flags.image;
+            if (!imageUrl) {
+              return { text: "Error: Image card requires --url <image-url>" };
+            }
+            const bubble = createImageCard(imageUrl, title, caption);
+            return buildLineReply({
+              flexMessage: {
+                altText: `${title}: ${caption}`.slice(0, 400),
+                contents: bubble,
+              },
+            });
+          }
+
+          case "action": {
+            const [title = "Actions", body = ""] = args;
+            const actions = parseActions(flags.actions);
+            if (actions.length === 0) {
+              return { text: 'Error: Action card requires --actions "Label1|data1,Label2|data2"' };
+            }
+            const bubble = createActionCard(title, body, actions, {
+              imageUrl: flags.url || flags.image,
+            });
+            return buildLineReply({
+              flexMessage: {
+                altText: `${title}: ${body}`.slice(0, 400),
+                contents: bubble,
+              },
+            });
+          }
+
+          case "list": {
+            const [title = "List", itemsStr = ""] = args;
+            const items = parseListItems(itemsStr || flags.items || "");
+            if (items.length === 0) {
+              return {
+                text:
+                  'Error: List card requires items. Usage: /card list "Title" "Item1|Desc1,Item2|Desc2"',
+              };
+            }
+            const bubble = createListCard(title, items);
+            return buildLineReply({
+              flexMessage: {
+                altText: `${title}: ${items.map((i) => i.title).join(", ")}`.slice(0, 400),
+                contents: bubble,
+              },
+            });
+          }
+
+          case "receipt": {
+            const [title = "Receipt", itemsStr = ""] = args;
+            const items = parseReceiptItems(itemsStr || flags.items || "");
+            const total = flags.total ? { label: "Total", value: flags.total } : undefined;
+            const footer = flags.footer;
+
+            if (items.length === 0) {
+              return {
+                text:
+                  'Error: Receipt card requires items. Usage: /card receipt "Title" "Item1:$10,Item2:$20" --total "$30"',
+              };
+            }
+
+            const bubble = createReceiptCard({ title, items, total, footer });
+            return buildLineReply({
+              flexMessage: {
+                altText: `${title}: ${items.map((i) => `${i.name} ${i.value}`).join(", ")}`.slice(
+                  0,
+                  400,
+                ),
+                contents: bubble,
+              },
+            });
+          }
+
+          case "confirm": {
+            const [question = "Confirm?"] = args;
+            const yesStr = flags.yes || "Yes|yes";
+            const noStr = flags.no || "No|no";
+
+            const [yesLabel, yesData] = yesStr.split("|").map((s) => s.trim());
+            const [noLabel, noData] = noStr.split("|").map((s) => s.trim());
+
+            return buildLineReply({
+              templateMessage: {
+                type: "confirm",
+                text: question,
+                confirmLabel: yesLabel || "Yes",
+                confirmData: yesData || "yes",
+                cancelLabel: noLabel || "No",
+                cancelData: noData || "no",
+                altText: question,
+              },
+            });
+          }
+
+          case "buttons": {
+            const [title = "Menu", text = "Choose an option"] = args;
+            const actionsStr = flags.actions || "";
+            const actionParts = parseActions(actionsStr);
+
+            if (actionParts.length === 0) {
+              return { text: 'Error: Buttons card requires --actions "Label1|data1,Label2|data2"' };
+            }
+
+            const templateActions: Array<{
+              type: "message" | "uri" | "postback";
+              label: string;
+              data?: string;
+              uri?: string;
+            }> = actionParts.map((a) => {
+              const action = a.action;
+              const label = action.label ?? a.label;
+              if (action.type === "uri") {
+                return { type: "uri" as const, label, uri: (action as { uri: string }).uri };
+              }
+              if (action.type === "postback") {
+                return {
+                  type: "postback" as const,
+                  label,
+                  data: (action as { data: string }).data,
+                };
+              }
+              return {
+                type: "message" as const,
+                label,
+                data: (action as { text: string }).text,
+              };
+            });
+
+            return buildLineReply({
+              templateMessage: {
+                type: "buttons",
+                title,
+                text,
+                thumbnailImageUrl: flags.url || flags.image,
+                actions: templateActions,
+              },
+            });
+          }
+
+          default:
+            return {
+              text: `Unknown card type: "${type}". Available types: info, image, action, list, receipt, confirm, buttons`,
+            };
+        }
+      } catch (err) {
+        return { text: `Error creating card: ${String(err)}` };
+      }
+    },
+  });
+}

docker-compose/ez-assistant/extensions/line/src/channel.logout.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MoltbotConfig, PluginRuntime } from "clawdbot/plugin-sdk";
+import { linePlugin } from "./channel.js";
+import { setLineRuntime } from "./runtime.js";
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+type LineRuntimeMocks = {
+  writeConfigFile: ReturnType<typeof vi.fn>;
+  resolveLineAccount: ReturnType<typeof vi.fn>;
+};
+
+function createRuntime(): { runtime: PluginRuntime; mocks: LineRuntimeMocks } {
+  const writeConfigFile = vi.fn(async () => {});
+  const resolveLineAccount = vi.fn(({ cfg, accountId }: { cfg: MoltbotConfig; accountId?: string }) => {
+    const lineConfig = (cfg.channels?.line ?? {}) as {
+      tokenFile?: string;
+      secretFile?: string;
+      channelAccessToken?: string;
+      channelSecret?: string;
+      accounts?: Record<string, Record<string, unknown>>;
+    };
+    const entry =
+      accountId && accountId !== DEFAULT_ACCOUNT_ID
+        ? lineConfig.accounts?.[accountId] ?? {}
+        : lineConfig;
+    const hasToken =
+      Boolean((entry as any).channelAccessToken) || Boolean((entry as any).tokenFile);
+    const hasSecret =
+      Boolean((entry as any).channelSecret) || Boolean((entry as any).secretFile);
+    return { tokenSource: hasToken && hasSecret ? "config" : "none" };
+  });
+
+  const runtime = {
+    config: { writeConfigFile },
+    channel: { line: { resolveLineAccount } },
+  } as unknown as PluginRuntime;
+
+  return { runtime, mocks: { writeConfigFile, resolveLineAccount } };
+}
+
+describe("linePlugin gateway.logoutAccount", () => {
+  beforeEach(() => {
+    setLineRuntime(createRuntime().runtime);
+  });
+
+  it("clears tokenFile/secretFile on default account logout", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+
+    const cfg: MoltbotConfig = {
+      channels: {
+        line: {
+          tokenFile: "/tmp/token",
+          secretFile: "/tmp/secret",
+        },
+      },
+    };
+
+    const result = await linePlugin.gateway.logoutAccount({
+      accountId: DEFAULT_ACCOUNT_ID,
+      cfg,
+    });
+
+    expect(result.cleared).toBe(true);
+    expect(result.loggedOut).toBe(true);
+    expect(mocks.writeConfigFile).toHaveBeenCalledWith({});
+  });
+
+  it("clears tokenFile/secretFile on account logout", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+
+    const cfg: MoltbotConfig = {
+      channels: {
+        line: {
+          accounts: {
+            primary: {
+              tokenFile: "/tmp/token",
+              secretFile: "/tmp/secret",
+            },
+          },
+        },
+      },
+    };
+
+    const result = await linePlugin.gateway.logoutAccount({
+      accountId: "primary",
+      cfg,
+    });
+
+    expect(result.cleared).toBe(true);
+    expect(result.loggedOut).toBe(true);
+    expect(mocks.writeConfigFile).toHaveBeenCalledWith({});
+  });
+});

docker-compose/ez-assistant/extensions/line/src/channel.sendPayload.test.ts

@@ -0,0 +1,308 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MoltbotConfig, PluginRuntime } from "clawdbot/plugin-sdk";
+import { linePlugin } from "./channel.js";
+import { setLineRuntime } from "./runtime.js";
+
+type LineRuntimeMocks = {
+  pushMessageLine: ReturnType<typeof vi.fn>;
+  pushMessagesLine: ReturnType<typeof vi.fn>;
+  pushFlexMessage: ReturnType<typeof vi.fn>;
+  pushTemplateMessage: ReturnType<typeof vi.fn>;
+  pushLocationMessage: ReturnType<typeof vi.fn>;
+  pushTextMessageWithQuickReplies: ReturnType<typeof vi.fn>;
+  createQuickReplyItems: ReturnType<typeof vi.fn>;
+  buildTemplateMessageFromPayload: ReturnType<typeof vi.fn>;
+  sendMessageLine: ReturnType<typeof vi.fn>;
+  chunkMarkdownText: ReturnType<typeof vi.fn>;
+  resolveLineAccount: ReturnType<typeof vi.fn>;
+  resolveTextChunkLimit: ReturnType<typeof vi.fn>;
+};
+
+function createRuntime(): { runtime: PluginRuntime; mocks: LineRuntimeMocks } {
+  const pushMessageLine = vi.fn(async () => ({ messageId: "m-text", chatId: "c1" }));
+  const pushMessagesLine = vi.fn(async () => ({ messageId: "m-batch", chatId: "c1" }));
+  const pushFlexMessage = vi.fn(async () => ({ messageId: "m-flex", chatId: "c1" }));
+  const pushTemplateMessage = vi.fn(async () => ({ messageId: "m-template", chatId: "c1" }));
+  const pushLocationMessage = vi.fn(async () => ({ messageId: "m-loc", chatId: "c1" }));
+  const pushTextMessageWithQuickReplies = vi.fn(async () => ({
+    messageId: "m-quick",
+    chatId: "c1",
+  }));
+  const createQuickReplyItems = vi.fn((labels: string[]) => ({ items: labels }));
+  const buildTemplateMessageFromPayload = vi.fn(() => ({ type: "buttons" }));
+  const sendMessageLine = vi.fn(async () => ({ messageId: "m-media", chatId: "c1" }));
+  const chunkMarkdownText = vi.fn((text: string) => [text]);
+  const resolveTextChunkLimit = vi.fn(() => 123);
+  const resolveLineAccount = vi.fn(({ cfg, accountId }: { cfg: MoltbotConfig; accountId?: string }) => {
+    const resolved = accountId ?? "default";
+    const lineConfig = (cfg.channels?.line ?? {}) as {
+      accounts?: Record<string, Record<string, unknown>>;
+    };
+    const accountConfig =
+      resolved !== "default" ? lineConfig.accounts?.[resolved] ?? {} : {};
+    return {
+      accountId: resolved,
+      config: { ...lineConfig, ...accountConfig },
+    };
+  });
+
+  const runtime = {
+    channel: {
+      line: {
+        pushMessageLine,
+        pushMessagesLine,
+        pushFlexMessage,
+        pushTemplateMessage,
+        pushLocationMessage,
+        pushTextMessageWithQuickReplies,
+        createQuickReplyItems,
+        buildTemplateMessageFromPayload,
+        sendMessageLine,
+        resolveLineAccount,
+      },
+      text: {
+        chunkMarkdownText,
+        resolveTextChunkLimit,
+      },
+    },
+  } as unknown as PluginRuntime;
+
+  return {
+    runtime,
+    mocks: {
+      pushMessageLine,
+      pushMessagesLine,
+      pushFlexMessage,
+      pushTemplateMessage,
+      pushLocationMessage,
+      pushTextMessageWithQuickReplies,
+      createQuickReplyItems,
+      buildTemplateMessageFromPayload,
+      sendMessageLine,
+      chunkMarkdownText,
+      resolveLineAccount,
+      resolveTextChunkLimit,
+    },
+  };
+}
+
+describe("linePlugin outbound.sendPayload", () => {
+  it("sends flex message without dropping text", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+    const cfg = { channels: { line: {} } } as MoltbotConfig;
+
+    const payload = {
+      text: "Now playing:",
+      channelData: {
+        line: {
+          flexMessage: {
+            altText: "Now playing",
+            contents: { type: "bubble" },
+          },
+        },
+      },
+    };
+
+    await linePlugin.outbound.sendPayload({
+      to: "line:group:1",
+      payload,
+      accountId: "default",
+      cfg,
+    });
+
+    expect(mocks.pushFlexMessage).toHaveBeenCalledTimes(1);
+    expect(mocks.pushMessageLine).toHaveBeenCalledWith("line:group:1", "Now playing:", {
+      verbose: false,
+      accountId: "default",
+    });
+  });
+
+  it("sends template message without dropping text", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+    const cfg = { channels: { line: {} } } as MoltbotConfig;
+
+    const payload = {
+      text: "Choose one:",
+      channelData: {
+        line: {
+          templateMessage: {
+            type: "confirm",
+            text: "Continue?",
+            confirmLabel: "Yes",
+            confirmData: "yes",
+            cancelLabel: "No",
+            cancelData: "no",
+          },
+        },
+      },
+    };
+
+    await linePlugin.outbound.sendPayload({
+      to: "line:user:1",
+      payload,
+      accountId: "default",
+      cfg,
+    });
+
+    expect(mocks.buildTemplateMessageFromPayload).toHaveBeenCalledTimes(1);
+    expect(mocks.pushTemplateMessage).toHaveBeenCalledTimes(1);
+    expect(mocks.pushMessageLine).toHaveBeenCalledWith("line:user:1", "Choose one:", {
+      verbose: false,
+      accountId: "default",
+    });
+  });
+
+  it("attaches quick replies when no text chunks are present", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+    const cfg = { channels: { line: {} } } as MoltbotConfig;
+
+    const payload = {
+      channelData: {
+        line: {
+          quickReplies: ["One", "Two"],
+          flexMessage: {
+            altText: "Card",
+            contents: { type: "bubble" },
+          },
+        },
+      },
+    };
+
+    await linePlugin.outbound.sendPayload({
+      to: "line:user:2",
+      payload,
+      accountId: "default",
+      cfg,
+    });
+
+    expect(mocks.pushFlexMessage).not.toHaveBeenCalled();
+    expect(mocks.pushMessagesLine).toHaveBeenCalledWith(
+      "line:user:2",
+      [
+        {
+          type: "flex",
+          altText: "Card",
+          contents: { type: "bubble" },
+          quickReply: { items: ["One", "Two"] },
+        },
+      ],
+      { verbose: false, accountId: "default" },
+    );
+    expect(mocks.createQuickReplyItems).toHaveBeenCalledWith(["One", "Two"]);
+  });
+
+  it("sends media before quick-reply text so buttons stay visible", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+    const cfg = { channels: { line: {} } } as MoltbotConfig;
+
+    const payload = {
+      text: "Hello",
+      mediaUrl: "https://example.com/img.jpg",
+      channelData: {
+        line: {
+          quickReplies: ["One", "Two"],
+        },
+      },
+    };
+
+    await linePlugin.outbound.sendPayload({
+      to: "line:user:3",
+      payload,
+      accountId: "default",
+      cfg,
+    });
+
+    expect(mocks.sendMessageLine).toHaveBeenCalledWith("line:user:3", "", {
+      verbose: false,
+      mediaUrl: "https://example.com/img.jpg",
+      accountId: "default",
+    });
+    expect(mocks.pushTextMessageWithQuickReplies).toHaveBeenCalledWith(
+      "line:user:3",
+      "Hello",
+      ["One", "Two"],
+      { verbose: false, accountId: "default" },
+    );
+    const mediaOrder = mocks.sendMessageLine.mock.invocationCallOrder[0];
+    const quickReplyOrder = mocks.pushTextMessageWithQuickReplies.mock.invocationCallOrder[0];
+    expect(mediaOrder).toBeLessThan(quickReplyOrder);
+  });
+
+  it("uses configured text chunk limit for payloads", async () => {
+    const { runtime, mocks } = createRuntime();
+    setLineRuntime(runtime);
+    const cfg = { channels: { line: { textChunkLimit: 123 } } } as MoltbotConfig;
+
+    const payload = {
+      text: "Hello world",
+      channelData: {
+        line: {
+          flexMessage: {
+            altText: "Card",
+            contents: { type: "bubble" },
+          },
+        },
+      },
+    };
+
+    await linePlugin.outbound.sendPayload({
+      to: "line:user:3",
+      payload,
+      accountId: "primary",
+      cfg,
+    });
+
+    expect(mocks.resolveTextChunkLimit).toHaveBeenCalledWith(
+      cfg,
+      "line",
+      "primary",
+      { fallbackLimit: 5000 },
+    );
+    expect(mocks.chunkMarkdownText).toHaveBeenCalledWith("Hello world", 123);
+  });
+});
+
+describe("linePlugin config.formatAllowFrom", () => {
+  it("strips line:user: prefixes without lowercasing", () => {
+    const formatted = linePlugin.config.formatAllowFrom({
+      allowFrom: ["line:user:UABC", "line:UDEF"],
+    });
+    expect(formatted).toEqual(["UABC", "UDEF"]);
+  });
+});
+
+describe("linePlugin groups.resolveRequireMention", () => {
+  it("uses account-level group settings when provided", () => {
+    const { runtime } = createRuntime();
+    setLineRuntime(runtime);
+
+    const cfg = {
+      channels: {
+        line: {
+          groups: {
+            "*": { requireMention: false },
+          },
+          accounts: {
+            primary: {
+              groups: {
+                "group-1": { requireMention: true },
+              },
+            },
+          },
+        },
+      },
+    } as MoltbotConfig;
+
+    const requireMention = linePlugin.groups.resolveRequireMention({
+      cfg,
+      accountId: "primary",
+      groupId: "group-1",
+    });
+
+    expect(requireMention).toBe(true);
+  });
+});

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

@@ -0,0 +1,773 @@
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  LineConfigSchema,
+  processLineMessage,
+  type ChannelPlugin,
+  type MoltbotConfig,
+  type LineConfig,
+  type LineChannelData,
+  type ResolvedLineAccount,
+} from "clawdbot/plugin-sdk";
+
+import { getLineRuntime } from "./runtime.js";
+
+// LINE channel metadata
+const meta = {
+  id: "line",
+  label: "LINE",
+  selectionLabel: "LINE (Messaging API)",
+  detailLabel: "LINE Bot",
+  docsPath: "/channels/line",
+  docsLabel: "line",
+  blurb: "LINE Messaging API bot for Japan/Taiwan/Thailand markets.",
+  systemImage: "message.fill",
+};
+
+function parseThreadId(threadId?: string | number | null): number | undefined {
+  if (threadId == null) return undefined;
+  if (typeof threadId === "number") {
+    return Number.isFinite(threadId) ? Math.trunc(threadId) : undefined;
+  }
+  const trimmed = threadId.trim();
+  if (!trimmed) return undefined;
+  const parsed = Number.parseInt(trimmed, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export const linePlugin: ChannelPlugin<ResolvedLineAccount> = {
+  id: "line",
+  meta: {
+    ...meta,
+    quickstartAllowFrom: true,
+  },
+  pairing: {
+    idLabel: "lineUserId",
+    normalizeAllowEntry: (entry) => {
+      // LINE IDs are case-sensitive; only strip prefix variants (line: / line:user:).
+      return entry.replace(/^line:(?:user:)?/i, "");
+    },
+    notifyApproval: async ({ cfg, id }) => {
+      const line = getLineRuntime().channel.line;
+      const account = line.resolveLineAccount({ cfg });
+      if (!account.channelAccessToken) {
+        throw new Error("LINE channel access token not configured");
+      }
+      await line.pushMessageLine(id, "Moltbot: your access has been approved.", {
+        channelAccessToken: account.channelAccessToken,
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    reactions: false,
+    threads: false,
+    media: true,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.line"] },
+  configSchema: buildChannelConfigSchema(LineConfigSchema),
+  config: {
+    listAccountIds: (cfg) => getLineRuntime().channel.line.listLineAccountIds(cfg),
+    resolveAccount: (cfg, accountId) =>
+      getLineRuntime().channel.line.resolveLineAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => getLineRuntime().channel.line.resolveDefaultLineAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const lineConfig = (cfg.channels?.line ?? {}) as LineConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            line: {
+              ...lineConfig,
+              enabled,
+            },
+          },
+        };
+      }
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          line: {
+            ...lineConfig,
+            accounts: {
+              ...lineConfig.accounts,
+              [accountId]: {
+                ...lineConfig.accounts?.[accountId],
+                enabled,
+              },
+            },
+          },
+        },
+      };
+    },
+    deleteAccount: ({ cfg, accountId }) => {
+      const lineConfig = (cfg.channels?.line ?? {}) as LineConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        const { channelAccessToken, channelSecret, tokenFile, secretFile, ...rest } = lineConfig;
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            line: rest,
+          },
+        };
+      }
+      const accounts = { ...lineConfig.accounts };
+      delete accounts[accountId];
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          line: {
+            ...lineConfig,
+            accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+          },
+        },
+      };
+    },
+    isConfigured: (account) => Boolean(account.channelAccessToken?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.channelAccessToken?.trim()),
+      tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (getLineRuntime().channel.line.resolveLineAccount({ cfg, accountId }).config.allowFrom ?? []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => {
+          // LINE sender IDs are case-sensitive; keep original casing.
+          return entry.replace(/^line:(?:user:)?/i, "");
+        }),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(
+        (cfg.channels?.line as LineConfig | undefined)?.accounts?.[resolvedAccountId],
+      );
+      const basePath = useAccountPath
+        ? `channels.line.accounts.${resolvedAccountId}.`
+        : "channels.line.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: "moltbot pairing approve line <code>",
+        normalizeEntry: (raw) => raw.replace(/^line:(?:user:)?/i, ""),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy =
+        (cfg.channels?.defaults as { groupPolicy?: string } | undefined)?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- LINE groups: groupPolicy="open" allows any member in groups to trigger. Set channels.line.groupPolicy="allowlist" + channels.line.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: ({ cfg, accountId, groupId }) => {
+      const account = getLineRuntime().channel.line.resolveLineAccount({ cfg, accountId });
+      const groups = account.config.groups;
+      if (!groups) return false;
+      const groupConfig = groups[groupId] ?? groups["*"];
+      return groupConfig?.requireMention ?? false;
+    },
+  },
+  messaging: {
+    normalizeTarget: (target) => {
+      const trimmed = target.trim();
+      if (!trimmed) return null;
+      return trimmed.replace(/^line:(group|room|user):/i, "").replace(/^line:/i, "");
+    },
+    targetResolver: {
+      looksLikeId: (id) => {
+        const trimmed = id?.trim();
+        if (!trimmed) return false;
+        // LINE user IDs are typically U followed by 32 hex characters
+        // Group IDs are C followed by 32 hex characters
+        // Room IDs are R followed by 32 hex characters
+        return /^[UCR][a-f0-9]{32}$/i.test(trimmed) || /^line:/i.test(trimmed);
+      },
+      hint: "<userId|groupId|roomId>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async () => [],
+    listGroups: async () => [],
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) =>
+      getLineRuntime().channel.line.normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) => {
+      const lineConfig = (cfg.channels?.line ?? {}) as LineConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            line: {
+              ...lineConfig,
+              name,
+            },
+          },
+        };
+      }
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          line: {
+            ...lineConfig,
+            accounts: {
+              ...lineConfig.accounts,
+              [accountId]: {
+                ...lineConfig.accounts?.[accountId],
+                name,
+              },
+            },
+          },
+        },
+      };
+    },
+    validateInput: ({ accountId, input }) => {
+      const typedInput = input as {
+        useEnv?: boolean;
+        channelAccessToken?: string;
+        channelSecret?: string;
+        tokenFile?: string;
+        secretFile?: string;
+      };
+      if (typedInput.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "LINE_CHANNEL_ACCESS_TOKEN can only be used for the default account.";
+      }
+      if (!typedInput.useEnv && !typedInput.channelAccessToken && !typedInput.tokenFile) {
+        return "LINE requires channelAccessToken or --token-file (or --use-env).";
+      }
+      if (!typedInput.useEnv && !typedInput.channelSecret && !typedInput.secretFile) {
+        return "LINE requires channelSecret or --secret-file (or --use-env).";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const typedInput = input as {
+        name?: string;
+        useEnv?: boolean;
+        channelAccessToken?: string;
+        channelSecret?: string;
+        tokenFile?: string;
+        secretFile?: string;
+      };
+      const lineConfig = (cfg.channels?.line ?? {}) as LineConfig;
+
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            line: {
+              ...lineConfig,
+              enabled: true,
+              ...(typedInput.name ? { name: typedInput.name } : {}),
+              ...(typedInput.useEnv
+                ? {}
+                : typedInput.tokenFile
+                  ? { tokenFile: typedInput.tokenFile }
+                  : typedInput.channelAccessToken
+                    ? { channelAccessToken: typedInput.channelAccessToken }
+                    : {}),
+              ...(typedInput.useEnv
+                ? {}
+                : typedInput.secretFile
+                  ? { secretFile: typedInput.secretFile }
+                  : typedInput.channelSecret
+                    ? { channelSecret: typedInput.channelSecret }
+                    : {}),
+            },
+          },
+        };
+      }
+
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          line: {
+            ...lineConfig,
+            enabled: true,
+            accounts: {
+              ...lineConfig.accounts,
+              [accountId]: {
+                ...lineConfig.accounts?.[accountId],
+                enabled: true,
+                ...(typedInput.name ? { name: typedInput.name } : {}),
+                ...(typedInput.tokenFile
+                  ? { tokenFile: typedInput.tokenFile }
+                  : typedInput.channelAccessToken
+                    ? { channelAccessToken: typedInput.channelAccessToken }
+                    : {}),
+                ...(typedInput.secretFile
+                  ? { secretFile: typedInput.secretFile }
+                  : typedInput.channelSecret
+                    ? { channelSecret: typedInput.channelSecret }
+                    : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getLineRuntime().channel.text.chunkMarkdownText(text, limit),
+    textChunkLimit: 5000, // LINE allows up to 5000 characters per text message
+    sendPayload: async ({ to, payload, accountId, cfg }) => {
+      const runtime = getLineRuntime();
+      const lineData = (payload.channelData?.line as LineChannelData | undefined) ?? {};
+      const sendText = runtime.channel.line.pushMessageLine;
+      const sendBatch = runtime.channel.line.pushMessagesLine;
+      const sendFlex = runtime.channel.line.pushFlexMessage;
+      const sendTemplate = runtime.channel.line.pushTemplateMessage;
+      const sendLocation = runtime.channel.line.pushLocationMessage;
+      const sendQuickReplies = runtime.channel.line.pushTextMessageWithQuickReplies;
+      const buildTemplate = runtime.channel.line.buildTemplateMessageFromPayload;
+      const createQuickReplyItems = runtime.channel.line.createQuickReplyItems;
+
+      let lastResult: { messageId: string; chatId: string } | null = null;
+      const hasQuickReplies = Boolean(lineData.quickReplies?.length);
+      const quickReply = hasQuickReplies
+        ? createQuickReplyItems(lineData.quickReplies!)
+        : undefined;
+
+      const sendMessageBatch = async (messages: Array<Record<string, unknown>>) => {
+        if (messages.length === 0) return;
+        for (let i = 0; i < messages.length; i += 5) {
+          const result = await sendBatch(to, messages.slice(i, i + 5), {
+            verbose: false,
+            accountId: accountId ?? undefined,
+          });
+          lastResult = { messageId: result.messageId, chatId: result.chatId };
+        }
+      };
+
+      const processed = payload.text
+        ? processLineMessage(payload.text)
+        : { text: "", flexMessages: [] };
+
+      const chunkLimit =
+        runtime.channel.text.resolveTextChunkLimit?.(
+          cfg,
+          "line",
+          accountId ?? undefined,
+          {
+            fallbackLimit: 5000,
+          },
+        ) ?? 5000;
+
+      const chunks = processed.text
+        ? runtime.channel.text.chunkMarkdownText(processed.text, chunkLimit)
+        : [];
+      const mediaUrls = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
+      const shouldSendQuickRepliesInline = chunks.length === 0 && hasQuickReplies;
+
+      if (!shouldSendQuickRepliesInline) {
+        if (lineData.flexMessage) {
+          lastResult = await sendFlex(
+            to,
+            lineData.flexMessage.altText,
+            lineData.flexMessage.contents,
+            {
+              verbose: false,
+              accountId: accountId ?? undefined,
+            },
+          );
+        }
+
+        if (lineData.templateMessage) {
+          const template = buildTemplate(lineData.templateMessage);
+          if (template) {
+            lastResult = await sendTemplate(to, template, {
+              verbose: false,
+              accountId: accountId ?? undefined,
+            });
+          }
+        }
+
+        if (lineData.location) {
+          lastResult = await sendLocation(to, lineData.location, {
+            verbose: false,
+            accountId: accountId ?? undefined,
+          });
+        }
+
+        for (const flexMsg of processed.flexMessages) {
+          lastResult = await sendFlex(to, flexMsg.altText, flexMsg.contents, {
+            verbose: false,
+            accountId: accountId ?? undefined,
+          });
+        }
+      }
+
+      const sendMediaAfterText = !(hasQuickReplies && chunks.length > 0);
+      if (mediaUrls.length > 0 && !shouldSendQuickRepliesInline && !sendMediaAfterText) {
+        for (const url of mediaUrls) {
+          lastResult = await runtime.channel.line.sendMessageLine(to, "", {
+            verbose: false,
+            mediaUrl: url,
+            accountId: accountId ?? undefined,
+          });
+        }
+      }
+
+      if (chunks.length > 0) {
+        for (let i = 0; i < chunks.length; i += 1) {
+          const isLast = i === chunks.length - 1;
+          if (isLast && hasQuickReplies) {
+            lastResult = await sendQuickReplies(to, chunks[i]!, lineData.quickReplies!, {
+              verbose: false,
+              accountId: accountId ?? undefined,
+            });
+          } else {
+            lastResult = await sendText(to, chunks[i]!, {
+              verbose: false,
+              accountId: accountId ?? undefined,
+            });
+          }
+        }
+      } else if (shouldSendQuickRepliesInline) {
+        const quickReplyMessages: Array<Record<string, unknown>> = [];
+        if (lineData.flexMessage) {
+          quickReplyMessages.push({
+            type: "flex",
+            altText: lineData.flexMessage.altText.slice(0, 400),
+            contents: lineData.flexMessage.contents,
+          });
+        }
+        if (lineData.templateMessage) {
+          const template = buildTemplate(lineData.templateMessage);
+          if (template) {
+            quickReplyMessages.push(template);
+          }
+        }
+        if (lineData.location) {
+          quickReplyMessages.push({
+            type: "location",
+            title: lineData.location.title.slice(0, 100),
+            address: lineData.location.address.slice(0, 100),
+            latitude: lineData.location.latitude,
+            longitude: lineData.location.longitude,
+          });
+        }
+        for (const flexMsg of processed.flexMessages) {
+          quickReplyMessages.push({
+            type: "flex",
+            altText: flexMsg.altText.slice(0, 400),
+            contents: flexMsg.contents,
+          });
+        }
+        for (const url of mediaUrls) {
+          const trimmed = url?.trim();
+          if (!trimmed) continue;
+          quickReplyMessages.push({
+            type: "image",
+            originalContentUrl: trimmed,
+            previewImageUrl: trimmed,
+          });
+        }
+        if (quickReplyMessages.length > 0 && quickReply) {
+          const lastIndex = quickReplyMessages.length - 1;
+          quickReplyMessages[lastIndex] = {
+            ...quickReplyMessages[lastIndex],
+            quickReply,
+          };
+          await sendMessageBatch(quickReplyMessages);
+        }
+      }
+
+      if (mediaUrls.length > 0 && !shouldSendQuickRepliesInline && sendMediaAfterText) {
+        for (const url of mediaUrls) {
+          lastResult = await runtime.channel.line.sendMessageLine(to, "", {
+            verbose: false,
+            mediaUrl: url,
+            accountId: accountId ?? undefined,
+          });
+        }
+      }
+
+      if (lastResult) return { channel: "line", ...lastResult };
+      return { channel: "line", messageId: "empty", chatId: to };
+    },
+    sendText: async ({ to, text, accountId }) => {
+      const runtime = getLineRuntime();
+      const sendText = runtime.channel.line.pushMessageLine;
+      const sendFlex = runtime.channel.line.pushFlexMessage;
+
+      // Process markdown: extract tables/code blocks, strip formatting
+      const processed = processLineMessage(text);
+
+      // Send cleaned text first (if non-empty)
+      let result: { messageId: string; chatId: string };
+      if (processed.text.trim()) {
+        result = await sendText(to, processed.text, {
+          verbose: false,
+          accountId: accountId ?? undefined,
+        });
+      } else {
+        // If text is empty after processing, still need a result
+        result = { messageId: "processed", chatId: to };
+      }
+
+      // Send flex messages for tables/code blocks
+      for (const flexMsg of processed.flexMessages) {
+        await sendFlex(to, flexMsg.altText, flexMsg.contents, {
+          verbose: false,
+          accountId: accountId ?? undefined,
+        });
+      }
+
+      return { channel: "line", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId }) => {
+      const send = getLineRuntime().channel.line.sendMessageLine;
+      const result = await send(to, text, {
+        verbose: false,
+        mediaUrl,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "line", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: ({ account }) => {
+      const issues: Array<{ level: "error" | "warning"; message: string }> = [];
+      if (!account.channelAccessToken?.trim()) {
+        issues.push({
+          level: "error",
+          message: "LINE channel access token not configured",
+        });
+      }
+      if (!account.channelSecret?.trim()) {
+        issues.push({
+          level: "error",
+          message: "LINE channel secret not configured",
+        });
+      }
+      return issues;
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      mode: snapshot.mode ?? null,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) =>
+      getLineRuntime().channel.line.probeLineBot(account.channelAccessToken, timeoutMs),
+    buildAccountSnapshot: ({ account, runtime, probe }) => {
+      const configured = Boolean(account.channelAccessToken?.trim());
+      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,
+        mode: "webhook",
+        probe,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const token = account.channelAccessToken.trim();
+      const secret = account.channelSecret.trim();
+
+      let lineBotLabel = "";
+      try {
+        const probe = await getLineRuntime().channel.line.probeLineBot(token, 2500);
+        const displayName = probe.ok ? probe.bot?.displayName?.trim() : null;
+        if (displayName) lineBotLabel = ` (${displayName})`;
+      } catch (err) {
+        if (getLineRuntime().logging.shouldLogVerbose()) {
+          ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`);
+        }
+      }
+
+      ctx.log?.info(`[${account.accountId}] starting LINE provider${lineBotLabel}`);
+
+      return getLineRuntime().channel.line.monitorLineProvider({
+        channelAccessToken: token,
+        channelSecret: secret,
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        webhookPath: account.config.webhookPath,
+      });
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+      const envToken = process.env.LINE_CHANNEL_ACCESS_TOKEN?.trim() ?? "";
+      const nextCfg = { ...cfg } as MoltbotConfig;
+      const lineConfig = (cfg.channels?.line ?? {}) as LineConfig;
+      const nextLine = { ...lineConfig };
+      let cleared = false;
+      let changed = false;
+
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        if (
+          nextLine.channelAccessToken ||
+          nextLine.channelSecret ||
+          nextLine.tokenFile ||
+          nextLine.secretFile
+        ) {
+          delete nextLine.channelAccessToken;
+          delete nextLine.channelSecret;
+          delete nextLine.tokenFile;
+          delete nextLine.secretFile;
+          cleared = true;
+          changed = true;
+        }
+      }
+
+      const accounts = nextLine.accounts ? { ...nextLine.accounts } : undefined;
+      if (accounts && accountId in accounts) {
+        const entry = accounts[accountId];
+        if (entry && typeof entry === "object") {
+          const nextEntry = { ...entry } as Record<string, unknown>;
+          if (
+            "channelAccessToken" in nextEntry ||
+            "channelSecret" in nextEntry ||
+            "tokenFile" in nextEntry ||
+            "secretFile" in nextEntry
+          ) {
+            cleared = true;
+            delete nextEntry.channelAccessToken;
+            delete nextEntry.channelSecret;
+            delete nextEntry.tokenFile;
+            delete nextEntry.secretFile;
+            changed = true;
+          }
+          if (Object.keys(nextEntry).length === 0) {
+            delete accounts[accountId];
+            changed = true;
+          } else {
+            accounts[accountId] = nextEntry as typeof entry;
+          }
+        }
+      }
+
+      if (accounts) {
+        if (Object.keys(accounts).length === 0) {
+          delete nextLine.accounts;
+          changed = true;
+        } else {
+          nextLine.accounts = accounts;
+        }
+      }
+
+      if (changed) {
+        if (Object.keys(nextLine).length > 0) {
+          nextCfg.channels = { ...nextCfg.channels, line: nextLine };
+        } else {
+          const nextChannels = { ...nextCfg.channels };
+          delete (nextChannels as Record<string, unknown>).line;
+          if (Object.keys(nextChannels).length > 0) {
+            nextCfg.channels = nextChannels;
+          } else {
+            delete nextCfg.channels;
+          }
+        }
+        await getLineRuntime().config.writeConfigFile(nextCfg);
+      }
+
+      const resolved = getLineRuntime().channel.line.resolveLineAccount({
+        cfg: changed ? nextCfg : cfg,
+        accountId,
+      });
+      const loggedOut = resolved.tokenSource === "none";
+
+      return { cleared, envToken: Boolean(envToken), loggedOut };
+    },
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "",
+      "### LINE Rich Messages",
+      "LINE supports rich visual messages. Use these directives in your reply when appropriate:",
+      "",
+      "**Quick Replies** (bottom button suggestions):",
+      "  [[quick_replies: Option 1, Option 2, Option 3]]",
+      "",
+      "**Location** (map pin):",
+      "  [[location: Place Name | Address | latitude | longitude]]",
+      "",
+      "**Confirm Dialog** (yes/no prompt):",
+      "  [[confirm: Question text? | Yes Label | No Label]]",
+      "",
+      "**Button Menu** (title + text + buttons):",
+      "  [[buttons: Title | Description | Btn1:action1, Btn2:https://url.com]]",
+      "",
+      "**Media Player Card** (music status):",
+      "  [[media_player: Song Title | Artist Name | Source | https://albumart.url | playing]]",
+      "  - Status: 'playing' or 'paused' (optional)",
+      "",
+      "**Event Card** (calendar events, meetings):",
+      "  [[event: Event Title | Date | Time | Location | Description]]",
+      "  - Time, Location, Description are optional",
+      "",
+      "**Agenda Card** (multiple events/schedule):",
+      "  [[agenda: Schedule Title | Event1:9:00 AM, Event2:12:00 PM, Event3:3:00 PM]]",
+      "",
+      "**Device Control Card** (smart devices, TVs, etc.):",
+      "  [[device: Device Name | Device Type | Status | Control1:data1, Control2:data2]]",
+      "",
+      "**Apple TV Remote** (full D-pad + transport):",
+      "  [[appletv_remote: Apple TV | Playing]]",
+      "",
+      "**Auto-converted**: Markdown tables become Flex cards, code blocks become styled cards.",
+      "",
+      "When to use rich messages:",
+      "- Use [[quick_replies:...]] when offering 2-4 clear options",
+      "- Use [[confirm:...]] for yes/no decisions",
+      "- Use [[buttons:...]] for menus with actions/links",
+      "- Use [[location:...]] when sharing a place",
+      "- Use [[media_player:...]] when showing what's playing",
+      "- Use [[event:...]] for calendar event details",
+      "- Use [[agenda:...]] for a day's schedule or event list",
+      "- Use [[device:...]] for smart device status/controls",
+      "- Tables/code in your response auto-convert to visual cards",
+    ],
+  },
+};

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

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

docker-compose/ez-assistant/extensions/llm-task/README.md

@@ -0,0 +1,97 @@
+# LLM Task (plugin)
+
+Adds an **optional** agent tool `llm-task` for running **JSON-only** LLM tasks
+(drafting, summarizing, classifying) with optional JSON Schema validation.
+
+Designed to be called from workflow engines (for example, Lobster via
+`clawd.invoke --each`) without adding new Clawdbot code per workflow.
+
+## Enable
+
+1) Enable the plugin:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  }
+}
+```
+
+2) Allowlist the tool (it is registered with `optional: true`):
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "allow": ["llm-task"] }
+      }
+    ]
+  }
+}
+```
+
+## Config (optional)
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": {
+        "enabled": true,
+        "config": {
+          "defaultProvider": "openai-codex",
+          "defaultModel": "gpt-5.2",
+          "defaultAuthProfileId": "main",
+          "allowedModels": ["openai-codex/gpt-5.2"],
+          "maxTokens": 800,
+          "timeoutMs": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+`allowedModels` is an allowlist of `provider/model` strings. If set, any request
+outside the list is rejected.
+
+## Tool API
+
+### Parameters
+
+- `prompt` (string, required)
+- `input` (any, optional)
+- `schema` (object, optional JSON Schema)
+- `provider` (string, optional)
+- `model` (string, optional)
+- `authProfileId` (string, optional)
+- `temperature` (number, optional)
+- `maxTokens` (number, optional)
+- `timeoutMs` (number, optional)
+
+### Output
+
+Returns `details.json` containing the parsed JSON (and validates against
+`schema` when provided).
+
+## Notes
+
+- The tool is **JSON-only** and instructs the model to output only JSON
+  (no code fences, no commentary).
+- No tools are exposed to the model for this run.
+- Side effects should be handled outside this tool (for example, approvals in
+  Lobster) before calling tools that send messages/emails.
+
+## Bundled extension note
+
+This extension depends on Clawdbot internal modules (the embedded agent runner).
+It is intended to ship as a **bundled** Clawdbot extension (like `lobster`) and
+be enabled via `plugins.entries` + tool allowlists.
+
+It is **not** currently designed to be copied into
+`~/.clawdbot/extensions` as a standalone plugin directory.

docker-compose/ez-assistant/extensions/llm-task/clawdbot.plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "llm-task",
+  "name": "LLM Task",
+  "description": "Generic JSON-only LLM tool for structured tasks callable from workflows.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "defaultProvider": { "type": "string" },
+      "defaultModel": { "type": "string" },
+      "defaultAuthProfileId": { "type": "string" },
+      "allowedModels": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Allowlist of provider/model keys like openai-codex/gpt-5.2."
+      },
+      "maxTokens": { "type": "number" },
+      "timeoutMs": { "type": "number" }
+    }
+  }
+}

docker-compose/ez-assistant/extensions/llm-task/index.ts

@@ -0,0 +1,7 @@
+import type { MoltbotPluginApi } from "../../src/plugins/types.js";
+
+import { createLlmTaskTool } from "./src/llm-task-tool.js";
+
+export default function register(api: MoltbotPluginApi) {
+  api.registerTool(createLlmTaskTool(api), { optional: true });
+}

docker-compose/ez-assistant/extensions/llm-task/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/llm-task",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot JSON-only LLM task plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

docker-compose/ez-assistant/extensions/llm-task/src/llm-task-tool.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../../src/agents/pi-embedded-runner.js", () => {
+  return {
+    runEmbeddedPiAgent: vi.fn(async () => ({
+      meta: { startedAt: Date.now() },
+      payloads: [{ text: "{}" }],
+    })),
+  };
+});
+
+import { runEmbeddedPiAgent } from "../../../src/agents/pi-embedded-runner.js";
+import { createLlmTaskTool } from "./llm-task-tool.js";
+
+function fakeApi(overrides: any = {}) {
+  return {
+    id: "llm-task",
+    name: "llm-task",
+    source: "test",
+    config: { agents: { defaults: { workspace: "/tmp", model: { primary: "openai-codex/gpt-5.2" } } } },
+    pluginConfig: {},
+    runtime: { version: "test" },
+    logger: { debug() {}, info() {}, warn() {}, error() {} },
+    registerTool() {},
+    ...overrides,
+  };
+}
+
+describe("llm-task tool (json-only)", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns parsed json", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: "bar" }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    const res = await tool.execute("id", { prompt: "return foo" });
+    expect((res as any).details.json).toEqual({ foo: "bar" });
+  });
+
+  it("strips fenced json", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: "```json\n{\"ok\":true}\n```" }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    const res = await tool.execute("id", { prompt: "return ok" });
+    expect((res as any).details.json).toEqual({ ok: true });
+  });
+
+  it("validates schema", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: "bar" }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    const schema = {
+      type: "object",
+      properties: { foo: { type: "string" } },
+      required: ["foo"],
+      additionalProperties: false,
+    };
+    const res = await tool.execute("id", { prompt: "return foo", schema });
+    expect((res as any).details.json).toEqual({ foo: "bar" });
+  });
+
+  it("throws on invalid json", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({ meta: {}, payloads: [{ text: "not-json" }] });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    await expect(tool.execute("id", { prompt: "x" })).rejects.toThrow(/invalid json/i);
+  });
+
+  it("throws on schema mismatch", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: 1 }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    const schema = { type: "object", properties: { foo: { type: "string" } }, required: ["foo"] };
+    await expect(tool.execute("id", { prompt: "x", schema })).rejects.toThrow(/match schema/i);
+  });
+
+  it("passes provider/model overrides to embedded runner", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ ok: true }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    await tool.execute("id", { prompt: "x", provider: "anthropic", model: "claude-4-sonnet" });
+    const call = (runEmbeddedPiAgent as any).mock.calls[0]?.[0];
+    expect(call.provider).toBe("anthropic");
+    expect(call.model).toBe("claude-4-sonnet");
+  });
+
+  it("enforces allowedModels", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ ok: true }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi({ pluginConfig: { allowedModels: ["openai-codex/gpt-5.2"] } }) as any);
+    await expect(tool.execute("id", { prompt: "x", provider: "anthropic", model: "claude-4-sonnet" })).rejects.toThrow(
+      /not allowed/i,
+    );
+  });
+
+  it("disables tools for embedded run", async () => {
+    (runEmbeddedPiAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ ok: true }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi() as any);
+    await tool.execute("id", { prompt: "x" });
+    const call = (runEmbeddedPiAgent as any).mock.calls[0]?.[0];
+    expect(call.disableTools).toBe(true);
+  });
+});

docker-compose/ez-assistant/extensions/llm-task/src/llm-task-tool.ts

@@ -0,0 +1,218 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import Ajv from "ajv";
+import { Type } from "@sinclair/typebox";
+
+// NOTE: This extension is intended to be bundled with Moltbot.
+// When running from source (tests/dev), Moltbot internals live under src/.
+// When running from a built install, internals live under dist/ (no src/ tree).
+// So we resolve internal imports dynamically with src-first, dist-fallback.
+
+import type { MoltbotPluginApi } from "../../../src/plugins/types.js";
+
+type RunEmbeddedPiAgentFn = (params: Record<string, unknown>) => Promise<unknown>;
+
+async function loadRunEmbeddedPiAgent(): Promise<RunEmbeddedPiAgentFn> {
+  // Source checkout (tests/dev)
+  try {
+    const mod = await import("../../../src/agents/pi-embedded-runner.js");
+    if (typeof (mod as any).runEmbeddedPiAgent === "function") return (mod as any).runEmbeddedPiAgent;
+  } catch {
+    // ignore
+  }
+
+  // Bundled install (built)
+  const mod = await import("../../../agents/pi-embedded-runner.js");
+  if (typeof (mod as any).runEmbeddedPiAgent !== "function") {
+    throw new Error("Internal error: runEmbeddedPiAgent not available");
+  }
+  return (mod as any).runEmbeddedPiAgent;
+}
+
+function stripCodeFences(s: string): string {
+  const trimmed = s.trim();
+  const m = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (m) return (m[1] ?? "").trim();
+  return trimmed;
+}
+
+function collectText(payloads: Array<{ text?: string; isError?: boolean }> | undefined): string {
+  const texts = (payloads ?? [])
+    .filter((p) => !p.isError && typeof p.text === "string")
+    .map((p) => p.text ?? "");
+  return texts.join("\n").trim();
+}
+
+function toModelKey(provider?: string, model?: string): string | undefined {
+  const p = provider?.trim();
+  const m = model?.trim();
+  if (!p || !m) return undefined;
+  return `${p}/${m}`;
+}
+
+type PluginCfg = {
+  defaultProvider?: string;
+  defaultModel?: string;
+  defaultAuthProfileId?: string;
+  allowedModels?: string[];
+  maxTokens?: number;
+  timeoutMs?: number;
+};
+
+export function createLlmTaskTool(api: MoltbotPluginApi) {
+  return {
+    name: "llm-task",
+    description:
+      "Run a generic JSON-only LLM task and return schema-validated JSON. Designed for orchestration from Lobster workflows via clawd.invoke.",
+    parameters: Type.Object({
+      prompt: Type.String({ description: "Task instruction for the LLM." }),
+      input: Type.Optional(Type.Unknown({ description: "Optional input payload for the task." })),
+      schema: Type.Optional(Type.Unknown({ description: "Optional JSON Schema to validate the returned JSON." })),
+      provider: Type.Optional(Type.String({ description: "Provider override (e.g. openai-codex, anthropic)." })),
+      model: Type.Optional(Type.String({ description: "Model id override." })),
+      authProfileId: Type.Optional(Type.String({ description: "Auth profile override." })),
+      temperature: Type.Optional(Type.Number({ description: "Best-effort temperature override." })),
+      maxTokens: Type.Optional(Type.Number({ description: "Best-effort maxTokens override." })),
+      timeoutMs: Type.Optional(Type.Number({ description: "Timeout for the LLM run." })),
+    }),
+
+    async execute(_id: string, params: Record<string, unknown>) {
+      const prompt = String(params.prompt ?? "");
+      if (!prompt.trim()) throw new Error("prompt required");
+
+      const pluginCfg = (api.pluginConfig ?? {}) as PluginCfg;
+
+      const primary = api.config?.agents?.defaults?.model?.primary;
+      const primaryProvider = typeof primary === "string" ? primary.split("/")[0] : undefined;
+      const primaryModel = typeof primary === "string" ? primary.split("/").slice(1).join("/") : undefined;
+
+      const provider =
+        (typeof params.provider === "string" && params.provider.trim()) ||
+        (typeof pluginCfg.defaultProvider === "string" && pluginCfg.defaultProvider.trim()) ||
+        primaryProvider ||
+        undefined;
+
+      const model =
+        (typeof params.model === "string" && params.model.trim()) ||
+        (typeof pluginCfg.defaultModel === "string" && pluginCfg.defaultModel.trim()) ||
+        primaryModel ||
+        undefined;
+
+      const authProfileId =
+        (typeof (params as any).authProfileId === "string" && (params as any).authProfileId.trim()) ||
+        (typeof pluginCfg.defaultAuthProfileId === "string" && pluginCfg.defaultAuthProfileId.trim()) ||
+        undefined;
+
+      const modelKey = toModelKey(provider, model);
+      if (!provider || !model || !modelKey) {
+        throw new Error(
+          `provider/model could not be resolved (provider=${String(provider ?? "")}, model=${String(model ?? "")})`,
+        );
+      }
+
+      const allowed = Array.isArray(pluginCfg.allowedModels) ? pluginCfg.allowedModels : undefined;
+      if (allowed && allowed.length > 0 && !allowed.includes(modelKey)) {
+        throw new Error(
+          `Model not allowed by llm-task plugin config: ${modelKey}. Allowed models: ${allowed.join(", ")}`,
+        );
+      }
+
+      const timeoutMs =
+        (typeof params.timeoutMs === "number" && params.timeoutMs > 0 ? params.timeoutMs : undefined) ||
+        (typeof pluginCfg.timeoutMs === "number" && pluginCfg.timeoutMs > 0 ? pluginCfg.timeoutMs : undefined) ||
+        30_000;
+
+      const streamParams = {
+        temperature: typeof params.temperature === "number" ? params.temperature : undefined,
+        maxTokens:
+          typeof params.maxTokens === "number"
+            ? params.maxTokens
+            : typeof pluginCfg.maxTokens === "number"
+              ? pluginCfg.maxTokens
+              : undefined,
+      };
+
+      const input = (params as any).input as unknown;
+      let inputJson: string;
+      try {
+        inputJson = JSON.stringify(input ?? null, null, 2);
+      } catch {
+        throw new Error("input must be JSON-serializable");
+      }
+
+      const system = [
+        "You are a JSON-only function.",
+        "Return ONLY a valid JSON value.",
+        "Do not wrap in markdown fences.",
+        "Do not include commentary.",
+        "Do not call tools.",
+      ].join(" ");
+
+      const fullPrompt = `${system}\n\nTASK:\n${prompt}\n\nINPUT_JSON:\n${inputJson}\n`;
+
+      let tmpDir: string | null = null;
+      try {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-llm-task-"));
+        const sessionId = `llm-task-${Date.now()}`;
+        const sessionFile = path.join(tmpDir, "session.json");
+
+        const runEmbeddedPiAgent = await loadRunEmbeddedPiAgent();
+
+        const result = await runEmbeddedPiAgent({
+          sessionId,
+          sessionFile,
+          workspaceDir: api.config?.agents?.defaults?.workspace ?? process.cwd(),
+          config: api.config,
+          prompt: fullPrompt,
+          timeoutMs,
+          runId: `llm-task-${Date.now()}`,
+          provider,
+          model,
+          authProfileId,
+          authProfileIdSource: authProfileId ? "user" : "auto",
+          streamParams,
+          disableTools: true,
+        });
+
+        const text = collectText((result as any).payloads);
+        if (!text) throw new Error("LLM returned empty output");
+
+        const raw = stripCodeFences(text);
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          throw new Error("LLM returned invalid JSON");
+        }
+
+        const schema = (params as any).schema as unknown;
+        if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+          const ajv = new Ajv({ allErrors: true, strict: false });
+          const validate = ajv.compile(schema as any);
+          const ok = validate(parsed);
+          if (!ok) {
+            const msg =
+              validate.errors?.map((e) => `${e.instancePath || "<root>"} ${e.message || "invalid"}`).join("; ") ??
+              "invalid";
+            throw new Error(`LLM JSON did not match schema: ${msg}`);
+          }
+        }
+
+        return {
+          content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+          details: { json: parsed, provider, model },
+        };
+      } finally {
+        if (tmpDir) {
+          try {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+          } catch {
+            // ignore
+          }
+        }
+      }
+    },
+  };
+}

docker-compose/ez-assistant/extensions/lobster/README.md

@@ -0,0 +1,80 @@
+# Lobster (plugin)
+
+Adds the `lobster` agent tool as an **optional** plugin tool.
+
+## What this is
+
+- Lobster is a standalone workflow shell (typed JSON-first pipelines + approvals/resume).
+- This plugin integrates Lobster with Clawdbot *without core changes*.
+
+## Enable
+
+Because this tool can trigger side effects (via workflows), it is registered with `optional: true`.
+
+Enable it in an agent allowlist:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster" // plugin id (enables all tools from this plugin)
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Using `clawd.invoke` (Lobster → Clawdbot tools)
+
+Some Lobster pipelines may include a `clawd.invoke` step to call back into Clawdbot tools/plugins (for example: `gog` for Google Workspace, `gh` for GitHub, `message.send`, etc.).
+
+For this to work, the Clawdbot Gateway must expose the tool bridge endpoint and the target tool must be allowed by policy:
+
+- Clawdbot provides an HTTP endpoint: `POST /tools/invoke`.
+- The request is gated by **gateway auth** (e.g. `Authorization: Bearer …` when token auth is enabled).
+- The invoked tool is gated by **tool policy** (global + per-agent + provider + group policy). If the tool is not allowed, Clawdbot returns `404 Tool not available`.
+
+### Allowlisting recommended
+
+To avoid letting workflows call arbitrary tools, set a tight allowlist on the agent that will be used by `clawd.invoke`.
+
+Example (allow only a small set of tools):
+
+```jsonc
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster",
+            "web_fetch",
+            "web_search",
+            "gog",
+            "gh"
+          ],
+          "deny": ["gateway"]
+        }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+- If `tools.allow` is omitted or empty, it behaves like "allow everything (except denied)". For a real allowlist, set a **non-empty** `allow`.
+- Tool names depend on which plugins you have installed/enabled.
+
+## Security
+
+- Runs the `lobster` executable as a local subprocess.
+- Does not manage OAuth/tokens.
+- Uses timeouts, stdout caps, and strict JSON envelope parsing.
+- Prefer an absolute `lobsterPath` in production to avoid PATH hijack.

docker-compose/ez-assistant/extensions/lobster/SKILL.md

@@ -0,0 +1,90 @@
+# Lobster
+
+Lobster executes multi-step workflows with approval checkpoints. Use it when:
+
+- User wants a repeatable automation (triage, monitor, sync)
+- Actions need human approval before executing (send, post, delete)
+- Multiple tool calls should run as one deterministic operation
+
+## When to use Lobster
+
+| User intent | Use Lobster? |
+|-------------|--------------|
+| "Triage my email" | Yes — multi-step, may send replies |
+| "Send a message" | No — single action, use message tool directly |
+| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval |
+| "What's the weather?" | No — simple query |
+| "Monitor this PR and notify me of changes" | Yes — stateful, recurring |
+
+## Basic usage
+
+### Run a pipeline
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
+}
+```
+
+Returns structured result:
+```json
+{
+  "protocolVersion": 1,
+  "ok": true,
+  "status": "ok",
+  "output": [{ "summary": {...}, "items": [...] }],
+  "requiresApproval": null
+}
+```
+
+### Handle approval
+
+If the workflow needs approval:
+```json
+{
+  "status": "needs_approval",
+  "output": [],
+  "requiresApproval": {
+    "prompt": "Send 3 draft replies?",
+    "items": [...],
+    "resumeToken": "..."
+  }
+}
+```
+
+Present the prompt to the user. If they approve:
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Example workflows
+
+### Email triage
+```
+gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
+```
+Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
+
+### Email triage with approval gate
+```
+gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
+```
+Same as above, but halts for approval before returning.
+
+## Key behaviors
+
+- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
+- **Approval gates**: `approve` command halts execution, returns token
+- **Resumable**: Use `resume` action with token to continue
+- **Structured output**: Always returns JSON envelope with `protocolVersion`
+
+## Don't use Lobster for
+
+- Simple single-action requests (just use the tool directly)
+- Queries that need LLM interpretation mid-flow
+- One-off tasks that won't be repeated

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

@@ -0,0 +1,10 @@
+{
+  "id": "lobster",
+  "name": "Lobster",
+  "description": "Typed workflow tool with resumable approvals.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

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

@@ -0,0 +1,13 @@
+import type { MoltbotPluginApi } from "../../src/plugins/types.js";
+
+import { createLobsterTool } from "./src/lobster-tool.js";
+
+export default function register(api: MoltbotPluginApi) {
+  api.registerTool(
+    (ctx) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    },
+    { optional: true },
+  );
+}

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

@@ -0,0 +1,11 @@
+{
+  "name": "@moltbot/lobster",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

docker-compose/ez-assistant/extensions/lobster/src/lobster-tool.test.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import type { MoltbotPluginApi, MoltbotPluginToolContext } from "../../../src/plugins/types.js";
+import { createLobsterTool } from "./lobster-tool.js";
+
+async function writeFakeLobsterScript(scriptBody: string, prefix = "moltbot-lobster-plugin-") {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  const isWindows = process.platform === "win32";
+
+  if (isWindows) {
+    const scriptPath = path.join(dir, "lobster.js");
+    const cmdPath = path.join(dir, "lobster.cmd");
+    await fs.writeFile(scriptPath, scriptBody, { encoding: "utf8" });
+    const cmd = `@echo off\r\n"${process.execPath}" "${scriptPath}" %*\r\n`;
+    await fs.writeFile(cmdPath, cmd, { encoding: "utf8" });
+    return { dir, binPath: cmdPath };
+  }
+
+  const binPath = path.join(dir, "lobster");
+  const file = `#!/usr/bin/env node\n${scriptBody}\n`;
+  await fs.writeFile(binPath, file, { encoding: "utf8", mode: 0o755 });
+  return { dir, binPath };
+}
+
+async function writeFakeLobster(params: { payload: unknown }) {
+  const scriptBody =
+    `const payload = ${JSON.stringify(params.payload)};\n` +
+    `process.stdout.write(JSON.stringify(payload));\n`;
+  return await writeFakeLobsterScript(scriptBody);
+}
+
+function fakeApi(): MoltbotPluginApi {
+  return {
+    id: "lobster",
+    name: "lobster",
+    source: "test",
+    config: {} as any,
+    runtime: { version: "test" } as any,
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool() {},
+    registerHttpHandler() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    resolvePath: (p) => p,
+  };
+}
+
+function fakeCtx(overrides: Partial<MoltbotPluginToolContext> = {}): MoltbotPluginToolContext {
+  return {
+    config: {} as any,
+    workspaceDir: "/tmp",
+    agentDir: "/tmp",
+    agentId: "main",
+    sessionKey: "main",
+    messageChannel: undefined,
+    agentAccountId: undefined,
+    sandboxed: false,
+    ...overrides,
+  };
+}
+
+describe("lobster plugin tool", () => {
+  it("runs lobster and returns parsed envelope in details", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    const res = await tool.execute("call1", {
+      action: "run",
+      pipeline: "noop",
+      lobsterPath: fake.binPath,
+      timeoutMs: 1000,
+    });
+
+    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+  });
+
+  it("tolerates noisy stdout before the JSON envelope", async () => {
+    const payload = { ok: true, status: "ok", output: [], requiresApproval: null };
+    const { binPath } = await writeFakeLobsterScript(
+      `const payload = ${JSON.stringify(payload)};\n` +
+        `console.log("noise before json");\n` +
+        `process.stdout.write(JSON.stringify(payload));\n`,
+      "moltbot-lobster-plugin-noisy-",
+    );
+
+    const tool = createLobsterTool(fakeApi());
+    const res = await tool.execute("call-noisy", {
+      action: "run",
+      pipeline: "noop",
+      lobsterPath: binPath,
+      timeoutMs: 1000,
+    });
+
+    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+  });
+
+  it("requires absolute lobsterPath when provided", async () => {
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call2", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: "./lobster",
+      }),
+    ).rejects.toThrow(/absolute path/);
+  });
+
+  it("rejects invalid JSON from lobster", async () => {
+    const { binPath } = await writeFakeLobsterScript(
+      `process.stdout.write("nope");\n`,
+      "moltbot-lobster-plugin-bad-",
+    );
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call3", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: binPath,
+      }),
+    ).rejects.toThrow(/invalid JSON/);
+  });
+
+  it("can be gated off in sandboxed contexts", async () => {
+    const api = fakeApi();
+    const factoryTool = (ctx: MoltbotPluginToolContext) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    };
+
+    expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();
+    expect(factoryTool(fakeCtx({ sandboxed: false }))?.name).toBe("lobster");
+  });
+});

docker-compose/ez-assistant/extensions/lobster/src/lobster-tool.ts

@@ -0,0 +1,240 @@
+import { Type } from "@sinclair/typebox";
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import type { MoltbotPluginApi } from "../../../src/plugins/types.js";
+
+type LobsterEnvelope =
+  | {
+      ok: true;
+      status: "ok" | "needs_approval" | "cancelled";
+      output: unknown[];
+      requiresApproval: null | {
+        type: "approval_request";
+        prompt: string;
+        items: unknown[];
+        resumeToken?: string;
+      };
+    }
+  | {
+      ok: false;
+      error: { type?: string; message: string };
+    };
+
+function resolveExecutablePath(lobsterPathRaw: string | undefined) {
+  const lobsterPath = lobsterPathRaw?.trim() || "lobster";
+  if (lobsterPath !== "lobster" && !path.isAbsolute(lobsterPath)) {
+    throw new Error("lobsterPath must be an absolute path (or omit to use PATH)");
+  }
+  return lobsterPath;
+}
+
+function isWindowsSpawnEINVAL(err: unknown) {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: unknown }).code;
+  return code === "EINVAL";
+}
+
+async function runLobsterSubprocessOnce(
+  params: {
+    execPath: string;
+    argv: string[];
+    cwd: string;
+    timeoutMs: number;
+    maxStdoutBytes: number;
+  },
+  useShell: boolean,
+) {
+  const { execPath, argv, cwd } = params;
+  const timeoutMs = Math.max(200, params.timeoutMs);
+  const maxStdoutBytes = Math.max(1024, params.maxStdoutBytes);
+
+  const env = { ...process.env, LOBSTER_MODE: "tool" } as Record<string, string | undefined>;
+  const nodeOptions = env.NODE_OPTIONS ?? "";
+  if (nodeOptions.includes("--inspect")) {
+    delete env.NODE_OPTIONS;
+  }
+
+  return await new Promise<{ stdout: string }>((resolve, reject) => {
+    const child = spawn(execPath, argv, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      shell: useShell,
+      windowsHide: useShell ? true : undefined,
+    });
+
+    let stdout = "";
+    let stdoutBytes = 0;
+    let stderr = "";
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+
+    child.stdout?.on("data", (chunk) => {
+      const str = String(chunk);
+      stdoutBytes += Buffer.byteLength(str, "utf8");
+      if (stdoutBytes > maxStdoutBytes) {
+        try {
+          child.kill("SIGKILL");
+        } finally {
+          reject(new Error("lobster output exceeded maxStdoutBytes"));
+        }
+        return;
+      }
+      stdout += str;
+    });
+
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } finally {
+        reject(new Error("lobster subprocess timed out"));
+      }
+    }, timeoutMs);
+
+    child.once("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`));
+        return;
+      }
+      resolve({ stdout });
+    });
+  });
+}
+
+async function runLobsterSubprocess(params: {
+  execPath: string;
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxStdoutBytes: number;
+}) {
+  try {
+    return await runLobsterSubprocessOnce(params, false);
+  } catch (err) {
+    if (process.platform === "win32" && isWindowsSpawnEINVAL(err)) {
+      return await runLobsterSubprocessOnce(params, true);
+    }
+    throw err;
+  }
+}
+
+function parseEnvelope(stdout: string): LobsterEnvelope {
+  const trimmed = stdout.trim();
+
+  const tryParse = (input: string) => {
+    try {
+      return JSON.parse(input) as unknown;
+    } catch {
+      return undefined;
+    }
+  };
+
+  let parsed: unknown = tryParse(trimmed);
+
+  // Some environments can leak extra stdout (e.g. warnings/logs) before the
+  // final JSON envelope. Be tolerant and parse the last JSON-looking suffix.
+  if (parsed === undefined) {
+    const suffixMatch = trimmed.match(/({[\s\S]*}|\[[\s\S]*])\s*$/);
+    if (suffixMatch?.[1]) {
+      parsed = tryParse(suffixMatch[1]);
+    }
+  }
+
+  if (parsed === undefined) {
+    throw new Error("lobster returned invalid JSON");
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("lobster returned invalid JSON envelope");
+  }
+
+  const ok = (parsed as { ok?: unknown }).ok;
+  if (ok === true || ok === false) {
+    return parsed as LobsterEnvelope;
+  }
+
+  throw new Error("lobster returned invalid JSON envelope");
+}
+
+export function createLobsterTool(api: MoltbotPluginApi) {
+  return {
+    name: "lobster",
+    description:
+      "Run Lobster pipelines as a local-first workflow runtime (typed JSON envelope + resumable approvals).",
+    parameters: Type.Object({
+      // NOTE: Prefer string enums in tool schemas; some providers reject unions/anyOf.
+      action: Type.Unsafe<"run" | "resume">({ type: "string", enum: ["run", "resume"] }),
+      pipeline: Type.Optional(Type.String()),
+      argsJson: Type.Optional(Type.String()),
+      token: Type.Optional(Type.String()),
+      approve: Type.Optional(Type.Boolean()),
+      lobsterPath: Type.Optional(Type.String()),
+      cwd: Type.Optional(Type.String()),
+      timeoutMs: Type.Optional(Type.Number()),
+      maxStdoutBytes: Type.Optional(Type.Number()),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const action = String(params.action || "").trim();
+      if (!action) throw new Error("action required");
+
+      const execPath = resolveExecutablePath(
+        typeof params.lobsterPath === "string" ? params.lobsterPath : undefined,
+      );
+      const cwd = typeof params.cwd === "string" && params.cwd.trim() ? params.cwd.trim() : process.cwd();
+      const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
+      const maxStdoutBytes = typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_000;
+
+      const argv = (() => {
+        if (action === "run") {
+          const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
+          if (!pipeline.trim()) throw new Error("pipeline required");
+          const argv = ["run", "--mode", "tool", pipeline];
+          const argsJson = typeof params.argsJson === "string" ? params.argsJson : "";
+          if (argsJson.trim()) {
+            argv.push("--args-json", argsJson);
+          }
+          return argv;
+        }
+        if (action === "resume") {
+          const token = typeof params.token === "string" ? params.token : "";
+          if (!token.trim()) throw new Error("token required");
+          const approve = params.approve;
+          if (typeof approve !== "boolean") throw new Error("approve required");
+          return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
+        }
+        throw new Error(`Unknown action: ${action}`);
+      })();
+
+      if (api.runtime?.version && api.logger?.debug) {
+        api.logger.debug(`lobster plugin runtime=${api.runtime.version}`);
+      }
+
+      const { stdout } = await runLobsterSubprocess({
+        execPath,
+        argv,
+        cwd,
+        timeoutMs,
+        maxStdoutBytes,
+      });
+
+      const envelope = parseEnvelope(stdout);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        details: envelope,
+      };
+    },
+  };
+}

docker-compose/ez-assistant/extensions/matrix/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 2026.1.23
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.22
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.21
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.20
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.17-1
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.17
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.16
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.15
+
+### Changes
+- Version alignment with core Moltbot release numbers.
+
+## 2026.1.14
+
+### Features
+- Version alignment with core Moltbot release numbers.
+- Matrix channel plugin with homeserver + user ID auth (access token or password login with device name).
+- Direct messages with pairing/allowlist/open/disabled policies and allowFrom support.
+- Group/room controls: allowlist policy, per-room config, mention gating, auto-reply, per-room skills/system prompts.
+- Threads: replyToMode controls and thread replies (off/inbound/always).
+- Messaging: text chunking, media uploads with size caps, reactions, polls, typing, and message edits/deletes.
+- Actions: read messages, list/remove reactions, pin/unpin/list pins, member info, room info.
+- Auto-join invites with allowlist support.
+- Status + probe reporting for health checks.

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

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

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

@@ -0,0 +1,18 @@
+import type { MoltbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { matrixPlugin } from "./src/channel.js";
+import { setMatrixRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "matrix",
+  name: "Matrix",
+  description: "Matrix channel plugin (matrix-js-sdk)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: MoltbotPluginApi) {
+    setMatrixRuntime(api.runtime);
+    api.registerChannel({ plugin: matrixPlugin });
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,36 @@
+{
+  "name": "@moltbot/matrix",
+  "version": "2026.1.26",
+  "type": "module",
+  "description": "Moltbot Matrix channel plugin",
+  "moltbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "matrix",
+      "label": "Matrix",
+      "selectionLabel": "Matrix (plugin)",
+      "docsPath": "/channels/matrix",
+      "docsLabel": "matrix",
+      "blurb": "open protocol; install the plugin to enable.",
+      "order": 70,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@moltbot/matrix",
+      "localPath": "extensions/matrix",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "markdown-it": "14.1.0",
+    "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
+    "music-metadata": "^11.10.6",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "moltbot": "workspace:*"
+  }
+}

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

@@ -0,0 +1,185 @@
+import {
+  createActionGate,
+  readNumberParam,
+  readStringParam,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionContext,
+  type ChannelMessageActionName,
+  type ChannelToolSend,
+} from "clawdbot/plugin-sdk";
+import { resolveMatrixAccount } from "./matrix/accounts.js";
+import { handleMatrixAction } from "./tool-actions.js";
+import type { CoreConfig } from "./types.js";
+
+export const matrixMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const account = resolveMatrixAccount({ cfg: cfg as CoreConfig });
+    if (!account.enabled || !account.configured) return [];
+    const gate = createActionGate((cfg as CoreConfig).channels?.matrix?.actions);
+    const actions = new Set<ChannelMessageActionName>(["send", "poll"]);
+    if (gate("reactions")) {
+      actions.add("react");
+      actions.add("reactions");
+    }
+    if (gate("messages")) {
+      actions.add("read");
+      actions.add("edit");
+      actions.add("delete");
+    }
+    if (gate("pins")) {
+      actions.add("pin");
+      actions.add("unpin");
+      actions.add("list-pins");
+    }
+    if (gate("memberInfo")) actions.add("member-info");
+    if (gate("channelInfo")) actions.add("channel-info");
+    return Array.from(actions);
+  },
+  supportsAction: ({ action }) => action !== "poll",
+  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;
+    return { to };
+  },
+  handleAction: async (ctx: ChannelMessageActionContext) => {
+    const { action, params, cfg } = ctx;
+    const resolveRoomId = () =>
+      readStringParam(params, "roomId") ??
+      readStringParam(params, "channelId") ??
+      readStringParam(params, "to", { required: true });
+
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+      const replyTo = readStringParam(params, "replyTo");
+      const threadId = readStringParam(params, "threadId");
+      return await handleMatrixAction(
+        {
+          action: "sendMessage",
+          to,
+          content,
+          mediaUrl: mediaUrl ?? undefined,
+          replyToId: replyTo ?? undefined,
+          threadId: threadId ?? undefined,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "react") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const emoji = readStringParam(params, "emoji", { allowEmpty: true });
+      const remove = typeof params.remove === "boolean" ? params.remove : undefined;
+      return await handleMatrixAction(
+        {
+          action: "react",
+          roomId: resolveRoomId(),
+          messageId,
+          emoji,
+          remove,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "reactions") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const limit = readNumberParam(params, "limit", { integer: true });
+      return await handleMatrixAction(
+        {
+          action: "reactions",
+          roomId: resolveRoomId(),
+          messageId,
+          limit,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "read") {
+      const limit = readNumberParam(params, "limit", { integer: true });
+      return await handleMatrixAction(
+        {
+          action: "readMessages",
+          roomId: resolveRoomId(),
+          limit,
+          before: readStringParam(params, "before"),
+          after: readStringParam(params, "after"),
+        },
+        cfg,
+      );
+    }
+
+    if (action === "edit") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const content = readStringParam(params, "message", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "editMessage",
+          roomId: resolveRoomId(),
+          messageId,
+          content,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "delete") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "deleteMessage",
+          roomId: resolveRoomId(),
+          messageId,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "pin" || action === "unpin" || action === "list-pins") {
+      const messageId =
+        action === "list-pins"
+          ? undefined
+          : readStringParam(params, "messageId", { required: true });
+      return await handleMatrixAction(
+        {
+          action:
+            action === "pin" ? "pinMessage" : action === "unpin" ? "unpinMessage" : "listPins",
+          roomId: resolveRoomId(),
+          messageId,
+        },
+        cfg,
+      );
+    }
+
+    if (action === "member-info") {
+      const userId = readStringParam(params, "userId", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "memberInfo",
+          userId,
+          roomId: readStringParam(params, "roomId") ?? readStringParam(params, "channelId"),
+        },
+        cfg,
+      );
+    }
+
+    if (action === "channel-info") {
+      return await handleMatrixAction(
+        {
+          action: "channelInfo",
+          roomId: resolveRoomId(),
+        },
+        cfg,
+      );
+    }
+
+    throw new Error(`Action ${action} is not supported for provider matrix.`);
+  },
+};

docker-compose/ez-assistant/extensions/matrix/src/channel.directory.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+import type { CoreConfig } from "./types.js";
+
+import { matrixPlugin } from "./channel.js";
+import { setMatrixRuntime } from "./runtime.js";
+
+describe("matrix directory", () => {
+  beforeEach(() => {
+    setMatrixRuntime({
+      state: {
+        resolveStateDir: (_env, homeDir) => homeDir(),
+      },
+    } as PluginRuntime);
+  });
+
+  it("lists peers and groups from config", async () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          dm: { allowFrom: ["matrix:@alice:example.org", "bob"] },
+          groupAllowFrom: ["@dana:example.org"],
+          groups: {
+            "!room1:example.org": { users: ["@carol:example.org"] },
+            "#alias:example.org": { users: [] },
+          },
+        },
+      },
+    } as unknown as CoreConfig;
+
+    expect(matrixPlugin.directory).toBeTruthy();
+    expect(matrixPlugin.directory?.listPeers).toBeTruthy();
+    expect(matrixPlugin.directory?.listGroups).toBeTruthy();
+
+    await expect(
+      matrixPlugin.directory!.listPeers({ cfg, accountId: undefined, query: undefined, limit: undefined }),
+    ).resolves.toEqual(
+      expect.arrayContaining([
+        { kind: "user", id: "user:@alice:example.org" },
+        { kind: "user", id: "bob", name: "incomplete id; expected @user:server" },
+        { kind: "user", id: "user:@carol:example.org" },
+        { kind: "user", id: "user:@dana:example.org" },
+      ]),
+    );
+
+    await expect(
+      matrixPlugin.directory!.listGroups({ cfg, accountId: undefined, query: undefined, limit: undefined }),
+    ).resolves.toEqual(
+      expect.arrayContaining([
+        { kind: "group", id: "room:!room1:example.org" },
+        { kind: "group", id: "#alias:example.org" },
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,417 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  setAccountEnabledInConfigSection,
+  type ChannelPlugin,
+} from "clawdbot/plugin-sdk";
+
+import { matrixMessageActions } from "./actions.js";
+import { MatrixConfigSchema } from "./config-schema.js";
+import { resolveMatrixGroupRequireMention, resolveMatrixGroupToolPolicy } from "./group-mentions.js";
+import type { CoreConfig } from "./types.js";
+import {
+  listMatrixAccountIds,
+  resolveDefaultMatrixAccountId,
+  resolveMatrixAccount,
+  type ResolvedMatrixAccount,
+} from "./matrix/accounts.js";
+import { resolveMatrixAuth } from "./matrix/client.js";
+import { normalizeAllowListLower } from "./matrix/monitor/allowlist.js";
+import { probeMatrix } from "./matrix/probe.js";
+import { sendMessageMatrix } from "./matrix/send.js";
+import { matrixOnboardingAdapter } from "./onboarding.js";
+import { matrixOutbound } from "./outbound.js";
+import { resolveMatrixTargets } from "./resolve-targets.js";
+import {
+  listMatrixDirectoryGroupsLive,
+  listMatrixDirectoryPeersLive,
+} from "./directory-live.js";
+
+const meta = {
+  id: "matrix",
+  label: "Matrix",
+  selectionLabel: "Matrix (plugin)",
+  docsPath: "/channels/matrix",
+  docsLabel: "matrix",
+  blurb: "open protocol; configure a homeserver + access token.",
+  order: 70,
+  quickstartAllowFrom: true,
+};
+
+function normalizeMatrixMessagingTarget(raw: string): string | undefined {
+  let normalized = raw.trim();
+  if (!normalized) return undefined;
+  const lowered = normalized.toLowerCase();
+  if (lowered.startsWith("matrix:")) {
+    normalized = normalized.slice("matrix:".length).trim();
+  }
+  const stripped = normalized.replace(/^(room|channel|user):/i, "").trim();
+  return stripped || undefined;
+}
+
+function buildMatrixConfigUpdate(
+  cfg: CoreConfig,
+  input: {
+    homeserver?: string;
+    userId?: string;
+    accessToken?: string;
+    password?: string;
+    deviceName?: string;
+    initialSyncLimit?: number;
+  },
+): CoreConfig {
+  const existing = cfg.channels?.matrix ?? {};
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      matrix: {
+        ...existing,
+        enabled: true,
+        ...(input.homeserver ? { homeserver: input.homeserver } : {}),
+        ...(input.userId ? { userId: input.userId } : {}),
+        ...(input.accessToken ? { accessToken: input.accessToken } : {}),
+        ...(input.password ? { password: input.password } : {}),
+        ...(input.deviceName ? { deviceName: input.deviceName } : {}),
+        ...(typeof input.initialSyncLimit === "number"
+          ? { initialSyncLimit: input.initialSyncLimit }
+          : {}),
+      },
+    },
+  };
+}
+
+export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
+  id: "matrix",
+  meta,
+  onboarding: matrixOnboardingAdapter,
+  pairing: {
+    idLabel: "matrixUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^matrix:/i, ""),
+    notifyApproval: async ({ id }) => {
+      await sendMessageMatrix(`user:${id}`, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    polls: true,
+    reactions: true,
+    threads: true,
+    media: true,
+  },
+  reload: { configPrefixes: ["channels.matrix"] },
+  configSchema: buildChannelConfigSchema(MatrixConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listMatrixAccountIds(cfg as CoreConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultMatrixAccountId(cfg as CoreConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "matrix",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "matrix",
+        accountId,
+        clearBaseFields: [
+          "name",
+          "homeserver",
+          "userId",
+          "accessToken",
+          "password",
+          "deviceName",
+          "initialSyncLimit",
+        ],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.homeserver,
+    }),
+    resolveAllowFrom: ({ cfg }) =>
+      ((cfg as CoreConfig).channels?.matrix?.dm?.allowFrom ?? []).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) => normalizeAllowListLower(allowFrom),
+  },
+  security: {
+    resolveDmPolicy: ({ account }) => ({
+      policy: account.config.dm?.policy ?? "pairing",
+      allowFrom: account.config.dm?.allowFrom ?? [],
+      policyPath: "channels.matrix.dm.policy",
+      allowFromPath: "channels.matrix.dm.allowFrom",
+      approveHint: formatPairingApproveHint("matrix"),
+      normalizeEntry: (raw) => raw.replace(/^matrix:/i, "").trim().toLowerCase(),
+    }),
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = (cfg as CoreConfig).channels?.defaults?.groupPolicy;
+      const groupPolicy =
+        account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        "- Matrix rooms: groupPolicy=\"open\" allows any room to trigger (mention-gated). Set channels.matrix.groupPolicy=\"allowlist\" + channels.matrix.groups (and optionally channels.matrix.groupAllowFrom) to restrict rooms.",
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveMatrixGroupRequireMention,
+    resolveToolPolicy: resolveMatrixGroupToolPolicy,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) =>
+      (cfg as CoreConfig).channels?.matrix?.replyToMode ?? "off",
+    buildToolContext: ({ context, hasRepliedRef }) => {
+      const currentTarget = context.To;
+      return {
+        currentChannelId: currentTarget?.trim() || undefined,
+        currentThreadTs:
+          context.MessageThreadId != null
+            ? String(context.MessageThreadId)
+            : context.ReplyToId,
+        hasRepliedRef,
+      };
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeMatrixMessagingTarget,
+    targetResolver: {
+      looksLikeId: (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed) return false;
+        if (/^(matrix:)?[!#@]/i.test(trimmed)) return true;
+        return trimmed.includes(":");
+      },
+      hint: "<room|alias|user>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() || "";
+      const ids = new Set<string>();
+
+      for (const entry of account.config.dm?.allowFrom ?? []) {
+        const raw = String(entry).trim();
+        if (!raw || raw === "*") continue;
+        ids.add(raw.replace(/^matrix:/i, ""));
+      }
+
+      for (const entry of account.config.groupAllowFrom ?? []) {
+        const raw = String(entry).trim();
+        if (!raw || raw === "*") continue;
+        ids.add(raw.replace(/^matrix:/i, ""));
+      }
+
+      const groups = account.config.groups ?? account.config.rooms ?? {};
+      for (const room of Object.values(groups)) {
+        for (const entry of room.users ?? []) {
+          const raw = String(entry).trim();
+          if (!raw || raw === "*") continue;
+          ids.add(raw.replace(/^matrix:/i, ""));
+        }
+      }
+
+      return Array.from(ids)
+        .map((raw) => raw.trim())
+        .filter(Boolean)
+        .map((raw) => {
+          const lowered = raw.toLowerCase();
+          const cleaned = lowered.startsWith("user:") ? raw.slice("user:".length).trim() : raw;
+          if (cleaned.startsWith("@")) return `user:${cleaned}`;
+          return cleaned;
+        })
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => {
+          const raw = id.startsWith("user:") ? id.slice("user:".length) : id;
+          const incomplete = !raw.startsWith("@") || !raw.includes(":");
+          return {
+            kind: "user",
+            id,
+            ...(incomplete ? { name: "incomplete id; expected @user:server" } : {}),
+          };
+        });
+    },
+    listGroups: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() || "";
+      const groups = account.config.groups ?? account.config.rooms ?? {};
+      const ids = Object.keys(groups)
+        .map((raw) => raw.trim())
+        .filter((raw) => Boolean(raw) && raw !== "*")
+        .map((raw) => raw.replace(/^matrix:/i, ""))
+        .map((raw) => {
+          const lowered = raw.toLowerCase();
+          if (lowered.startsWith("room:") || lowered.startsWith("channel:")) return raw;
+          if (raw.startsWith("!")) return `room:${raw}`;
+          return raw;
+        })
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "group", id }) as const);
+      return ids;
+    },
+    listPeersLive: async ({ cfg, query, limit }) =>
+      listMatrixDirectoryPeersLive({ cfg, query, limit }),
+    listGroupsLive: async ({ cfg, query, limit }) =>
+      listMatrixDirectoryGroupsLive({ cfg, query, limit }),
+  },
+  resolver: {
+    resolveTargets: async ({ cfg, inputs, kind, runtime }) =>
+      resolveMatrixTargets({ cfg, inputs, kind, runtime }),
+  },
+  actions: matrixMessageActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "matrix",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (input.useEnv) return null;
+      if (!input.homeserver?.trim()) return "Matrix requires --homeserver";
+      const accessToken = input.accessToken?.trim();
+      const password = input.password?.trim();
+      const userId = input.userId?.trim();
+      if (!accessToken && !password) {
+        return "Matrix requires --access-token or --password";
+      }
+      if (!accessToken) {
+        if (!userId) return "Matrix requires --user-id when using --password";
+        if (!password) return "Matrix requires --password when using --user-id";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "matrix",
+        accountId: DEFAULT_ACCOUNT_ID,
+        name: input.name,
+      });
+      if (input.useEnv) {
+        return {
+          ...namedConfig,
+          channels: {
+            ...namedConfig.channels,
+            matrix: {
+              ...namedConfig.channels?.matrix,
+              enabled: true,
+            },
+          },
+        } as CoreConfig;
+      }
+      return buildMatrixConfigUpdate(namedConfig as CoreConfig, {
+        homeserver: input.homeserver?.trim(),
+        userId: input.userId?.trim(),
+        accessToken: input.accessToken?.trim(),
+        password: input.password?.trim(),
+        deviceName: input.deviceName?.trim(),
+        initialSyncLimit: input.initialSyncLimit,
+      });
+    },
+  },
+  outbound: matrixOutbound,
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "matrix",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    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, cfg }) => {
+      try {
+        const auth = await resolveMatrixAuth({ cfg: cfg as CoreConfig });
+        return await probeMatrix({
+          homeserver: auth.homeserver,
+          accessToken: auth.accessToken,
+          userId: auth.userId,
+          timeoutMs,
+        });
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          elapsedMs: 0,
+        };
+      }
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.homeserver,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastProbeAt: runtime?.lastProbeAt ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.homeserver,
+      });
+      ctx.log?.info(
+        `[${account.accountId}] starting provider (${account.homeserver ?? "matrix"})`,
+      );
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorMatrixProvider } = await import("./matrix/index.js");
+      return monitorMatrixProvider({
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+        initialSyncLimit: account.config.initialSyncLimit,
+        replyToMode: account.config.replyToMode,
+        accountId: account.accountId,
+      });
+    },
+  },
+};

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

@@ -0,0 +1,62 @@
+import { MarkdownConfigSchema, ToolPolicySchema } from "clawdbot/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const matrixActionSchema = z
+  .object({
+    reactions: z.boolean().optional(),
+    messages: z.boolean().optional(),
+    pins: z.boolean().optional(),
+    memberInfo: z.boolean().optional(),
+    channelInfo: z.boolean().optional(),
+  })
+  .optional();
+
+const matrixDmSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(allowFromEntry).optional(),
+  })
+  .optional();
+
+const matrixRoomSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    allow: z.boolean().optional(),
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    autoReply: z.boolean().optional(),
+    users: z.array(allowFromEntry).optional(),
+    skills: z.array(z.string()).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .optional();
+
+export const MatrixConfigSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema,
+  homeserver: z.string().optional(),
+  userId: z.string().optional(),
+  accessToken: z.string().optional(),
+  password: z.string().optional(),
+  deviceName: z.string().optional(),
+  initialSyncLimit: z.number().optional(),
+  encryption: z.boolean().optional(),
+  allowlistOnly: z.boolean().optional(),
+  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
+  replyToMode: z.enum(["off", "first", "all"]).optional(),
+  threadReplies: z.enum(["off", "inbound", "always"]).optional(),
+  textChunkLimit: z.number().optional(),
+  chunkMode: z.enum(["length", "newline"]).optional(),
+  mediaMaxMb: z.number().optional(),
+  autoJoin: z.enum(["always", "allowlist", "off"]).optional(),
+  autoJoinAllowlist: z.array(allowFromEntry).optional(),
+  groupAllowFrom: z.array(allowFromEntry).optional(),
+  dm: matrixDmSchema,
+  groups: z.object({}).catchall(matrixRoomSchema).optional(),
+  rooms: z.object({}).catchall(matrixRoomSchema).optional(),
+  actions: matrixActionSchema,
+});