@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/thread-bindings.ts

@@ -0,0 +1,331 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import {
+  resolveThreadBindingIdleTimeoutMsForChannel,
+  resolveThreadBindingMaxAgeMsForChannel,
+  registerSessionBindingAdapter,
+  resolveThreadBindingConversationIdFromBindingId,
+  unregisterSessionBindingAdapter,
+  type BindingTargetKind,
+  type SessionBindingAdapter,
+  type SessionBindingRecord,
+} from "klaw/plugin-sdk/conversation-runtime";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "klaw/plugin-sdk/routing";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+
+type FeishuBindingTargetKind = "subagent" | "acp";
+
+type FeishuThreadBindingRecord = {
+  accountId: string;
+  conversationId: string;
+  parentConversationId?: string;
+  deliveryTo?: string;
+  deliveryThreadId?: string;
+  targetKind: FeishuBindingTargetKind;
+  targetSessionKey: string;
+  agentId?: string;
+  label?: string;
+  boundBy?: string;
+  boundAt: number;
+  lastActivityAt: number;
+};
+
+type FeishuThreadBindingManager = {
+  accountId: string;
+  getByConversationId: (conversationId: string) => FeishuThreadBindingRecord | undefined;
+  listBySessionKey: (targetSessionKey: string) => FeishuThreadBindingRecord[];
+  bindConversation: (params: {
+    conversationId: string;
+    parentConversationId?: string;
+    targetKind: BindingTargetKind;
+    targetSessionKey: string;
+    metadata?: Record<string, unknown>;
+  }) => FeishuThreadBindingRecord | null;
+  touchConversation: (conversationId: string, at?: number) => FeishuThreadBindingRecord | null;
+  unbindConversation: (conversationId: string) => FeishuThreadBindingRecord | null;
+  unbindBySessionKey: (targetSessionKey: string) => FeishuThreadBindingRecord[];
+  stop: () => void;
+};
+
+type FeishuThreadBindingsState = {
+  managersByAccountId: Map<string, FeishuThreadBindingManager>;
+  bindingsByAccountConversation: Map<string, FeishuThreadBindingRecord>;
+};
+
+const FEISHU_THREAD_BINDINGS_STATE_KEY = Symbol.for("klaw.feishuThreadBindingsState");
+let state: FeishuThreadBindingsState | undefined;
+
+function getState(): FeishuThreadBindingsState {
+  if (!state) {
+    const globalStore = globalThis as Record<PropertyKey, unknown>;
+    state = (globalStore[FEISHU_THREAD_BINDINGS_STATE_KEY] as
+      | FeishuThreadBindingsState
+      | undefined) ?? {
+      managersByAccountId: new Map(),
+      bindingsByAccountConversation: new Map(),
+    };
+    globalStore[FEISHU_THREAD_BINDINGS_STATE_KEY] = state;
+  }
+  return state;
+}
+
+function resolveBindingKey(params: { accountId: string; conversationId: string }): string {
+  return `${params.accountId}:${params.conversationId}`;
+}
+
+function toSessionBindingTargetKind(raw: FeishuBindingTargetKind): BindingTargetKind {
+  return raw === "subagent" ? "subagent" : "session";
+}
+
+function toFeishuTargetKind(raw: BindingTargetKind): FeishuBindingTargetKind {
+  return raw === "subagent" ? "subagent" : "acp";
+}
+
+function toSessionBindingRecord(
+  record: FeishuThreadBindingRecord,
+  defaults: { idleTimeoutMs: number; maxAgeMs: number },
+): SessionBindingRecord {
+  const idleExpiresAt =
+    defaults.idleTimeoutMs > 0 ? record.lastActivityAt + defaults.idleTimeoutMs : undefined;
+  const maxAgeExpiresAt = defaults.maxAgeMs > 0 ? record.boundAt + defaults.maxAgeMs : undefined;
+  const expiresAt =
+    idleExpiresAt != null && maxAgeExpiresAt != null
+      ? Math.min(idleExpiresAt, maxAgeExpiresAt)
+      : (idleExpiresAt ?? maxAgeExpiresAt);
+  return {
+    bindingId: resolveBindingKey({
+      accountId: record.accountId,
+      conversationId: record.conversationId,
+    }),
+    targetSessionKey: record.targetSessionKey,
+    targetKind: toSessionBindingTargetKind(record.targetKind),
+    conversation: {
+      channel: "feishu",
+      accountId: record.accountId,
+      conversationId: record.conversationId,
+      parentConversationId: record.parentConversationId,
+    },
+    status: "active",
+    boundAt: record.boundAt,
+    expiresAt,
+    metadata: {
+      agentId: record.agentId,
+      label: record.label,
+      boundBy: record.boundBy,
+      deliveryTo: record.deliveryTo,
+      deliveryThreadId: record.deliveryThreadId,
+      lastActivityAt: record.lastActivityAt,
+      idleTimeoutMs: defaults.idleTimeoutMs,
+      maxAgeMs: defaults.maxAgeMs,
+    },
+  };
+}
+
+export function createFeishuThreadBindingManager(params: {
+  accountId?: string;
+  cfg: KlawConfig;
+}): FeishuThreadBindingManager {
+  const accountId = normalizeAccountId(params.accountId);
+  const existing = getState().managersByAccountId.get(accountId);
+  if (existing) {
+    return existing;
+  }
+
+  const idleTimeoutMs = resolveThreadBindingIdleTimeoutMsForChannel({
+    cfg: params.cfg,
+    channel: "feishu",
+    accountId,
+  });
+  const maxAgeMs = resolveThreadBindingMaxAgeMsForChannel({
+    cfg: params.cfg,
+    channel: "feishu",
+    accountId,
+  });
+
+  const manager: FeishuThreadBindingManager = {
+    accountId,
+    getByConversationId: (conversationId) =>
+      getState().bindingsByAccountConversation.get(
+        resolveBindingKey({ accountId, conversationId }),
+      ),
+    listBySessionKey: (targetSessionKey) =>
+      [...getState().bindingsByAccountConversation.values()].filter(
+        (record) => record.accountId === accountId && record.targetSessionKey === targetSessionKey,
+      ),
+    bindConversation: ({
+      conversationId,
+      parentConversationId,
+      targetKind,
+      targetSessionKey,
+      metadata,
+    }) => {
+      const normalizedConversationId = conversationId.trim();
+      const normalizedTargetSessionKey = targetSessionKey.trim();
+      if (!normalizedConversationId || !normalizedTargetSessionKey) {
+        return null;
+      }
+      const existing = getState().bindingsByAccountConversation.get(
+        resolveBindingKey({ accountId, conversationId: normalizedConversationId }),
+      );
+      const now = Date.now();
+      const record: FeishuThreadBindingRecord = {
+        accountId,
+        conversationId: normalizedConversationId,
+        parentConversationId:
+          normalizeOptionalString(parentConversationId) ?? existing?.parentConversationId,
+        deliveryTo:
+          typeof metadata?.deliveryTo === "string" && metadata.deliveryTo.trim()
+            ? metadata.deliveryTo.trim()
+            : existing?.deliveryTo,
+        deliveryThreadId:
+          typeof metadata?.deliveryThreadId === "string" && metadata.deliveryThreadId.trim()
+            ? metadata.deliveryThreadId.trim()
+            : existing?.deliveryThreadId,
+        targetKind: toFeishuTargetKind(targetKind),
+        targetSessionKey: normalizedTargetSessionKey,
+        agentId:
+          typeof metadata?.agentId === "string" && metadata.agentId.trim()
+            ? metadata.agentId.trim()
+            : (existing?.agentId ?? resolveAgentIdFromSessionKey(normalizedTargetSessionKey)),
+        label:
+          typeof metadata?.label === "string" && metadata.label.trim()
+            ? metadata.label.trim()
+            : existing?.label,
+        boundBy:
+          typeof metadata?.boundBy === "string" && metadata.boundBy.trim()
+            ? metadata.boundBy.trim()
+            : existing?.boundBy,
+        boundAt: now,
+        lastActivityAt: now,
+      };
+      getState().bindingsByAccountConversation.set(
+        resolveBindingKey({ accountId, conversationId: normalizedConversationId }),
+        record,
+      );
+      return record;
+    },
+    touchConversation: (conversationId, at = Date.now()) => {
+      const key = resolveBindingKey({ accountId, conversationId });
+      const existingRecord = getState().bindingsByAccountConversation.get(key);
+      if (!existingRecord) {
+        return null;
+      }
+      const updated = { ...existingRecord, lastActivityAt: at };
+      getState().bindingsByAccountConversation.set(key, updated);
+      return updated;
+    },
+    unbindConversation: (conversationId) => {
+      const key = resolveBindingKey({ accountId, conversationId });
+      const existingRecord = getState().bindingsByAccountConversation.get(key);
+      if (!existingRecord) {
+        return null;
+      }
+      getState().bindingsByAccountConversation.delete(key);
+      return existingRecord;
+    },
+    unbindBySessionKey: (targetSessionKey) => {
+      const removed: FeishuThreadBindingRecord[] = [];
+      for (const record of getState().bindingsByAccountConversation.values()) {
+        if (record.accountId !== accountId || record.targetSessionKey !== targetSessionKey) {
+          continue;
+        }
+        getState().bindingsByAccountConversation.delete(
+          resolveBindingKey({ accountId, conversationId: record.conversationId }),
+        );
+        removed.push(record);
+      }
+      return removed;
+    },
+    stop: () => {
+      for (const key of getState().bindingsByAccountConversation.keys()) {
+        if (key.startsWith(`${accountId}:`)) {
+          getState().bindingsByAccountConversation.delete(key);
+        }
+      }
+      getState().managersByAccountId.delete(accountId);
+      unregisterSessionBindingAdapter({
+        channel: "feishu",
+        accountId,
+        adapter: sessionBindingAdapter,
+      });
+    },
+  };
+
+  const sessionBindingAdapter: SessionBindingAdapter = {
+    channel: "feishu",
+    accountId,
+    capabilities: {
+      placements: ["current"],
+    },
+    bind: async (input) => {
+      if (input.conversation.channel !== "feishu" || input.placement === "child") {
+        return null;
+      }
+      const bound = manager.bindConversation({
+        conversationId: input.conversation.conversationId,
+        parentConversationId: input.conversation.parentConversationId,
+        targetKind: input.targetKind,
+        targetSessionKey: input.targetSessionKey,
+        metadata: input.metadata,
+      });
+      return bound ? toSessionBindingRecord(bound, { idleTimeoutMs, maxAgeMs }) : null;
+    },
+    listBySession: (targetSessionKey) =>
+      manager
+        .listBySessionKey(targetSessionKey)
+        .map((entry) => toSessionBindingRecord(entry, { idleTimeoutMs, maxAgeMs })),
+    resolveByConversation: (ref) => {
+      if (ref.channel !== "feishu") {
+        return null;
+      }
+      const found = manager.getByConversationId(ref.conversationId);
+      return found ? toSessionBindingRecord(found, { idleTimeoutMs, maxAgeMs }) : null;
+    },
+    touch: (bindingId, at) => {
+      const conversationId = resolveThreadBindingConversationIdFromBindingId({
+        accountId,
+        bindingId,
+      });
+      if (conversationId) {
+        manager.touchConversation(conversationId, at);
+      }
+    },
+    unbind: async (input) => {
+      if (input.targetSessionKey?.trim()) {
+        return manager
+          .unbindBySessionKey(input.targetSessionKey.trim())
+          .map((entry) => toSessionBindingRecord(entry, { idleTimeoutMs, maxAgeMs }));
+      }
+      const conversationId = resolveThreadBindingConversationIdFromBindingId({
+        accountId,
+        bindingId: input.bindingId,
+      });
+      if (!conversationId) {
+        return [];
+      }
+      const removed = manager.unbindConversation(conversationId);
+      return removed ? [toSessionBindingRecord(removed, { idleTimeoutMs, maxAgeMs })] : [];
+    },
+  };
+
+  registerSessionBindingAdapter(sessionBindingAdapter);
+
+  getState().managersByAccountId.set(accountId, manager);
+  return manager;
+}
+
+export function getFeishuThreadBindingManager(
+  accountId?: string,
+): FeishuThreadBindingManager | null {
+  return getState().managersByAccountId.get(normalizeAccountId(accountId)) ?? null;
+}
+
+export const testing = {
+  resetFeishuThreadBindingsForTests() {
+    for (const manager of getState().managersByAccountId.values()) {
+      manager.stop();
+    }
+    getState().managersByAccountId.clear();
+    getState().bindingsByAccountConversation.clear();
+  },
+};
+export { testing as __testing };

