@soimy/dingtalk 3.3.0 → 3.4.1

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();
+    },
+  };
+}

package/src/reply-strategy.ts

@@ -0,0 +1,72 @@
+/**
+ * Reply strategy interface for DingTalk message delivery.
+ *
+ * Abstracts the "how to deliver a reply" concern away from
+ * handleDingTalkMessage, so card and markdown modes each manage
+ * their own state and lifecycle independently.
+ */
+
+import type { AICardInstance, DingTalkConfig, Logger, QuotedRef } from "./types";
+import { createCardReplyStrategy } from "./reply-strategy-card";
+import { createMarkdownReplyStrategy } from "./reply-strategy-markdown";
+
+// ---- Public types ------------------------------------------------
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrls: string[];
+  kind: "block" | "final" | "tool";
+}
+
+export interface ReplyOptions {
+  disableBlockStreaming: boolean;
+  onPartialReply?: (payload: { text?: string }) => void;
+  onReasoningStream?: (payload: { text?: string }) => void;
+  onAssistantMessageStart?: () => void;
+}
+
+export interface ReplyStrategy {
+  /** Options forwarded to the runtime dispatcher. */
+  getReplyOptions(): ReplyOptions;
+
+  /** Called by the deliver callback for each payload chunk. */
+  deliver(payload: DeliverPayload): Promise<void>;
+
+  /** Called after dispatch completes successfully. */
+  finalize(): Promise<void>;
+
+  /** Called when dispatch throws an error. */
+  abort(error: Error): Promise<void>;
+
+  /** Last known final text (for external consumers such as logging). */
+  getFinalText(): string | undefined;
+}
+
+/** Shared context passed to every strategy implementation. */
+export interface ReplyStrategyContext {
+  config: DingTalkConfig;
+  to: string;
+  sessionWebhook: string;
+  senderId: string;
+  isDirect: boolean;
+  accountId: string;
+  storePath: string;
+  groupId?: string;
+  log?: Logger;
+  replyQuotedRef?: QuotedRef;
+  deliverMedia: (urls: string[]) => Promise<void>;
+}
+
+// ---- Factory -----------------------------------------------------
+
+export function createReplyStrategy(
+  params: ReplyStrategyContext & {
+    card: AICardInstance | undefined;
+    useCardMode: boolean;
+  },
+): ReplyStrategy {
+  if (params.useCardMode && params.card) {
+    return createCardReplyStrategy({ ...params, card: params.card });
+  }
+  return createMarkdownReplyStrategy(params);
+}

package/src/runtime.ts

@@ -1,14 +1,12 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 
-let runtime: PluginRuntime | null = null;
+const runtimeStore = createPluginRuntimeStore<PluginRuntime>("DingTalk runtime not initialized");
 
 export function setDingTalkRuntime(next: PluginRuntime): void {
-  runtime = next;
+  runtimeStore.setRuntime(next);
 }
 
 export function getDingTalkRuntime(): PluginRuntime {
-  if (!runtime) {
-    throw new Error("DingTalk runtime not initialized");
-  }
-  return runtime;
+  return runtimeStore.getRuntime();
 }