@openclaw/feishu 2026.3.1 → 2026.3.7

package/src/bot.test.ts

@@ -1,7 +1,14 @@
-import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/feishu";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createPluginRuntimeMock } from "../../test-utils/plugin-runtime-mock.js";
 import type { FeishuMessageEvent } from "./bot.js";
-import { buildFeishuAgentBody, handleFeishuMessage, toMessageResourceType } from "./bot.js";
+import {
+  buildBroadcastSessionKey,
+  buildFeishuAgentBody,
+  handleFeishuMessage,
+  resolveBroadcastAgents,
+  toMessageResourceType,
+} from "./bot.js";
 import { setFeishuRuntime } from "./runtime.js";
 
 const {
@@ -27,8 +34,10 @@ const {
   mockCreateFeishuClient: vi.fn(),
   mockResolveAgentRoute: vi.fn(() => ({
     agentId: "main",
+    channel: "feishu",
     accountId: "default",
     sessionKey: "agent:main:feishu:dm:ou-attacker",
+    mainSessionKey: "agent:main:main",
     matchedBy: "default",
   })),
 }));
@@ -122,7 +131,9 @@ describe("handleFeishuMessage command authorization", () => {
   const mockBuildPairingReply = vi.fn(() => "Pairing response");
   const mockEnqueueSystemEvent = vi.fn();
   const mockSaveMediaBuffer = vi.fn().mockResolvedValue({
+    id: "inbound-clip.mp4",
     path: "/tmp/inbound-clip.mp4",
+    size: Buffer.byteLength("video"),
     contentType: "video/mp4",
   });
 
@@ -131,8 +142,10 @@ describe("handleFeishuMessage command authorization", () => {
     mockShouldComputeCommandAuthorized.mockReset().mockReturnValue(true);
     mockResolveAgentRoute.mockReturnValue({
       agentId: "main",
+      channel: "feishu",
       accountId: "default",
       sessionKey: "agent:main:feishu:dm:ou-attacker",
+      mainSessionKey: "agent:main:main",
       matchedBy: "default",
     });
     mockCreateFeishuClient.mockReturnValue({
@@ -143,38 +156,46 @@ describe("handleFeishuMessage command authorization", () => {
       },
     });
     mockEnqueueSystemEvent.mockReset();
-    setFeishuRuntime({
-      system: {
-        enqueueSystemEvent: mockEnqueueSystemEvent,
-      },
-      channel: {
-        routing: {
-          resolveAgentRoute: mockResolveAgentRoute,
-        },
-        reply: {
-          resolveEnvelopeFormatOptions: vi.fn(() => ({ template: "channel+name+time" })),
-          formatAgentEnvelope: vi.fn((params: { body: string }) => params.body),
-          finalizeInboundContext: mockFinalizeInboundContext,
-          dispatchReplyFromConfig: mockDispatchReplyFromConfig,
-          withReplyDispatcher: mockWithReplyDispatcher,
+    setFeishuRuntime(
+      createPluginRuntimeMock({
+        system: {
+          enqueueSystemEvent: mockEnqueueSystemEvent,
         },
-        commands: {
-          shouldComputeCommandAuthorized: mockShouldComputeCommandAuthorized,
-          resolveCommandAuthorizedFromAuthorizers: mockResolveCommandAuthorizedFromAuthorizers,
+        channel: {
+          routing: {
+            resolveAgentRoute:
+              mockResolveAgentRoute as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"],
+          },
+          reply: {
+            resolveEnvelopeFormatOptions: vi.fn(
+              () => ({}),
+            ) as unknown as PluginRuntime["channel"]["reply"]["resolveEnvelopeFormatOptions"],
+            formatAgentEnvelope: vi.fn((params: { body: string }) => params.body),
+            finalizeInboundContext:
+              mockFinalizeInboundContext as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"],
+            dispatchReplyFromConfig: mockDispatchReplyFromConfig,
+            withReplyDispatcher:
+              mockWithReplyDispatcher as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"],
+          },
+          commands: {
+            shouldComputeCommandAuthorized: mockShouldComputeCommandAuthorized,
+            resolveCommandAuthorizedFromAuthorizers: mockResolveCommandAuthorizedFromAuthorizers,
+          },
+          media: {
+            saveMediaBuffer:
+              mockSaveMediaBuffer as unknown as PluginRuntime["channel"]["media"]["saveMediaBuffer"],
+          },
+          pairing: {
+            readAllowFromStore: mockReadAllowFromStore,
+            upsertPairingRequest: mockUpsertPairingRequest,
+            buildPairingReply: mockBuildPairingReply,
+          },
         },
         media: {
-          saveMediaBuffer: mockSaveMediaBuffer,
-        },
-        pairing: {
-          readAllowFromStore: mockReadAllowFromStore,
-          upsertPairingRequest: mockUpsertPairingRequest,
-          buildPairingReply: mockBuildPairingReply,
+          detectMime: vi.fn(async () => "application/octet-stream"),
         },
-      },
-      media: {
-        detectMime: vi.fn(async () => "application/octet-stream"),
-      },
-    } as unknown as PluginRuntime);
+      }),
+    );
   });
 
   it("does not enqueue inbound preview text as system events", async () => {
@@ -366,6 +387,41 @@ describe("handleFeishuMessage command authorization", () => {
     );
   });
 
+  it("replies pairing challenge to DM chat_id instead of user:sender id", async () => {
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          dmPolicy: "pairing",
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          user_id: "u_mobile_only",
+        },
+      },
+      message: {
+        message_id: "msg-pairing-chat-reply",
+        chat_id: "oc_dm_chat_1",
+        chat_type: "p2p",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    };
+
+    mockReadAllowFromStore.mockResolvedValue([]);
+    mockUpsertPairingRequest.mockResolvedValue({ code: "ABCDEFGH", created: true });
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockSendMessageFeishu).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat:oc_dm_chat_1",
+      }),
+    );
+  });
   it("creates pairing request and drops unauthorized DMs in pairing mode", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(false);
     mockReadAllowFromStore.mockResolvedValue([]);
@@ -403,14 +459,17 @@ describe("handleFeishuMessage command authorization", () => {
       id: "ou-unapproved",
       meta: { name: undefined },
     });
-    expect(mockBuildPairingReply).toHaveBeenCalledWith({
-      channel: "feishu",
-      idLine: "Your Feishu user id: ou-unapproved",
-      code: "ABCDEFGH",
-    });
     expect(mockSendMessageFeishu).toHaveBeenCalledWith(
       expect.objectContaining({
-        to: "user:ou-unapproved",
+        to: "chat:oc-dm",
+        text: expect.stringContaining("Your Feishu user id: ou-unapproved"),
+        accountId: "default",
+      }),
+    );
+    expect(mockSendMessageFeishu).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "chat:oc-dm",
+        text: expect.stringContaining("Pairing code: ABCDEFGH"),
         accountId: "default",
       }),
     );
