feat(feishu): improve document comment session, rich parsing, and typing feedback (openclaw#63785)

* Feishu: upgrade comment session, context parsing, and typing reaction

* test(feishu): align comment prompt assertions

Author: wittam-01

extensions/feishu/src/comment-dispatcher.test.ts

@@ -0,0 +1,160 @@
+import { 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";
+
+describe("createFeishuCommentReplyDispatcher", () => {
+  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,
+    });
+
+    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,
+    });
+
+    const options = createReplyDispatcherWithTypingMock.mock.calls.at(-1)?.[0];
+    const deliverPromise = options.deliver({ text: "hello world" }, { kind: "final" });
+    const status = await Promise.race([
+      deliverPromise.then(() => "done"),
+      new Promise<string>((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+
+    expect(status).toBe("done");
+    expect(deliverCommentThreadTextMock).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        file_token: "doc_token_1",
+        file_type: "docx",
+        comment_id: "comment_1",
+        content: "hello world",
+        is_whole_comment: false,
+      }),
+    );
+    expect(cleanup).not.toHaveBeenCalled();
+
+    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 () => {}),
+    });
+
+    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,
+    });
+
+    const options = createReplyDispatcherWithTypingMock.mock.calls.at(-1)?.[0];
+    await options.onReplyStart?.();
+
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+});

extensions/feishu/src/comment-dispatcher.ts

@@ -7,6 +7,7 @@ import {
   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";
@@ -19,6 +20,7 @@ export type CreateFeishuCommentReplyDispatcherParams = {
   fileToken: string;
   fileType: CommentFileType;
   commentId: string;
+  replyId?: string;
   isWholeComment?: boolean;
 };
 
@@ -43,12 +45,23 @@ export function createFeishuCommentReplyDispatcher(
     },
   );
   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 } =
+  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;
@@ -78,7 +91,17 @@ export function createFeishuCommentReplyDispatcher(
           `feishu[${params.accountId ?? "default"}]: comment dispatcher failed kind=${info.kind} comment=${params.commentId}: ${String(err)}`,
         );
       },
+      onCleanup: () => {
+        void typingReaction.cleanup();
+      },
     });
 
-  return { dispatcher, replyOptions, markDispatchIdle };
+  return {
+    dispatcher,
+    replyOptions,
+    markDispatchIdle,
+    markRunComplete,
+    startTypingReaction: typingReaction.start,
+    cleanupTypingReaction: typingReaction.cleanup,
+  };
 }

extensions/feishu/src/comment-handler.test.ts

@@ -164,6 +164,9 @@ describe("handleFeishuCommentEvent", () => {
       },
       replyOptions: {},
       markDispatchIdle: vi.fn(),
+      markRunComplete: vi.fn(),
+      startTypingReaction: vi.fn(async () => {}),
+      cleanupTypingReaction: vi.fn(async () => {}),
     });
   });
 
@@ -198,9 +201,15 @@ describe("handleFeishuCommentEvent", () => {
         OriginatingChannel: "feishu",
         OriginatingTo: "comment:docx:doc_token_1:comment_1",
         MessageSid: "drive-comment:evt_1",
+        MessageThreadId: "reply_1",
       }),
     );
     expect(recordInboundSession).toHaveBeenCalledTimes(1);
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionKey: "agent:main:feishu:direct:comment-doc:docx:doc_token_1",
+      }),
+    );
     expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
   });
 
@@ -309,8 +318,124 @@ describe("handleFeishuCommentEvent", () => {
         commentId: "comment_whole",
         fileToken: "doc_token_1",
         fileType: "docx",
+        replyId: "reply_whole",
         isWholeComment: true,
       }),
     );
   });
+
+  it("always finalizes comment typing cleanup even when dispatch fails", async () => {
+    const dispatchReplyFromConfig = vi.fn(async () => {
+      throw new Error("dispatch failed");
+    });
+    const runtime = createTestRuntime({ dispatchReplyFromConfig });
+    setFeishuRuntime(runtime);
+    const markRunComplete = vi.fn();
+    const markDispatchIdle = vi.fn();
+    const cleanupTypingReaction = vi.fn(async () => {});
+    createFeishuCommentReplyDispatcherMock.mockReturnValue({
+      dispatcher: {
+        markComplete: vi.fn(),
+        waitForIdle: vi.fn(async () => {}),
+      },
+      replyOptions: {},
+      markDispatchIdle,
+      markRunComplete,
+      startTypingReaction: vi.fn(async () => {}),
+      cleanupTypingReaction,
+    });
+
+    await expect(
+      handleFeishuCommentEvent({
+        cfg: buildConfig(),
+        accountId: "default",
+        event: { event_id: "evt_1" },
+        botOpenId: "ou_bot",
+        runtime: {
+          log: vi.fn(),
+          error: vi.fn(),
+        } as never,
+      }),
+    ).rejects.toThrow("dispatch failed");
+
+    expect(markRunComplete).toHaveBeenCalledTimes(1);
+    expect(markDispatchIdle).toHaveBeenCalledTimes(1);
+    expect(cleanupTypingReaction).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not wait for comment typing cleanup before returning", async () => {
+    let resolveCleanup: (() => void) | undefined;
+    const cleanupTypingReaction = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveCleanup = resolve;
+        }),
+    );
+    createFeishuCommentReplyDispatcherMock.mockReturnValue({
+      dispatcher: {
+        markComplete: vi.fn(),
+        waitForIdle: vi.fn(async () => {}),
+      },
+      replyOptions: {},
+      markDispatchIdle: vi.fn(),
+      markRunComplete: vi.fn(),
+      startTypingReaction: vi.fn(async () => {}),
+      cleanupTypingReaction,
+    });
+
+    const eventPromise = handleFeishuCommentEvent({
+      cfg: buildConfig(),
+      accountId: "default",
+      event: { event_id: "evt_1" },
+      botOpenId: "ou_bot",
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+      } as never,
+    });
+
+    const status = await Promise.race([
+      eventPromise.then(() => "done"),
+      new Promise<string>((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+
+    expect(status).toBe("done");
+    expect(cleanupTypingReaction).toHaveBeenCalledTimes(1);
+
+    resolveCleanup?.();
+    await eventPromise;
+  });
+
+  it("does not start comment typing reaction before dispatch begins", async () => {
+    const startTypingReaction = vi.fn(async () => {});
+    createFeishuCommentReplyDispatcherMock.mockReturnValue({
+      dispatcher: {
+        markComplete: vi.fn(),
+        waitForIdle: vi.fn(async () => {}),
+      },
+      replyOptions: {},
+      markDispatchIdle: vi.fn(),
+      markRunComplete: vi.fn(),
+      startTypingReaction,
+      cleanupTypingReaction: vi.fn(async () => {}),
+    });
+
+    await handleFeishuCommentEvent({
+      cfg: buildConfig(),
+      accountId: "default",
+      event: { event_id: "evt_1" },
+      botOpenId: "ou_bot",
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+      } as never,
+    });
+
+    expect(startTypingReaction).not.toHaveBeenCalled();
+    const runtime = (await import("./runtime.js")).getFeishuRuntime();
+    const dispatchReplyFromConfig = runtime.channel.reply.dispatchReplyFromConfig as ReturnType<
+      typeof vi.fn
+    >;
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
 });