@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/sequential-key.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import type { FeishuMessageEvent } from "./bot.js";
+import { getFeishuSequentialKey } from "./sequential-key.js";
+
+function createTextEvent(params: {
+  text: string;
+  messageId?: string;
+  chatId?: string;
+}): FeishuMessageEvent {
+  return {
+    sender: {
+      sender_id: {
+        open_id: "ou_sender_1",
+        user_id: "ou_user_1",
+      },
+      sender_type: "user",
+    },
+    message: {
+      message_id: params.messageId ?? "om_message_1",
+      chat_id: params.chatId ?? "oc_dm_chat",
+      chat_type: "p2p",
+      message_type: "text",
+      content: JSON.stringify({ text: params.text }),
+    },
+  } as FeishuMessageEvent;
+}
+
+describe("getFeishuSequentialKey", () => {
+  it.each([
+    [createTextEvent({ text: "hello" }), "feishu:default:oc_dm_chat"],
+    [createTextEvent({ text: "/status" }), "feishu:default:oc_dm_chat"],
+    [createTextEvent({ text: "/stop" }), "feishu:default:oc_dm_chat:control"],
+    [createTextEvent({ text: "/btw what changed?" }), "feishu:default:oc_dm_chat:btw"],
+  ])("resolves sequential key %#", (event, expected) => {
+    expect(
+      getFeishuSequentialKey({
+        accountId: "default",
+        event,
+      }),
+    ).toBe(expected);
+  });
+
+  it("keeps /btw on a stable per-chat lane across different message ids", () => {
+    const first = createTextEvent({ text: "/btw one", messageId: "om_message_1" });
+    const second = createTextEvent({ text: "/btw two", messageId: "om_message_2" });
+
+    expect(
+      getFeishuSequentialKey({
+        accountId: "default",
+        event: first,
+      }),
+    ).toBe("feishu:default:oc_dm_chat:btw");
+    expect(
+      getFeishuSequentialKey({
+        accountId: "default",
+        event: second,
+      }),
+    ).toBe("feishu:default:oc_dm_chat:btw");
+  });
+
+  it("falls back to a stable btw lane when the message id is unavailable", () => {
+    const event = createTextEvent({ text: "/btw what changed?" });
+    delete (event.message as { message_id?: string }).message_id;
+
+    expect(
+      getFeishuSequentialKey({
+        accountId: "default",
+        event,
+      }),
+    ).toBe("feishu:default:oc_dm_chat:btw");
+  });
+});

package/src/sequential-key.ts

@@ -0,0 +1,28 @@
+import {
+  isAbortRequestText,
+  isBtwRequestText,
+} from "openclaw/plugin-sdk/command-primitives-runtime";
+import { parseFeishuMessageEvent, type FeishuMessageEvent } from "./bot.js";
+
+export function getFeishuSequentialKey(params: {
+  accountId: string;
+  event: FeishuMessageEvent;
+  botOpenId?: string;
+  botName?: string;
+}): string {
+  const { accountId, event, botOpenId, botName } = params;
+  const chatId = event.message.chat_id?.trim() || "unknown";
+  const baseKey = `feishu:${accountId}:${chatId}`;
+  const parsed = parseFeishuMessageEvent(event, botOpenId, botName);
+  const text = parsed.content.trim();
+
+  if (isAbortRequestText(text)) {
+    return `${baseKey}:control`;
+  }
+
+  if (isBtwRequestText(text)) {
+    return `${baseKey}:btw`;
+  }
+
+  return baseKey;
+}