@@ -465,6 +524,42 @@ describe("handleFeishuMessage command authorization", () => {
     );
   });
 
+  it("normalizes group mention-prefixed slash commands before command-auth probing", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(true);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-attacker",
+        },
+      },
+      message: {
+        message_id: "msg-group-mention-command-probe",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "@_user_1/model" }),
+        mentions: [{ key: "@_user_1", id: { open_id: "ou-bot" }, name: "Bot", tenant_key: "" }],
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockShouldComputeCommandAuthorized).toHaveBeenCalledWith("/model", cfg);
+  });
+
   it("falls back to top-level allowFrom for group command authorization", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(true);
     mockResolveCommandAuthorizedFromAuthorizers.mockReturnValue(true);
@@ -996,7 +1091,7 @@ describe("handleFeishuMessage command authorization", () => {
       channels: {
         feishu: {
           appId: "cli_test",
-          appSecret: "sec_test",
+          appSecret: "sec_test", // pragma: allowlist secret
           groups: {
             "oc-group": {
               requireMention: false,
@@ -1038,6 +1133,67 @@ describe("handleFeishuMessage command authorization", () => {
     );
   });
 
+  it("ignores stale non-existent contact scope permission errors", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+    mockCreateFeishuClient.mockReturnValue({
+      contact: {
+        user: {
+          get: vi.fn().mockRejectedValue({
+            response: {
+              data: {
+                code: 99991672,
+                msg: "permission denied: contact:contact.base:readonly https://open.feishu.cn/app/cli_scope_bug",
+              },
+            },
+          }),
+        },
+      },
+    });
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          appId: "cli_scope_bug",
+          appSecret: "sec_scope_bug", // pragma: allowlist secret
+          groups: {
+            "oc-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-perm-scope",
+        },
+      },
+      message: {
+        message_id: "msg-perm-scope-1",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello group" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(mockFinalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        BodyForAgent: expect.not.stringContaining("Permission grant URL"),
+      }),
+    );
+    expect(mockFinalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        BodyForAgent: expect.stringContaining("ou-perm-scope: hello group"),
+      }),
+    );
+  });
+
   it("routes group sessions by sender when groupSessionScope=group_sender", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(false);
 
@@ -1113,16 +1269,16 @@ describe("handleFeishuMessage command authorization", () => {
     );
   });
 
