@actagent/feishu 2026.6.2

package/src/tools-config.test.ts

@@ -0,0 +1,52 @@
+// Feishu tests cover tools config plugin behavior.
+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);
+  });
+
+  it("enables bitable tool by default", () => {
+    const resolved = resolveToolsConfig(undefined);
+    expect(resolved.bitable).toBe(true);
+    expect(resolved.base).toBe(true);
+  });
+
+  it("accepts tools.bitable and tools.base in config schema", () => {
+    const parsed = FeishuConfigSchema.parse({
+      enabled: true,
+      tools: {
+        bitable: false,
+        base: false,
+      },
+    });
+
+    expect(parsed.tools?.bitable).toBe(false);
+    expect(parsed.tools?.base).toBe(false);
+  });
+
+  it("uses base as a backward-compatible bitable alias", () => {
+    expect(resolveToolsConfig({ base: false }).bitable).toBe(false);
+    expect(resolveToolsConfig({ base: false }).base).toBe(false);
+  });
+
+  it("prefers explicit bitable over base alias", () => {
+    const resolved = resolveToolsConfig({ bitable: true, base: false });
+    expect(resolved.bitable).toBe(true);
+    expect(resolved.base).toBe(true);
+  });
+});

package/src/tools-config.ts

@@ -0,0 +1,29 @@
+// Feishu helper module supports tools config behavior.
+import type { FeishuToolsConfig } from "./types.js";
+
+/**
+ * Default tool configuration.
+ * - doc, chat, wiki, drive, scopes, bitable/base: enabled by default
+ * - perm: disabled by default (sensitive operation)
+ */
+const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
+  doc: true,
+  chat: true,
+  wiki: true,
+  drive: true,
+  perm: false,
+  scopes: true,
+  bitable: true,
+  base: true,
+};
+
+/**
+ * Resolve tools config with defaults.
+ *
+ * `base` is a backward-compatible alias for the Bitable tool family. When both
+ * keys are present, the explicit `bitable` value wins and `base` mirrors it.
+ */
+export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
+  const bitable = cfg?.bitable ?? cfg?.base ?? DEFAULT_TOOLS_CONFIG.bitable;
+  return { ...DEFAULT_TOOLS_CONFIG, ...cfg, bitable, base: bitable };
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+// Feishu type declarations define plugin contracts.
+import type { MessageReceipt } from "actagent/plugin-sdk/channel-outbound";
+import type { BaseProbeResult } from "actagent/plugin-sdk/core";
+import type { FeishuConfigSchema, FeishuAccountConfigSchema, z } from "./config-schema.js";
+import type { MentionTarget } from "./mention-target.types.js";
+
+export type FeishuConfig = z.infer<typeof FeishuConfigSchema>;
+export type FeishuAccountConfig = z.infer<typeof FeishuAccountConfigSchema>;
+
+export type FeishuDomain = "feishu" | "lark" | (string & {});
+
+export type FeishuDefaultAccountSelectionSource =
+  | "explicit-default"
+  | "mapped-default"
+  | "fallback";
+type FeishuAccountSelectionSource = "explicit" | FeishuDefaultAccountSelectionSource;
+
+export type ResolvedFeishuAccount = {
+  accountId: string;
+  selectionSource: FeishuAccountSelectionSource;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  appId?: string;
+  appSecret?: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  domain: FeishuDomain;
+  /** Merged config (top-level defaults + account-specific overrides) */
+  config: FeishuConfig;
+};
+
+export type FeishuIdType = "open_id" | "user_id" | "union_id" | "chat_id";
+
+export type FeishuMessageContext = {
+  chatId: string;
+  messageId: string;
+  replyTargetMessageId?: string;
+  suppressReplyTarget?: boolean;
+  senderId: string;
+  senderOpenId: string;
+  senderName?: string;
+  chatType: FeishuChatType;
+  mentionedBot: boolean;
+  hasAnyMention?: boolean;
+  rootId?: string;
+  parentId?: string;
+  threadId?: string;
+  content: string;
+  contentType: string;
+  /** Mention forward targets (excluding the bot itself) */
+  mentionTargets?: MentionTarget[];
+};
+
+export type FeishuSendResult = {
+  messageId: string;
+  chatId: string;
+  receipt: MessageReceipt;
+};
+
+export type FeishuChatType = "p2p" | "group" | "topic_group" | "private";
+
+export function isFeishuGroupChatType(chatType: FeishuChatType | undefined): boolean {
+  return chatType === "group" || chatType === "topic_group";
+}
+
+export type FeishuMessageInfo = {
+  messageId: string;
+  chatId: string;
+  chatType?: FeishuChatType;
+  senderId?: string;
+  senderOpenId?: string;
+  senderType?: string;
+  content: string;
+  contentType: string;
+  createTime?: number;
+  /** Feishu thread ID (omt_xxx) — present when the message belongs to a topic thread. */
+  threadId?: string;
+};
+
+export interface FeishuProbeResult extends BaseProbeResult {
+  appId?: string;
+  botName?: string;
+  botOpenId?: string;
+}
+
+export type FeishuMediaInfo = {
+  path: string;
+  contentType?: string;
+  placeholder: string;
+};
+
+export type FeishuToolsConfig = {
+  doc?: boolean;
+  chat?: boolean;
+  wiki?: boolean;
+  drive?: boolean;
+  perm?: boolean;
+  scopes?: boolean;
+  /** Bitable/Base operations (default: true). */
+  bitable?: boolean;
+  /** @deprecated Use bitable. */
+  base?: boolean;
+};
+
+export type DynamicAgentCreationConfig = {
+  enabled?: boolean;
+  workspaceTemplate?: string;
+  agentDirTemplate?: string;
+  maxAgents?: number;
+};

