@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/dynamic-agent.test.ts

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { KlawConfig, PluginRuntime } from "../runtime-api.js";
+import { maybeCreateDynamicAgent } from "./dynamic-agent.js";
+
+let tempRoot: string;
+
+beforeEach(async () => {
+  tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "klaw-feishu-agent-"));
+});
+
+afterEach(async () => {
+  await fs.promises.rm(tempRoot, { recursive: true, force: true });
+});
+
+function createRuntime() {
+  const replaceConfigFile = vi.fn(async () => {});
+  return {
+    runtime: {
+      config: {
+        replaceConfigFile,
+      },
+    } as unknown as PluginRuntime,
+    replaceConfigFile,
+  };
+}
+
+function createDynamicConfig() {
+  return {
+    enabled: true,
+    workspaceTemplate: path.join(tempRoot, "workspace-{agentId}"),
+    agentDirTemplate: path.join(tempRoot, "agent-{agentId}"),
+  };
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  return fs.promises
+    .stat(target)
+    .then(() => true)
+    .catch((err: unknown) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return false;
+      }
+      throw err;
+    });
+}
+
+describe("maybeCreateDynamicAgent", () => {
+  it("does not persist dynamic agents when config writes are disabled", async () => {
+    const { runtime, replaceConfigFile } = createRuntime();
+    const dynamicCfg = createDynamicConfig();
+
+    const result = await maybeCreateDynamicAgent({
+      cfg: {
+        channels: { feishu: { configWrites: false } },
+        agents: { list: [] },
+        bindings: [],
+      } as KlawConfig,
+      runtime,
+      senderOpenId: "ou_sender",
+      dynamicCfg,
+      configWritesAllowed: false,
+      log: vi.fn(),
+    });
+
+    expect(result).toEqual({
+      created: false,
+      updatedCfg: {
+        channels: { feishu: { configWrites: false } },
+        agents: { list: [] },
+        bindings: [],
+      },
+    });
+    expect(replaceConfigFile).not.toHaveBeenCalled();
+    expect(await pathExists(path.join(tempRoot, "workspace-feishu-ou_sender"))).toBe(false);
+    expect(await pathExists(path.join(tempRoot, "agent-feishu-ou_sender"))).toBe(false);
+  });
+
+  it("persists a sender agent and direct binding when config writes are allowed", async () => {
+    const { runtime, replaceConfigFile } = createRuntime();
+
+    const result = await maybeCreateDynamicAgent({
+      cfg: {
+        agents: { list: [] },
+        bindings: [],
+      } as KlawConfig,
+      runtime,
+      senderOpenId: "ou_sender",
+      dynamicCfg: createDynamicConfig(),
+      configWritesAllowed: true,
+      log: vi.fn(),
+    });
+
+    expect(result.created).toBe(true);
+    expect(result.agentId).toBe("feishu-ou_sender");
+    expect(replaceConfigFile).toHaveBeenCalledTimes(1);
+    expect(replaceConfigFile).toHaveBeenCalledWith({
+      nextConfig: {
+        agents: {
+          list: [
+            {
+              id: "feishu-ou_sender",
+              workspace: path.join(tempRoot, "workspace-feishu-ou_sender"),
+              agentDir: path.join(tempRoot, "agent-feishu-ou_sender"),
+            },
+          ],
+        },
+        bindings: [
+          {
+            agentId: "feishu-ou_sender",
+            match: {
+              channel: "feishu",
+              peer: { kind: "direct", id: "ou_sender" },
+            },
+          },
+        ],
+      },
+      afterWrite: { mode: "auto" },
+    });
+    expect(await pathExists(path.join(tempRoot, "workspace-feishu-ou_sender"))).toBe(true);
+    expect(await pathExists(path.join(tempRoot, "agent-feishu-ou_sender"))).toBe(true);
+  });
+
+  it("keeps the maxAgents limit before adding a missing binding", async () => {
+    const { runtime, replaceConfigFile } = createRuntime();
+
+    const result = await maybeCreateDynamicAgent({
+      cfg: {
+        agents: {
+          list: [
+            {
+              id: "feishu-ou_sender",
+              workspace: path.join(tempRoot, "existing-workspace"),
+              agentDir: path.join(tempRoot, "existing-agent"),
+            },
+          ],
+        },
+        bindings: [],
+      } as KlawConfig,
+      runtime,
+      senderOpenId: "ou_sender",
+      dynamicCfg: {
+        ...createDynamicConfig(),
+        maxAgents: 1,
+      },
+      configWritesAllowed: true,
+      log: vi.fn(),
+    });
+
+    expect(result.created).toBe(false);
+    expect(replaceConfigFile).not.toHaveBeenCalled();
+  });
+});