-  it("maps legacy topicSessionMode=enabled to group_topic routing", async () => {
+  it("keeps root_id as topic key when root_id and thread_id both exist", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(false);
 
     const cfg: ClawdbotConfig = {
       channels: {
         feishu: {
-          topicSessionMode: "enabled",
           groups: {
             "oc-group": {
               requireMention: false,
+              groupSessionScope: "group_topic_sender",
             },
           },
         },
@@ -1130,14 +1286,15 @@ describe("handleFeishuMessage command authorization", () => {
     } as ClawdbotConfig;
 
     const event: FeishuMessageEvent = {
-      sender: { sender_id: { open_id: "ou-legacy" } },
+      sender: { sender_id: { open_id: "ou-topic-user" } },
       message: {
-        message_id: "msg-legacy-topic-mode",
+        message_id: "msg-scope-topic-thread-id",
         chat_id: "oc-group",
         chat_type: "group",
-        root_id: "om_root_legacy",
+        root_id: "om_root_topic",
+        thread_id: "omt_topic_1",
         message_type: "text",
-        content: JSON.stringify({ text: "legacy topic mode" }),
+        content: JSON.stringify({ text: "topic sender scope" }),
       },
     };
 
@@ -1145,13 +1302,13 @@ describe("handleFeishuMessage command authorization", () => {
 
     expect(mockResolveAgentRoute).toHaveBeenCalledWith(
       expect.objectContaining({
-        peer: { kind: "group", id: "oc-group:topic:om_root_legacy" },
+        peer: { kind: "group", id: "oc-group:topic:om_root_topic:sender:ou-topic-user" },
         parentPeer: { kind: "group", id: "oc-group" },
       }),
     );
   });
 
-  it("uses message_id as topic root when group_topic + replyInThread and no root_id", async () => {
+  it("uses thread_id as topic key when root_id is missing", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(false);
 
     const cfg: ClawdbotConfig = {
@@ -1160,8 +1317,7 @@ describe("handleFeishuMessage command authorization", () => {
           groups: {
             "oc-group": {
               requireMention: false,
-              groupSessionScope: "group_topic",
-              replyInThread: "enabled",
+              groupSessionScope: "group_topic_sender",
             },
           },
         },
@@ -1169,13 +1325,14 @@ describe("handleFeishuMessage command authorization", () => {
     } as ClawdbotConfig;
 
     const event: FeishuMessageEvent = {
-      sender: { sender_id: { open_id: "ou-topic-init" } },
+      sender: { sender_id: { open_id: "ou-topic-user" } },
       message: {
-        message_id: "msg-new-topic-root",
+        message_id: "msg-scope-topic-thread-only",
         chat_id: "oc-group",
         chat_type: "group",
+        thread_id: "omt_topic_1",
         message_type: "text",
-        content: JSON.stringify({ text: "create topic" }),
+        content: JSON.stringify({ text: "topic sender scope" }),
       },
     };
 
@@ -1183,57 +1340,768 @@ describe("handleFeishuMessage command authorization", () => {
 
     expect(mockResolveAgentRoute).toHaveBeenCalledWith(
       expect.objectContaining({
-        peer: { kind: "group", id: "oc-group:topic:msg-new-topic-root" },
+        peer: { kind: "group", id: "oc-group:topic:omt_topic_1:sender:ou-topic-user" },
         parentPeer: { kind: "group", id: "oc-group" },
       }),
     );
   });
 
-  it("does not dispatch twice for the same image message_id (concurrent dedupe)", async () => {
+  it("maps legacy topicSessionMode=enabled to group_topic routing", async () => {
     mockShouldComputeCommandAuthorized.mockReturnValue(false);
 
     const cfg: ClawdbotConfig = {
       channels: {
         feishu: {
-          dmPolicy: "open",
+          topicSessionMode: "enabled",
+          groups: {
+            "oc-group": {
+              requireMention: false,
+            },
+          },
         },
       },
     } as ClawdbotConfig;
 
     const event: FeishuMessageEvent = {
-      sender: {
-        sender_id: {
-          open_id: "ou-image-dedup",
+      sender: { sender_id: { open_id: "ou-legacy" } },
+      message: {
+        message_id: "msg-legacy-topic-mode",
+        chat_id: "oc-group",
+        chat_type: "group",
+        root_id: "om_root_legacy",
+        message_type: "text",
+        content: JSON.stringify({ text: "legacy topic mode" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockResolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        peer: { kind: "group", id: "oc-group:topic:om_root_legacy" },
+        parentPeer: { kind: "group", id: "oc-group" },
+      }),
+    );
+  });
+
+  it("maps legacy topicSessionMode=enabled to root_id when both root_id and thread_id exist", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          topicSessionMode: "enabled",
+          groups: {
+            "oc-group": {
+              requireMention: false,
+            },
+          },
         },
       },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-legacy-thread-id" } },
       message: {
-        message_id: "msg-image-dedup",
-        chat_id: "oc-dm",
-        chat_type: "p2p",
-        message_type: "image",
-        content: JSON.stringify({
-          image_key: "img_dedup_payload",
-        }),
+        message_id: "msg-legacy-topic-thread-id",
+        chat_id: "oc-group",
+        chat_type: "group",
+        root_id: "om_root_legacy",
+        thread_id: "omt_topic_legacy",
+        message_type: "text",
+        content: JSON.stringify({ text: "legacy topic mode" }),
       },
     };
 
-    await Promise.all([dispatchMessage({ cfg, event }), dispatchMessage({ cfg, event })]);
-    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
-  });
-});
+    await dispatchMessage({ cfg, event });
 
-describe("toMessageResourceType", () => {
-  it("maps image to image", () => {
-    expect(toMessageResourceType("image")).toBe("image");
+    expect(mockResolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        peer: { kind: "group", id: "oc-group:topic:om_root_legacy" },
+        parentPeer: { kind: "group", id: "oc-group" },
+      }),
+    );
   });
 
-  it("maps audio to file", () => {
-    expect(toMessageResourceType("audio")).toBe("file");
-  });
+  it("uses message_id as topic root when group_topic + replyInThread and no root_id", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
 
-  it("maps video/file/sticker to file", () => {
-    expect(toMessageResourceType("video")).toBe("file");
-    expect(toMessageResourceType("file")).toBe("file");
-    expect(toMessageResourceType("sticker")).toBe("file");
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group_topic",
+              replyInThread: "enabled",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-init" } },
+      message: {
+        message_id: "msg-new-topic-root",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "create topic" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockResolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        peer: { kind: "group", id: "oc-group:topic:msg-new-topic-root" },
+        parentPeer: { kind: "group", id: "oc-group" },
+      }),
+    );
+  });
+
+  it("keeps topic session key stable after first turn creates a thread", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group_topic",
+              replyInThread: "enabled",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const firstTurn: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-init" } },
+      message: {
+        message_id: "msg-topic-first",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "create topic" }),
+      },
+    };
+    const secondTurn: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-init" } },
+      message: {
+        message_id: "msg-topic-second",
+        chat_id: "oc-group",
+        chat_type: "group",
+        root_id: "msg-topic-first",
+        thread_id: "omt_topic_created",
+        message_type: "text",
+        content: JSON.stringify({ text: "follow up in same topic" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event: firstTurn });
+    await dispatchMessage({ cfg, event: secondTurn });
+
+    expect(mockResolveAgentRoute).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        peer: { kind: "group", id: "oc-group:topic:msg-topic-first" },
+      }),
+    );
+    expect(mockResolveAgentRoute).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        peer: { kind: "group", id: "oc-group:topic:msg-topic-first" },
+      }),
+    );
+  });
+
+  it("replies to the topic root when handling a message inside an existing topic", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              replyInThread: "enabled",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-user" } },
+      message: {
+        message_id: "om_child_message",
+        root_id: "om_root_topic",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "reply inside topic" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyToMessageId: "om_root_topic",
+        rootId: "om_root_topic",
+      }),
+    );
+  });
+
+  it("replies to triggering message in normal group even when root_id is present (#32980)", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-normal-user" } },
+      message: {
+        message_id: "om_quote_reply",
+        root_id: "om_original_msg",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello in normal group" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyToMessageId: "om_quote_reply",
+        rootId: "om_original_msg",
+      }),
+    );
+  });
+
+  it("replies to topic root in topic-mode group with root_id", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group_topic",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-user" } },
+      message: {
+        message_id: "om_topic_reply",
+        root_id: "om_topic_root",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello in topic group" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyToMessageId: "om_topic_root",
+        rootId: "om_topic_root",
+      }),
+    );
+  });
+
+  it("replies to topic root in topic-sender group with root_id", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group_topic_sender",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-topic-sender-user" } },
+      message: {
+        message_id: "om_topic_sender_reply",
+        root_id: "om_topic_sender_root",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello in topic sender group" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyToMessageId: "om_topic_sender_root",
+        rootId: "om_topic_sender_root",
+      }),
+    );
+  });
+
+  it("forces thread replies when inbound message contains thread_id", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+              groupSessionScope: "group",
+              replyInThread: "disabled",
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-thread-reply" } },
+      message: {
+        message_id: "msg-thread-reply",
+        chat_id: "oc-group",
+        chat_type: "group",
+        thread_id: "omt_topic_thread_reply",
+        message_type: "text",
+        content: JSON.stringify({ text: "thread content" }),
+      },
+    };
+
+    await dispatchMessage({ cfg, event });
+
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyInThread: true,
+        threadReply: true,
+      }),
+    );
+  });
+
+  it("does not dispatch twice for the same image message_id (concurrent dedupe)", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          dmPolicy: "open",
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-image-dedup",
+        },
+      },
+      message: {
+        message_id: "msg-image-dedup",
+        chat_id: "oc-dm",
+        chat_type: "p2p",
+        message_type: "image",
+        content: JSON.stringify({
+          image_key: "img_dedup_payload",
+        }),
+      },
+    };
+
+    await Promise.all([dispatchMessage({ cfg, event }), dispatchMessage({ cfg, event })]);
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("toMessageResourceType", () => {
+  it("maps image to image", () => {
+    expect(toMessageResourceType("image")).toBe("image");
+  });
+
+  it("maps audio to file", () => {
+    expect(toMessageResourceType("audio")).toBe("file");
+  });
+
+  it("maps video/file/sticker to file", () => {
+    expect(toMessageResourceType("video")).toBe("file");
+    expect(toMessageResourceType("file")).toBe("file");
+    expect(toMessageResourceType("sticker")).toBe("file");
+  });
+});
+
+describe("resolveBroadcastAgents", () => {
+  it("returns agent list when broadcast config has the peerId", () => {
+    const cfg = { broadcast: { oc_group123: ["susan", "main"] } } as unknown as ClawdbotConfig;
+    expect(resolveBroadcastAgents(cfg, "oc_group123")).toEqual(["susan", "main"]);
+  });
+
+  it("returns null when no broadcast config", () => {
+    const cfg = {} as ClawdbotConfig;
+    expect(resolveBroadcastAgents(cfg, "oc_group123")).toBeNull();
+  });
+
+  it("returns null when peerId not in broadcast", () => {
+    const cfg = { broadcast: { oc_other: ["susan"] } } as unknown as ClawdbotConfig;
+    expect(resolveBroadcastAgents(cfg, "oc_group123")).toBeNull();
+  });
+
+  it("returns null when agent list is empty", () => {
+    const cfg = { broadcast: { oc_group123: [] } } as unknown as ClawdbotConfig;
+    expect(resolveBroadcastAgents(cfg, "oc_group123")).toBeNull();
+  });
+});
+
+describe("buildBroadcastSessionKey", () => {
+  it("replaces agent ID prefix in session key", () => {
+    expect(buildBroadcastSessionKey("agent:main:feishu:group:oc_group123", "main", "susan")).toBe(
+      "agent:susan:feishu:group:oc_group123",
+    );
+  });
+
+  it("handles compound peer IDs", () => {
+    expect(
+      buildBroadcastSessionKey(
+        "agent:main:feishu:group:oc_group123:sender:ou_user1",
+        "main",
+        "susan",
+      ),
+    ).toBe("agent:susan:feishu:group:oc_group123:sender:ou_user1");
+  });
+
+  it("returns base key unchanged when prefix does not match", () => {
+    expect(buildBroadcastSessionKey("custom:key:format", "main", "susan")).toBe(
+      "custom:key:format",
+    );
+  });
+});
+
+describe("broadcast dispatch", () => {
+  const mockFinalizeInboundContext = vi.fn((ctx: unknown) => ctx);
+  const mockDispatchReplyFromConfig = vi
+    .fn()
+    .mockResolvedValue({ queuedFinal: false, counts: { final: 1 } });
+  const mockWithReplyDispatcher = vi.fn(
+    async ({
+      dispatcher,
+      run,
+      onSettled,
+    }: Parameters<PluginRuntime["channel"]["reply"]["withReplyDispatcher"]>[0]) => {
+      try {
+        return await run();
+      } finally {
+        dispatcher.markComplete();
+        try {
+          await dispatcher.waitForIdle();
+        } finally {
+          await onSettled?.();
+        }
+      }
+    },
+  );
+  const mockShouldComputeCommandAuthorized = vi.fn(() => false);
+  const mockSaveMediaBuffer = vi.fn().mockResolvedValue({
+    path: "/tmp/inbound-clip.mp4",
+    contentType: "video/mp4",
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockResolveAgentRoute.mockReturnValue({
+      agentId: "main",
+      channel: "feishu",
+      accountId: "default",
+      sessionKey: "agent:main:feishu:group:oc-broadcast-group",
+      mainSessionKey: "agent:main:main",
+      matchedBy: "default",
+    });
+    mockCreateFeishuClient.mockReturnValue({
+      contact: {
+        user: {
+          get: vi.fn().mockResolvedValue({ data: { user: { name: "Sender" } } }),
+        },
+      },
+    });
+    setFeishuRuntime({
+      system: {
+        enqueueSystemEvent: vi.fn(),
+      },
+      channel: {
+        routing: {
+          resolveAgentRoute: mockResolveAgentRoute,
+        },
+        reply: {
+          resolveEnvelopeFormatOptions: vi.fn(() => ({ template: "channel+name+time" })),
+          formatAgentEnvelope: vi.fn((params: { body: string }) => params.body),
+          finalizeInboundContext: mockFinalizeInboundContext,
+          dispatchReplyFromConfig: mockDispatchReplyFromConfig,
+          withReplyDispatcher: mockWithReplyDispatcher,
+        },
+        commands: {
+          shouldComputeCommandAuthorized: mockShouldComputeCommandAuthorized,
+          resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false),
+        },
+        media: {
+          saveMediaBuffer: mockSaveMediaBuffer,
+        },
+        pairing: {
+          readAllowFromStore: vi.fn().mockResolvedValue([]),
+          upsertPairingRequest: vi.fn().mockResolvedValue({ code: "ABCDEFGH", created: false }),
+          buildPairingReply: vi.fn(() => "Pairing response"),
+        },
+      },
+      media: {
+        detectMime: vi.fn(async () => "application/octet-stream"),
+      },
+    } as unknown as PluginRuntime);
+  });
+
+  it("dispatches to all broadcast agents when bot is mentioned", async () => {
+    const cfg: ClawdbotConfig = {
+      broadcast: { "oc-broadcast-group": ["susan", "main"] },
+      agents: { list: [{ id: "main" }, { id: "susan" }] },
+      channels: {
+        feishu: {
+          groups: {
+            "oc-broadcast-group": {
+              requireMention: true,
+            },
+          },
+        },
+      },
+    } as unknown as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-sender" } },
+      message: {
+        message_id: "msg-broadcast-mentioned",
+        chat_id: "oc-broadcast-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello @bot" }),
+        mentions: [
+          { key: "@_user_1", id: { open_id: "bot-open-id" }, name: "Bot", tenant_key: "" },
+        ],
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      botOpenId: "bot-open-id",
+      runtime: createRuntimeEnv(),
+    });
+
+    // Both agents should get dispatched
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(2);
+
+    // Verify session keys for both agents
+    const sessionKeys = mockFinalizeInboundContext.mock.calls.map(
+      (call: unknown[]) => (call[0] as { SessionKey: string }).SessionKey,
+    );
+    expect(sessionKeys).toContain("agent:susan:feishu:group:oc-broadcast-group");
+    expect(sessionKeys).toContain("agent:main:feishu:group:oc-broadcast-group");
+
+    // Active agent (mentioned) gets the real Feishu reply dispatcher
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledTimes(1);
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "main" }),
+    );
+  });
+
+  it("skips broadcast dispatch when bot is NOT mentioned (requireMention=true)", async () => {
+    const cfg: ClawdbotConfig = {
+      broadcast: { "oc-broadcast-group": ["susan", "main"] },
+      agents: { list: [{ id: "main" }, { id: "susan" }] },
+      channels: {
+        feishu: {
+          groups: {
+            "oc-broadcast-group": {
+              requireMention: true,
+            },
+          },
+        },
+      },
+    } as unknown as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-sender" } },
+      message: {
+        message_id: "msg-broadcast-not-mentioned",
+        chat_id: "oc-broadcast-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello everyone" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: createRuntimeEnv(),
+    });
+
+    // No dispatch: requireMention=true and bot not mentioned → returns early.
+    // The mentioned bot's handler (on another account or same account with
+    // matching botOpenId) will handle broadcast dispatch for all agents.
+    expect(mockDispatchReplyFromConfig).not.toHaveBeenCalled();
+    expect(mockCreateFeishuReplyDispatcher).not.toHaveBeenCalled();
+  });
+
+  it("preserves single-agent dispatch when no broadcast config", async () => {
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          groups: {
+            "oc-broadcast-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-sender" } },
+      message: {
+        message_id: "msg-no-broadcast",
+        chat_id: "oc-broadcast-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: createRuntimeEnv(),
+    });
+
+    // Single dispatch (no broadcast)
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(mockCreateFeishuReplyDispatcher).toHaveBeenCalledTimes(1);
+    expect(mockFinalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        SessionKey: "agent:main:feishu:group:oc-broadcast-group",
+      }),
+    );
+  });
+
+  it("cross-account broadcast dedup: second account skips dispatch", async () => {
+    const cfg: ClawdbotConfig = {
+      broadcast: { "oc-broadcast-group": ["susan", "main"] },
+      agents: { list: [{ id: "main" }, { id: "susan" }] },
+      channels: {
+        feishu: {
+          groups: {
+            "oc-broadcast-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as unknown as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-sender" } },
+      message: {
+        message_id: "msg-multi-account-dedup",
+        chat_id: "oc-broadcast-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    };
+
+    // First account handles broadcast normally
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: createRuntimeEnv(),
+      accountId: "account-A",
+    });
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(2);
+
+    mockDispatchReplyFromConfig.mockClear();
+    mockFinalizeInboundContext.mockClear();
+
+    // Second account: same message ID, different account.
+    // Per-account dedup passes (different namespace), but cross-account
+    // broadcast dedup blocks dispatch.
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: createRuntimeEnv(),
+      accountId: "account-B",
+    });
+    expect(mockDispatchReplyFromConfig).not.toHaveBeenCalled();
+  });
+
+  it("skips unknown agents not in agents.list", async () => {
+    const cfg: ClawdbotConfig = {
+      broadcast: { "oc-broadcast-group": ["susan", "unknown-agent"] },
+      agents: { list: [{ id: "main" }, { id: "susan" }] },
+      channels: {
+        feishu: {
+          groups: {
+            "oc-broadcast-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as unknown as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: { sender_id: { open_id: "ou-sender" } },
+      message: {
+        message_id: "msg-broadcast-unknown-agent",
+        chat_id: "oc-broadcast-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: createRuntimeEnv(),
+    });
+
+    // Only susan should get dispatched (unknown-agent skipped)
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    const sessionKey = (mockFinalizeInboundContext.mock.calls[0]?.[0] as { SessionKey: string })
+      .SessionKey;
+    expect(sessionKey).toBe("agent:susan:feishu:group:oc-broadcast-group");
   });
 });