@soimy/dingtalk 3.3.0 → 3.4.0

package/src/messaging/quoted-ref.ts

@@ -0,0 +1,97 @@
+import {
+  resolveByQuotedRef,
+  type MessageRecord,
+} from "../message-context-store";
+import type { DingTalkInboundMessage, Logger, MessageContent, QuotedRef } from "../types";
+
+function firstTrimmedString(...candidates: Array<string | undefined>): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+function firstFiniteNumber(...candidates: Array<number | undefined>): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+export function buildInboundQuotedRef(
+  data: DingTalkInboundMessage,
+  content: MessageContent,
+): QuotedRef | undefined {
+  const repliedMsg = data.text?.repliedMsg;
+  const repliedMsgId = firstTrimmedString(repliedMsg?.msgId, data.originalMsgId, content.quoted?.msgId);
+  const fallbackCreatedAt = firstFiniteNumber(
+    repliedMsg?.createdAt,
+    content.quoted?.cardCreatedAt,
+    content.quoted?.fileCreatedAt,
+  );
+  const isOutboundQuoted =
+    firstTrimmedString(data.originalProcessQueryKey) !== undefined ||
+    repliedMsg?.senderId === data.chatbotUserId ||
+    content.quoted?.isQuotedCard === true;
+  if (isOutboundQuoted) {
+    const processQueryKey = firstTrimmedString(data.originalProcessQueryKey, content.quoted?.processQueryKey);
+    if (processQueryKey) {
+      return {
+        targetDirection: "outbound",
+        key: "processQueryKey",
+        value: processQueryKey,
+        fallbackCreatedAt,
+      };
+    }
+    if (!fallbackCreatedAt) {
+      return undefined;
+    }
+    return {
+      targetDirection: "outbound",
+      fallbackCreatedAt,
+    };
+  }
+  if (!repliedMsgId) {
+    return undefined;
+  }
+  return {
+    targetDirection: "inbound",
+    key: "msgId",
+    value: repliedMsgId,
+  };
+}
+
+export function createReplyQuotedRef(msgId: string | undefined): QuotedRef | undefined {
+  const value = firstTrimmedString(msgId);
+  if (!value) {
+    return undefined;
+  }
+  return {
+    targetDirection: "inbound",
+    key: "msgId",
+    value,
+  };
+}
+
+export function resolveQuotedRecord(params: {
+  storePath?: string;
+  accountId: string;
+  conversationId: string | null;
+  quotedRef?: QuotedRef;
+  log?: Logger;
+}): MessageRecord | null {
+  if (!params.quotedRef) {
+    return null;
+  }
+  return resolveByQuotedRef({
+    storePath: params.storePath,
+    accountId: params.accountId,
+    conversationId: params.conversationId,
+    quotedRef: params.quotedRef,
+    log: params.log,
+  });
+}

package/src/onboarding.ts

@@ -1,8 +1,8 @@
 import type { OpenClawConfig, ChannelOnboardingAdapter, WizardPrompter } from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId, formatDocsLink } from "openclaw/plugin-sdk";
+import { DEFAULT_MESSAGE_CONTEXT_TTL_DAYS } from "./message-context-store.js";
 import type { DingTalkConfig, DingTalkChannelConfig } from "./types.js";
 import { listDingTalkAccountIds, resolveDingTalkAccount } from "./types.js";
-import { DEFAULT_JOURNAL_TTL_DAYS } from "./quote-journal.js";
 
 const channel = "dingtalk" as const;
 
@@ -104,6 +104,10 @@ function applyAccountConfig(params: {
     ...(input.dmPolicy ? { dmPolicy: input.dmPolicy } : {}),
     ...(input.groupPolicy ? { groupPolicy: input.groupPolicy } : {}),
     ...(input.allowFrom && input.allowFrom.length > 0 ? { allowFrom: input.allowFrom } : {}),
+    ...(input.groupAllowFrom && input.groupAllowFrom.length > 0 ? { groupAllowFrom: input.groupAllowFrom } : {}),
+    ...(input.displayNameResolution
+      ? { displayNameResolution: input.displayNameResolution }
+      : {}),
     ...(input.messageType ? { messageType: input.messageType } : {}),
     ...(input.cardTemplateId ? { cardTemplateId: input.cardTemplateId } : {}),
     ...(input.cardTemplateKey ? { cardTemplateKey: input.cardTemplateKey } : {}),
@@ -317,10 +321,61 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
       options: [
         { label: "Open - any group can use bot", value: "open" },
         { label: "Allowlist - only allowed groups", value: "allowlist" },
+        { label: "Disabled - block all group messages", value: "disabled" },
       ],
       initialValue: resolved.groupPolicy ?? "open",
     });
 
