@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/monitor.startup.ts

@@ -1,8 +1,26 @@
-import type { RuntimeEnv } from "openclaw/plugin-sdk/feishu";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import type { RuntimeEnv } from "../runtime-api.js";
 import { probeFeishu } from "./probe.js";
 import type { ResolvedFeishuAccount } from "./types.js";
 
-export const FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS = 10_000;
+const FEISHU_STARTUP_BOT_INFO_TIMEOUT_DEFAULT_MS = 30_000;
+const FEISHU_STARTUP_BOT_INFO_TIMEOUT_ENV = "OPENCLAW_FEISHU_STARTUP_PROBE_TIMEOUT_MS";
+
+function resolveStartupProbeTimeoutMs(): number {
+  const raw = process.env[FEISHU_STARTUP_BOT_INFO_TIMEOUT_ENV];
+  if (raw) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return Math.floor(parsed);
+    }
+    console.warn(
+      `[feishu] ${FEISHU_STARTUP_BOT_INFO_TIMEOUT_ENV}="${raw}" is invalid; using default ${FEISHU_STARTUP_BOT_INFO_TIMEOUT_DEFAULT_MS}ms`,
+    );
+  }
+  return FEISHU_STARTUP_BOT_INFO_TIMEOUT_DEFAULT_MS;
+}
+
+const FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS = resolveStartupProbeTimeoutMs();
 
 type FetchBotOpenIdOptions = {
   runtime?: RuntimeEnv;
@@ -16,13 +34,12 @@ export type FeishuMonitorBotIdentity = {
 };
 
 function isTimeoutErrorMessage(message: string | undefined): boolean {
-  return message?.toLowerCase().includes("timeout") || message?.toLowerCase().includes("timed out")
-    ? true
-    : false;
+  const lower = normalizeLowercaseStringOrEmpty(message);
+  return lower.includes("timeout") || lower.includes("timed out");
 }
 
 function isAbortErrorMessage(message: string | undefined): boolean {
-  return message?.toLowerCase().includes("aborted") ?? false;
+  return normalizeLowercaseStringOrEmpty(message).includes("aborted");
 }
 
 export async function fetchBotIdentityForMonitor(
@@ -42,11 +59,12 @@ export async function fetchBotIdentityForMonitor(
     return { botOpenId: result.botOpenId, botName: result.botName };
   }
 
-  if (options.abortSignal?.aborted || isAbortErrorMessage(result.error)) {
+  const probeError = result.error ?? undefined;
+  if (options.abortSignal?.aborted || isAbortErrorMessage(probeError)) {
     return {};
   }
 
-  if (isTimeoutErrorMessage(result.error)) {
+  if (isTimeoutErrorMessage(probeError)) {
     const error = options.runtime?.error ?? console.error;
     error(
       `feishu[${account.accountId}]: bot info probe timed out after ${timeoutMs}ms; continuing startup`,
@@ -54,11 +72,3 @@ export async function fetchBotIdentityForMonitor(
   }
   return {};
 }
-
-export async function fetchBotOpenIdForMonitor(
-  account: ResolvedFeishuAccount,
-  options: FetchBotOpenIdOptions = {},
-): Promise<string | undefined> {
-  const identity = await fetchBotIdentityForMonitor(account, options);
-  return identity.botOpenId;
-}

package/src/monitor.state.ts

@@ -1,20 +1,20 @@
-import * as http from "http";
-import * as Lark from "@larksuiteoapi/node-sdk";
+import * as http from "node:http";
+import type * as Lark from "@larksuiteoapi/node-sdk";
 import {
   createFixedWindowRateLimiter,
   createWebhookAnomalyTracker,
   type RuntimeEnv,
   WEBHOOK_ANOMALY_COUNTER_DEFAULTS as WEBHOOK_ANOMALY_COUNTER_DEFAULTS_FROM_SDK,
   WEBHOOK_RATE_LIMIT_DEFAULTS as WEBHOOK_RATE_LIMIT_DEFAULTS_FROM_SDK,
-} from "openclaw/plugin-sdk/feishu";
+} from "./monitor-state-runtime-api.js";
 
 export const wsClients = new Map<string, Lark.WSClient>();
 export const httpServers = new Map<string, http.Server>();
 export const botOpenIds = new Map<string, string>();
 export const botNames = new Map<string, string>();
 
-export const FEISHU_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
-export const FEISHU_WEBHOOK_BODY_TIMEOUT_MS = 30_000;
+export const FEISHU_WEBHOOK_MAX_BODY_BYTES = 64 * 1024;
+export const FEISHU_WEBHOOK_BODY_TIMEOUT_MS = 5_000;
 
 type WebhookRateLimitDefaults = {
   windowMs: number;
@@ -104,6 +104,17 @@ const feishuWebhookAnomalyTracker = createWebhookAnomalyTracker({
   logEvery: feishuWebhookAnomalyDefaults.logEvery,
 });
 
+function closeWsClient(client: Lark.WSClient | undefined): void {
+  if (!client) {
+    return;
+  }
+  try {
+    client.close();
+  } catch {
+    /* Best-effort cleanup */
+  }
+}
+
 export function clearFeishuWebhookRateLimitStateForTest(): void {
   feishuWebhookRateLimiter.clear();
   feishuWebhookAnomalyTracker.clear();
@@ -134,6 +145,7 @@ export function recordWebhookStatus(
 
 export function stopFeishuMonitorState(accountId?: string): void {
   if (accountId) {
+    closeWsClient(wsClients.get(accountId));
     wsClients.delete(accountId);
     const server = httpServers.get(accountId);
     if (server) {
@@ -145,6 +157,9 @@ export function stopFeishuMonitorState(accountId?: string): void {
     return;
   }
 
+  for (const client of wsClients.values()) {
+    closeWsClient(client);
+  }
   wsClients.clear();
   for (const server of httpServers.values()) {
     server.close();

package/src/monitor.synthetic-error.ts

@@ -0,0 +1,18 @@
+export class FeishuRetryableSyntheticEventError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "FeishuRetryableSyntheticEventError";
+  }
+}
+
+export function isFeishuRetryableSyntheticEventError(
+  error: unknown,
+): error is FeishuRetryableSyntheticEventError {
+  return (
+    error instanceof FeishuRetryableSyntheticEventError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "FeishuRetryableSyntheticEventError")
+  );
+}

package/src/monitor.test-mocks.ts

@@ -1,11 +1,11 @@
 import { vi } from "vitest";
 
 export function createFeishuClientMockModule(): {
-  createFeishuWSClient: () => { start: () => void };
+  createFeishuWSClient: () => { start: () => void; close: () => void };
   createEventDispatcher: () => { register: () => void };
 } {
   return {
-    createFeishuWSClient: vi.fn(() => ({ start: vi.fn() })),
+    createFeishuWSClient: vi.fn(() => ({ start: vi.fn(), close: vi.fn() })),
     createEventDispatcher: vi.fn(() => ({ register: vi.fn() })),
   };
 }

package/src/monitor.transport.ts

@@ -1,13 +1,15 @@
-import * as http from "http";
 import crypto from "node:crypto";
+import * as http from "node:http";
 import * as Lark from "@larksuiteoapi/node-sdk";
+import { waitForAbortableDelay } from "./async.js";
+import { createFeishuWSClient } from "./client.js";
 import {
   applyBasicWebhookRequestGuards,
-  readJsonBodyWithLimit,
   type RuntimeEnv,
   installRequestBodyLimitGuard,
-} from "openclaw/plugin-sdk/feishu";
-import { createFeishuWSClient } from "./client.js";
+  readWebhookBodyOrReject,
+  safeEqualSecret,
+} from "./monitor-transport-runtime-api.js";
 import {
   botNames,
   botOpenIds,
@@ -20,7 +22,7 @@ import {
 } from "./monitor.state.js";
 import type { ResolvedFeishuAccount } from "./types.js";
 
-export type MonitorTransportParams = {
+type MonitorTransportParams = {
   account: ResolvedFeishuAccount;
   accountId: string;
   runtime?: RuntimeEnv;
@@ -28,6 +30,13 @@ export type MonitorTransportParams = {
   eventDispatcher: Lark.EventDispatcher;
 };
 
+const FEISHU_WS_RECONNECT_INITIAL_DELAY_MS = 1_000;
+const FEISHU_WS_RECONNECT_MAX_DELAY_MS = 30_000;
+const FEISHU_WS_LOG_ERROR_MAX_LENGTH = 500;
+const FEISHU_WS_RECONNECT_EXHAUSTED_RE = /^WebSocket reconnect exhausted after \d+ attempts?/;
+const FEISHU_WS_AUTORECONNECT_DISABLED_ERROR =
+  "WebSocket connect failed and autoReconnect is disabled";
+
 function isFeishuWebhookPayload(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -39,14 +48,23 @@ function buildFeishuWebhookEnvelope(
   return Object.assign(Object.create({ headers: req.headers }), payload) as Record<string, unknown>;
 }
 
+function parseFeishuWebhookPayload(rawBody: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(rawBody) as unknown;
+    return isFeishuWebhookPayload(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 function isFeishuWebhookSignatureValid(params: {
   headers: http.IncomingHttpHeaders;
-  payload: Record<string, unknown>;
+  rawBody: string;
   encryptKey?: string;
 }): boolean {
   const encryptKey = params.encryptKey?.trim();
   if (!encryptKey) {
-    return true;
+    return false;
   }
 
   const timestampHeader = params.headers["x-lark-request-timestamp"];
@@ -61,9 +79,9 @@ function isFeishuWebhookSignatureValid(params: {
 
   const computedSignature = crypto
     .createHash("sha256")
-    .update(timestamp + nonce + encryptKey + JSON.stringify(params.payload))
+    .update(timestamp + nonce + encryptKey + params.rawBody)
     .digest("hex");
-  return computedSignature === signature;
+  return safeEqualSecret(computedSignature, signature);
 }
 
 function respondText(res: http.ServerResponse, statusCode: number, body: string): void {
@@ -72,6 +90,104 @@ function respondText(res: http.ServerResponse, statusCode: number, body: string)
   res.end(body);
 }
 
+function getFeishuWsReconnectDelayMs(attempt: number): number {
+  return Math.min(
+    FEISHU_WS_RECONNECT_INITIAL_DELAY_MS * 2 ** Math.max(0, attempt - 1),
+    FEISHU_WS_RECONNECT_MAX_DELAY_MS,
+  );
+}
+
+function formatFeishuWsErrorForLog(err: unknown): string {
+  const raw = err instanceof Error ? err.message || err.name : String(err);
+  const singleLine = Array.from(raw, (char) => {
+    const code = char.charCodeAt(0);
+    return code <= 31 || code === 127 ? " " : char;
+  }).join("");
+  const redacted = singleLine
+    .replace(/:\/\/[^:@/\s]+:[^@/\s]+@/g, "://[redacted]@")
+    .replace(/\b(authorization\s*[:=]\s*Bearer\s+)[^\s,;]+/gi, "$1[redacted]")
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+=*/g, "$1[redacted]")
+    .replace(
+      /\b((?:app[_-]?secret|tenant[_-]?access[_-]?token|access[_-]?token|refresh[_-]?token|token|secret|password)\s*[:=]\s*)[^\s&;,]+/gi,
+      "$1[redacted]",
+    )
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!redacted) {
+    return "unknown error";
+  }
+  if (redacted.length <= FEISHU_WS_LOG_ERROR_MAX_LENGTH) {
+    return redacted;
+  }
+  return `${redacted.slice(0, FEISHU_WS_LOG_ERROR_MAX_LENGTH)}...`;
+}
+
+function isFeishuWsTerminalError(err: Error): boolean {
+  const message = err.message.trim();
+  return (
+    FEISHU_WS_RECONNECT_EXHAUSTED_RE.test(message) ||
+    message.startsWith(FEISHU_WS_AUTORECONNECT_DISABLED_ERROR)
+  );
+}
+
+function cleanupFeishuWsClient(params: {
+  accountId: string;
+  wsClient?: Lark.WSClient;
+  error: (message: string) => void;
+  clearIdentity: boolean;
+}): void {
+  const { accountId, wsClient, error, clearIdentity } = params;
+  if (wsClient) {
+    try {
+      wsClient.close();
+    } catch (err) {
+      error(
+        `feishu[${accountId}]: error closing WebSocket client: ${formatFeishuWsErrorForLog(err)}`,
+      );
+    }
+  }
+  wsClients.delete(accountId);
+  if (clearIdentity) {
+    botOpenIds.delete(accountId);
+    botNames.delete(accountId);
+  }
+}
+
+function waitForFeishuWsCycleEnd(params: {
+  abortSignal?: AbortSignal;
+  terminalError: Promise<Error>;
+}): Promise<"abort" | Error> {
+  if (params.abortSignal?.aborted) {
+    return Promise.resolve("abort");
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let handleAbort: (() => void) | undefined;
+
+    const finish = (result: "abort" | Error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (handleAbort) {
+        params.abortSignal?.removeEventListener("abort", handleAbort);
+      }
+      resolve(result);
+    };
+
+    handleAbort = () => finish("abort");
+    params.abortSignal?.addEventListener("abort", handleAbort, { once: true });
+    if (params.abortSignal?.aborted) {
+      finish("abort");
+      return;
+    }
+
+    void params.terminalError.then(finish);
+  });
+}
+
 export async function monitorWebSocket({
   account,
   accountId,
@@ -80,41 +196,81 @@ export async function monitorWebSocket({
   eventDispatcher,
 }: MonitorTransportParams): Promise<void> {
   const log = runtime?.log ?? console.log;
-  log(`feishu[${accountId}]: starting WebSocket connection...`);
-
-  const wsClient = createFeishuWSClient(account);
-  wsClients.set(accountId, wsClient);
-
-  return new Promise((resolve, reject) => {
-    const cleanup = () => {
-      wsClients.delete(accountId);
-      botOpenIds.delete(accountId);
-      botNames.delete(accountId);
-    };
-
-    const handleAbort = () => {
-      log(`feishu[${accountId}]: abort signal received, stopping`);
-      cleanup();
-      resolve();
-    };
+  const error = runtime?.error ?? console.error;
 
+  let attempt = 0;
+  while (true) {
     if (abortSignal?.aborted) {
-      cleanup();
-      resolve();
-      return;
+      break;
     }
 
-    abortSignal?.addEventListener("abort", handleAbort, { once: true });
-
+    let wsClient: Lark.WSClient | undefined;
     try {
-      wsClient.start({ eventDispatcher });
+      let reportTerminalError: (err: Error) => void = () => {};
+      const terminalError = new Promise<Error>((resolve) => {
+        reportTerminalError = resolve;
+      });
+      const handleWsError = (err: Error) => {
+        if (isFeishuWsTerminalError(err)) {
+          reportTerminalError(err);
+          return;
+        }
+
+        error(
+          `feishu[${accountId}]: WebSocket SDK reported recoverable error: ${formatFeishuWsErrorForLog(err)}`,
+        );
+      };
+      log(`feishu[${accountId}]: starting WebSocket connection...`);
+      wsClient = await createFeishuWSClient(account, {
+        onError: handleWsError,
+      });
+      if (abortSignal?.aborted) {
+        cleanupFeishuWsClient({ accountId, wsClient, error, clearIdentity: true });
+        break;
+      }
+      wsClients.set(accountId, wsClient);
+      await wsClient.start({ eventDispatcher });
+      attempt = 0;
       log(`feishu[${accountId}]: WebSocket client started`);
+      const cycleEnd = await waitForFeishuWsCycleEnd({ abortSignal, terminalError });
+      if (cycleEnd === "abort") {
+        log(`feishu[${accountId}]: abort signal received, stopping`);
+        cleanupFeishuWsClient({ accountId, wsClient, error, clearIdentity: true });
+        return;
+      }
+
+      cleanupFeishuWsClient({ accountId, wsClient, error, clearIdentity: false });
+      if (abortSignal?.aborted) {
+        break;
+      }
+
+      attempt += 1;
+      const delayMs = getFeishuWsReconnectDelayMs(attempt);
+      error(
+        `feishu[${accountId}]: WebSocket connection ended, recreating client in ${delayMs}ms: ${formatFeishuWsErrorForLog(cycleEnd)}`,
+      );
+      const shouldRetry = await waitForAbortableDelay(delayMs, abortSignal);
+      if (!shouldRetry) {
+        break;
+      }
     } catch (err) {
-      cleanup();
-      abortSignal?.removeEventListener("abort", handleAbort);
-      reject(err);
+      cleanupFeishuWsClient({ accountId, wsClient, error, clearIdentity: false });
+      if (abortSignal?.aborted) {
+        break;
+      }
+
+      attempt += 1;
+      const delayMs = getFeishuWsReconnectDelayMs(attempt);
+      error(
+        `feishu[${accountId}]: WebSocket start failed, retrying in ${delayMs}ms: ${formatFeishuWsErrorForLog(err)}`,
+      );
+      const shouldRetry = await waitForAbortableDelay(delayMs, abortSignal);
+      if (!shouldRetry) {
+        break;
+      }
     }
-  });
+  }
+  cleanupFeishuWsClient({ accountId, wsClient: undefined, error, clearIdentity: true });
 }
 
 export async function monitorWebhook({
@@ -126,6 +282,10 @@ export async function monitorWebhook({
 }: MonitorTransportParams): Promise<void> {
   const log = runtime?.log ?? console.log;
   const error = runtime?.error ?? console.error;
+  const encryptKey = account.encryptKey?.trim();
+  if (!encryptKey) {
+    throw new Error(`Feishu account "${accountId}" webhook mode requires encryptKey`);
+  }
 
   const port = account.config.webhookPort ?? 3000;
   const path = account.config.webhookPath ?? "/feishu/events";
@@ -165,38 +325,41 @@ export async function monitorWebhook({
 
     void (async () => {
       try {
-        const bodyResult = await readJsonBodyWithLimit(req, {
+        const body = await readWebhookBodyOrReject({
+          req,
+          res,
           maxBytes: FEISHU_WEBHOOK_MAX_BODY_BYTES,
           timeoutMs: FEISHU_WEBHOOK_BODY_TIMEOUT_MS,
+          profile: "pre-auth",
         });
-        if (guard.isTripped() || res.writableEnded) {
+        if (!body.ok || res.writableEnded) {
           return;
         }
-        if (!bodyResult.ok) {
-          if (bodyResult.code === "INVALID_JSON") {
-            respondText(res, 400, "Invalid JSON");
-          }
-          return;
-        }
-        if (!isFeishuWebhookPayload(bodyResult.value)) {
-          respondText(res, 400, "Invalid JSON");
+        if (guard.isTripped()) {
           return;
         }
+        const rawBody = body.value;
 
-        // Lark's default adapter drops invalid signatures as an empty 200. Reject here instead.
+        // Reject invalid signatures before any JSON parsing to keep the auth boundary strict.
         if (
           !isFeishuWebhookSignatureValid({
             headers: req.headers,
-            payload: bodyResult.value,
-            encryptKey: account.encryptKey,
+            rawBody,
+            encryptKey,
           })
         ) {
           respondText(res, 401, "Invalid signature");
           return;
         }
 
-        const { isChallenge, challenge } = Lark.generateChallenge(bodyResult.value, {
-          encryptKey: account.encryptKey ?? "",
+        const payload = parseFeishuWebhookPayload(rawBody);
+        if (!payload) {
+          respondText(res, 400, "Invalid JSON");
+          return;
+        }
+
+        const { isChallenge, challenge } = Lark.generateChallenge(payload, {
+          encryptKey,
         });
         if (isChallenge) {
           res.statusCode = 200;
@@ -205,21 +368,18 @@ export async function monitorWebhook({
           return;
         }
 
-        const value = await eventDispatcher.invoke(
-          buildFeishuWebhookEnvelope(req, bodyResult.value),
-          { needCheck: false },
-        );
+        const value = await eventDispatcher.invoke(buildFeishuWebhookEnvelope(req, payload), {
+          needCheck: false,
+        });
         if (!res.headersSent) {
           res.statusCode = 200;
           res.setHeader("Content-Type", "application/json; charset=utf-8");
           res.end(JSON.stringify(value));
         }
       } catch (err) {
-        if (!guard.isTripped()) {
-          error(`feishu[${accountId}]: webhook handler error: ${String(err)}`);
-          if (!res.headersSent) {
-            respondText(res, 500, "Internal Server Error");
-          }
+        error(`feishu[${accountId}]: webhook handler error: ${String(err)}`);
+        if (!res.headersSent) {
+          respondText(res, 500, "Internal Server Error");
         }
       } finally {
         guard.dispose();

package/src/monitor.ts

@@ -1,10 +1,5 @@
-import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk/feishu";
-import { listEnabledFeishuAccounts, resolveFeishuAccount } from "./accounts.js";
-import {
-  monitorSingleAccount,
-  resolveReactionSyntheticEvent,
-  type FeishuReactionCreatedEvent,
-} from "./monitor.account.js";
+import type { ClawdbotConfig, RuntimeEnv } from "../runtime-api.js";
+import { listEnabledFeishuAccounts, resolveFeishuRuntimeAccount } from "./accounts.js";
 import { fetchBotIdentityForMonitor } from "./monitor.startup.js";
 import {
   clearFeishuWebhookRateLimitStateForTest,
@@ -20,13 +15,18 @@ export type MonitorFeishuOpts = {
   accountId?: string;
 };
 
+let monitorAccountRuntimePromise: Promise<typeof import("./monitor.account.js")> | undefined;
+
+async function loadMonitorAccountRuntime() {
+  monitorAccountRuntimePromise ??= import("./monitor.account.js");
+  return await monitorAccountRuntimePromise;
+}
+
 export {
   clearFeishuWebhookRateLimitStateForTest,
   getFeishuWebhookRateLimitStateSizeForTest,
   isWebhookRateLimitedForTest,
-  resolveReactionSyntheticEvent,
 };
-export type { FeishuReactionCreatedEvent };
 
 export async function monitorFeishuProvider(opts: MonitorFeishuOpts = {}): Promise<void> {
   const cfg = opts.config;
@@ -37,10 +37,14 @@ export async function monitorFeishuProvider(opts: MonitorFeishuOpts = {}): Promi
   const log = opts.runtime?.log ?? console.log;
 
   if (opts.accountId) {
-    const account = resolveFeishuAccount({ cfg, accountId: opts.accountId });
+    const account = resolveFeishuRuntimeAccount(
+      { cfg, accountId: opts.accountId },
+      { requireEventSecrets: true },
+    );
     if (!account.enabled || !account.configured) {
       throw new Error(`Feishu account "${opts.accountId}" not configured or disabled`);
     }
+    const { monitorSingleAccount } = await loadMonitorAccountRuntime();
     return monitorSingleAccount({
       cfg,
       account,
@@ -58,6 +62,7 @@ export async function monitorFeishuProvider(opts: MonitorFeishuOpts = {}): Promi
     `feishu: starting ${accounts.length} account(s): ${accounts.map((a) => a.accountId).join(", ")}`,
   );
 
+  const { monitorSingleAccount } = await loadMonitorAccountRuntime();
   const monitorPromises: Promise<void>[] = [];
   for (const account of accounts) {
     if (opts.abortSignal?.aborted) {