package/src/tool-account-routing.test.ts

@@ -0,0 +1,250 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import type { KlawPluginApi } from "../runtime-api.js";
+import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
+
+const createFeishuClientMock = vi.fn((account: { appId?: string } | undefined) => ({
+  __appId: account?.appId,
+  wiki: {
+    spaceNode: {
+      list: vi.fn(async () => ({
+        code: 0,
+        data: { items: [] },
+      })),
+    },
+  },
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: (account: { appId?: string } | undefined) => createFeishuClientMock(account),
+}));
+
+let registerFeishuBitableTools: typeof import("./bitable.js").registerFeishuBitableTools;
+let registerFeishuDriveTools: typeof import("./drive.js").registerFeishuDriveTools;
+let registerFeishuPermTools: typeof import("./perm.js").registerFeishuPermTools;
+let registerFeishuWikiTools: typeof import("./wiki.js").registerFeishuWikiTools;
+
+function createConfig(params: {
+  toolsA?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  toolsB?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  defaultAccount?: string;
+}): KlawPluginApi["config"] {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        defaultAccount: params.defaultAccount,
+        accounts: {
+          a: {
+            appId: "app-a",
+            appSecret: "sec-a", // pragma: allowlist secret
+            tools: params.toolsA,
+          },
+          b: {
+            appId: "app-b",
+            appSecret: "sec-b", // pragma: allowlist secret
+            tools: params.toolsB,
+          },
+        },
+      },
+    },
+  } as KlawPluginApi["config"];
+}
+
+function clientAppIdAt(index: number): string | undefined {
+  const calls = createFeishuClientMock.mock.calls;
+  const resolvedIndex = index < 0 ? calls.length + index : index;
+  return calls[resolvedIndex]?.[0]?.appId;
+}
+
+function lastClientAppId(): string | undefined {
+  return clientAppIdAt(-1);
+}
+
+describe("feishu tool account routing", () => {
+  beforeAll(async () => {
+    ({ registerFeishuBitableTools, registerFeishuDriveTools, registerFeishuPermTools } =
+      await import("./bitable.js").then(async ({ registerFeishuBitableTools }) => ({
+        registerFeishuBitableTools,
+        ...(await import("./drive.js")),
+        ...(await import("./perm.js")),
+        ...(await import("./wiki.js")),
+      })));
+    ({ registerFeishuWikiTools } = await import("./wiki.js"));
+  });
+
+  afterAll(() => {
+    vi.doUnmock("./client.js");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("wiki tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: false },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "b" });
+    await tool.execute("call", { action: "search" });
+
+    expect(lastClientAppId()).toBe("app-b");
+  });
+
+  test("wiki tool prefers the active contextual account over configured defaultAccount", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        defaultAccount: "b",
+        toolsA: { wiki: true },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
+    await tool.execute("call", { action: "search" });
+
+    expect(lastClientAppId()).toBe("app-a");
+  });
+
+  test("wiki tool rejects number-typed space IDs before Lark receives precision-corrupted values", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
+    const result = await tool.execute("call", {
+      action: "nodes",
+      space_id: 7616123456789015000,
+    });
+
+    expect(createFeishuClientMock).not.toHaveBeenCalled();
+    expect(result.details.error).toContain("space_id must be a string");
+    expect(result.details.error).toContain("precision loss");
+  });
+
+  test("wiki tool forwards quoted numeric-looking space IDs unchanged", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
+    await tool.execute("call", {
+      action: "nodes",
+      space_id: "7616123456789014828",
+    });
+
+    const client = createFeishuClientMock.mock.results[0]?.value;
+    expect(client.wiki.spaceNode.list).toHaveBeenCalledWith({
+      path: { space_id: "7616123456789014828" },
+      params: { parent_node_token: undefined },
+    });
+  });
+
+  test("drive tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { drive: false },
+        toolsB: { drive: true },
+      }),
+    );
+    registerFeishuDriveTools(api);
+
+    const tool = resolveTool("feishu_drive", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(lastClientAppId()).toBe("app-b");
+  });
+
+  test("perm tool registers when only second account enables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { perm: false },
+        toolsB: { perm: true },
+      }),
+    );
+    registerFeishuPermTools(api);
+
+    const tool = resolveTool("feishu_perm", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(lastClientAppId()).toBe("app-b");
+  });
+
+  test("bitable tool routes to agentAccountId and allows explicit accountId override", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(createConfig({}));
+    registerFeishuBitableTools(api);
+
+    const tool = resolveTool("feishu_bitable_get_meta", { agentAccountId: "b" });
+    await tool.execute("call-ctx", { url: "invalid-url" });
+    await tool.execute("call-override", { url: "invalid-url", accountId: "a" });
+
+    expect(clientAppIdAt(0)).toBe("app-b");
+    expect(clientAppIdAt(1)).toBe("app-a");
+  });
+
+  test("falls back to the configured Feishu default selection when agentAccountId is not a real account", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: true },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "agent-spawner" });
+    await tool.execute("call", { action: "search" });
+
+    expect(lastClientAppId()).toBe("app-a");
+  });
+
+  test("does not silently fall back when the contextual account is real but uses non-env SecretRefs", async () => {
+    const { api, resolveTool } = createToolFactoryHarness({
+      channels: {
+        feishu: {
+          enabled: true,
+          accounts: {
+            a: {
+              appId: "app-a",
+              appSecret: "sec-a", // pragma: allowlist secret
+              tools: { wiki: true },
+            },
+            b: {
+              appId: "app-b",
+              appSecret: { source: "file", provider: "default", id: "feishu/b-secret" },
+              tools: { wiki: true },
+            } as never,
+          },
+        },
+      },
+    } as KlawPluginApi["config"]);
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "b" });
+    const result = await tool.execute("call", { action: "search" });
+
+    expect(createFeishuClientMock).not.toHaveBeenCalled();
+    expect(typeof result.details.error === "string" ? result.details.error : "").toContain(
+      "Resolve this command against an active gateway runtime snapshot before reading it.",
+    );
+  });
+});

package/src/tool-account.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { resolveFeishuToolAccount } from "./tool-account.js";
+
+describe("resolveFeishuToolAccount", () => {
+  const cfg = {
+    channels: {
+      feishu: {
+        enabled: true,
+        defaultAccount: "ops",
+        appId: "base-app-id",
+        appSecret: "base-app-secret", // pragma: allowlist secret
+        accounts: {
+          ops: {
+            enabled: true,
+            appId: "ops-app-id",
+            appSecret: "ops-app-secret", // pragma: allowlist secret
+          },
+          work: {
+            enabled: true,
+            appId: "work-app-id",
+            appSecret: "work-app-secret", // pragma: allowlist secret
+          },
+        },
+      },
+    },
+  };
+
+  it("prefers the active contextual account over configured defaultAccount", () => {
+    const resolved = resolveFeishuToolAccount({
+      api: { config: cfg },
+      defaultAccountId: "work",
+    });
+
+    expect(resolved.accountId).toBe("work");
+  });
+
+  it("falls back to configured defaultAccount when there is no contextual account", () => {
+    const resolved = resolveFeishuToolAccount({
+      api: { config: cfg },
+    });
+
+    expect(resolved.accountId).toBe("ops");
+  });
+});