package/src/dynamic-agent.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { KlawConfig, PluginRuntime } from "../runtime-api.js";
+import type { DynamicAgentCreationConfig } from "./types.js";
+
+type MaybeCreateDynamicAgentResult = {
+  created: boolean;
+  updatedCfg: KlawConfig;
+  agentId?: string;
+};
+
+/**
+ * Check if a dynamic agent should be created for a DM user and create it if needed.
+ * This creates a unique agent instance with its own workspace for each DM user.
+ */
+export async function maybeCreateDynamicAgent(params: {
+  cfg: KlawConfig;
+  runtime: PluginRuntime;
+  senderOpenId: string;
+  dynamicCfg: DynamicAgentCreationConfig;
+  configWritesAllowed: boolean;
+  log: (msg: string) => void;
+}): Promise<MaybeCreateDynamicAgentResult> {
+  const { cfg, runtime, senderOpenId, dynamicCfg, configWritesAllowed, log } = params;
+
+  if (!configWritesAllowed) {
+    log(`feishu: config writes disabled, not creating agent for ${senderOpenId}`);
+    return { created: false, updatedCfg: cfg };
+  }
+
+  // Check if there's already a binding for this user
+  const existingBindings = cfg.bindings ?? [];
+  const hasBinding = existingBindings.some(
+    (b) =>
+      b.match?.channel === "feishu" &&
+      b.match?.peer?.kind === "direct" &&
+      b.match?.peer?.id === senderOpenId,
+  );
+
+  if (hasBinding) {
+    return { created: false, updatedCfg: cfg };
+  }
+
+  // Check maxAgents limit if configured
+  if (dynamicCfg.maxAgents !== undefined) {
+    const feishuAgentCount = (cfg.agents?.list ?? []).filter((a) =>
+      a.id.startsWith("feishu-"),
+    ).length;
+    if (feishuAgentCount >= dynamicCfg.maxAgents) {
+      log(
+        `feishu: maxAgents limit (${dynamicCfg.maxAgents}) reached, not creating agent for ${senderOpenId}`,
+      );
+      return { created: false, updatedCfg: cfg };
+    }
+  }
+
+  // Use full OpenID as agent ID suffix (OpenID format: ou_xxx is already filesystem-safe)
+  const agentId = `feishu-${senderOpenId}`;
+
+  // Check if agent already exists (but binding was missing)
+  const existingAgent = (cfg.agents?.list ?? []).find((a) => a.id === agentId);
+  if (existingAgent) {
+    // Agent exists but binding doesn't - just add the binding
+    log(`feishu: agent "${agentId}" exists, adding missing binding for ${senderOpenId}`);
+
+    const updatedCfg: KlawConfig = {
+      ...cfg,
+      bindings: [
+        ...existingBindings,
+        {
+          agentId,
+          match: {
+            channel: "feishu",
+            peer: { kind: "direct", id: senderOpenId },
+          },
+        },
+      ],
+    };
+
+    await runtime.config.replaceConfigFile({
+      nextConfig: updatedCfg,
+      afterWrite: { mode: "auto" },
+    });
+    return { created: true, updatedCfg, agentId };
+  }
+
+  // Resolve path templates with substitutions
+  const workspaceTemplate = dynamicCfg.workspaceTemplate ?? "~/.klaw/workspace-{agentId}";
+  const agentDirTemplate = dynamicCfg.agentDirTemplate ?? "~/.klaw/agents/{agentId}/agent";
+
+  const workspace = resolveUserPath(
+    workspaceTemplate.replace("{userId}", senderOpenId).replace("{agentId}", agentId),
+  );
+  const agentDir = resolveUserPath(
+    agentDirTemplate.replace("{userId}", senderOpenId).replace("{agentId}", agentId),
+  );
+
+  log(`feishu: creating dynamic agent "${agentId}" for user ${senderOpenId}`);
+  log(`  workspace: ${workspace}`);
+  log(`  agentDir: ${agentDir}`);
+
+  // Create directories
+  await fs.promises.mkdir(workspace, { recursive: true });
+  await fs.promises.mkdir(agentDir, { recursive: true });
+
+  // Update configuration with new agent and binding
+  const updatedCfg: KlawConfig = {
+    ...cfg,
+    agents: {
+      ...cfg.agents,
+      list: [...(cfg.agents?.list ?? []), { id: agentId, workspace, agentDir }],
+    },
+    bindings: [
+      ...existingBindings,
+      {
+        agentId,
+        match: {
+          channel: "feishu",
+          peer: { kind: "direct", id: senderOpenId },
+        },
+      },
+    ],
+  };
+
+  // Write updated config using PluginRuntime API
+  await runtime.config.replaceConfigFile({
+    nextConfig: updatedCfg,
+    afterWrite: { mode: "auto" },
+  });
+
+  return { created: true, updatedCfg, agentId };
+}
+
+/**
+ * Resolve a path that may start with ~ to the user's home directory.
+ */
+function resolveUserPath(p: string): string {
+  if (p.startsWith("~/")) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}