+    if (groupPolicyValue === "allowlist") {
+      await prompter.note(
+        [
+          'groupPolicy=allowlist requires "groups" config to specify allowed group IDs.',
+          "After setup, manually add group conversationIds to your config:",
+          "",
+          '  "groups": { "cidXXX": {}, "cidYYY": { "systemPrompt": "..." } }',
+          "",
+          "Groups not listed will be blocked. Use \"*\" as key to allow all groups.",
+        ].join("\n"),
+      );
+    }
+
+    let groupAllowFrom: string[] | undefined;
+    if (groupPolicyValue !== "disabled") {
+      const groupAllowFromEntry = await prompter.text({
+        message: "Group sender allowlist - user IDs allowed in groups (comma-separated, optional)",
+        placeholder: "user1, user2",
+        initialValue: (resolved.groupAllowFrom || []).join(", ") || undefined,
+      });
+      const parsedGroupAllowFrom = parseList(String(groupAllowFromEntry ?? ""));
+      groupAllowFrom = parsedGroupAllowFrom.length > 0 ? parsedGroupAllowFrom : undefined;
+    }
+
+    await prompter.note(
+      [
+        "Enabling learned displayName target resolution has tradeoffs:",
+        "- learned names come from observed inbound messages and can become stale",
+        "- duplicate display names can resolve to the wrong group or user",
+        "- current upstream target resolution does not provide requester authz, so \"all\" applies to every caller that can reach the send flow",
+        "Use explicit IDs for sensitive or high-risk deliveries.",
+      ].join("\n"),
+      "displayName resolution risk",
+    );
+
+    const displayNameResolutionValue = await prompter.select({
+      message: "Learned displayName target resolution",
+      options: [
+        {
+          label: "Disabled - require explicit IDs",
+          value: "disabled",
+        },
+        {
+          label: "All - learned lookup for all callers (higher risk)",
+          value: "all",
+        },
+      ],
+      initialValue: resolved.displayNameResolution ?? "disabled",
+    });
+
     let maxReconnectCycles: number | undefined;
     const wantsReconnectLimits = await prompter.confirm({
       message: "Configure runtime reconnect cycle limit? (recommended)",
@@ -390,11 +445,11 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
         String(
           await prompter.text({
             message: "Quote journal retention days",
-            placeholder: String(DEFAULT_JOURNAL_TTL_DAYS),
+            placeholder: String(DEFAULT_MESSAGE_CONTEXT_TTL_DAYS),
             initialValue:
               typeof resolved.journalTTLDays === "number"
                 ? String(resolved.journalTTLDays)
-                : String(DEFAULT_JOURNAL_TTL_DAYS),
+                : String(DEFAULT_MESSAGE_CONTEXT_TTL_DAYS),
             validate: (value) => {
               const raw = String(value ?? "").trim();
               const num = Number(raw);
@@ -412,7 +467,7 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
       journalTTLDays =
         Number.isInteger(parsedJournalTTL) && parsedJournalTTL > 0
           ? parsedJournalTTL
-          : DEFAULT_JOURNAL_TTL_DAYS;
+          : DEFAULT_MESSAGE_CONTEXT_TTL_DAYS;
     }
 
     const next = applyAccountConfig({
@@ -425,8 +480,10 @@ export const dingtalkOnboardingAdapter: ChannelOnboardingAdapter = {
         corpId,
         agentId,
         dmPolicy: dmPolicyValue as "open" | "allowlist",
-        groupPolicy: groupPolicyValue as "open" | "allowlist",
+        groupPolicy: groupPolicyValue as "open" | "allowlist" | "disabled",
         allowFrom,
+        groupAllowFrom,
+        displayNameResolution: displayNameResolutionValue as "disabled" | "all",
         mediaUrlAllowlist,
         messageType,
         cardTemplateId,

package/src/reply-strategy-card.ts

@@ -0,0 +1,225 @@
+/**
+ * AI Card reply strategy.
+ *
+ * Encapsulates the card draft controller lifecycle, deliver routing
+ * (final / tool / block), finalization, and failure fallback so that
+ * inbound-handler only coordinates — it no longer owns card state.
+ */
+
+import {
+  finishAICard,
+  formatContentForCard,
+  isCardInTerminalState,
+} from "./card-service";
+import { createCardDraftController } from "./card-draft-controller";
+import type { DeliverPayload, ReplyOptions, ReplyStrategy, ReplyStrategyContext } from "./reply-strategy";
+import { sendBySession, sendMessage } from "./send-service";
+import type { AICardInstance } from "./types";
+import { AICardStatus } from "./types";
+import { formatDingTalkErrorPayloadLog } from "./utils";
+
+export function createCardReplyStrategy(
+  ctx: ReplyStrategyContext & { card: AICardInstance },
+): ReplyStrategy {
+  const { card, config, log } = ctx;
+
+  const controller = createCardDraftController({ card, log });
+  let finalTextForFallback: string | undefined;
+
+  return {
+    getReplyOptions(): ReplyOptions {
+      return {
+        // Card mode: intermediate blocks are unused — card updates go through
+        // onPartialReply (real-time) or deliver(final) -> finishAICard.
+        disableBlockStreaming: true,
+
+        onAssistantMessageStart: () => {
+          controller.notifyNewAssistantTurn();
+        },
+
+        onPartialReply: config.cardRealTimeStream
+          ? (payload) => {
+              if (payload.text) {
+                controller.updateAnswer(payload.text);
+              }
+            }
+          : undefined,
+
+        onReasoningStream: (payload) => {
+          if (payload.text) {
+            controller.updateReasoning(payload.text);
+          }
+        },
+      };
+    },
+
+    async deliver(payload: DeliverPayload): Promise<void> {
+      const textToSend = payload.text;
+
+      // Empty-payload guard — card final is an exception (e.g. file-only response).
+      if ((typeof textToSend !== "string" || textToSend.length === 0) && payload.mediaUrls.length === 0) {
+        if (payload.kind !== "final") {
+          return;
+        }
+      }
+
+      // ---- final: defer to finalize, just save text ----
+      if (payload.kind === "final") {
+        log?.info?.(
+          `[DingTalk][Finalize] deliver(final) received — cardState=${card.state} ` +
+          `textLen=${typeof textToSend === "string" ? textToSend.length : "null"} ` +
+          `mediaUrls=${payload.mediaUrls.length} ` +
+          `lastAnswer="${(controller.getLastAnswerContent() ?? "").slice(0, 80)}" ` +
+          `lastContent="${(controller.getLastContent() ?? "").slice(0, 80)}"`,
+        );
+        if (payload.mediaUrls.length > 0) {
+          await ctx.deliverMedia(payload.mediaUrls);
+        }
+        const rawFinalText = typeof textToSend === "string" ? textToSend : "";
+        if (rawFinalText) {
+          finalTextForFallback = rawFinalText;
+        }
+        return;
+      }
+
+      // ---- tool: append to card ----
+      if (payload.kind === "tool") {
+        if (controller.isFailed() || isCardInTerminalState(card.state)) {
+          log?.debug?.("[DingTalk] Card failed, skipping tool result (will send full reply on final)");
+          return;
+        }
+        await controller.flush();
+        await controller.waitForInFlight();
+        log?.info?.(
+          `[DingTalk] Tool result received, streaming to AI Card: ${(textToSend ?? "").slice(0, 100)}`,
+        );
+        const toolText = typeof textToSend === "string" ? formatContentForCard(textToSend, "tool") : "";
+        if (toolText) {
+          const sendResult = await sendMessage(ctx.config, ctx.to, toolText, {
+            sessionWebhook: ctx.sessionWebhook,
+            atUserId: !ctx.isDirect ? ctx.senderId : null,
+            log,
+            card,
+            accountId: ctx.accountId,
+            storePath: ctx.storePath,
+            conversationId: ctx.groupId,
+            cardUpdateMode: "append",
+          });
+          if (!sendResult.ok) {
+            throw new Error(sendResult.error || "Tool stream send failed");
+          }
+        }
+        return;
+      }
+
+      // ---- block: only handle media (text blocks are unused) ----
+      if (payload.mediaUrls.length > 0) {
+        await ctx.deliverMedia(payload.mediaUrls);
+      }
+    },
+
+    async finalize(): Promise<void> {
+      log?.info?.(
+        `[DingTalk][Finalize] Step 5 entry — ` +
+        `cardState=${card.state ?? "N/A"} ` +
+        `controllerFailed=${controller.isFailed()} ` +
+        `finalTextForFallback="${(finalTextForFallback ?? "").slice(0, 80)}" ` +
+        `lastAnswer="${(controller.getLastAnswerContent() ?? "").slice(0, 80)}" ` +
+        `lastContent="${(controller.getLastContent() ?? "").slice(0, 80)}"`,
+      );
+
+      if (card.state === AICardStatus.FINISHED) {
+        log?.info?.("[DingTalk][Finalize] Skipping — card already FINISHED");
+        return;
+      }
+
+      // Card failed -> markdown fallback (bypass sendMessage to avoid duplicate card).
+      if (card.state === AICardStatus.FAILED || controller.isFailed()) {
+        const fallbackText = finalTextForFallback
+          || controller.getLastAnswerContent()
+          || controller.getLastContent()
+          || card.lastStreamedContent;
+        if (fallbackText) {
+          log?.debug?.("[DingTalk] Card failed during streaming, sending markdown fallback");
+          const sendResult = await sendMessage(ctx.config, ctx.to, fallbackText, {
+            sessionWebhook: ctx.sessionWebhook,
+            atUserId: !ctx.isDirect ? ctx.senderId : null,
+            log,
+            accountId: ctx.accountId,
+            storePath: ctx.storePath,
+            conversationId: ctx.groupId,
+            quotedRef: ctx.replyQuotedRef,
+            forceMarkdown: true,
+          });
+          if (!sendResult.ok) {
+            throw new Error(sendResult.error || "Markdown fallback send failed after card failure");
+          }
+        } else {
+          log?.debug?.("[DingTalk] Card failed but no content to fallback with");
+        }
+        return;
+      }
+
+      // Normal finalize.
+      try {
+        await controller.flush();
+        await controller.waitForInFlight();
+        controller.stop();
+        const finalText = controller.getLastAnswerContent()
+          || finalTextForFallback
+          || "✅ Done";
+        log?.info?.(
+          `[DingTalk][Finalize] Calling finishAICard — finalTextLen=${finalText.length} ` +
+          `source=${controller.getLastAnswerContent() ? "lastAnswerContent" : finalTextForFallback ? "finalTextForFallback" : "fallbackDone"} ` +
+          `preview="${finalText.slice(0, 120)}"`,
+        );
+        await finishAICard(card, finalText, log, {
+          quotedRef: ctx.replyQuotedRef,
+        });
+
+        // In group chats, send a lightweight @mention via session webhook
+        // so the sender gets a notification — card API doesn't support @mention.
+        const cardAtSenderText = (ctx.config.cardAtSender || "").trim();
+        if (!ctx.isDirect && ctx.senderId && ctx.sessionWebhook && cardAtSenderText) {
+          try {
+            await sendBySession(ctx.config, ctx.sessionWebhook, cardAtSenderText, {
+              atUserId: ctx.senderId,
+              log,
+            });
+          } catch (atErr: unknown) {
+            const msg = atErr instanceof Error ? atErr.message : String(atErr);
+            log?.debug?.(`[DingTalk] Post-card @mention send failed: ${msg}`);
+          }
+        }
+      } catch (err: unknown) {
+        log?.debug?.(`[DingTalk] AI Card finalization failed: ${(err as Error).message}`);
+        const errObj = err as { response?: { data?: unknown } };
+        if (errObj?.response?.data !== undefined) {
+          log?.debug?.(formatDingTalkErrorPayloadLog("inbound.cardFinalize", errObj.response.data));
+        }
+        if ((card.state as string) !== AICardStatus.FINISHED) {
+          card.state = AICardStatus.FAILED;
+          card.lastUpdated = Date.now();
+        }
+      }
+    },
+
+    async abort(_error: Error): Promise<void> {
+      if (!isCardInTerminalState(card.state)) {
+        controller.stop();
+        await controller.waitForInFlight();
+        try {
+          await finishAICard(card, "❌ 处理失败", log);
+        } catch (cardCloseErr: unknown) {
+          log?.debug?.(`[DingTalk] Failed to finalize card after dispatch error: ${(cardCloseErr as Error).message}`);
+          card.state = AICardStatus.FAILED;
+          card.lastUpdated = Date.now();
+        }
+      }
+    },
+
+    getFinalText(): string | undefined {
+      return controller.getLastAnswerContent() || finalTextForFallback;
+    },
+  };
+}

package/src/reply-strategy-markdown.ts

@@ -0,0 +1,55 @@
+/**
+ * Markdown / text reply strategy.
+ *
+ * Buffers all blocks (disableBlockStreaming=true) and delivers the
+ * final text as a single message via sendMessage.
+ */
+
+import type { DeliverPayload, ReplyOptions, ReplyStrategy, ReplyStrategyContext } from "./reply-strategy";
+import { sendMessage } from "./send-service";
+
+export function createMarkdownReplyStrategy(
+  ctx: ReplyStrategyContext,
+): ReplyStrategy {
+  let finalText: string | undefined;
+
+  return {
+    getReplyOptions(): ReplyOptions {
+      return { disableBlockStreaming: true };
+    },
+
+    async deliver(payload: DeliverPayload): Promise<void> {
+      if (payload.mediaUrls.length > 0) {
+        await ctx.deliverMedia(payload.mediaUrls);
+      }
+
+      if (payload.kind === "final" && typeof payload.text === "string" && payload.text.length > 0) {
+        finalText = payload.text;
+        const sendResult = await sendMessage(ctx.config, ctx.to, payload.text, {
+          sessionWebhook: ctx.sessionWebhook,
+          atUserId: !ctx.isDirect ? ctx.senderId : null,
+          log: ctx.log,
+          accountId: ctx.accountId,
+          storePath: ctx.storePath,
+          conversationId: ctx.groupId,
+          quotedRef: ctx.replyQuotedRef,
+        });
+        if (!sendResult.ok) {
+          throw new Error(sendResult.error || "Reply send failed");
+        }
+      }
+    },
+
+    async finalize(): Promise<void> {
+      // Markdown mode: delivery already happened in deliver(final).
+    },
+
+    async abort(): Promise<void> {
+      // Nothing to clean up.
+    },
+
+    getFinalText(): string | undefined {
+      return finalText;
+    },
+  };
+}

package/src/reply-strategy-with-reaction.ts

@@ -0,0 +1,190 @@
+/**
+ * Dynamic ack-reaction decorator for ReplyStrategy.
+ *
+ * When ackReaction is set to "emoji", wraps an inner strategy to switch
+ * the native ack-reaction emoji based on runtime tool execution events.
+ *
+ * Usage:
+ *   let strategy = createReplyStrategy({ ... });
+ *   if (ackReaction === "emoji" && runtimeEvents) {
+ *     strategy = withDynamicReaction(strategy, { ... });
+ *   }
+ *
+ * This decorator:
+ * - Subscribes to rt.events.onAgentEvent before dispatch
+ * - Maps tool_execution_start events to emoji via resolveToolReactionEmoji
+ * - Recalls the previous reaction and attaches the new one
+ * - Fires a heartbeat reaction if no tool event arrives for 55+ seconds
+ * - On dispose: recalls the current reaction and notifies the caller via
+ *   onReactionDisposed so the finally block does not double-recall
+ * - Cleans up (unsubscribe + clear timer) on finalize/abort
+ *
+ * Important: the subscription MUST filter by runId or sessionKey to avoid
+ * cross-session reaction contamination when multiple messages are processed
+ * concurrently. The `sessionFilter` parameter is required for this reason.
+ */
+
+import type { DeliverPayload, ReplyOptions, ReplyStrategy } from "./reply-strategy";
+import type { DingTalkConfig, Logger } from "./types";
+
+const TOOL_REACTION_SILENCE_MS = 55_000;
+const TOOL_HEARTBEAT_INTERVAL_MS = 60_000;
+const TOOL_HEARTBEAT_REACTION = "⏳";
+
+export interface DynamicReactionParams {
+  config: DingTalkConfig;
+  msgId: string;
+  conversationId?: string;
+  initialReaction: string;
+  /** Only process events matching this predicate (session isolation). */
+  sessionFilter: (event: unknown) => boolean;
+  onAttachReaction: (reactionName: string) => Promise<boolean>;
+  onRecallReaction: (reactionName: string) => Promise<void>;
+  subscribeAgentEvents: (listener: (event: unknown) => void) => () => void;
+  /**
+   * Called when the decorator recalls its current reaction during dispose.
+   * The caller should set ackReactionAttached=false so the finally block
+   * does not attempt to recall the same (already-removed) reaction.
+   */
+  onReactionDisposed?: () => void;
+  log?: Logger;
+}
+
+function resolveToolReactionEmoji(toolName: unknown): string {
+  const name = typeof toolName === "string" ? toolName.trim().toLowerCase() : "";
+  switch (name) {
+    case "bash":
+    case "exec":
+    case "process":
+      return "🛠️";
+    case "read":
+    case "view":
+      return "📂";
+    case "write":
+    case "edit":
+    case "patch":
+      return "✍️";
+    case "web_search":
+    case "search":
+    case "browser.search":
+    case "browser_search":
+      return "🌐";
+    case "fetch":
+    case "open":
+    case "open_url":
+    case "browser.open":
+    case "browser_open":
+      return "🔗";
+    default:
+      return "🛠️";
+  }
+}
+
+export function withDynamicReaction(
+  inner: ReplyStrategy,
+  params: DynamicReactionParams,
+): ReplyStrategy {
+  const { log } = params;
+  let currentReaction = params.initialReaction;
+  let reactionChanged = false;
+  let disposed = false;
+  let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  let lastEventAt = 0;
+  let updateChain: Promise<void> = Promise.resolve();
+
+  const switchReaction = async (nextReaction: string) => {
+    if (disposed || nextReaction === currentReaction) {
+      return;
+    }
+    const prev = currentReaction;
+    await params.onRecallReaction(prev);
+    const ok = await params.onAttachReaction(nextReaction);
+    if (ok) {
+      currentReaction = nextReaction;
+      reactionChanged = true;
+      lastEventAt = Date.now();
+    }
+  };
+
+  const queueSwitch = (nextReaction: string) => {
+    updateChain = updateChain
+      .then(() => switchReaction(nextReaction))
+      .catch((err: unknown) => {
+        log?.warn?.(`[DingTalk] Dynamic reaction update failed: ${(err as Error).message}`);
+      });
+  };
+
+  const handleEvent = (event: unknown) => {
+    if (disposed) {
+      return;
+    }
+    if (!params.sessionFilter(event)) {
+      return;
+    }
+    const toolEvent = event as { stream?: string; data?: { phase?: string; name?: string } };
+    if (toolEvent?.stream !== "tool" || toolEvent?.data?.phase !== "start") {
+      return;
+    }
+    lastEventAt = Date.now();
+    queueSwitch(resolveToolReactionEmoji(toolEvent.data?.name));
+  };
+
+  const unsubscribe = params.subscribeAgentEvents(handleEvent);
+
+  heartbeatTimer = setInterval(() => {
+    if (disposed || lastEventAt === 0) {
+      return;
+    }
+    if (Date.now() - lastEventAt >= TOOL_REACTION_SILENCE_MS) {
+      queueSwitch(TOOL_HEARTBEAT_REACTION);
+    }
+  }, TOOL_HEARTBEAT_INTERVAL_MS);
+
+  const dispose = async () => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    unsubscribe();
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = undefined;
+    }
+    // Wait for any in-flight reaction update to finish.
+    await updateChain.catch(() => undefined);
+    // Recall whatever reaction is currently displayed, then notify the
+    // caller so the finally block does not double-recall.
+    if (reactionChanged) {
+      try {
+        await params.onRecallReaction(currentReaction);
+        params.onReactionDisposed?.();
+      } catch (err: unknown) {
+        log?.warn?.(`[DingTalk] Failed to recall reaction on dispose: ${(err as Error).message}`);
+      }
+    }
+  };
+
+  return {
+    getReplyOptions(): ReplyOptions {
+      return inner.getReplyOptions();
+    },
+
+    async deliver(payload: DeliverPayload): Promise<void> {
+      await inner.deliver(payload);
+    },
+
+    async finalize(): Promise<void> {
+      await dispose();
+      await inner.finalize();
+    },
+
+    async abort(_error: Error): Promise<void> {
+      await dispose();
+      await inner.abort(_error);
+    },
+
+    getFinalText(): string | undefined {
+      return inner.getFinalText();
+    },
+  };
+}