@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/thread-bindings.ts

@@ -0,0 +1,330 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  resolveThreadBindingIdleTimeoutMsForChannel,
+  resolveThreadBindingMaxAgeMsForChannel,
+  registerSessionBindingAdapter,
+  resolveThreadBindingConversationIdFromBindingId,
+  unregisterSessionBindingAdapter,
+  type BindingTargetKind,
+  type SessionBindingAdapter,
+  type SessionBindingRecord,
+} from "openclaw/plugin-sdk/conversation-runtime";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-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("openclaw.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: OpenClawConfig;
+}): 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();
+  },
+};

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

@@ -1,10 +1,6 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import { registerFeishuBitableTools } from "./bitable.js";
-import { registerFeishuDriveTools } from "./drive.js";
-import { registerFeishuPermTools } from "./perm.js";
+import { beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import type { OpenClawPluginApi } from "../runtime-api.js";
 import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
-import { registerFeishuWikiTools } from "./wiki.js";
 
 const createFeishuClientMock = vi.fn((account: { appId?: string } | undefined) => ({
   __appId: account?.appId,
@@ -14,6 +10,11 @@ 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;
@@ -50,6 +51,17 @@ function createConfig(params: {
 }
 
 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"));
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -69,7 +81,7 @@ describe("feishu tool account routing", () => {
     expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
   });
 
-  test("wiki tool prefers configured defaultAccount over inherited default account context", async () => {
+  test("wiki tool prefers the active contextual account over configured defaultAccount", async () => {
     const { api, resolveTool } = createToolFactoryHarness(
       createConfig({
         defaultAccount: "b",
@@ -82,7 +94,7 @@ describe("feishu tool account routing", () => {
     const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
     await tool.execute("call", { action: "search" });
 
-    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-a");
   });
 
   test("drive tool registers when first account disables it and routes to agentAccountId", async () => {
@@ -126,4 +138,50 @@ describe("feishu tool account routing", () => {
     expect(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-b");
     expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).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(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).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 OpenClawPluginApi["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");
+  });
+});

package/src/tool-account.ts

@@ -1,24 +1,50 @@
 import type * as Lark from "@larksuiteoapi/node-sdk";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
-import { resolveFeishuAccount } from "./accounts.js";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import type { OpenClawPluginApi } from "../runtime-api.js";
+import {
+  listFeishuAccountIds,
+  resolveFeishuAccount,
+  resolveFeishuRuntimeAccount,
+} from "./accounts.js";
 import { createFeishuClient } from "./client.js";
 import { resolveToolsConfig } from "./tools-config.js";
 import type { FeishuToolsConfig, ResolvedFeishuAccount } from "./types.js";
 
 type AccountAwareParams = { accountId?: string };
 
-function normalizeOptionalAccountId(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : undefined;
-}
+function resolveImplicitToolAccountId(params: {
+  api: Pick<OpenClawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): string | undefined {
+  const explicitAccountId = normalizeOptionalString(params.executeParams?.accountId);
+  if (explicitAccountId) {
+    return explicitAccountId;
+  }
+
+  const contextualAccountId = normalizeOptionalString(params.defaultAccountId);
+  if (
+    contextualAccountId &&
+    listFeishuAccountIds(params.api.config).includes(contextualAccountId)
+  ) {
+    const contextualAccount = resolveFeishuAccount({
+      cfg: params.api.config,
+      accountId: contextualAccountId,
+    });
+    if (contextualAccount.enabled) {
+      return contextualAccountId;
+    }
+  }
 
-function readConfiguredDefaultAccountId(config: OpenClawPluginApi["config"]): string | undefined {
-  const value = (config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
-    ?.defaultAccount;
-  if (typeof value !== "string") {
-    return undefined;
+  const configuredDefaultAccountId = normalizeOptionalString(
+    (params.api.config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
+      ?.defaultAccount,
+  );
+  if (configuredDefaultAccountId) {
+    return configuredDefaultAccountId;
   }
-  return normalizeOptionalAccountId(value);
+
+  return undefined;
 }
 
 export function resolveFeishuToolAccount(params: {
@@ -29,12 +55,9 @@ export function resolveFeishuToolAccount(params: {
   if (!params.api.config) {
     throw new Error("Feishu config unavailable");
   }
-  return resolveFeishuAccount({
+  return resolveFeishuRuntimeAccount({
     cfg: params.api.config,
-    accountId:
-      normalizeOptionalAccountId(params.executeParams?.accountId) ??
-      readConfiguredDefaultAccountId(params.api.config) ??
-      normalizeOptionalAccountId(params.defaultAccountId),
+    accountId: resolveImplicitToolAccountId(params),
   });
 }
 

package/src/tool-factory-test-harness.ts

@@ -1,27 +1,30 @@
-import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import type { OpenClawPluginApi } from "../runtime-api.js";
 
 type ToolContextLike = {
   agentAccountId?: string;
 };
 
-type ToolFactoryLike = (ctx: ToolContextLike) => AnyAgentTool | AnyAgentTool[] | null | undefined;
-
 export type ToolLike = {
   name: string;
-  execute: (toolCallId: string, params: unknown) => Promise<unknown> | unknown;
+  execute: (
+    toolCallId: string,
+    params: unknown,
+  ) => Promise<{ details: Record<string, unknown> }> | { details: Record<string, unknown> };
 };
 
 type RegisteredTool = {
-  tool: AnyAgentTool | ToolFactoryLike;
+  tool: unknown;
   opts?: { name?: string };
 };
 
-function toToolList(value: AnyAgentTool | AnyAgentTool[] | null | undefined): AnyAgentTool[] {
-  if (!value) return [];
+function toToolList(value: unknown): unknown[] {
+  if (!value) {
+    return [];
+  }
   return Array.isArray(value) ? value : [value];
 }
 
-function asToolLike(tool: AnyAgentTool, fallbackName?: string): ToolLike {
+function asToolLike(tool: unknown, fallbackName?: string): ToolLike {
   const candidate = tool as Partial<ToolLike>;
   const name = candidate.name ?? fallbackName;
   const execute = candidate.execute;

package/src/tool-result.ts

@@ -1,3 +1,5 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+
 export function jsonToolResult(data: unknown) {
   return {
     content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
@@ -10,5 +12,5 @@ export function unknownToolActionResult(action: unknown) {
 }
 
 export function toolExecutionErrorResult(error: unknown) {
-  return jsonToolResult({ error: error instanceof Error ? error.message : String(error) });
+  return jsonToolResult({ error: formatErrorMessage(error) });
 }

package/src/tools-config.ts

@@ -5,7 +5,7 @@ import type { FeishuToolsConfig } from "./types.js";
  * - doc, chat, wiki, drive, scopes: enabled by default
  * - perm: disabled by default (sensitive operation)
  */
-export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
+const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   doc: true,
   chat: true,
   wiki: true,