package/src/event-types.ts

@@ -0,0 +1,45 @@
+export type FeishuMessageEvent = {
+  sender: {
+    sender_id: {
+      open_id?: string;
+      user_id?: string;
+      union_id?: string;
+    };
+    sender_type?: string;
+    tenant_key?: string;
+  };
+  message: {
+    message_id: string;
+    reply_target_message_id?: string;
+    suppress_reply_target?: boolean;
+    root_id?: string;
+    parent_id?: string;
+    thread_id?: string;
+    chat_id: string;
+    chat_type: "p2p" | "group" | "topic_group" | "private";
+    message_type: string;
+    content: string;
+    create_time?: string;
+    mentions?: Array<{
+      key: string;
+      id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+      };
+      name: string;
+      tenant_key?: string;
+    }>;
+  };
+};
+
+export type FeishuBotAddedEvent = {
+  chat_id: string;
+  operator_id: {
+    open_id?: string;
+    user_id?: string;
+    union_id?: string;
+  };
+  external: boolean;
+  operator_tenant_key?: string;
+};

package/src/external-keys.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+
+describe("normalizeFeishuExternalKey", () => {
+  it("accepts a normal feishu key and trims surrounding spaces", () => {
+    expect(normalizeFeishuExternalKey("  img_v3_01abcDEF123  ")).toBe("img_v3_01abcDEF123");
+  });
+
+  it("rejects traversal and path separator patterns", () => {
+    expect(normalizeFeishuExternalKey("../etc/passwd")).toBeUndefined();
+    expect(normalizeFeishuExternalKey("a/../../b")).toBeUndefined();
+    expect(normalizeFeishuExternalKey("a\\..\\b")).toBeUndefined();
+  });
+
+  it("rejects empty, non-string, and control-char values", () => {
+    expect(normalizeFeishuExternalKey("   ")).toBeUndefined();
+    expect(normalizeFeishuExternalKey(123)).toBeUndefined();
+    expect(normalizeFeishuExternalKey("abc\u0000def")).toBeUndefined();
+  });
+});

package/src/external-keys.ts

@@ -0,0 +1,19 @@
+const CONTROL_CHARS_RE = /\p{Cc}/u;
+const MAX_EXTERNAL_KEY_LENGTH = 512;
+
+export function normalizeFeishuExternalKey(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const normalized = value.trim();
+  if (!normalized || normalized.length > MAX_EXTERNAL_KEY_LENGTH) {
+    return undefined;
+  }
+  if (CONTROL_CHARS_RE.test(normalized)) {
+    return undefined;
+  }
+  if (normalized.includes("/") || normalized.includes("\\") || normalized.includes("..")) {
+    return undefined;
+  }
+  return normalized;
+}

package/src/lifecycle.test-support.ts

