@openclaw/feishu 2026.3.13 → 2026.5.1-beta.1

package/src/comment-handler.ts

@@ -0,0 +1,309 @@
+import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing";
+import { resolveOpenDmAllowlistAccess } from "openclaw/plugin-sdk/security-runtime";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { createFeishuCommentReplyDispatcher } from "./comment-dispatcher.js";
+import {
+  createChannelPairingController,
+  type ClawdbotConfig,
+  type RuntimeEnv,
+} from "./comment-handler-runtime-api.js";
+import { buildFeishuCommentTarget } from "./comment-target.js";
+import { deliverCommentThreadText } from "./drive.js";
+import { maybeCreateDynamicAgent } from "./dynamic-agent.js";
+import {
+  resolveDriveCommentEventTurn,
+  type FeishuDriveCommentNoticeEvent,
+} from "./monitor.comment.js";
+import { resolveFeishuAllowlistMatch } from "./policy.js";
+import { getFeishuRuntime } from "./runtime.js";
+import type { DynamicAgentCreationConfig } from "./types.js";
+
+type HandleFeishuCommentEventParams = {
+  cfg: ClawdbotConfig;
+  accountId: string;
+  runtime?: RuntimeEnv;
+  event: FeishuDriveCommentNoticeEvent;
+  botOpenId?: string;
+};
+
+function buildCommentSessionKey(params: {
+  core: ReturnType<typeof getFeishuRuntime>;
+  route: ResolvedAgentRoute;
+  fileType: string;
+  fileToken: string;
+}): string {
+  return params.core.channel.routing.buildAgentSessionKey({
+    agentId: params.route.agentId,
+    channel: "feishu",
+    accountId: params.route.accountId,
+    peer: {
+      kind: "direct",
+      id: `comment-doc:${params.fileType}:${params.fileToken}`,
+    },
+    dmScope: "per-account-channel-peer",
+  });
+}
+
+function parseTimestampMs(value: string | undefined): number {
+  const parsed = value ? Number.parseInt(value, 10) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+export async function handleFeishuCommentEvent(
+  params: HandleFeishuCommentEventParams,
+): Promise<void> {
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
+  const feishuCfg = account.config;
+  const core = getFeishuRuntime();
+  const log = params.runtime?.log ?? console.log;
+  const error = params.runtime?.error ?? console.error;
+  const runtime = (params.runtime ?? { log, error }) as RuntimeEnv;
+
+  const turn = await resolveDriveCommentEventTurn({
+    cfg: params.cfg,
+    accountId: account.accountId,
+    event: params.event,
+    botOpenId: params.botOpenId,
+    logger: log,
+  });
+  if (!turn) {
+    log(
+      `feishu[${account.accountId}]: drive comment notice skipped ` +
+        `event=${params.event.event_id ?? "unknown"} comment=${params.event.comment_id ?? "unknown"}`,
+    );
+    return;
+  }
+
+  const commentTarget = buildFeishuCommentTarget({
+    fileType: turn.fileType,
+    fileToken: turn.fileToken,
+    commentId: turn.commentId,
+  });
+  const dmPolicy = feishuCfg?.dmPolicy ?? "pairing";
+  const configAllowFrom = feishuCfg?.allowFrom ?? [];
+  const pairing = createChannelPairingController({
+    core,
+    channel: "feishu",
+    accountId: account.accountId,
+  });
+  const storeAllowFrom =
+    dmPolicy !== "allowlist" && dmPolicy !== "open"
+      ? await pairing.readAllowFromStore().catch(() => [])
+      : [];
+  const effectiveDmAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+  const senderAllowed = resolveFeishuAllowlistMatch({
+    allowFrom: effectiveDmAllowFrom,
+    senderId: turn.senderId,
+    senderIds: [turn.senderUserId],
+  }).allowed;
+  const dmAccessAllowed =
+    dmPolicy === "open"
+      ? resolveOpenDmAllowlistAccess({
+          effectiveAllowFrom: effectiveDmAllowFrom,
+          isSenderAllowed: (allowFrom) =>
+            resolveFeishuAllowlistMatch({
+              allowFrom,
+              senderId: turn.senderId,
+              senderIds: [turn.senderUserId],
+            }).allowed,
+        }).decision === "allow"
+      : senderAllowed;
+  if (!dmAccessAllowed) {
+    if (dmPolicy === "pairing") {
+      const client = createFeishuClient(account);
+      await pairing.issueChallenge({
+        senderId: turn.senderId,
+        senderIdLine: `Your Feishu user id: ${turn.senderId}`,
+        meta: { name: turn.senderId },
+        onCreated: ({ code }) => {
+          log(
+            `feishu[${account.accountId}]: comment pairing request sender=${turn.senderId} code=${code}`,
+          );
+        },
+        sendPairingReply: async (text) => {
+          await deliverCommentThreadText(client, {
+            file_token: turn.fileToken,
+            file_type: turn.fileType,
+            comment_id: turn.commentId,
+            content: text,
+            is_whole_comment: turn.isWholeComment,
+          });
+        },
+        onReplyError: (err) => {
+          log(
+            `feishu[${account.accountId}]: comment pairing reply failed for ${turn.senderId}: ${String(err)}`,
+          );
+        },
+      });
+    } else {
+      log(
+        `feishu[${account.accountId}]: blocked unauthorized comment sender ${turn.senderId} ` +
+          `(dmPolicy=${dmPolicy}, comment=${turn.commentId})`,
+      );
+    }
+    return;
+  }
+
+  let effectiveCfg = params.cfg;
+  let route = core.channel.routing.resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "feishu",
+    accountId: account.accountId,
+    peer: {
+      kind: "direct",
+      id: turn.senderId,
+    },
+  });
+  if (route.matchedBy === "default") {
+    const dynamicCfg = feishuCfg?.dynamicAgentCreation as DynamicAgentCreationConfig | undefined;
+    if (dynamicCfg?.enabled) {
+      const dynamicResult = await maybeCreateDynamicAgent({
+        cfg: params.cfg,
+        runtime: core,
+        senderOpenId: turn.senderId,
+        dynamicCfg,
+        log: (message) => log(message),
+      });
+      if (dynamicResult.created) {
+        effectiveCfg = dynamicResult.updatedCfg;
+        route = core.channel.routing.resolveAgentRoute({
+          cfg: dynamicResult.updatedCfg,
+          channel: "feishu",
+          accountId: account.accountId,
+          peer: {
+            kind: "direct",
+            id: turn.senderId,
+          },
+        });
+        log(
+          `feishu[${account.accountId}]: dynamic agent created for comment flow, route=${route.sessionKey}`,
+        );
+      }
+    }
+  }
+
+  const commentSessionKey = buildCommentSessionKey({
+    core,
+    route,
+    fileType: turn.fileType,
+    fileToken: turn.fileToken,
+  });
+  const bodyForAgent = `[message_id: ${turn.messageId}]\n${turn.prompt}`;
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: bodyForAgent,
+    BodyForAgent: bodyForAgent,
+    RawBody: turn.targetReplyText ?? turn.rootCommentText ?? turn.prompt,
+    CommandBody: turn.targetReplyText ?? turn.rootCommentText ?? turn.prompt,
+    From: `feishu:${turn.senderId}`,
+    To: commentTarget,
+    SessionKey: commentSessionKey,
+    AccountId: route.accountId,
+    ChatType: "direct",
+    ConversationLabel: turn.documentTitle
+      ? `Feishu comment · ${turn.documentTitle}`
+      : "Feishu comment",
+    SenderName: turn.senderId,
+    SenderId: turn.senderId,
+    Provider: "feishu",
+    Surface: "feishu-comment",
+    MessageSid: turn.messageId,
+    // For Feishu comment turns, MessageThreadId carries the inbound reply_id so
+    // comment-aware tools can clean typing reaction before sending visible output.
+    MessageThreadId: turn.replyId,
+    Timestamp: parseTimestampMs(turn.timestamp),
+    WasMentioned: turn.isMentioned,
+    CommandAuthorized: false,
+    OriginatingChannel: "feishu",
+    OriginatingTo: commentTarget,
+  });
+
+  const storePath = core.channel.session.resolveStorePath(effectiveCfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle, markRunComplete, cleanupTypingReaction } =
+    createFeishuCommentReplyDispatcher({
+      cfg: effectiveCfg,
+      agentId: route.agentId,
+      runtime,
+      accountId: account.accountId,
+      fileToken: turn.fileToken,
+      fileType: turn.fileType,
+      commentId: turn.commentId,
+      replyId: turn.replyId,
+      isWholeComment: turn.isWholeComment,
+    });
+
+  let dispatchSettledBeforeStart = false;
+  try {
+    log(
+      `feishu[${account.accountId}]: dispatching drive comment to agent ` +
+        `(session=${commentSessionKey} comment=${turn.commentId} type=${turn.noticeType})`,
+    );
+    const turnResult = await core.channel.turn.run({
+      channel: "feishu",
+      accountId: route.accountId,
+      raw: turn,
+      adapter: {
+        ingest: () => ({
+          id: turn.messageId,
+          timestamp: parseTimestampMs(turn.timestamp),
+          rawText: ctxPayload.RawBody ?? "",
+          textForAgent: ctxPayload.BodyForAgent,
+          textForCommands: ctxPayload.CommandBody,
+          raw: turn,
+        }),
+        resolveTurn: () => ({
+          channel: "feishu",
+          accountId: route.accountId,
+          routeSessionKey: commentSessionKey,
+          storePath,
+          ctxPayload,
+          recordInboundSession: core.channel.session.recordInboundSession,
+          record: {
+            onRecordError: (err) => {
+              error(
+                `feishu[${account.accountId}]: failed to record comment inbound session ${commentSessionKey}: ${String(err)}`,
+              );
+            },
+          },
+          onPreDispatchFailure: async () => {
+            dispatchSettledBeforeStart = true;
+            await core.channel.reply.settleReplyDispatcher({
+              dispatcher,
+              onSettled: () => {
+                markRunComplete();
+                markDispatchIdle();
+              },
+            });
+          },
+          runDispatch: () =>
+            core.channel.reply.withReplyDispatcher({
+              dispatcher,
+              run: () =>
+                core.channel.reply.dispatchReplyFromConfig({
+                  ctx: ctxPayload,
+                  cfg: effectiveCfg,
+                  dispatcher,
+                  replyOptions,
+                }),
+            }),
+        }),
+      },
+    });
+    const dispatchResult = turnResult.dispatched ? turnResult.dispatchResult : undefined;
+    const queuedFinal = dispatchResult?.queuedFinal ?? false;
+    const counts = dispatchResult?.counts ?? { tool: 0, block: 0, final: 0 };
+    log(
+      `feishu[${account.accountId}]: drive comment dispatch complete ` +
+        `(queuedFinal=${queuedFinal}, replies=${counts.final}, session=${commentSessionKey})`,
+    );
+  } finally {
+    if (!dispatchSettledBeforeStart) {
+      markRunComplete();
+      markDispatchIdle();
+    }
+    void cleanupTypingReaction();
+  }
+}