package/src/sequential-queue.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { createSequentialQueue } from "./sequential-queue.js";
+
+function createDeferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+describe("createSequentialQueue", () => {
+  it("serializes tasks for the same key", async () => {
+    const enqueue = createSequentialQueue();
+    const gate = createDeferred();
+    const order: string[] = [];
+
+    const first = enqueue("feishu:default:chat-1", async () => {
+      order.push("first:start");
+      await gate.promise;
+      order.push("first:end");
+    });
+    const second = enqueue("feishu:default:chat-1", async () => {
+      order.push("second:start");
+      order.push("second:end");
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["first:start"]);
+
+    gate.resolve();
+    await Promise.all([first, second]);
+
+    expect(order).toEqual(["first:start", "first:end", "second:start", "second:end"]);
+  });
+
+  it("allows different keys to run concurrently", async () => {
+    const enqueue = createSequentialQueue();
+    const gateA = createDeferred();
+    const gateB = createDeferred();
+    const order: string[] = [];
+
+    const first = enqueue("feishu:default:chat-1", async () => {
+      order.push("chat-1:start");
+      await gateA.promise;
+      order.push("chat-1:end");
+    });
+    const second = enqueue("feishu:default:chat-1:btw:om_2", async () => {
+      order.push("btw:start");
+      await gateB.promise;
+      order.push("btw:end");
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["chat-1:start", "btw:start"]);
+
+    gateA.resolve();
+    gateB.resolve();
+    await Promise.all([first, second]);
+
+    expect(order).toContain("chat-1:end");
+    expect(order).toContain("btw:end");
+  });
+
+  it("does not leak unhandled rejections when a queued task fails", async () => {
+    const enqueue = createSequentialQueue();
+    const unhandled: unknown[] = [];
+    const onUnhandledRejection = (reason: unknown) => {
+      unhandled.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    try {
+      await expect(
+        enqueue("feishu:default:chat-1", async () => {
+          throw new Error("boom");
+        }),
+      ).rejects.toThrow("boom");
+
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(unhandled).toEqual([]);
+
+      await expect(
+        enqueue("feishu:default:chat-1", async () => {
+          return;
+        }),
+      ).resolves.toBeUndefined();
+    } finally {
+      process.off("unhandledRejection", onUnhandledRejection);
+    }
+  });
+});

package/src/sequential-queue.ts

@@ -0,0 +1,16 @@
+export function createSequentialQueue() {
+  const queues = new Map<string, Promise<void>>();
+
+  return (key: string, task: () => Promise<void>): Promise<void> => {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const next = previous.then(task, task);
+    queues.set(key, next);
+    const cleanup = () => {
+      if (queues.get(key) === next) {
+        queues.delete(key);
+      }
+    };
+    next.then(cleanup, cleanup);
+    return next;
+  };
+}

package/src/session-conversation.ts

@@ -0,0 +1,42 @@
+import { buildFeishuConversationId, parseFeishuConversationId } from "./conversation-id.js";
+
+function resolveFeishuParentConversationCandidates(rawId: string): string[] {
+  const parsed = parseFeishuConversationId({ conversationId: rawId });
+  if (!parsed) {
+    return [];
+  }
+  switch (parsed.scope) {
+    case "group_topic_sender":
+      return [
+        buildFeishuConversationId({
+          chatId: parsed.chatId,
+          scope: "group_topic",
+          topicId: parsed.topicId,
+        }),
+        parsed.chatId,
+      ];
+    case "group_topic":
+    case "group_sender":
+      return [parsed.chatId];
+    case "group":
+    default:
+      return [];
+  }
+}
+
+export function resolveFeishuSessionConversation(params: {
+  kind: "group" | "channel";
+  rawId: string;
+}) {
+  const parsed = parseFeishuConversationId({ conversationId: params.rawId });
+  if (!parsed) {
+    return null;
+  }
+  return {
+    id: parsed.canonicalConversationId,
+    baseConversationId: parsed.chatId,
+    parentConversationCandidates: resolveFeishuParentConversationCandidates(
+      parsed.canonicalConversationId,
+    ),
+  };
+}

package/src/session-route.ts

@@ -0,0 +1,48 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "openclaw/plugin-sdk/channel-core";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export function resolveFeishuOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  let trimmed = stripChannelTargetPrefix(params.target, "feishu", "lark");
+  if (!trimmed) {
+    return null;
+  }
+
+  const lower = normalizeLowercaseStringOrEmpty(trimmed);
+  let isGroup = false;
+  let typeExplicit = false;
+
+  if (lower.startsWith("group:") || lower.startsWith("chat:") || lower.startsWith("channel:")) {
+    trimmed = trimmed.replace(/^(group|chat|channel):/i, "").trim();
+    isGroup = true;
+    typeExplicit = true;
+  } else if (lower.startsWith("user:") || lower.startsWith("dm:")) {
+    trimmed = trimmed.replace(/^(user|dm):/i, "").trim();
+    isGroup = false;
+    typeExplicit = true;
+  }
+
+  if (!typeExplicit) {
+    const idLower = normalizeLowercaseStringOrEmpty(trimmed);
+    if (idLower.startsWith("ou_") || idLower.startsWith("on_")) {
+      isGroup = false;
+    }
+  }
+
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "feishu",
+    accountId: params.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: trimmed,
+    },
+    chatType: isGroup ? "group" : "direct",
+    from: isGroup ? `feishu:group:${trimmed}` : `feishu:${trimmed}`,
+    to: trimmed,
+  });
+}

package/src/setup-core.ts