@@ -0,0 +1,220 @@
+import { vi, type Mock } from "vitest";
+
+type BoundConversation = {
+  bindingId: string;
+  targetSessionKey: string;
+};
+type UnknownMock = Mock<(...args: unknown[]) => unknown>;
+type AsyncUnknownMock = Mock<(...args: unknown[]) => Promise<unknown>>;
+type FinalizeInboundContextMock = Mock<
+  (ctx: Record<string, unknown>, opts?: unknown) => Record<string, unknown>
+>;
+type DispatchReplyCounts = {
+  final: number;
+  block?: number;
+  tool?: number;
+};
+type DispatchReplyContext = Record<string, unknown> & {
+  SessionKey?: string;
+};
+type DispatchReplyDispatcher = {
+  sendFinalReply: (payload: { text: string }) => unknown;
+};
+type FeishuReplyDispatcherMockValue = {
+  dispatcher: DispatchReplyDispatcher;
+  replyOptions: Record<string, never>;
+  markDispatchIdle: () => unknown;
+};
+type CreateFeishuReplyDispatcherMock = Mock<(params?: unknown) => FeishuReplyDispatcherMockValue>;
+type DispatchReplyFromConfigMock = Mock<
+  (params: {
+    ctx: DispatchReplyContext;
+    dispatcher: DispatchReplyDispatcher;
+  }) => Promise<{ queuedFinal: boolean; counts: DispatchReplyCounts }>
+>;
+type WithReplyDispatcherMock = Mock<
+  (params: {
+    dispatcher?: DispatchReplyDispatcher;
+    onSettled?: () => unknown;
+    run: () => unknown;
+  }) => Promise<unknown>
+>;
+type FeishuLifecycleTestMocks = {
+  createEventDispatcherMock: UnknownMock;
+  monitorWebSocketMock: AsyncUnknownMock;
+  monitorWebhookMock: AsyncUnknownMock;
+  createFeishuThreadBindingManagerMock: UnknownMock;
+  createFeishuReplyDispatcherMock: CreateFeishuReplyDispatcherMock;
+  resolveBoundConversationMock: Mock<(ref?: unknown) => BoundConversation | null>;
+  touchBindingMock: UnknownMock;
+  resolveAgentRouteMock: UnknownMock;
+  resolveConfiguredBindingRouteMock: UnknownMock;
+  ensureConfiguredBindingRouteReadyMock: UnknownMock;
+  dispatchReplyFromConfigMock: DispatchReplyFromConfigMock;
+  withReplyDispatcherMock: WithReplyDispatcherMock;
+  finalizeInboundContextMock: FinalizeInboundContextMock;
+  getMessageFeishuMock: AsyncUnknownMock;
+  listFeishuThreadMessagesMock: AsyncUnknownMock;
+  sendMessageFeishuMock: AsyncUnknownMock;
+  sendCardFeishuMock: AsyncUnknownMock;
+};
+
+const feishuLifecycleTestMocks = vi.hoisted(
+  (): FeishuLifecycleTestMocks => ({
+    createEventDispatcherMock: vi.fn(),
+    monitorWebSocketMock: vi.fn(async () => {}),
+    monitorWebhookMock: vi.fn(async () => {}),
+    createFeishuThreadBindingManagerMock: vi.fn(() => ({ stop: vi.fn() })),
+    createFeishuReplyDispatcherMock: vi.fn(),
+    resolveBoundConversationMock: vi.fn<(ref?: unknown) => BoundConversation | null>(() => null),
+    touchBindingMock: vi.fn(),
+    resolveAgentRouteMock: vi.fn(),
+    resolveConfiguredBindingRouteMock: vi.fn(),
+    ensureConfiguredBindingRouteReadyMock: vi.fn(),
+    dispatchReplyFromConfigMock: vi.fn(),
+    withReplyDispatcherMock: vi.fn(),
+    finalizeInboundContextMock: vi.fn((ctx) => ctx),
+    getMessageFeishuMock: vi.fn(async () => null),
+    listFeishuThreadMessagesMock: vi.fn(async () => []),
+    sendMessageFeishuMock: vi.fn(async () => ({ messageId: "om_sent", chatId: "chat_default" })),
+    sendCardFeishuMock: vi.fn(async () => ({ messageId: "om_card", chatId: "chat_default" })),
+  }),
+);
+
+export function getFeishuLifecycleTestMocks(): FeishuLifecycleTestMocks {
+  return feishuLifecycleTestMocks;
+}
+
+export function resetFeishuLifecycleTestMocks(): void {
+  for (const mock of Object.values(feishuLifecycleTestMocks)) {
+    mock.mockReset();
+  }
+  feishuLifecycleTestMocks.monitorWebSocketMock.mockResolvedValue(undefined);
+  feishuLifecycleTestMocks.monitorWebhookMock.mockResolvedValue(undefined);
+  feishuLifecycleTestMocks.createFeishuThreadBindingManagerMock.mockReturnValue({ stop: vi.fn() });
+  feishuLifecycleTestMocks.resolveBoundConversationMock.mockReturnValue(null);
+  feishuLifecycleTestMocks.finalizeInboundContextMock.mockImplementation((ctx) => ctx);
+  feishuLifecycleTestMocks.getMessageFeishuMock.mockResolvedValue(null);
+  feishuLifecycleTestMocks.listFeishuThreadMessagesMock.mockResolvedValue([]);
+  feishuLifecycleTestMocks.sendMessageFeishuMock.mockResolvedValue({
+    messageId: "om_sent",
+    chatId: "chat_default",
+  });
+  feishuLifecycleTestMocks.sendCardFeishuMock.mockResolvedValue({
+    messageId: "om_card",
+    chatId: "chat_default",
+  });
+}
+
+const {
+  createEventDispatcherMock,
+  monitorWebSocketMock,
+  monitorWebhookMock,
+  createFeishuThreadBindingManagerMock,
+  createFeishuReplyDispatcherMock,
+  resolveBoundConversationMock,
+  touchBindingMock,
+  resolveConfiguredBindingRouteMock,
+  ensureConfiguredBindingRouteReadyMock,
+  getMessageFeishuMock,
+  listFeishuThreadMessagesMock,
+  sendMessageFeishuMock,
+  sendCardFeishuMock,
+} = feishuLifecycleTestMocks;
+
+vi.mock("./client.js", () => {
+  return {
+    FEISHU_HTTP_TIMEOUT_ENV_VAR: "KLAW_FEISHU_HTTP_TIMEOUT_MS",
+    FEISHU_HTTP_TIMEOUT_MAX_MS: 300_000,
+    FEISHU_HTTP_TIMEOUT_MS: 30_000,
+    FEISHU_USER_AGENT: "klaw-feishu-test",
+    clearClientCache: vi.fn(),
+    createFeishuClient: vi.fn(() => {
+      throw new Error("unexpected Feishu client call in lifecycle test");
+    }),
+    createFeishuWSClient: vi.fn(async () => ({
+      close: vi.fn(),
+      start: vi.fn(),
+    })),
+    createEventDispatcher: createEventDispatcherMock,
+    getFeishuClient: vi.fn(() => null),
+    getFeishuUserAgent: vi.fn(() => "klaw-feishu-test"),
+    pluginVersion: "test",
+    setFeishuClientRuntimeForTest: vi.fn(),
+  };
+});
+
+vi.mock("./monitor.transport.js", () => ({
+  monitorWebSocket: monitorWebSocketMock,
+  monitorWebhook: monitorWebhookMock,
+}));
+
+vi.mock("./thread-bindings.js", () => ({
+  createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock,
+}));
+
+vi.mock("./reply-dispatcher.js", () => ({
+  createFeishuReplyDispatcher: createFeishuReplyDispatcherMock,
+}));
+
+vi.mock("./send.js", () => ({
+  sendCardFeishu: sendCardFeishuMock,
+  getMessageFeishu: getMessageFeishuMock,
+  listFeishuThreadMessages: listFeishuThreadMessagesMock,
+  sendMessageFeishu: sendMessageFeishuMock,
+}));
+
+vi.mock("klaw/plugin-sdk/conversation-runtime", async () => {
+  const actual = await vi.importActual<typeof import("klaw/plugin-sdk/conversation-runtime")>(
+    "klaw/plugin-sdk/conversation-runtime",
+  );
+  return {
+    ...actual,
+    resolveConfiguredBindingRoute: (
+      params: Parameters<typeof actual.resolveConfiguredBindingRoute>[0],
+    ) =>
+      resolveConfiguredBindingRouteMock.getMockImplementation()
+        ? resolveConfiguredBindingRouteMock(params)
+        : actual.resolveConfiguredBindingRoute(params),
+    resolveRuntimeConversationBindingRoute: (
+      params: Parameters<typeof actual.resolveRuntimeConversationBindingRoute>[0],
+    ) => {
+      const conversation =
+        "conversation" in params
+          ? params.conversation
+          : {
+              channel: params.channel,
+              accountId: params.accountId,
+              conversationId: params.conversationId,
+              parentConversationId: params.parentConversationId,
+            };
+      const bindingRecord = resolveBoundConversationMock(conversation);
+      const boundSessionKey = bindingRecord?.targetSessionKey?.trim();
+      if (!bindingRecord || !boundSessionKey) {
+        return { bindingRecord: null, route: params.route };
+      }
+      touchBindingMock(bindingRecord.bindingId);
+      return {
+        bindingRecord,
+        boundSessionKey,
+        boundAgentId: params.route.agentId,
+        route: {
+          ...params.route,
+          sessionKey: boundSessionKey,
+          lastRoutePolicy: boundSessionKey === params.route.mainSessionKey ? "main" : "session",
+          matchedBy: "binding.channel",
+        },
+      };
+    },
+    ensureConfiguredBindingRouteReady: (
+      params: Parameters<typeof actual.ensureConfiguredBindingRouteReady>[0],
+    ) =>
+      ensureConfiguredBindingRouteReadyMock.getMockImplementation()
+        ? ensureConfiguredBindingRouteReadyMock(params)
+        : actual.ensureConfiguredBindingRouteReady(params),
+    getSessionBindingService: () => ({
+      resolveByConversation: resolveBoundConversationMock,
+      touch: touchBindingMock,
+    }),
+  };
+});