@actagent/feishu 2026.6.2

package/src/client.ts

@@ -0,0 +1,263 @@
+// Feishu plugin module implements client behavior.
+import type { Agent } from "node:https";
+import { createRequire } from "node:module";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  readPluginPackageVersion,
+  resolveAmbientNodeProxyAgent,
+} from "actagent/plugin-sdk/extension-shared";
+import {
+  FEISHU_HTTP_TIMEOUT_ENV_VAR,
+  FEISHU_HTTP_TIMEOUT_MAX_MS,
+  FEISHU_HTTP_TIMEOUT_MS,
+  resolveConfiguredHttpTimeoutMs,
+} from "./client-timeout.js";
+import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+
+const require = createRequire(import.meta.url);
+const pluginVersion = readPluginPackageVersion({ require });
+
+export { pluginVersion };
+
+const FEISHU_USER_AGENT = `actagent-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;
+    });
+  }
+}
+
+export { FEISHU_HTTP_TIMEOUT_ENV_VAR, FEISHU_HTTP_TIMEOUT_MAX_MS, FEISHU_HTTP_TIMEOUT_MS };
+
+type FeishuHttpInstanceLike = Pick<
+  typeof feishuClientSdk.defaultHttpInstance,
+  "request" | "get" | "post" | "put" | "patch" | "delete" | "head" | "options"
+>;
+
+async function getWsProxyAgent() {
+  return resolveAmbientNodeProxyAgent<Agent>();
+}
+
+// Multi-account client cache
+const clientCache = new Map<
+  string,
+  {
+    client: Lark.Client;
+    config: { appId: string; appSecret: string; domain?: FeishuDomain; httpTimeoutMs: number };
+  }
+>();
+
+function resolveDomain(domain: FeishuDomain | undefined): Lark.Domain | string {
+  if (domain === "lark") {
+    return feishuClientSdk.Domain.Lark;
+  }
+  if (domain === "feishu" || !domain) {
+    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 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: FeishuHttpInstanceLike = feishuClientSdk.defaultHttpInstance;
+
+  function injectTimeout<D>(opts?: Lark.HttpRequestOptions<D>): Lark.HttpRequestOptions<D> {
+    return { timeout: defaultTimeoutMs, ...opts } as Lark.HttpRequestOptions<D>;
+  }
+
+  return {
+    request: (opts) => base.request(injectTimeout(opts)),
+    get: (url, opts) => base.get(url, injectTimeout(opts)),
+    post: (url, data, opts) => base.post(url, data, injectTimeout(opts)),
+    put: (url, data, opts) => base.put(url, data, injectTimeout(opts)),
+    patch: (url, data, opts) => base.patch(url, data, injectTimeout(opts)),
+    delete: (url, opts) => base.delete(url, injectTimeout(opts)),
+    head: (url, opts) => base.head(url, injectTimeout(opts)),
+    options: (url, opts) => base.options(url, injectTimeout(opts)),
+  };
+}
+
+/**
+ * Credentials needed to create a Feishu client.
+ * Both FeishuConfig and ResolvedFeishuAccount satisfy this interface.
+ */
+export type FeishuClientCredentials = {
+  accountId?: string;
+  appId?: string;
+  appSecret?: string;
+  domain?: FeishuDomain;
+  httpTimeoutMs?: number;
+  config?: Pick<FeishuConfig, "httpTimeoutMs">;
+};
+
+/**
+ * Create or get a cached Feishu client for an account.
+ * Accepts any object with appId, appSecret, and optional domain/accountId.
+ */
+export function createFeishuClient(creds: FeishuClientCredentials): Lark.Client {
+  const { accountId = "default", appId, appSecret, domain } = creds;
+  const defaultHttpTimeoutMs = resolveConfiguredHttpTimeoutMs(creds);
+
+  if (!appId || !appSecret) {
+    throw new Error(`Feishu credentials not configured for account "${accountId}"`);
+  }
+
+  // Check cache
+  const cached = clientCache.get(accountId);
+  if (
+    cached &&
+    cached.config.appId === appId &&
+    cached.config.appSecret === appSecret &&
+    cached.config.domain === domain &&
+    cached.config.httpTimeoutMs === defaultHttpTimeoutMs
+  ) {
+    return cached.client;
+  }
+
+  // Create new client with timeout-aware HTTP instance
+  const client = new feishuClientSdk.Client({
+    appId,
+    appSecret,
+    appType: feishuClientSdk.AppType.SelfBuild,
+    domain: resolveDomain(domain),
+    httpInstance: createTimeoutHttpInstance(defaultHttpTimeoutMs),
+  });
+
+  // Cache it
+  clientCache.set(accountId, {
+    client,
+    config: { appId, appSecret, domain, httpTimeoutMs: defaultHttpTimeoutMs },
+  });
+
+  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 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 = await getWsProxyAgent();
+  return new feishuClientSdk.WSClient({
+    appId,
+    appSecret,
+    domain: resolveDomain(domain),
+    ...callbacks,
+    loggerLevel: feishuClientSdk.LoggerLevel.info,
+    wsConfig: FEISHU_WS_CONFIG,
+    ...(agent ? { agent } : {}),
+  } as ConstructorParameters<typeof feishuClientSdk.WSClient>[0] & {
+    wsConfig: typeof FEISHU_WS_CONFIG;
+  });
+}
+
+/**
+ * Create an event dispatcher for an account.
+ */
+export function createEventDispatcher(account: ResolvedFeishuAccount): Lark.EventDispatcher {
+  return new feishuClientSdk.EventDispatcher({
+    encryptKey: account.encryptKey,
+    verificationToken: account.verificationToken,
+  });
+}
+
+/**
+ * Get a cached client for an account (if exists).
+ */
+export function getFeishuClient(accountId: string): Lark.Client | null {
+  return clientCache.get(accountId)?.client ?? null;
+}
+
+/**
+ * Clear client cache for a specific account or all accounts.
+ */
+export function clearClientCache(accountId?: string): void {
+  if (accountId) {
+    clientCache.delete(accountId);
+  } else {
+    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,7 @@
+// Feishu API module exposes the plugin public contract.
+export {
+  createReplyPrefixContext,
+  type ACTAgentBotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";

package/src/comment-dispatcher.test.ts

@@ -0,0 +1,186 @@
+// Feishu tests cover comment dispatcher plugin behavior.
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolveFeishuRuntimeAccountMock = vi.hoisted(() => vi.fn());
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+const createReplyPrefixContextMock = vi.hoisted(() => vi.fn());
+const createCommentTypingReactionLifecycleMock = vi.hoisted(() => vi.fn());
+const deliverCommentThreadTextMock = vi.hoisted(() => vi.fn());
+const createReplyDispatcherWithTypingMock = vi.hoisted(() => vi.fn());
+const getFeishuRuntimeMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./accounts.js", () => ({
+  resolveFeishuRuntimeAccount: resolveFeishuRuntimeAccountMock,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+vi.mock("./comment-dispatcher-runtime-api.js", () => ({
+  createReplyPrefixContext: createReplyPrefixContextMock,
+}));
+
+vi.mock("./comment-reaction.js", () => ({
+  createCommentTypingReactionLifecycle: createCommentTypingReactionLifecycleMock,
+}));
+
+vi.mock("./drive.js", () => ({
+  deliverCommentThreadText: deliverCommentThreadTextMock,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getFeishuRuntime: getFeishuRuntimeMock,
+}));
+
+import { createFeishuCommentReplyDispatcher } from "./comment-dispatcher.js";
+
+async function raceWithNextMacrotask<T>(promise: Promise<T>): Promise<T | "pending"> {
+  return await Promise.race([
+    promise,
+    new Promise<"pending">((resolve) => {
+      setImmediate(() => resolve("pending"));
+    }),
+  ]);
+}
+
+describe("createFeishuCommentReplyDispatcher", () => {
+  afterAll(() => {
+    vi.doUnmock("./accounts.js");
+    vi.doUnmock("./client.js");
+    vi.doUnmock("./comment-dispatcher-runtime-api.js");
+    vi.doUnmock("./comment-reaction.js");
+    vi.doUnmock("./drive.js");
+    vi.doUnmock("./runtime.js");
+    vi.resetModules();
+  });
+
+  function createTestCommentReplyDispatcher() {
+    createFeishuCommentReplyDispatcher({
+      cfg: {} as never,
+      agentId: "main",
+      runtime: { log: vi.fn(), error: vi.fn() } as never,
+      accountId: "main",
+      fileToken: "doc_token_1",
+      fileType: "docx",
+      commentId: "comment_1",
+      replyId: "reply_1",
+      isWholeComment: false,
+    });
+  }
+
+  function latestReplyDispatcherOptions() {
+    const options = createReplyDispatcherWithTypingMock.mock.calls.at(-1)?.[0];
+    if (!options) {
+      throw new Error("expected reply dispatcher options");
+    }
+    return options as {
+      deliver: (payload: { text: string }, phase: { kind: string }) => Promise<void> | void;
+      onCleanup?: () => Promise<void> | void;
+      onReplyStart?: () => Promise<void> | void;
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resolveFeishuRuntimeAccountMock.mockReturnValue({
+      accountId: "main",
+      appId: "app_id",
+      appSecret: "app_secret",
+      domain: "feishu",
+      config: {},
+    });
+    createFeishuClientMock.mockReturnValue({});
+    createReplyPrefixContextMock.mockReturnValue({
+      responsePrefix: undefined,
+      responsePrefixContextProvider: undefined,
+    });
+    deliverCommentThreadTextMock.mockResolvedValue({
+      delivery_mode: "reply_comment",
+      reply_id: "reply_1",
+    });
+    createCommentTypingReactionLifecycleMock.mockReturnValue({
+      start: vi.fn(async () => {}),
+      cleanup: vi.fn(async () => {}),
+    });
+    createReplyDispatcherWithTypingMock.mockImplementation(() => ({
+      dispatcher: {
+        markComplete: vi.fn(),
+        waitForIdle: vi.fn(async () => {}),
+      },
+      replyOptions: {},
+      markDispatchIdle: vi.fn(),
+      markRunComplete: vi.fn(),
+    }));
+    getFeishuRuntimeMock.mockReturnValue({
+      channel: {
+        text: {
+          resolveTextChunkLimit: vi.fn(() => 4000),
+          resolveChunkMode: vi.fn(() => "line"),
+          chunkTextWithMode: vi.fn((text: string) => [text]),
+        },
+        reply: {
+          createReplyDispatcherWithTyping: createReplyDispatcherWithTypingMock,
+          resolveHumanDelayConfig: vi.fn(() => undefined),
+        },
+      },
+    });
+  });
+
+  it("sends final comment text without waiting for typing cleanup", async () => {
+    let resolveCleanup: (() => void) | undefined;
+    const cleanup = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveCleanup = resolve;
+        }),
+    );
+    createCommentTypingReactionLifecycleMock.mockReturnValue({
+      start: vi.fn(async () => {}),
+      cleanup,
+    });
+
+    createTestCommentReplyDispatcher();
+
+    const options = latestReplyDispatcherOptions();
+    const deliverPromise = Promise.resolve(
+      options.deliver({ text: "hello world" }, { kind: "final" }),
+    );
+    const status = await raceWithNextMacrotask(deliverPromise.then(() => "done"));
+
+    expect(status).toBe("done");
+    const client = createFeishuClientMock.mock.results[0]?.value;
+    if (!client) {
+      throw new Error("Expected Feishu client");
+    }
+    expect(deliverCommentThreadTextMock).toHaveBeenCalledWith(client, {
+      file_token: "doc_token_1",
+      file_type: "docx",
+      comment_id: "comment_1",
+      content: "hello world",
+      is_whole_comment: false,
+    });
+    expect(cleanup).not.toHaveBeenCalled();
+
+    void options.onCleanup?.();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+
+    resolveCleanup?.();
+    await deliverPromise;
+  });
+
+  it("starts the typing reaction from dispatcher onReplyStart", async () => {
+    const start = vi.fn(async () => {});
+    createCommentTypingReactionLifecycleMock.mockReturnValue({
+      start,
+      cleanup: vi.fn(async () => {}),
+    });
+
+    createTestCommentReplyDispatcher();
+
+    const options = latestReplyDispatcherOptions();
+    await options.onReplyStart?.();
+
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+});

package/src/comment-dispatcher.ts

@@ -0,0 +1,108 @@
+// Feishu plugin module implements comment dispatcher behavior.
+import { resolveSendableOutboundReplyParts } from "actagent/plugin-sdk/reply-payload";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import {
+  createReplyPrefixContext,
+  type ACTAgentBotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "./comment-dispatcher-runtime-api.js";
+import { createCommentTypingReactionLifecycle } from "./comment-reaction.js";
+import type { CommentFileType } from "./comment-target.js";
+import { deliverCommentThreadText } from "./drive.js";
+import { getFeishuRuntime } from "./runtime.js";
+
+type CreateFeishuCommentReplyDispatcherParams = {
+  cfg: ACTAgentBotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  accountId?: string;
+  fileToken: string;
+  fileType: CommentFileType;
+  commentId: string;
+  replyId?: string;
+  isWholeComment?: boolean;
+};
+
+export function createFeishuCommentReplyDispatcher(
+  params: CreateFeishuCommentReplyDispatcherParams,
+) {
+  const core = getFeishuRuntime();
+  const prefixContext = createReplyPrefixContext({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "feishu",
+    accountId: params.accountId,
+  });
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  const client = createFeishuClient(account);
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit(
+    params.cfg,
+    "feishu",
+    params.accountId,
+    {
+      fallbackLimit: 4000,
+    },
+  );
+  const chunkMode = core.channel.text.resolveChunkMode(params.cfg, "feishu");
+  const typingReaction = createCommentTypingReactionLifecycle({
+    cfg: params.cfg,
+    fileToken: params.fileToken,
+    fileType: params.fileType,
+    replyId: params.replyId,
+    accountId: params.accountId,
+    runtime: params.runtime,
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle, markRunComplete } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(params.cfg, params.agentId),
+      onReplyStart: async () => {
+        await typingReaction.start();
+      },
+      deliver: async (payload: ReplyPayload, info) => {
+        if (info.kind !== "final") {
+          return;
+        }
+        const reply = resolveSendableOutboundReplyParts(payload);
+        if (!reply.hasText) {
+          if (reply.hasMedia) {
+            params.runtime.log?.(
+              `feishu[${params.accountId ?? "default"}]: comment reply ignored media-only payload for comment=${params.commentId}`,
+            );
+          }
+          return;
+        }
+        const chunks = core.channel.text.chunkTextWithMode(reply.text, textChunkLimit, chunkMode);
+        for (const chunk of chunks) {
+          await deliverCommentThreadText(client, {
+            file_token: params.fileToken,
+            file_type: params.fileType,
+            comment_id: params.commentId,
+            content: chunk,
+            is_whole_comment: params.isWholeComment,
+          });
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(
+          `feishu[${params.accountId ?? "default"}]: comment dispatcher failed kind=${info.kind} comment=${params.commentId}: ${String(err)}`,
+        );
+      },
+      onCleanup: () => {
+        void typingReaction.cleanup();
+      },
+    });
+
+  return {
+    dispatcher,
+    replyOptions,
+    markDispatchIdle,
+    markRunComplete,
+    startTypingReaction: typingReaction.start,
+    cleanupTypingReaction: typingReaction.cleanup,
+  };
+}

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

@@ -0,0 +1,4 @@
+// Feishu API module exposes the plugin public contract.
+export type { ACTAgentConfig as ACTAgentBotConfig } from "actagent/plugin-sdk/config-contracts";
+export type { RuntimeEnv } from "actagent/plugin-sdk/runtime";
+export { createChannelPairingController } from "actagent/plugin-sdk/channel-pairing";