@kodelyth/feishu 2026.5.39 → 2026.5.42

package/src/tool-account.ts

@@ -0,0 +1,93 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { KlawPluginApi } 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 resolveImplicitToolAccountId(params: {
+  api: Pick<KlawPluginApi, "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;
+    }
+  }
+
+  const configuredDefaultAccountId = normalizeOptionalString(
+    (params.api.config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
+      ?.defaultAccount,
+  );
+  if (configuredDefaultAccountId) {
+    return configuredDefaultAccountId;
+  }
+
+  return undefined;
+}
+
+export function resolveFeishuToolAccount(params: {
+  api: Pick<KlawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): ResolvedFeishuAccount {
+  if (!params.api.config) {
+    throw new Error("Feishu config unavailable");
+  }
+  return resolveFeishuRuntimeAccount({
+    cfg: params.api.config,
+    accountId: resolveImplicitToolAccountId(params),
+  });
+}
+
+export function createFeishuToolClient(params: {
+  api: Pick<KlawPluginApi, "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,79 @@
+import type { KlawPluginApi } from "../runtime-api.js";
+
+type ToolContextLike = {
+  agentAccountId?: string;
+};
+
+export type ToolLike = {
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: unknown,
+  ) => Promise<{ details: Record<string, unknown> }> | { details: Record<string, unknown> };
+};
+
+type RegisteredTool = {
+  tool: unknown;
+  opts?: { name?: string };
+};
+
+function toToolList(value: unknown): unknown[] {
+  if (!value) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+function asToolLike(tool: unknown, 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: KlawPluginApi["config"]) {
+  const registered: RegisteredTool[] = [];
+
+  const api: Pick<KlawPluginApi, "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 KlawPluginApi,
+    resolveTool,
+  };
+}

package/src/tool-result.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import {
+  jsonToolResult,
+  toolExecutionErrorResult,
+  unknownToolActionResult,
+} from "./tool-result.js";
+
+describe("jsonToolResult", () => {
+  it("formats tool result with text content and details", () => {
+    const payload = { ok: true, id: "abc" };
+    expect(jsonToolResult(payload)).toEqual({
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      details: payload,
+    });
+  });
+
+  it("formats unknown action errors", () => {
+    expect(unknownToolActionResult("create")).toEqual({
+      content: [
+        { type: "text", text: JSON.stringify({ error: "Unknown action: create" }, null, 2) },
+      ],
+      details: { error: "Unknown action: create" },
+    });
+  });
+
+  it("formats execution errors", () => {
+    expect(toolExecutionErrorResult(new Error("boom"))).toEqual({
+      content: [{ type: "text", text: JSON.stringify({ error: "boom" }, null, 2) }],
+      details: { error: "boom" },
+    });
+  });
+});

package/src/tool-result.ts

@@ -0,0 +1,16 @@
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+
+export function jsonToolResult(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+export function unknownToolActionResult(action: unknown) {
+  return jsonToolResult({ error: `Unknown action: ${String(action)}` });
+}
+
+export function toolExecutionErrorResult(error: unknown) {
+  return jsonToolResult({ error: formatErrorMessage(error) });
+}

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

@@ -0,0 +1,22 @@
+import type { FeishuToolsConfig } from "./types.js";
+
+/**
+ * Default tool configuration.
+ * - doc, chat, wiki, drive, scopes: 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,
+};
+
+/**
+ * Resolve tools config with defaults.
+ */
+export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
+  return { ...DEFAULT_TOOLS_CONFIG, ...cfg };
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+import type { MessageReceipt } from "klaw/plugin-sdk/channel-message";
+import type { BaseProbeResult } from "klaw/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;
+};
+
+export type DynamicAgentCreationConfig = {
+  enabled?: boolean;
+  workspaceTemplate?: string;
+  agentDirTemplate?: string;
+  maxAgents?: number;
+};

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);
+  });
+});