@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/client.test.ts

@@ -1,17 +1,27 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { FeishuConfig, ResolvedFeishuAccount } from "./types.js";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FeishuConfigSchema } from "./config-schema.js";
+import type { ResolvedFeishuAccount } from "./types.js";
 
+type CreateFeishuClient = typeof import("./client.js").createFeishuClient;
+type CreateFeishuWSClient = typeof import("./client.js").createFeishuWSClient;
+type ClearClientCache = typeof import("./client.js").clearClientCache;
+type SetFeishuClientRuntimeForTest = typeof import("./client.js").setFeishuClientRuntimeForTest;
+
+const clientCtorMock = vi.hoisted(() =>
+  vi.fn(function clientCtor() {
+    return { connected: true };
+  }),
+);
 const wsClientCtorMock = vi.hoisted(() =>
   vi.fn(function wsClientCtor() {
     return { connected: true };
   }),
 );
-const httpsProxyAgentCtorMock = vi.hoisted(() =>
-  vi.fn(function httpsProxyAgentCtor(proxyUrl: string) {
-    return { proxyUrl };
+const proxyAgentCtorMock = vi.hoisted(() =>
+  vi.fn(function proxyAgentCtor() {
+    return { proxied: true };
   }),
 );
-
 const mockBaseHttpInstance = vi.hoisted(() => ({
   request: vi.fn().mockResolvedValue({}),
   get: vi.fn().mockResolvedValue({}),
@@ -22,36 +32,64 @@ const mockBaseHttpInstance = vi.hoisted(() => ({
   head: vi.fn().mockResolvedValue({}),
   options: vi.fn().mockResolvedValue({}),
 }));
+const proxyEnvKeys = ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"] as const;
+type ProxyEnvKey = (typeof proxyEnvKeys)[number];
+const registerFeishuDocToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuChatToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuWikiToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuDriveToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuPermToolsMock = vi.hoisted(() => vi.fn());
+const registerFeishuBitableToolsMock = vi.hoisted(() => vi.fn());
+const feishuPluginMock = vi.hoisted(() => ({ id: "feishu-test-plugin" }));
+const setFeishuRuntimeMock = vi.hoisted(() => vi.fn());
+const registerFeishuSubagentHooksMock = vi.hoisted(() => vi.fn());
+
+let createFeishuClient: CreateFeishuClient;
+let createFeishuWSClient: CreateFeishuWSClient;
+let clearClientCache: ClearClientCache;
+let setFeishuClientRuntimeForTest: SetFeishuClientRuntimeForTest;
+let FEISHU_HTTP_TIMEOUT_MS: number;
+let FEISHU_HTTP_TIMEOUT_MAX_MS: number;
+let FEISHU_HTTP_TIMEOUT_ENV_VAR: string;
 
-vi.mock("@larksuiteoapi/node-sdk", () => ({
-  AppType: { SelfBuild: "self" },
-  Domain: { Feishu: "https://open.feishu.cn", Lark: "https://open.larksuite.com" },
-  LoggerLevel: { info: "info" },
-  Client: vi.fn(),
-  WSClient: wsClientCtorMock,
-  EventDispatcher: vi.fn(),
-  defaultHttpInstance: mockBaseHttpInstance,
+let priorProxyEnv: Partial<Record<ProxyEnvKey, string | undefined>> = {};
+let priorFeishuTimeoutEnv: string | undefined;
+
+vi.mock("./channel.js", () => ({
+  feishuPlugin: feishuPluginMock,
 }));
 
-vi.mock("https-proxy-agent", () => ({
-  HttpsProxyAgent: httpsProxyAgentCtorMock,
+vi.mock("./docx.js", () => ({
+  registerFeishuDocTools: registerFeishuDocToolsMock,
 }));
 
-import { Client as LarkClient } from "@larksuiteoapi/node-sdk";
-import {
-  createFeishuClient,
-  createFeishuWSClient,
-  clearClientCache,
-  FEISHU_HTTP_TIMEOUT_MS,
-  FEISHU_HTTP_TIMEOUT_MAX_MS,
-  FEISHU_HTTP_TIMEOUT_ENV_VAR,
-} from "./client.js";
+vi.mock("./chat.js", () => ({
+  registerFeishuChatTools: registerFeishuChatToolsMock,
+}));
 
-const proxyEnvKeys = ["https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"] as const;
-type ProxyEnvKey = (typeof proxyEnvKeys)[number];
+vi.mock("./wiki.js", () => ({
+  registerFeishuWikiTools: registerFeishuWikiToolsMock,
+}));
 
-let priorProxyEnv: Partial<Record<ProxyEnvKey, string | undefined>> = {};
-let priorFeishuTimeoutEnv: string | undefined;
+vi.mock("./drive.js", () => ({
+  registerFeishuDriveTools: registerFeishuDriveToolsMock,
+}));
+
+vi.mock("./perm.js", () => ({
+  registerFeishuPermTools: registerFeishuPermToolsMock,
+}));
+
+vi.mock("./bitable.js", () => ({
+  registerFeishuBitableTools: registerFeishuBitableToolsMock,
+}));
+
+vi.mock("./runtime.js", () => ({
+  setFeishuRuntime: setFeishuRuntimeMock,
+}));
+
+vi.mock("./subagent-hooks.js", () => ({
+  registerFeishuSubagentHooks: registerFeishuSubagentHooksMock,
+}));
 
 const baseAccount: ResolvedFeishuAccount = {
   accountId: "main",
@@ -61,14 +99,70 @@ const baseAccount: ResolvedFeishuAccount = {
   appId: "app_123",
   appSecret: "secret_123", // pragma: allowlist secret
   domain: "feishu",
-  config: {} as FeishuConfig,
+  config: FeishuConfigSchema.parse({}),
 };
 
-function firstWsClientOptions(): { agent?: unknown } {
-  const calls = wsClientCtorMock.mock.calls as unknown as Array<[options: { agent?: unknown }]>;
-  return calls[0]?.[0] ?? {};
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
 }
 
+type HttpInstanceLike = {
+  get: (url: string, options?: Record<string, unknown>) => Promise<unknown>;
+  post: (url: string, body?: unknown, options?: Record<string, unknown>) => Promise<unknown>;
+};
+
+function readCallOptions(
+  mock: { mock: { calls: unknown[][] } },
+  index = -1,
+): Record<string, unknown> {
+  const call = index < 0 ? mock.mock.calls.at(index)?.[0] : mock.mock.calls[index]?.[0];
+  return isRecord(call) ? call : {};
+}
+
+function firstWsClientOptions(): {
+  agent?: unknown;
+  wsConfig?: unknown;
+  onError?: unknown;
+  onReady?: unknown;
+  onReconnected?: unknown;
+  onReconnecting?: unknown;
+} {
+  const options = readCallOptions(wsClientCtorMock, 0);
+  return {
+    agent: options.agent,
+    wsConfig: options.wsConfig,
+    onError: options.onError,
+    onReady: options.onReady,
+    onReconnected: options.onReconnected,
+    onReconnecting: options.onReconnecting,
+  };
+}
+
+beforeAll(async () => {
+  vi.doMock("@larksuiteoapi/node-sdk", () => ({
+    AppType: { SelfBuild: "self" },
+    Domain: { Feishu: "https://open.feishu.cn", Lark: "https://open.larksuite.com" },
+    LoggerLevel: { info: "info" },
+    Client: clientCtorMock,
+    WSClient: wsClientCtorMock,
+    EventDispatcher: vi.fn(),
+    defaultHttpInstance: mockBaseHttpInstance,
+  }));
+  vi.doMock("proxy-agent", () => ({
+    ProxyAgent: proxyAgentCtorMock,
+  }));
+
+  ({
+    createFeishuClient,
+    createFeishuWSClient,
+    clearClientCache,
+    setFeishuClientRuntimeForTest,
+    FEISHU_HTTP_TIMEOUT_MS,
+    FEISHU_HTTP_TIMEOUT_MAX_MS,
+    FEISHU_HTTP_TIMEOUT_ENV_VAR,
+  } = await import("./client.js"));
+});
+
 beforeEach(() => {
   priorProxyEnv = {};
   priorFeishuTimeoutEnv = process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR];
@@ -78,6 +172,21 @@ beforeEach(() => {
     delete process.env[key];
   }
   vi.clearAllMocks();
+  clearClientCache();
+  setFeishuClientRuntimeForTest({
+    sdk: {
+      AppType: { SelfBuild: "self" } as never,
+      Domain: {
+        Feishu: "https://open.feishu.cn",
+        Lark: "https://open.larksuite.com",
+      } as never,
+      LoggerLevel: { info: "info" } as never,
+      Client: clientCtorMock as never,
+      WSClient: wsClientCtorMock as never,
+      EventDispatcher: vi.fn() as never,
+      defaultHttpInstance: mockBaseHttpInstance as never,
+    },
+  });
 });
 
 afterEach(() => {
@@ -94,19 +203,23 @@ afterEach(() => {
   } else {
     process.env[FEISHU_HTTP_TIMEOUT_ENV_VAR] = priorFeishuTimeoutEnv;
   }
+  setFeishuClientRuntimeForTest();
 });
 
 describe("createFeishuClient HTTP timeout", () => {
-  beforeEach(() => {
-    clearClientCache();
-  });
-
-  const getLastClientHttpInstance = () => {
-    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
-    const lastCall = calls[calls.length - 1]?.[0] as
-      | { httpInstance?: { get: (...args: unknown[]) => Promise<unknown> } }
-      | undefined;
-    return lastCall?.httpInstance;
+  const getLastClientHttpInstance = (): HttpInstanceLike | undefined => {
+    const httpInstance = readCallOptions(clientCtorMock).httpInstance;
+    if (
+      isRecord(httpInstance) &&
+      typeof httpInstance.get === "function" &&
+      typeof httpInstance.post === "function"
+    ) {
+      return {
+        get: httpInstance.get as HttpInstanceLike["get"],
+        post: httpInstance.post as HttpInstanceLike["post"],
+      };
+    }
+    return undefined;
   };
 
   const expectGetCallTimeout = async (timeout: number) => {
@@ -122,21 +235,16 @@ describe("createFeishuClient HTTP timeout", () => {
   it("passes a custom httpInstance with default timeout to Lark.Client", () => {
     createFeishuClient({ appId: "app_1", appSecret: "secret_1", accountId: "timeout-test" }); // pragma: allowlist secret
 
-    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
-    const lastCall = calls[calls.length - 1][0] as { httpInstance?: unknown };
-    expect(lastCall.httpInstance).toBeDefined();
+    expect(readCallOptions(clientCtorMock).httpInstance).toBeDefined();
   });
 
   it("injects default timeout into HTTP request options", async () => {
     createFeishuClient({ appId: "app_2", appSecret: "secret_2", accountId: "timeout-inject" }); // pragma: allowlist secret
 
-    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
-    const lastCall = calls[calls.length - 1][0] as {
-      httpInstance: { post: (...args: unknown[]) => Promise<unknown> };
-    };
-    const httpInstance = lastCall.httpInstance;
+    const httpInstance = getLastClientHttpInstance();
 
-    await httpInstance.post(
+    expect(httpInstance).toBeDefined();
+    await httpInstance?.post(
       "https://example.com/api",
       { data: 1 },
       { headers: { "X-Custom": "yes" } },
@@ -152,13 +260,10 @@ describe("createFeishuClient HTTP timeout", () => {
   it("allows explicit timeout override per-request", async () => {
     createFeishuClient({ appId: "app_3", appSecret: "secret_3", accountId: "timeout-override" }); // pragma: allowlist secret
 
-    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
-    const lastCall = calls[calls.length - 1][0] as {
-      httpInstance: { get: (...args: unknown[]) => Promise<unknown> };
-    };
-    const httpInstance = lastCall.httpInstance;
+    const httpInstance = getLastClientHttpInstance();
 
-    await httpInstance.get("https://example.com/api", { timeout: 5_000 });
+    expect(httpInstance).toBeDefined();
+    await httpInstance?.get("https://example.com/api", { timeout: 5_000 });
 
     expect(mockBaseHttpInstance.get).toHaveBeenCalledWith(
       "https://example.com/api",
@@ -241,13 +346,10 @@ describe("createFeishuClient HTTP timeout", () => {
       config: { httpTimeoutMs: 45_000 },
     });
 
-    const calls = (LarkClient as unknown as ReturnType<typeof vi.fn>).mock.calls;
-    expect(calls.length).toBe(2);
-
-    const lastCall = calls[calls.length - 1][0] as {
-      httpInstance: { get: (...args: unknown[]) => Promise<unknown> };
-    };
-    await lastCall.httpInstance.get("https://example.com/api");
+    expect(clientCtorMock.mock.calls.length).toBe(2);
+    const httpInstance = getLastClientHttpInstance();
+    expect(httpInstance).toBeDefined();
+    await httpInstance?.get("https://example.com/api");
 
     expect(mockBaseHttpInstance.get).toHaveBeenCalledWith(
       "https://example.com/api",
@@ -257,68 +359,75 @@ describe("createFeishuClient HTTP timeout", () => {
 });
 
 describe("createFeishuWSClient proxy handling", () => {
-  it("does not set a ws proxy agent when proxy env is absent", () => {
-    createFeishuWSClient(baseAccount);
+  it("passes heartbeat wsConfig defaults to Lark.WSClient", async () => {
+    await createFeishuWSClient(baseAccount);
 
-    expect(httpsProxyAgentCtorMock).not.toHaveBeenCalled();
     const options = firstWsClientOptions();
-    expect(options?.agent).toBeUndefined();
+    expect(options.wsConfig).toEqual({
+      PingInterval: 30,
+      PingTimeout: 3,
+    });
   });
 
-  it("uses proxy env precedence: https_proxy first, then HTTPS_PROXY, then http_proxy/HTTP_PROXY", () => {
-    // NOTE: On Windows, environment variables are case-insensitive, so it's not
-    // possible to set both https_proxy and HTTPS_PROXY to different values.
-    // Keep this test cross-platform by asserting precedence via mutually-exclusive
-    // setups.
-    process.env.https_proxy = "http://lower-https:8001";
-    process.env.http_proxy = "http://lower-http:8003";
-    process.env.HTTP_PROXY = "http://upper-http:8004";
+  it("passes lifecycle callbacks while preserving heartbeat wsConfig defaults", async () => {
+    const onError = vi.fn();
+    const onReady = vi.fn();
+    const onReconnected = vi.fn();
+    const onReconnecting = vi.fn();
+
+    await createFeishuWSClient(baseAccount, {
+      onError,
+      onReady,
+      onReconnected,
+      onReconnecting,
+    });
+
+    const options = firstWsClientOptions();
+    expect(options.onError).toBe(onError);
+    expect(options.onReady).toBe(onReady);
+    expect(options.onReconnected).toBe(onReconnected);
+    expect(options.onReconnecting).toBe(onReconnecting);
+    expect(options.wsConfig).toEqual({
+      PingInterval: 30,
+      PingTimeout: 3,
+    });
+  });
 
-    createFeishuWSClient(baseAccount);
+  it("does not set a ws proxy agent when proxy env is absent", async () => {
+    await createFeishuWSClient(baseAccount);
 
-    // On Windows env keys are case-insensitive, so setting HTTPS_PROXY may
-    // overwrite https_proxy. We assert https proxies still win over http.
-    const expectedProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
-    expect(expectedProxy).toBeTruthy();
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedProxy);
+    expect(proxyAgentCtorMock).not.toHaveBeenCalled();
     const options = firstWsClientOptions();
-    expect(options.agent).toEqual({ proxyUrl: expectedProxy });
+    expect(options.agent).toBeUndefined();
   });
 
-  it("accepts lowercase https_proxy when it is the configured HTTPS proxy var", () => {
+  it("creates a ws proxy agent when lowercase https_proxy is set", async () => {
     process.env.https_proxy = "http://lower-https:8001";
 
-    createFeishuWSClient(baseAccount);
+    await createFeishuWSClient(baseAccount);
 
-    const expectedHttpsProxy = process.env.https_proxy || process.env.HTTPS_PROXY;
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
-    expect(expectedHttpsProxy).toBeTruthy();
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith(expectedHttpsProxy);
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
     const options = firstWsClientOptions();
-    expect(options.agent).toEqual({ proxyUrl: expectedHttpsProxy });
+    expect(options.agent).toEqual({ proxied: true });
   });
 
-  it("uses HTTPS_PROXY when https_proxy is unset", () => {
+  it("creates a ws proxy agent when uppercase HTTPS_PROXY is set", async () => {
     process.env.HTTPS_PROXY = "http://upper-https:8002";
-    process.env.http_proxy = "http://lower-http:8003";
 
-    createFeishuWSClient(baseAccount);
+    await createFeishuWSClient(baseAccount);
 
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith("http://upper-https:8002");
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
     const options = firstWsClientOptions();
-    expect(options.agent).toEqual({ proxyUrl: "http://upper-https:8002" });
+    expect(options.agent).toEqual({ proxied: true });
   });
 
-  it("passes HTTP_PROXY to ws client when https vars are unset", () => {
+  it("falls back to HTTP_PROXY for ws proxy agent creation", async () => {
     process.env.HTTP_PROXY = "http://upper-http:8999";
 
-    createFeishuWSClient(baseAccount);
+    await createFeishuWSClient(baseAccount);
 
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledTimes(1);
-    expect(httpsProxyAgentCtorMock).toHaveBeenCalledWith("http://upper-http:8999");
+    expect(proxyAgentCtorMock).toHaveBeenCalledTimes(1);
     const options = firstWsClientOptions();
-    expect(options.agent).toEqual({ proxyUrl: "http://upper-http:8999" });
+    expect(options.agent).toEqual({ proxied: true });
   });
 });

package/src/client.ts

@@ -1,20 +1,94 @@
+import type { Agent } from "node:https";
+import { createRequire } from "node:module";
 import * as Lark from "@larksuiteoapi/node-sdk";
-import { HttpsProxyAgent } from "https-proxy-agent";
+import {
+  readPluginPackageVersion,
+  resolveAmbientNodeProxyAgent,
+} from "openclaw/plugin-sdk/extension-shared";
 import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
 
+const require = createRequire(import.meta.url);
+const pluginVersion = readPluginPackageVersion({ require });
+
+export { pluginVersion };
+
+const FEISHU_USER_AGENT = `openclaw-feishu-builtin/${pluginVersion}/${process.platform}`;
+export { FEISHU_USER_AGENT };
+
+const FEISHU_WS_CONFIG = {
+  PingInterval: 30,
+  PingTimeout: 3,
+} as const;
+
+/** User-Agent header value for all Feishu API requests. */
+export function getFeishuUserAgent(): string {
+  return FEISHU_USER_AGENT;
+}
+
+type FeishuClientSdk = Pick<
+  typeof Lark,
+  | "AppType"
+  | "Client"
+  | "defaultHttpInstance"
+  | "Domain"
+  | "EventDispatcher"
+  | "LoggerLevel"
+  | "WSClient"
+>;
+
+const defaultFeishuClientSdk: FeishuClientSdk = {
+  AppType: Lark.AppType,
+  Client: Lark.Client,
+  defaultHttpInstance: Lark.defaultHttpInstance,
+  Domain: Lark.Domain,
+  EventDispatcher: Lark.EventDispatcher,
+  LoggerLevel: Lark.LoggerLevel,
+  WSClient: Lark.WSClient,
+};
+
+let feishuClientSdk: FeishuClientSdk = defaultFeishuClientSdk;
+
+// Override the SDK's default User-Agent interceptor.
+// The Lark SDK registers an axios request interceptor that sets
+// 'oapi-node-sdk/1.0.0'. Axios request interceptors execute in LIFO order
+// (last-registered runs first), so simply appending ours doesn't work — the
+// SDK's interceptor would run last and overwrite our UA. We must clear
+// handlers[] first, then register our own as the sole interceptor.
+//
+// Risk is low: the SDK only registers one interceptor (UA) at init time, and
+// we clear it at module load before any other code can register handlers.
+// If a future SDK version adds more interceptors, the upgrade will need
+// compatibility verification regardless.
+{
+  const inst = Lark.defaultHttpInstance as {
+    interceptors?: {
+      request: { handlers: unknown[]; use: (fn: (req: unknown) => unknown) => void };
+    };
+  };
+  if (inst.interceptors?.request) {
+    inst.interceptors.request.handlers = [];
+    inst.interceptors.request.use((req: unknown) => {
+      const r = req as { headers?: Record<string, string> };
+      if (r.headers) {
+        r.headers["User-Agent"] = getFeishuUserAgent();
+      }
+      return req;
+    });
+  }
+}
+
 /** Default HTTP timeout for Feishu API requests (30 seconds). */
 export const FEISHU_HTTP_TIMEOUT_MS = 30_000;
 export const FEISHU_HTTP_TIMEOUT_MAX_MS = 300_000;
 export const FEISHU_HTTP_TIMEOUT_ENV_VAR = "OPENCLAW_FEISHU_HTTP_TIMEOUT_MS";
 
-function getWsProxyAgent(): HttpsProxyAgent<string> | undefined {
-  const proxyUrl =
-    process.env.https_proxy ||
-    process.env.HTTPS_PROXY ||
-    process.env.http_proxy ||
-    process.env.HTTP_PROXY;
-  if (!proxyUrl) return undefined;
-  return new HttpsProxyAgent(proxyUrl);
+type FeishuHttpInstanceLike = Pick<
+  typeof feishuClientSdk.defaultHttpInstance,
+  "request" | "get" | "post" | "put" | "patch" | "delete" | "head" | "options"
+>;
+
+async function getWsProxyAgent() {
+  return resolveAmbientNodeProxyAgent<Agent>();
 }
 
 // Multi-account client cache
@@ -28,21 +102,21 @@ const clientCache = new Map<
 
 function resolveDomain(domain: FeishuDomain | undefined): Lark.Domain | string {
   if (domain === "lark") {
-    return Lark.Domain.Lark;
+    return feishuClientSdk.Domain.Lark;
   }
   if (domain === "feishu" || !domain) {
-    return Lark.Domain.Feishu;
+    return feishuClientSdk.Domain.Feishu;
   }
   return domain.replace(/\/+$/, ""); // Custom URL for private deployment
 }
 
 /**
  * Create an HTTP instance that delegates to the Lark SDK's default instance
- * but injects a default request timeout to prevent indefinite hangs
- * (e.g. when the Feishu API is slow, causing per-chat queue deadlocks).
+ * but injects a default request timeout and User-Agent header to prevent
+ * indefinite hangs and set a standardized User-Agent per OAPI best practices.
  */
 function createTimeoutHttpInstance(defaultTimeoutMs: number): Lark.HttpInstance {
-  const base: Lark.HttpInstance = Lark.defaultHttpInstance as unknown as Lark.HttpInstance;
+  const base: FeishuHttpInstanceLike = feishuClientSdk.defaultHttpInstance;
 
   function injectTimeout<D>(opts?: Lark.HttpRequestOptions<D>): Lark.HttpRequestOptions<D> {
     return { timeout: defaultTimeoutMs, ...opts } as Lark.HttpRequestOptions<D>;
@@ -129,10 +203,10 @@ export function createFeishuClient(creds: FeishuClientCredentials): Lark.Client
   }
 
   // Create new client with timeout-aware HTTP instance
-  const client = new Lark.Client({
+  const client = new feishuClientSdk.Client({
     appId,
     appSecret,
-    appType: Lark.AppType.SelfBuild,
+    appType: feishuClientSdk.AppType.SelfBuild,
     domain: resolveDomain(domain),
     httpInstance: createTimeoutHttpInstance(defaultHttpTimeoutMs),
   });
@@ -146,24 +220,36 @@ export function createFeishuClient(creds: FeishuClientCredentials): Lark.Client
   return client;
 }
 
+export type FeishuWsClientCallbacks = Pick<
+  ConstructorParameters<typeof feishuClientSdk.WSClient>[0],
+  "onError" | "onReady" | "onReconnected" | "onReconnecting"
+>;
+
 /**
  * Create a Feishu WebSocket client for an account.
  * Note: WSClient is not cached since each call creates a new connection.
  */
-export function createFeishuWSClient(account: ResolvedFeishuAccount): Lark.WSClient {
+export async function createFeishuWSClient(
+  account: ResolvedFeishuAccount,
+  callbacks: FeishuWsClientCallbacks = {},
+): Promise<Lark.WSClient> {
   const { accountId, appId, appSecret, domain } = account;
 
   if (!appId || !appSecret) {
     throw new Error(`Feishu credentials not configured for account "${accountId}"`);
   }
 
-  const agent = getWsProxyAgent();
-  return new Lark.WSClient({
+  const agent = await getWsProxyAgent();
+  return new feishuClientSdk.WSClient({
     appId,
     appSecret,
     domain: resolveDomain(domain),
-    loggerLevel: Lark.LoggerLevel.info,
+    ...callbacks,
+    loggerLevel: feishuClientSdk.LoggerLevel.info,
+    wsConfig: FEISHU_WS_CONFIG,
     ...(agent ? { agent } : {}),
+  } as ConstructorParameters<typeof feishuClientSdk.WSClient>[0] & {
+    wsConfig: typeof FEISHU_WS_CONFIG;
   });
 }
 
@@ -171,7 +257,7 @@ export function createFeishuWSClient(account: ResolvedFeishuAccount): Lark.WSCli
  * Create an event dispatcher for an account.
  */
 export function createEventDispatcher(account: ResolvedFeishuAccount): Lark.EventDispatcher {
-  return new Lark.EventDispatcher({
+  return new feishuClientSdk.EventDispatcher({
     encryptKey: account.encryptKey,
     verificationToken: account.verificationToken,
   });
@@ -194,3 +280,11 @@ export function clearClientCache(accountId?: string): void {
     clientCache.clear();
   }
 }
+
+export function setFeishuClientRuntimeForTest(overrides?: {
+  sdk?: Partial<FeishuClientSdk>;
+}): void {
+  feishuClientSdk = overrides?.sdk
+    ? { ...defaultFeishuClientSdk, ...overrides.sdk }
+    : defaultFeishuClientSdk;
+}

package/src/comment-dispatcher-runtime-api.ts

@@ -0,0 +1,6 @@
+export {
+  createReplyPrefixContext,
+  type ClawdbotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";