@kodelyth/feishu 2026.5.39 → 2026.5.42

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,25 @@
+import { isAbortRequestText, isBtwRequestText } from "klaw/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,165 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createSequentialQueue } from "./sequential-queue.js";
+
+function createDeferred() {
+  let resolve: (() => void) | undefined;
+  const promise = new Promise<void>((res) => {
+    resolve = res;
+  });
+  if (!resolve) {
+    throw new Error("Expected deferred resolver to be initialized");
+  }
+  return { promise, resolve };
+}
+
+describe("createSequentialQueue", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  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<void>((resolve) => setImmediate(resolve));
+      expect(unhandled).toStrictEqual([]);
+
+      await expect(
+        enqueue("feishu:default:chat-1", async () => {
+          return;
+        }),
+      ).resolves.toBeUndefined();
+    } finally {
+      process.off("unhandledRejection", onUnhandledRejection);
+    }
+  });
+
+  it("evicts a stuck task after taskTimeoutMs so newer same-key work proceeds", async () => {
+    vi.useFakeTimers();
+    const timeouts: Array<{ key: string; timeoutMs: number }> = [];
+    const enqueue = createSequentialQueue({
+      taskTimeoutMs: 25,
+      onTaskTimeout: (key, timeoutMs) => {
+        timeouts.push({ key, timeoutMs });
+      },
+    });
+    const order: string[] = [];
+
+    // Stuck task — never resolves until the test cleans up.
+    const stuckGate = createDeferred();
+    const stuck = enqueue("feishu:default:chat-stuck", async () => {
+      order.push("stuck:start");
+      await stuckGate.promise;
+      order.push("stuck:end");
+    });
+
+    // Second same-key task — would be starved indefinitely without the cap.
+    const followUp = enqueue("feishu:default:chat-stuck", async () => {
+      order.push("follow-up:ran");
+    });
+
+    await vi.advanceTimersByTimeAsync(25);
+    await followUp;
+
+    expect(order).toEqual(["stuck:start", "follow-up:ran"]);
+    expect(timeouts).toEqual([{ key: "feishu:default:chat-stuck", timeoutMs: 25 }]);
+
+    // Drain the leaked stuck task so it doesn't trip the unhandled-rejection guard.
+    stuckGate.resolve();
+    await stuck;
+  });
+
+  it("disables the timeout cap when taskTimeoutMs is 0 (legacy behavior)", async () => {
+    vi.useFakeTimers();
+    const timeouts: Array<{ key: string; timeoutMs: number }> = [];
+    const enqueue = createSequentialQueue({
+      taskTimeoutMs: 0,
+      onTaskTimeout: (key, timeoutMs) => {
+        timeouts.push({ key, timeoutMs });
+      },
+    });
+    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:ran");
+    });
+
+    // Wait long enough that a timeout would have fired if it were active.
+    await vi.advanceTimersByTimeAsync(30);
+    expect(order).toEqual(["first:start"]);
+    expect(timeouts).toStrictEqual([]);
+
+    gate.resolve();
+    await Promise.all([first, second]);
+    expect(order).toEqual(["first:start", "first:end", "second:ran"]);
+  });
+});

package/src/sequential-queue.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-key serial task queue for Feishu inbound message handling.
+ *
+ * Tasks enqueued under the same key run in FIFO order. Different keys run
+ * concurrently. This preserves the channel's same-chat ordering contract
+ * (see #64324) while letting cross-chat work proceed in parallel.
+ *
+ * `taskTimeoutMs` bounds how long the queue will block subsequent same-key
+ * tasks behind a single in-flight task. After the cap, the in-flight task
+ * is evicted from the blocking chain so newer messages for the same key
+ * can proceed. The original task is NOT aborted — it continues running in
+ * the background; it just stops starving the queue.
+ *
+ * Without this cap, a single hung dispatch (e.g. an agent call that never
+ * resolves) keeps later same-chat messages in `queued` state until the
+ * gateway is restarted. See #70133.
+ */
+
+const DEFAULT_TASK_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface SequentialQueueOptions {
+  /**
+   * Maximum time (ms) to block subsequent same-key tasks behind a single
+   * in-flight task. Pass 0 (or a non-finite value) to disable the cap and
+   * restore unbounded legacy behavior.
+   *
+   * Default: 5 minutes.
+   */
+  taskTimeoutMs?: number;
+
+  /**
+   * Optional callback fired when a task exceeds `taskTimeoutMs`. The task
+   * itself is not awaited further; this callback is the only signal the
+   * caller gets that the queue moved on without it.
+   */
+  onTaskTimeout?: (key: string, timeoutMs: number) => void;
+}
+
+export function createSequentialQueue(options: SequentialQueueOptions = {}) {
+  const queues = new Map<string, Promise<void>>();
+  const taskTimeoutMs = options.taskTimeoutMs ?? DEFAULT_TASK_TIMEOUT_MS;
+  const onTaskTimeout = options.onTaskTimeout;
+
+  return (key: string, task: () => Promise<void>): Promise<void> => {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const wrapped = () => boundedRun(key, task, taskTimeoutMs, onTaskTimeout);
+    const next = previous.then(wrapped, wrapped);
+    queues.set(key, next);
+    const cleanup = () => {
+      if (queues.get(key) === next) {
+        queues.delete(key);
+      }
+    };
+    next.then(cleanup, cleanup);
+    return next;
+  };
+}
+
+async function boundedRun(
+  key: string,
+  task: () => Promise<void>,
+  timeoutMs: number,
+  onTaskTimeout: ((key: string, timeoutMs: number) => void) | undefined,
+): Promise<void> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return task();
+  }
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      try {
+        onTaskTimeout?.(key, timeoutMs);
+      } catch {
+        // Swallow logging errors so they cannot poison the queue chain.
+      }
+      resolve();
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([task(), timeoutPromise]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}

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 "klaw/plugin-sdk/channel-core";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-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 KlawConfig,
+} from "klaw/plugin-sdk/setup";
+import { resolveDefaultFeishuAccountId } from "./accounts.js";
+import type { FeishuConfig } from "./types.js";
+
+export function setFeishuNamedAccountEnabled(
+  cfg: KlawConfig,
+  accountId: string,
+  enabled: boolean,
+): KlawConfig {
+  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);
+  },
+};