package/src/comment-reaction.test.ts

@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import {
+  cleanupAmbientCommentTypingReaction,
+  createCommentTypingReactionLifecycle,
+} from "./comment-reaction.js";
+
+const resolveFeishuRuntimeAccountMock = vi.hoisted(() => vi.fn());
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./accounts.js", () => ({
+  resolveFeishuRuntimeAccount: resolveFeishuRuntimeAccountMock,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+describe("createCommentTypingReactionLifecycle", () => {
+  const request = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resolveFeishuRuntimeAccountMock.mockReturnValue({
+      accountId: "default",
+      configured: true,
+      config: {
+        typingIndicator: true,
+      },
+    });
+    createFeishuClientMock.mockReturnValue({
+      request,
+    });
+    request.mockResolvedValue({
+      code: 0,
+      data: {},
+    });
+  });
+
+  function createTypingReactionLifecycle(...args: [replyId?: string]) {
+    return createCommentTypingReactionLifecycle({
+      cfg: {} as ClawdbotConfig,
+      fileToken: "doc_token_1",
+      fileType: "docx",
+      replyId: args.length === 0 ? "reply_1" : args[0],
+      runtime: {
+        log: vi.fn(),
+      } as never,
+    });
+  }
+
+  const cleanupAmbientReply = () =>
+    cleanupAmbientCommentTypingReaction({
+      client: { request } as never,
+      deliveryContext: {
+        channel: "feishu",
+        to: "comment:docx:doc_token_1:comment_1",
+        threadId: "reply_1",
+      },
+    });
+
+  it("adds and removes a comment typing reaction using reply_id", async () => {
+    const lifecycle = createTypingReactionLifecycle();
+
+    await lifecycle.start();
+    await lifecycle.cleanup();
+
+    expect(request).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        method: "POST",
+        url: "/open-apis/drive/v2/files/doc_token_1/comments/reaction?file_type=docx",
+        data: {
+          action: "add",
+          reply_id: "reply_1",
+          reaction_type: "Typing",
+        },
+      }),
+    );
+    expect(request).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        method: "POST",
+        url: "/open-apis/drive/v2/files/doc_token_1/comments/reaction?file_type=docx",
+        data: {
+          action: "delete",
+          reply_id: "reply_1",
+          reaction_type: "Typing",
+        },
+      }),
+    );
+  });
+
+  it("skips requests when reply_id is missing", async () => {
+    const lifecycle = createTypingReactionLifecycle(undefined);
+
+    await lifecycle.start();
+    await lifecycle.cleanup();
+
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  it("shares cleanup state so ambient cleanup and finally cleanup do not delete twice", async () => {
+    const lifecycle = createTypingReactionLifecycle();
+
+    await lifecycle.start();
+    await cleanupAmbientReply();
+    await lifecycle.cleanup();
+
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(request).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        data: {
+          action: "delete",
+          reply_id: "reply_1",
+          reaction_type: "Typing",
+        },
+      }),
+    );
+  });
+
+  it("retries delete during later cleanup after an ambient delete failure", async () => {
+    request
+      .mockResolvedValueOnce({
+        code: 0,
+        data: {},
+      })
+      .mockResolvedValueOnce({
+        code: 5001,
+        msg: "temporary failure",
+      })
+      .mockResolvedValueOnce({
+        code: 0,
+        data: {},
+      });
+
+    const lifecycle = createTypingReactionLifecycle();
+
+    await lifecycle.start();
+    await cleanupAmbientReply();
+    await lifecycle.cleanup();
+
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(request).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        data: {
+          action: "delete",
+          reply_id: "reply_1",
+          reaction_type: "Typing",
+        },
+      }),
+    );
+    expect(request).toHaveBeenNthCalledWith(
+      3,
+      expect.objectContaining({
+        data: {
+          action: "delete",
+          reply_id: "reply_1",
+          reaction_type: "Typing",
+        },
+      }),
+    );
+  });
+});