package/src/typing.test.ts

@@ -0,0 +1,145 @@
+// Feishu tests cover typing plugin behavior.
+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

@@ -0,0 +1,215 @@
+// Feishu plugin module implements typing behavior.
+import type { ACTAgentBotConfig, RuntimeEnv } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } 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;
+};
+
+type FeishuMessageReactionCreateResponse = Awaited<
+  ReturnType<ReturnType<typeof createFeishuClient>["im"]["messageReaction"]["create"]>
+>;
+
+/**
+ * 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: ACTAgentBotConfig;
+  messageId: string;
+  accountId?: string;
+  runtime?: RuntimeEnv;
+}): Promise<TypingIndicatorState> {
+  const { cfg, messageId, accountId, runtime } = params;
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    return { messageId, reactionId: null };
+  }
+
+  const client = createFeishuClient(account);
+
+  try {
+    const response = await client.im.messageReaction.create({
+      path: { message_id: messageId },
+      data: {
+        reaction_type: { emoji_type: TYPING_EMOJI },
+      },
+    });
+
+    // 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);
+    }
+
+    const typedResponse: FeishuMessageReactionCreateResponse = response;
+    const reactionId = typedResponse.data?.reaction_id ?? null;
+    return { messageId, reactionId };
+  } catch (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.
+ *
+ * Rate-limit and quota errors are re-thrown for the same reason as above.
+ */
+export async function removeTypingIndicator(params: {
+  cfg: ACTAgentBotConfig;
+  state: TypingIndicatorState;
+  accountId?: string;
+  runtime?: RuntimeEnv;
+}): Promise<void> {
+  const { cfg, state, accountId, runtime } = params;
+  if (!state.reactionId) {
+    return;
+  }
+
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    return;
+  }
+
+  const client = createFeishuClient(account);
+
+  try {
+    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) {
+    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)}`);
+    }
+  }
+}

package/src/wiki-schema.ts

@@ -0,0 +1,70 @@
+// Feishu helper module supports wiki schema behavior.
+import { Type, type Static } from "typebox";
+
+const WIKI_SPACE_ID_DESCRIPTION =
+  "Knowledge space ID. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.";
+
+export const FeishuWikiSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("spaces"),
+  }),
+  Type.Object({
+    action: Type.Literal("nodes"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    parent_node_token: Type.Optional(
+      Type.String({ description: "Parent node token (optional, omit for root)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("get"),
+    token: Type.String({ description: "Wiki node token (from URL /wiki/XXX)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("search"),
+    query: Type.String({ description: "Search query" }),
+    space_id: Type.Optional(
+      Type.String({
+        description:
+          "Limit search to this knowledge space. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+      }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("create"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    title: Type.String({ description: "Node title" }),
+    obj_type: Type.Optional(
+      Type.Union([Type.Literal("docx"), Type.Literal("sheet"), Type.Literal("bitable")], {
+        description: "Object type (default: docx)",
+      }),
+    ),
+    parent_node_token: Type.Optional(
+      Type.String({ description: "Parent node token (optional, omit for root)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("move"),
+    space_id: Type.String({
+      description:
+        "Source knowledge space ID. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+    }),
+    node_token: Type.String({ description: "Node token to move" }),
+    target_space_id: Type.Optional(
+      Type.String({
+        description:
+          "Target knowledge space ID (optional, same space if omitted). Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+      }),
+    ),
+    target_parent_token: Type.Optional(
+      Type.String({ description: "Target parent node token (optional, root if omitted)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("rename"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    node_token: Type.String({ description: "Node token to rename" }),
+    title: Type.String({ description: "New title" }),
+  }),
+]);
+
+export type FeishuWikiParams = Static<typeof FeishuWikiSchema>;