@@ -0,0 +1,51 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  type ChannelSetupAdapter,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/setup";
+import { resolveDefaultFeishuAccountId } from "./accounts.js";
+import type { FeishuConfig } from "./types.js";
+
+export function setFeishuNamedAccountEnabled(
+  cfg: OpenClawConfig,
+  accountId: string,
+  enabled: boolean,
+): OpenClawConfig {
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      feishu: {
+        ...feishuCfg,
+        accounts: {
+          ...feishuCfg?.accounts,
+          [accountId]: {
+            ...feishuCfg?.accounts?.[accountId],
+            enabled,
+          },
+        },
+      },
+    },
+  };
+}
+
+export const feishuSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ cfg, accountId }) => accountId?.trim() || resolveDefaultFeishuAccountId(cfg),
+  applyAccountConfig: ({ cfg, accountId }) => {
+    const isDefault = !accountId || accountId === DEFAULT_ACCOUNT_ID;
+    if (isDefault) {
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          feishu: {
+            ...cfg.channels?.feishu,
+            enabled: true,
+          },
+        },
+      };
+    }
+    return setFeishuNamedAccountEnabled(cfg, accountId, true);
+  },
+};

package/src/{onboarding.test.ts → setup-surface.test.ts}

@@ -1,17 +1,27 @@
+import {
+  createNonExitingRuntimeEnv,
+  createPluginSetupWizardConfigure,
+  createPluginSetupWizardStatus,
+  createTestWizardPrompter,
+  runSetupWizardConfigure,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
 import { describe, expect, it, vi } from "vitest";
 
 vi.mock("./probe.js", () => ({
   probeFeishu: vi.fn(async () => ({ ok: false, error: "mocked" })),
 }));
 
-import { feishuOnboardingAdapter } from "./onboarding.js";
+vi.mock("./app-registration.js", () => ({
+  initAppRegistration: vi.fn(async () => {
+    throw new Error("mocked: scan-to-create not available");
+  }),
+  beginAppRegistration: vi.fn(),
+  pollAppRegistration: vi.fn(),
+  printQrCode: vi.fn(async () => {}),
+  getAppOwnerOpenId: vi.fn(async () => undefined),
+}));
 
-const baseConfigureContext = {
-  runtime: {} as never,
-  accountOverrides: {},
-  shouldPromptAccountIds: false,
-  forceAllowFrom: false,
-};
+import { feishuPlugin } from "./channel.js";
 
 const baseStatusContext = {
   accountOverrides: {},
@@ -42,7 +52,7 @@ async function withEnvVars(values: Record<string, string | undefined>, run: () =
 }
 
 async function getStatusWithEnvRefs(params: { appIdKey: string; appSecretKey: string }) {
-  return await feishuOnboardingAdapter.getStatus({
+  return await feishuGetStatus({
     cfg: {
       channels: {
         feishu: {
@@ -55,25 +65,26 @@ async function getStatusWithEnvRefs(params: { appIdKey: string; appSecretKey: st
   });
 }
 
-describe("feishuOnboardingAdapter.configure", () => {
+const feishuConfigure = createPluginSetupWizardConfigure(feishuPlugin);
+const feishuGetStatus = createPluginSetupWizardStatus(feishuPlugin);
+
+describe("feishu setup wizard", () => {
   it("does not throw when config appId/appSecret are SecretRef objects", async () => {
     const text = vi
       .fn()
       .mockResolvedValueOnce("cli_from_prompt")
-      .mockResolvedValueOnce("secret_from_prompt")
-      .mockResolvedValueOnce("oc_group_1");
-
-    const prompter = {
-      note: vi.fn(async () => undefined),
+      .mockResolvedValueOnce("secret_from_prompt");
+    const prompter = createTestWizardPrompter({
       text,
       confirm: vi.fn(async () => true),
       select: vi.fn(
-        async ({ initialValue }: { initialValue?: string }) => initialValue ?? "allowlist",
-      ),
-    } as never;
+        async ({ initialValue }: { initialValue?: string }) => initialValue ?? "bot",
+      ) as never,
+    });
 
     await expect(
-      feishuOnboardingAdapter.configure({
+      runSetupWizardConfigure({
+        configure: feishuConfigure,
         cfg: {
           channels: {
             feishu: {
@@ -83,15 +94,35 @@ describe("feishuOnboardingAdapter.configure", () => {
           },
         } as never,
         prompter,
-        ...baseConfigureContext,
+        runtime: createNonExitingRuntimeEnv(),
       }),
     ).resolves.toBeTruthy();
   });
 });
 
-describe("feishuOnboardingAdapter.getStatus", () => {
+describe("feishu setup wizard status", () => {
+  it("treats SecretRef appSecret as configured when appId is present", async () => {
+    const status = await feishuGetStatus({
+      cfg: {
+        channels: {
+          feishu: {
+            appId: "cli_a123456",
+            appSecret: {
+              source: "env",
+              provider: "default",
+              id: "FEISHU_APP_SECRET",
+            },
+          },
+        },
+      } as never,
+      accountOverrides: {},
+    });
+
+    expect(status.configured).toBe(true);
+  });
+
   it("does not fallback to top-level appId when account explicitly sets empty appId", async () => {
-    const status = await feishuOnboardingAdapter.getStatus({
+    const status = await feishuGetStatus({
       cfg: {
         channels: {
           feishu: {