@openclaw/feishu 2026.2.24 → 2026.3.1

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

@@ -0,0 +1,129 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { registerFeishuBitableTools } from "./bitable.js";
+import { registerFeishuDriveTools } from "./drive.js";
+import { registerFeishuPermTools } from "./perm.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,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: (account: { appId?: string } | undefined) => createFeishuClientMock(account),
+}));
+
+function createConfig(params: {
+  toolsA?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  toolsB?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  defaultAccount?: string;
+}): OpenClawPluginApi["config"] {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        defaultAccount: params.defaultAccount,
+        accounts: {
+          a: {
+            appId: "app-a",
+            appSecret: "sec-a",
+            tools: params.toolsA,
+          },
+          b: {
+            appId: "app-b",
+            appSecret: "sec-b",
+            tools: params.toolsB,
+          },
+        },
+      },
+    },
+  } as OpenClawPluginApi["config"];
+}
+
+describe("feishu tool account routing", () => {
+  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(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("wiki tool prefers configured defaultAccount over inherited default account context", 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(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  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(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).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(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).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(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-b");
+    expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).toBe("app-a");
+  });
+});

package/src/tool-account.ts

@@ -0,0 +1,70 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } 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 readConfiguredDefaultAccountId(config: OpenClawPluginApi["config"]): string | undefined {
+  const value = (config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
+    ?.defaultAccount;
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  return normalizeOptionalAccountId(value);
+}
+
+export function resolveFeishuToolAccount(params: {
+  api: Pick<OpenClawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): ResolvedFeishuAccount {
+  if (!params.api.config) {
+    throw new Error("Feishu config unavailable");
+  }
+  return resolveFeishuAccount({
+    cfg: params.api.config,
+    accountId:
+      normalizeOptionalAccountId(params.executeParams?.accountId) ??
+      readConfiguredDefaultAccountId(params.api.config) ??
+      normalizeOptionalAccountId(params.defaultAccountId),
+  });
+}
+
+export function createFeishuToolClient(params: {
+  api: Pick<OpenClawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): Lark.Client {
+  return createFeishuClient(resolveFeishuToolAccount(params));
+}
+
+export function resolveAnyEnabledFeishuToolsConfig(
+  accounts: ResolvedFeishuAccount[],
+): Required<FeishuToolsConfig> {
+  const merged: Required<FeishuToolsConfig> = {
+    doc: false,
+    chat: false,
+    wiki: false,
+    drive: false,
+    perm: false,
+    scopes: false,
+  };
+  for (const account of accounts) {
+    const cfg = resolveToolsConfig(account.config.tools);
+    merged.doc = merged.doc || cfg.doc;
+    merged.chat = merged.chat || cfg.chat;
+    merged.wiki = merged.wiki || cfg.wiki;
+    merged.drive = merged.drive || cfg.drive;
+    merged.perm = merged.perm || cfg.perm;
+    merged.scopes = merged.scopes || cfg.scopes;
+  }
+  return merged;
+}

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

@@ -0,0 +1,76 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+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;
+};
+
+type RegisteredTool = {
+  tool: AnyAgentTool | ToolFactoryLike;
+  opts?: { name?: string };
+};
+
+function toToolList(value: AnyAgentTool | AnyAgentTool[] | null | undefined): AnyAgentTool[] {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function asToolLike(tool: AnyAgentTool, fallbackName?: string): ToolLike {
+  const candidate = tool as Partial<ToolLike>;
+  const name = candidate.name ?? fallbackName;
+  const execute = candidate.execute;
+  if (!name || typeof execute !== "function") {
+    throw new Error(`Resolved tool is missing required fields (name=${String(name)})`);
+  }
+  return {
+    name,
+    execute: (toolCallId, params) => execute(toolCallId, params),
+  };
+}
+
+export function createToolFactoryHarness(cfg: OpenClawPluginApi["config"]) {
+  const registered: RegisteredTool[] = [];
+
+  const api: Pick<OpenClawPluginApi, "config" | "logger" | "registerTool"> = {
+    config: cfg,
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    registerTool: (tool, opts) => {
+      registered.push({ tool, opts });
+    },
+  };
+
+  const resolveTool = (name: string, ctx: ToolContextLike = {}): ToolLike => {
+    for (const entry of registered) {
+      if (entry.opts?.name === name && typeof entry.tool !== "function") {
+        return asToolLike(entry.tool, name);
+      }
+
+      if (typeof entry.tool === "function") {
+        const builtTools = toToolList(entry.tool(ctx));
+        const hit = builtTools.find((tool) => (tool as { name?: string }).name === name);
+        if (hit) {
+          return asToolLike(hit, name);
+        }
+      } else if ((entry.tool as { name?: string }).name === name) {
+        return asToolLike(entry.tool, name);
+      }
+    }
+    throw new Error(`Tool not registered: ${name}`);
+  };
+
+  return {
+    api: api as OpenClawPluginApi,
+    resolveTool,
+  };
+}

package/src/tools-config.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { FeishuConfigSchema } from "./config-schema.js";
+import { resolveToolsConfig } from "./tools-config.js";
+
+describe("feishu tools config", () => {
+  it("enables chat tool by default", () => {
+    const resolved = resolveToolsConfig(undefined);
+    expect(resolved.chat).toBe(true);
+  });
+
+  it("accepts tools.chat in config schema", () => {
+    const parsed = FeishuConfigSchema.parse({
+      enabled: true,
+      tools: {
+        chat: false,
+      },
+    });
+
+    expect(parsed.tools?.chat).toBe(false);
+  });
+});

package/src/tools-config.ts

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

package/src/types.ts

@@ -67,6 +67,7 @@ export type FeishuMediaInfo = {
 
 export type FeishuToolsConfig = {
   doc?: boolean;
+  chat?: boolean;
   wiki?: boolean;
   drive?: boolean;
   perm?: boolean;

package/src/typing.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { isFeishuBackoffError, getBackoffCodeFromResponse, FeishuBackoffError } from "./typing.js";
+
+describe("isFeishuBackoffError", () => {
+  it("returns true for HTTP 429 (AxiosError shape)", () => {
+    const err = { response: { status: 429, data: {} } };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("returns true for Feishu quota exceeded code 99991403", () => {
+    const err = { response: { status: 200, data: { code: 99991403 } } };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("returns true for Feishu rate limit code 99991400", () => {
+    const err = { response: { status: 200, data: { code: 99991400 } } };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("returns true for SDK error with code 429", () => {
+    const err = { code: 429, message: "too many requests" };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("returns true for SDK error with top-level code 99991403", () => {
+    const err = { code: 99991403, message: "quota exceeded" };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("returns false for other HTTP errors (e.g. 500)", () => {
+    const err = { response: { status: 500, data: {} } };
+    expect(isFeishuBackoffError(err)).toBe(false);
+  });
+
+  it("returns false for non-rate-limit Feishu codes", () => {
+    const err = { response: { status: 200, data: { code: 99991401 } } };
+    expect(isFeishuBackoffError(err)).toBe(false);
+  });
+
+  it("returns false for generic Error", () => {
+    expect(isFeishuBackoffError(new Error("network timeout"))).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(isFeishuBackoffError(null)).toBe(false);
+  });
+
+  it("returns false for undefined", () => {
+    expect(isFeishuBackoffError(undefined)).toBe(false);
+  });
+
+  it("returns false for string", () => {
+    expect(isFeishuBackoffError("429")).toBe(false);
+  });
+
+  it("returns true for 429 even without data", () => {
+    const err = { response: { status: 429 } };
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+});
+
+describe("getBackoffCodeFromResponse", () => {
+  it("returns backoff code for response with quota exceeded code", () => {
+    const response = { code: 99991403, msg: "quota exceeded", data: null };
+    expect(getBackoffCodeFromResponse(response)).toBe(response.code);
+  });
+
+  it("returns backoff code for response with rate limit code", () => {
+    const response = { code: 99991400, msg: "rate limit", data: null };
+    expect(getBackoffCodeFromResponse(response)).toBe(response.code);
+  });
+
+  it("returns backoff code for response with code 429", () => {
+    const response = { code: 429, msg: "too many requests", data: null };
+    expect(getBackoffCodeFromResponse(response)).toBe(response.code);
+  });
+
+  it("returns undefined for successful response (code 0)", () => {
+    const response = { code: 0, msg: "success", data: { reaction_id: "r1" } };
+    expect(getBackoffCodeFromResponse(response)).toBeUndefined();
+  });
+
+  it("returns undefined for other error codes", () => {
+    const response = { code: 99991401, msg: "other error", data: null };
+    expect(getBackoffCodeFromResponse(response)).toBeUndefined();
+  });
+
+  it("returns undefined for null", () => {
+    expect(getBackoffCodeFromResponse(null)).toBeUndefined();
+  });
+
+  it("returns undefined for undefined", () => {
+    expect(getBackoffCodeFromResponse(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for response without code field", () => {
+    const response = { data: { reaction_id: "r1" } };
+    expect(getBackoffCodeFromResponse(response)).toBeUndefined();
+  });
+});
+
+describe("FeishuBackoffError", () => {
+  it("is detected by isFeishuBackoffError via .code property", () => {
+    const err = new FeishuBackoffError(99991403);
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("is detected for rate limit code 99991400", () => {
+    const err = new FeishuBackoffError(99991400);
+    expect(isFeishuBackoffError(err)).toBe(true);
+  });
+
+  it("has correct name and message", () => {
+    const err = new FeishuBackoffError(99991403);
+    expect(err.name).toBe("FeishuBackoffError");
+    expect(err.message).toBe("Feishu API backoff: code 99991403");
+    expect(err.code).toBe(99991403);
+  });
+
+  it("is an instance of Error", () => {
+    const err = new FeishuBackoffError(99991403);
+    expect(err instanceof Error).toBe(true);
+  });
+
+  it("survives catch-and-rethrow pattern", () => {
+    // Simulates the exact pattern in addTypingIndicator/removeTypingIndicator:
+    // thrown inside try, caught by catch, isFeishuBackoffError must match
+    let caught: unknown;
+    try {
+      try {
+        throw new FeishuBackoffError(99991403);
+      } catch (err) {
+        if (isFeishuBackoffError(err)) {
+          throw err; // re-thrown — this is the fix
+        }
+        // would be silently swallowed with plain Error
+        caught = "swallowed";
+      }
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(FeishuBackoffError);
+  });
+});

package/src/typing.ts

@@ -1,26 +1,112 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
 import { resolveFeishuAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
+import { getFeishuRuntime } from "./runtime.js";
 
 // Feishu emoji types for typing indicator
 // See: https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
 // Full list: https://github.com/go-lark/lark/blob/main/emoji.go
 const TYPING_EMOJI = "Typing"; // Typing indicator emoji
 
+/**
+ * Feishu API error codes that indicate the caller should back off.
+ * These must propagate to the typing circuit breaker so the keepalive loop
+ * can trip and stop retrying.
+ *
+ * - 99991400: Rate limit (too many requests per second)
+ * - 99991403: Monthly API call quota exceeded
+ * - 429: Standard HTTP 429 returned as a Feishu SDK error code
+ *
+ * @see https://open.feishu.cn/document/server-docs/api-call-guide/generic-error-code
+ */
+const FEISHU_BACKOFF_CODES = new Set([99991400, 99991403, 429]);
+
+/**
+ * Custom error class for Feishu backoff conditions detected from non-throwing
+ * SDK responses. Carries a numeric `.code` so that `isFeishuBackoffError()`
+ * recognises it when the error is caught downstream.
+ */
+export class FeishuBackoffError extends Error {
+  code: number;
+  constructor(code: number) {
+    super(`Feishu API backoff: code ${code}`);
+    this.name = "FeishuBackoffError";
+    this.code = code;
+  }
+}
+
 export type TypingIndicatorState = {
   messageId: string;
   reactionId: string | null;
 };
 
 /**
- * Add a typing indicator (reaction) to a message
+ * Check whether an error represents a rate-limit or quota-exceeded condition
+ * from the Feishu API that should stop the typing keepalive loop.
+ *
+ * Handles two shapes:
+ * 1. AxiosError with `response.status` and `response.data.code`
+ * 2. Feishu SDK error with a top-level `code` property
+ */
+export function isFeishuBackoffError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+
+  // AxiosError shape: err.response.status / err.response.data.code
+  const response = (err as { response?: { status?: number; data?: { code?: number } } }).response;
+  if (response) {
+    if (response.status === 429) {
+      return true;
+    }
+    if (typeof response.data?.code === "number" && FEISHU_BACKOFF_CODES.has(response.data.code)) {
+      return true;
+    }
+  }
+
+  // Feishu SDK error shape: err.code
+  const code = (err as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check whether a Feishu SDK response object contains a backoff error code.
+ *
+ * The Feishu SDK sometimes returns a normal response (no throw) with an
+ * API-level error code in the response body. This must be detected so the
+ * circuit breaker can trip. See codex review on #28157.
+ */
+export function getBackoffCodeFromResponse(response: unknown): number | undefined {
+  if (typeof response !== "object" || response === null) {
+    return undefined;
+  }
+  const code = (response as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return code;
+  }
+  return undefined;
+}
+
+/**
+ * Add a typing indicator (reaction) to a message.
+ *
+ * Rate-limit and quota errors are re-thrown so the circuit breaker in
+ * `createTypingCallbacks` (typing-start-guard) can trip and stop the
+ * keepalive loop. See #28062.
+ *
+ * Also checks for backoff codes in non-throwing SDK responses (#28157).
  */
 export async function addTypingIndicator(params: {
   cfg: ClawdbotConfig;
   messageId: string;
   accountId?: string;
+  runtime?: RuntimeEnv;
 }): Promise<TypingIndicatorState> {
-  const { cfg, messageId, accountId } = params;
+  const { cfg, messageId, accountId, runtime } = params;
   const account = resolveFeishuAccount({ cfg, accountId });
   if (!account.configured) {
     return { messageId, reactionId: null };
@@ -36,25 +122,48 @@ export async function addTypingIndicator(params: {
       },
     });
 
+    // Feishu SDK may return a normal response with an API-level error code
+    // instead of throwing. Detect backoff codes and throw to trip the breaker.
+    const backoffCode = getBackoffCodeFromResponse(response);
+    if (backoffCode !== undefined) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          `[feishu] typing indicator response contains backoff code ${backoffCode}, stopping keepalive`,
+        );
+      }
+      throw new FeishuBackoffError(backoffCode);
+    }
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK response type
     const reactionId = (response as any)?.data?.reaction_id ?? null;
     return { messageId, reactionId };
   } catch (err) {
-    // Silently fail - typing indicator is not critical
-    console.log(`[feishu] failed to add typing indicator: ${err}`);
+    if (isFeishuBackoffError(err)) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.("[feishu] typing indicator hit rate-limit/quota, stopping keepalive");
+      }
+      throw err;
+    }
+    // Silently fail for other non-critical errors (e.g. message deleted, permission issues)
+    if (getFeishuRuntime().logging.shouldLogVerbose()) {
+      runtime?.log?.(`[feishu] failed to add typing indicator: ${String(err)}`);
+    }
     return { messageId, reactionId: null };
   }
 }
 
 /**
- * Remove a typing indicator (reaction) from a message
+ * Remove a typing indicator (reaction) from a message.
+ *
+ * Rate-limit and quota errors are re-thrown for the same reason as above.
  */
 export async function removeTypingIndicator(params: {
   cfg: ClawdbotConfig;
   state: TypingIndicatorState;
   accountId?: string;
+  runtime?: RuntimeEnv;
 }): Promise<void> {
-  const { cfg, state, accountId } = params;
+  const { cfg, state, accountId, runtime } = params;
   if (!state.reactionId) {
     return;
   }
@@ -67,14 +176,35 @@ export async function removeTypingIndicator(params: {
   const client = createFeishuClient(account);
 
   try {
-    await client.im.messageReaction.delete({
+    const result = await client.im.messageReaction.delete({
       path: {
         message_id: state.messageId,
         reaction_id: state.reactionId,
       },
     });
+
+    // Check for backoff codes in non-throwing SDK responses
+    const backoffCode = getBackoffCodeFromResponse(result);
+    if (backoffCode !== undefined) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          `[feishu] typing indicator removal response contains backoff code ${backoffCode}, stopping keepalive`,
+        );
+      }
+      throw new FeishuBackoffError(backoffCode);
+    }
   } catch (err) {
-    // Silently fail - cleanup is not critical
-    console.log(`[feishu] failed to remove typing indicator: ${err}`);
+    if (isFeishuBackoffError(err)) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          "[feishu] typing indicator removal hit rate-limit/quota, stopping keepalive",
+        );
+      }
+      throw err;
+    }
+    // Silently fail for other non-critical errors
+    if (getFeishuRuntime().logging.shouldLogVerbose()) {
+      runtime?.log?.(`[feishu] failed to remove typing indicator: ${String(err)}`);
+    }
   }
 }