@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/test-support/lifecycle-test-support.ts

@@ -0,0 +1,454 @@
+import { randomUUID } from "node:crypto";
+import { createPluginRuntimeMock } from "klaw/plugin-sdk/channel-test-helpers";
+import { expect, vi, type Mock } from "vitest";
+import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../../runtime-api.js";
+import { setFeishuRuntime } from "../runtime.js";
+import type { ResolvedFeishuAccount } from "../types.js";
+
+const FEISHU_LIFECYCLE_WAIT_TIMEOUT_MS = 10_000;
+
+type InboundDebouncerParams<T> = {
+  onFlush?: (items: T[]) => Promise<void>;
+  onError?: (err: unknown, items: T[]) => void;
+};
+type UnknownMock = Mock<(...args: unknown[]) => unknown>;
+type AsyncUnknownMock = Mock<(...args: unknown[]) => Promise<unknown>>;
+type FeishuDispatchReplyCounts = {
+  final: number;
+  block?: number;
+  tool?: number;
+};
+type FeishuDispatchReplyContext = Record<string, unknown> & {
+  SessionKey?: string;
+};
+type FeishuDispatchReplyDispatcher = {
+  sendFinalReply: (payload: { text: string }) => unknown;
+};
+type FeishuDispatchReplyMock = Mock<
+  (args: {
+    ctx: FeishuDispatchReplyContext;
+    dispatcher: FeishuDispatchReplyDispatcher;
+  }) => Promise<{ queuedFinal: boolean; counts: FeishuDispatchReplyCounts }>
+>;
+type FeishuLifecycleReplyDispatcher = {
+  dispatcher: {
+    sendToolResult: UnknownMock;
+    sendBlockReply: UnknownMock;
+    sendFinalReply: AsyncUnknownMock;
+    waitForIdle: AsyncUnknownMock;
+    getQueuedCounts: UnknownMock;
+    markComplete: UnknownMock;
+  };
+  replyOptions: Record<string, never>;
+  markDispatchIdle: UnknownMock;
+};
+
+export function setFeishuLifecycleStateDir(prefix: string) {
+  process.env.KLAW_STATE_DIR = `/tmp/${prefix}-${randomUUID()}`;
+}
+
+export function restoreFeishuLifecycleStateDir(originalStateDir: string | undefined) {
+  if (originalStateDir === undefined) {
+    delete process.env.KLAW_STATE_DIR;
+    return;
+  }
+  process.env.KLAW_STATE_DIR = originalStateDir;
+}
+
+const FEISHU_PREFETCHED_BOT_OPEN_ID_SOURCE = {
+  kind: "prefetched",
+  botOpenId: "ou_bot_1",
+  botName: "Bot",
+} as const;
+
+export function createFeishuLifecycleReplyDispatcher(): FeishuLifecycleReplyDispatcher {
+  return {
+    dispatcher: {
+      sendToolResult: vi.fn(() => false),
+      sendBlockReply: vi.fn(() => false),
+      sendFinalReply: vi.fn(async () => true),
+      waitForIdle: vi.fn(async () => {}),
+      getQueuedCounts: vi.fn(() => ({ tool: 0, block: 0, final: 0 })),
+      markComplete: vi.fn(),
+    },
+    replyOptions: {},
+    markDispatchIdle: vi.fn(),
+  };
+}
+
+function createImmediateInboundDebounce() {
+  return {
+    resolveInboundDebounceMs: vi.fn(() => 0),
+    createInboundDebouncer: <T>(params: InboundDebouncerParams<T>) => ({
+      enqueue: async (item: T) => {
+        try {
+          await params.onFlush?.([item]);
+        } catch (err) {
+          params.onError?.(err, [item]);
+        }
+      },
+      flushKey: async () => {},
+      cancelKey: () => false,
+    }),
+  };
+}
+
+function installFeishuLifecycleRuntime(params: {
+  resolveAgentRoute: PluginRuntime["channel"]["routing"]["resolveAgentRoute"];
+  finalizeInboundContext: PluginRuntime["channel"]["reply"]["finalizeInboundContext"];
+  dispatchReplyFromConfig: PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"];
+  withReplyDispatcher: PluginRuntime["channel"]["reply"]["withReplyDispatcher"];
+  resolveStorePath: PluginRuntime["channel"]["session"]["resolveStorePath"];
+  hasControlCommand?: PluginRuntime["channel"]["text"]["hasControlCommand"];
+  shouldComputeCommandAuthorized?: PluginRuntime["channel"]["commands"]["shouldComputeCommandAuthorized"];
+  resolveCommandAuthorizedFromAuthorizers?: PluginRuntime["channel"]["commands"]["resolveCommandAuthorizedFromAuthorizers"];
+  readAllowFromStore?: PluginRuntime["channel"]["pairing"]["readAllowFromStore"];
+  upsertPairingRequest?: PluginRuntime["channel"]["pairing"]["upsertPairingRequest"];
+  buildPairingReply?: PluginRuntime["channel"]["pairing"]["buildPairingReply"];
+  detectMime?: PluginRuntime["media"]["detectMime"];
+}): PluginRuntime {
+  const runtime = createPluginRuntimeMock({
+    channel: {
+      debounce: createImmediateInboundDebounce(),
+      text: {
+        hasControlCommand: params.hasControlCommand ?? vi.fn(() => false),
+      },
+      routing: {
+        resolveAgentRoute: params.resolveAgentRoute,
+      },
+      reply: {
+        resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+        formatAgentEnvelope: vi.fn((value: { body: string }) => value.body),
+        finalizeInboundContext: params.finalizeInboundContext,
+        dispatchReplyFromConfig: params.dispatchReplyFromConfig,
+        withReplyDispatcher: params.withReplyDispatcher,
+      },
+      commands: {
+        shouldComputeCommandAuthorized: params.shouldComputeCommandAuthorized ?? vi.fn(() => false),
+        resolveCommandAuthorizedFromAuthorizers:
+          params.resolveCommandAuthorizedFromAuthorizers ?? vi.fn(() => false),
+      },
+      session: {
+        readSessionUpdatedAt: vi.fn(),
+        resolveStorePath: params.resolveStorePath,
+      },
+      pairing: {
+        readAllowFromStore: params.readAllowFromStore ?? vi.fn().mockResolvedValue([]),
+        upsertPairingRequest: params.upsertPairingRequest ?? vi.fn(),
+        buildPairingReply: params.buildPairingReply ?? vi.fn(),
+      },
+    },
+    media: {
+      detectMime: params.detectMime ?? vi.fn(async () => "text/plain"),
+    },
+  }) as unknown as PluginRuntime;
+  setFeishuRuntime(runtime);
+  return runtime;
+}
+
+export function installFeishuLifecycleReplyRuntime(params: {
+  resolveAgentRouteMock: unknown;
+  finalizeInboundContextMock: unknown;
+  dispatchReplyFromConfigMock: unknown;
+  withReplyDispatcherMock: unknown;
+  storePath: string;
+}): PluginRuntime {
+  return installFeishuLifecycleRuntime({
+    resolveAgentRoute:
+      params.resolveAgentRouteMock as PluginRuntime["channel"]["routing"]["resolveAgentRoute"],
+    finalizeInboundContext:
+      params.finalizeInboundContextMock as PluginRuntime["channel"]["reply"]["finalizeInboundContext"],
+    dispatchReplyFromConfig:
+      params.dispatchReplyFromConfigMock as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"],
+    withReplyDispatcher:
+      params.withReplyDispatcherMock as PluginRuntime["channel"]["reply"]["withReplyDispatcher"],
+    resolveStorePath: vi.fn(() => params.storePath),
+  });
+}
+
+export function mockFeishuReplyOnceDispatch(params: {
+  dispatchReplyFromConfigMock: FeishuDispatchReplyMock;
+  replyText: string;
+  shouldSendFinalReply?: (ctx: unknown) => boolean;
+}) {
+  params.dispatchReplyFromConfigMock.mockImplementation(async ({ ctx, dispatcher }) => {
+    const shouldSendFinalReply = params.shouldSendFinalReply?.(ctx) ?? true;
+    if (shouldSendFinalReply && typeof dispatcher?.sendFinalReply === "function") {
+      await dispatcher.sendFinalReply({ text: params.replyText });
+    }
+    return {
+      queuedFinal: false,
+      counts: { final: shouldSendFinalReply ? 1 : 0 },
+    };
+  });
+}
+
+export function createFeishuLifecycleConfig(params: {
+  accountId: string;
+  appId: string;
+  appSecret: string;
+  channelConfig?: Record<string, unknown>;
+  accountConfig?: Record<string, unknown>;
+  extraConfig?: Record<string, unknown>;
+}): ClawdbotConfig {
+  const extraConfig = params.extraConfig ?? {};
+  return {
+    ...extraConfig,
+    channels: {
+      ...(extraConfig.channels as Record<string, unknown> | undefined),
+      feishu: {
+        enabled: true,
+        requireMention: false,
+        resolveSenderNames: false,
+        ...params.channelConfig,
+        accounts: {
+          [params.accountId]: {
+            enabled: true,
+            appId: params.appId,
+            appSecret: params.appSecret, // pragma: allowlist secret
+            connectionMode: "websocket",
+            requireMention: false,
+            resolveSenderNames: false,
+            ...params.accountConfig,
+          },
+        },
+      },
+    },
+    messages: {
+      inbound: {
+        debounceMs: 0,
+        byChannel: {
+          feishu: 0,
+        },
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+export function createFeishuLifecycleFixture(params: {
+  accountId: string;
+  appId: string;
+  appSecret: string;
+  channelConfig?: Record<string, unknown>;
+  accountConfig?: Record<string, unknown>;
+  extraConfig?: Record<string, unknown>;
+}) {
+  return {
+    cfg: createFeishuLifecycleConfig(params),
+    account: createResolvedFeishuLifecycleAccount({
+      accountId: params.accountId,
+      appId: params.appId,
+      appSecret: params.appSecret,
+      config: {
+        ...params.channelConfig,
+        ...params.accountConfig,
+      },
+    }),
+  };
+}
+
+export function createResolvedFeishuLifecycleAccount(params: {
+  accountId: string;
+  appId: string;
+  appSecret: string;
+  config: Record<string, unknown>;
+}): ResolvedFeishuAccount {
+  return {
+    accountId: params.accountId,
+    selectionSource: "config",
+    enabled: true,
+    configured: true,
+    appId: params.appId,
+    appSecret: params.appSecret, // pragma: allowlist secret
+    domain: "feishu",
+    config: {
+      enabled: true,
+      connectionMode: "websocket",
+      requireMention: false,
+      resolveSenderNames: false,
+      ...params.config,
+    },
+  } as unknown as ResolvedFeishuAccount;
+}
+
+export function createFeishuTextMessageEvent(params: {
+  messageId: string;
+  chatId: string;
+  text: string;
+  chatType?: "group" | "p2p";
+  senderOpenId?: string;
+  rootId?: string;
+  threadId?: string;
+}) {
+  return {
+    sender: {
+      sender_id: { open_id: params.senderOpenId ?? "ou_sender_1" },
+      sender_type: "user",
+    },
+    message: {
+      message_id: params.messageId,
+      ...(params.rootId ? { root_id: params.rootId } : {}),
+      ...(params.threadId ? { thread_id: params.threadId } : {}),
+      chat_id: params.chatId,
+      chat_type: params.chatType ?? "group",
+      message_type: "text",
+      content: JSON.stringify({ text: params.text }),
+      create_time: "1710000000000",
+    },
+  };
+}
+
+async function expectFeishuLifecycleEventually(
+  assertion: () => void | Promise<void>,
+  timeoutMs: number,
+) {
+  try {
+    await assertion();
+  } catch {
+    await vi.waitFor(assertion, { timeout: timeoutMs });
+  }
+}
+
+async function replayFeishuLifecycleEvent(params: {
+  handler: (data: unknown) => Promise<void>;
+  event: unknown;
+  waitForFirst: () => void | Promise<void>;
+  waitForSecond?: () => void | Promise<void>;
+  waitTimeoutMs?: number;
+}) {
+  const waitTimeoutMs = params.waitTimeoutMs ?? FEISHU_LIFECYCLE_WAIT_TIMEOUT_MS;
+  await params.handler(params.event);
+  await expectFeishuLifecycleEventually(params.waitForFirst, waitTimeoutMs);
+  await params.handler(params.event);
+  await expectFeishuLifecycleEventually(params.waitForSecond ?? params.waitForFirst, waitTimeoutMs);
+}
+
+export async function runFeishuLifecycleSequence(
+  deliveries: Array<() => Promise<void>>,
+  waits: Array<() => void | Promise<void>>,
+) {
+  for (const [index, deliver] of deliveries.entries()) {
+    await deliver();
+    await expectFeishuLifecycleEventually(
+      waits[index] ?? waits.at(-1) ?? (() => {}),
+      FEISHU_LIFECYCLE_WAIT_TIMEOUT_MS,
+    );
+  }
+}
+
+export async function expectFeishuSingleEffectAcrossReplay(params: {
+  handler: (data: unknown) => Promise<void>;
+  event: unknown;
+  effectMock: ReturnType<typeof vi.fn>;
+  effectCount?: number;
+}) {
+  const effectCount = params.effectCount ?? 1;
+  await replayFeishuLifecycleEvent({
+    handler: params.handler,
+    event: params.event,
+    waitForFirst: () => {
+      expect(params.effectMock).toHaveBeenCalledTimes(effectCount);
+    },
+  });
+}
+
+export async function expectFeishuReplyPipelineDedupedAcrossReplay(params: {
+  handler: (data: unknown) => Promise<void>;
+  event: unknown;
+  dispatchReplyFromConfigMock: ReturnType<typeof vi.fn>;
+  createFeishuReplyDispatcherMock: ReturnType<typeof vi.fn>;
+  waitTimeoutMs?: number;
+}) {
+  const waitTimeoutMs = params.waitTimeoutMs ?? FEISHU_LIFECYCLE_WAIT_TIMEOUT_MS;
+  await replayFeishuLifecycleEvent({
+    handler: params.handler,
+    event: params.event,
+    waitTimeoutMs,
+    waitForFirst: () => {
+      expect(params.dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1);
+    },
+    waitForSecond: () => {
+      expect(params.dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1);
+      expect(params.createFeishuReplyDispatcherMock).toHaveBeenCalledTimes(1);
+    },
+  });
+}
+
+export async function expectFeishuReplyPipelineDedupedAfterPostSendFailure(params: {
+  handler: (data: unknown) => Promise<void>;
+  event: unknown;
+  dispatchReplyFromConfigMock: ReturnType<typeof vi.fn>;
+  runtimeErrorMock: ReturnType<typeof vi.fn>;
+  waitTimeoutMs?: number;
+}) {
+  const waitTimeoutMs = params.waitTimeoutMs ?? FEISHU_LIFECYCLE_WAIT_TIMEOUT_MS;
+  await replayFeishuLifecycleEvent({
+    handler: params.handler,
+    event: params.event,
+    waitTimeoutMs,
+    waitForFirst: () => {
+      expect(params.dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1);
+      expect(params.runtimeErrorMock).toHaveBeenCalledTimes(1);
+    },
+    waitForSecond: () => {
+      expect(params.dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1);
+      expect(params.runtimeErrorMock).toHaveBeenCalledTimes(1);
+    },
+  });
+}
+
+export function expectFeishuReplyDispatcherSentFinalReplyOnce(params: {
+  createFeishuReplyDispatcherMock: ReturnType<typeof vi.fn>;
+}) {
+  const dispatcher = params.createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as {
+    sendFinalReply: ReturnType<typeof vi.fn>;
+  };
+  expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1);
+}
+
+async function loadMonitorSingleAccount() {
+  const module = await import("../monitor.account.js");
+  return module.monitorSingleAccount;
+}
+
+export async function setupFeishuLifecycleHandler(params: {
+  createEventDispatcherMock: {
+    mockReturnValue: (value: unknown) => unknown;
+    mockReturnValueOnce: (value: unknown) => unknown;
+  };
+  onRegister: (registered: Record<string, (data: unknown) => Promise<void>>) => void;
+  runtime: RuntimeEnv;
+  cfg: ClawdbotConfig;
+  account: ResolvedFeishuAccount;
+  handlerKey: string;
+  missingHandlerMessage: string;
+  once?: boolean;
+}): Promise<(data: unknown) => Promise<void>> {
+  const register = vi.fn((registered: Record<string, (data: unknown) => Promise<void>>) => {
+    params.onRegister(registered);
+  });
+  if (params.once) {
+    params.createEventDispatcherMock.mockReturnValueOnce({ register });
+  } else {
+    params.createEventDispatcherMock.mockReturnValue({ register });
+  }
+
+  const monitorSingleAccount = await loadMonitorSingleAccount();
+  await monitorSingleAccount({
+    cfg: params.cfg,
+    account: params.account,
+    runtime: params.runtime,
+    botOpenIdSource: FEISHU_PREFETCHED_BOT_OPEN_ID_SOURCE,
+    fireAndForget: false,
+  });
+
+  const handlers: Record<string, (data: unknown) => Promise<void>> = {};
+  for (const [key, value] of Object.entries(register.mock.calls.at(0)?.[0] ?? {})) {
+    handlers[key] = value as (data: unknown) => Promise<void>;
+  }
+  const handler = handlers[params.handlerKey];
+  if (!handler) {
+    throw new Error(params.missingHandlerMessage);
+  }
+  return handler;
+}

package/src/thread-bindings.test.ts

@@ -0,0 +1,180 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { getSessionBindingService } from "klaw/plugin-sdk/conversation-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { testing, createFeishuThreadBindingManager } from "./thread-bindings.js";
+
+const baseCfg = {
+  session: { mainKey: "main", scope: "per-sender" },
+} satisfies KlawConfig;
+
+describe("Feishu thread bindings", () => {
+  beforeEach(() => {
+    testing.resetFeishuThreadBindingsForTests();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("registers current-placement adapter capabilities for Feishu", () => {
+    createFeishuThreadBindingManager({ cfg: baseCfg, accountId: "default" });
+
+    expect(
+      getSessionBindingService().getCapabilities({
+        channel: "feishu",
+        accountId: "default",
+      }),
+    ).toEqual({
+      adapterAvailable: true,
+      bindSupported: true,
+      unbindSupported: true,
+      placements: ["current"],
+    });
+  });
+
+  it("binds and resolves a Feishu topic conversation", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    createFeishuThreadBindingManager({ cfg: baseCfg, accountId: "default" });
+
+    const binding = await getSessionBindingService().bind({
+      targetSessionKey: "agent:codex:acp:binding:feishu:default:abc123",
+      targetKind: "session",
+      conversation: {
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root",
+        parentConversationId: "oc_group_chat",
+      },
+      placement: "current",
+      metadata: {
+        agentId: "codex",
+        label: "codex-main",
+      },
+    });
+
+    expect(binding.conversation.conversationId).toBe("oc_group_chat:topic:om_topic_root");
+    const resolved = getSessionBindingService().resolveByConversation({
+      channel: "feishu",
+      accountId: "default",
+      conversationId: "oc_group_chat:topic:om_topic_root",
+    });
+    expect(resolved).toEqual({
+      bindingId: "default:oc_group_chat:topic:om_topic_root",
+      targetSessionKey: "agent:codex:acp:binding:feishu:default:abc123",
+      targetKind: "session",
+      conversation: {
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root",
+        parentConversationId: "oc_group_chat",
+      },
+      status: "active",
+      boundAt: 1_700_000_000_000,
+      expiresAt: 1_700_086_400_000,
+      metadata: {
+        agentId: "codex",
+        label: "codex-main",
+        boundBy: undefined,
+        deliveryTo: undefined,
+        deliveryThreadId: undefined,
+        lastActivityAt: 1_700_000_000_000,
+        idleTimeoutMs: 86_400_000,
+        maxAgeMs: 0,
+      },
+    });
+  });
+
+  it("clears account-scoped bindings when the manager stops", async () => {
+    const manager = createFeishuThreadBindingManager({ cfg: baseCfg, accountId: "default" });
+
+    await getSessionBindingService().bind({
+      targetSessionKey: "agent:codex:acp:binding:feishu:default:abc123",
+      targetKind: "session",
+      conversation: {
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root",
+        parentConversationId: "oc_group_chat",
+      },
+      placement: "current",
+      metadata: {
+        agentId: "codex",
+      },
+    });
+
+    manager.stop();
+
+    expect(
+      getSessionBindingService().resolveByConversation({
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root",
+      }),
+    ).toBeNull();
+  });
+
+  it("preserves delivery routing metadata when rebinding the same conversation", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_100_000);
+    const manager = createFeishuThreadBindingManager({ cfg: baseCfg, accountId: "default" });
+
+    manager.bindConversation({
+      conversationId: "oc_group_chat:topic:om_topic_root:sender:ou_sender_1",
+      parentConversationId: "oc_group_chat",
+      targetKind: "subagent",
+      targetSessionKey: "agent:main:subagent:child",
+      metadata: {
+        agentId: "codex",
+        label: "child",
+        boundBy: "system",
+        deliveryTo: "user:ou_sender_1",
+        deliveryThreadId: "om_topic_root",
+      },
+    });
+
+    await getSessionBindingService().bind({
+      targetSessionKey: "agent:main:subagent:child",
+      targetKind: "subagent",
+      conversation: {
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root:sender:ou_sender_1",
+        parentConversationId: "oc_group_chat",
+      },
+      placement: "current",
+      metadata: {
+        label: "child",
+      },
+    });
+
+    expect(
+      getSessionBindingService().resolveByConversation({
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root:sender:ou_sender_1",
+      }),
+    ).toEqual({
+      bindingId: "default:oc_group_chat:topic:om_topic_root:sender:ou_sender_1",
+      targetSessionKey: "agent:main:subagent:child",
+      targetKind: "subagent",
+      conversation: {
+        channel: "feishu",
+        accountId: "default",
+        conversationId: "oc_group_chat:topic:om_topic_root:sender:ou_sender_1",
+        parentConversationId: "oc_group_chat",
+      },
+      status: "active",
+      boundAt: 1_700_000_100_000,
+      expiresAt: 1_700_086_500_000,
+      metadata: {
+        agentId: "codex",
+        label: "child",
+        boundBy: "system",
+        deliveryTo: "user:ou_sender_1",
+        deliveryThreadId: "om_topic_root",
+        lastActivityAt: 1_700_000_100_000,
+        idleTimeoutMs: 86_400_000,
+        maxAgeMs: 0,
+      },
+    });
+  });
+});