@soimy/dingtalk 3.5.3 → 3.6.0

package/src/inbound-handler.ts

@@ -1,14 +1,17 @@
 import fs from "node:fs";
 import * as path from "node:path";
+import { isAbortRequestText, isBtwRequestText } from "openclaw/plugin-sdk/reply-runtime";
 import axios from "./http-client";
 import { normalizeAllowFrom, isSenderAllowed, resolveGroupAccess } from "./access-control";
 import { buildAgentSessionKey, resolveSubAgentRoute, dispatchSubAgents } from "./targeting/agent-routing";
+import { getAgentDisplayName } from "./targeting/agent-name-matcher";
 import { classifyAckReactionEmoji } from "./ack-reaction-classifier";
 import { attachNativeAckReaction } from "./ack-reaction-service";
 import { createDynamicAckReactionController } from "./ack-reaction/dynamic-ack-reaction-controller";
 import { extractAttachmentText } from "./messaging/attachment-text-extractor";
 import { getAccessToken } from "./auth";
-import { createAICard, finishAICard, isCardInTerminalState } from "./card-service";
+import { createAICard, commitAICardBlocks, isCardInTerminalState } from "./card-service";
+import { renderStatusLine } from "./card/statusline-renderer";
 import { handleInboundCommandDispatch } from "./command/inbound-command-dispatch-service";
 import { resolveAckReactionSetting, resolveGroupConfig, resolveRelativePath, resolveRobotCode } from "./config";
 import { AICardStatus } from "./types";
@@ -30,6 +33,7 @@ import {
   upsertInboundMessageContext,
 } from "./message-context-store";
 import { extractMessageContent } from "./message-utils";
+import { deliverBtwReply, stripLeadingMentions } from "./messaging/btw-deliver";
 import { resolveQuotedRuntimeContext } from "./messaging/quoted-context";
 import {
   buildInboundQuotedRef,
@@ -43,7 +47,7 @@ import {
 } from "./proactive-risk-registry";
 import { downloadGroupFile, getUnionIdByStaffId, resolveQuotedFile } from "./messaging/quoted-file-service";
 import { createReplyStrategy } from "./reply-strategy";
-import type { DeliverPayload } from "./reply-strategy";
+import type { DeliverPayload } from "./reply-strategy-types";
 import { getDingTalkRuntime } from "./runtime";
 import { sendBySession, sendMessage, sendProactiveMedia } from "./send-service";
 import { acquireSessionLock } from "./session-lock";
@@ -53,13 +57,13 @@ import {
   setSessionPeerOverride,
 } from "./session-peer-store";
 import { resolveDingTalkSessionPeer } from "./session-routing";
+import { getSessionState, initSessionState } from "./session-state";
 import {
   upsertObservedGroupTarget,
   upsertObservedUserTarget,
 } from "./targeting/target-directory-store";
 import type { DingTalkConfig, HandleDingTalkMessageParams, Logger, MediaFile } from "./types";
 import { formatDingTalkErrorPayloadLog, getErrorMessage, getErrorResponseData, maskSensitiveData, parseBooleanLike } from "./utils";
-import { isAbortRequestText } from "openclaw/plugin-sdk/reply-runtime";
 import { parseInlineDirectives } from "openclaw/plugin-sdk/text-runtime";
 
 const DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS = 24;
@@ -387,6 +391,8 @@ function buildGroupTurnContextPrompt(params: {
 type ReplyStreamPayload = {
   text?: string;
   isReasoning?: boolean;
+  mediaUrl?: string;
+  mediaUrls?: string[];
 };
 
 type ReplyChunkInfo = {
@@ -534,6 +540,10 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
 
+  // Preserve raw inbound text before any rewriting (e.g., sub-agent context hint)
+  // for use in card quoteContent which should show the user's original message.
+  const rawInboundText = extractedContent.text.trim();
+
   // Add context hint for sub-agent mode, stripping quoted prefix to avoid protocol noise in agent context.
   if (subAgentOptions) {
     const cleanText = extractedContent.text.replace(/^\[引用[^\]]*\]\s*/, "");
@@ -808,21 +818,51 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   if (commandHandled) {
     return;
   }
+
+  const journalTTLDays = dingtalkConfig.journalTTLDays ?? DEFAULT_MESSAGE_CONTEXT_TTL_DAYS;
+  const quotedRef = buildInboundQuotedRef(data, extractedContent);
+  const replyQuotedRef = createReplyQuotedRef(data.msgId);
+  const content = extractedContent;
+  const isBtwBypass = isBtwRequestText(stripLeadingMentions(content.text).trim());
+  const taskInfoConversationId = groupId || to;
+  const sessionTaskState = initSessionState(accountId, taskInfoConversationId);
+  const initialStatusLine = renderStatusLine({
+    model: sessionTaskState.model,
+    effort: sessionTaskState.effort,
+    agent: getAgentDisplayName({
+      subAgentOptions,
+      agentId: route.agentId,
+      agentsList: cfg.agents?.list,
+    }),
+  }, dingtalkConfig) || undefined;
+
   // 3) Select response mode (card vs markdown).
   // Card creation runs BEFORE media download so the user sees immediate visual
   // feedback while large files are still being downloaded.
+  // /btw is gated out here (`!isBtwBypass`) because it must never create a card —
+  // it has its own bypass dispatch later that returns before reaching the main
+  // run. Abort (/stop) is intentionally NOT gated: in card mode the existing
+  // abort branch finalizes the card with the abort confirmation text instead of
+  // sending a separate plain-text message.
   let useCardMode = dingtalkConfig.messageType === "card";
   let currentAICard: import("./types").AICardInstance | undefined;
 
-  if (useCardMode) {
+  if (useCardMode && !isBtwBypass) {
     try {
       log?.debug?.(
         `[DingTalk][AICard] conversationType=${data.conversationType}, conversationId=${to}`,
       );
+      // quoteContent always shows the inbound message text so the user can
+      // identify which of their messages this card is replying to.
+      // Use rawInboundText ( preserved before sub-agent rewriting) to avoid
+      // showing internal routing context like "[你被 @ 为...]" in the card UI.
+      const inboundQuoteText = rawInboundText.slice(0, 200);
       const aiCard = await createAICard(dingtalkConfig, to, log, {
         accountId,
         storePath: accountStorePath,
         contextConversationId: groupId,
+        quoteContent: inboundQuoteText,
+        statusLine: initialStatusLine,
       });
       if (aiCard) {
         currentAICard = aiCard;
@@ -848,11 +888,6 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
     }
   }
-
-  const journalTTLDays = dingtalkConfig.journalTTLDays ?? DEFAULT_MESSAGE_CONTEXT_TTL_DAYS;
-  const quotedRef = buildInboundQuotedRef(data, extractedContent);
-  const replyQuotedRef = createReplyQuotedRef(data.msgId);
-  const content = extractedContent;
   const hasLegacyQuoteContent =
     typeof data.content?.quoteContent === "string" && data.content.quoteContent.trim().length > 0;
 
@@ -1436,7 +1471,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   // "@Agent /stop" are correctly recognised as abort requests in both DM and group
   // chats. In groups DingTalk usually strips @BotName at the protocol level, but
   // in DMs with multi-agent routing the @mention prefix survives all the way here.
-  const textForAbortCheck = inboundText.replace(/^(?:@\S+\s+)*/u, "").trim();
+  const textForAbortCheck = stripLeadingMentions(inboundText).trim();
   if (isAbortRequestText(textForAbortCheck)) {
     log?.info?.(
       `[DingTalk] Abort request detected, bypassing session lock for session=${route.sessionKey}`,
@@ -1488,9 +1523,19 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
     // Finalize the card that was created for this message before the abort check.
     // Without this, the card stays in PROCESSING ("处理中...") indefinitely.
+    // Use V2 finalize (commitAICardBlocks) for consistent state transition.
     if (currentAICard && !isCardInTerminalState(currentAICard.state)) {
       try {
-        await finishAICard(currentAICard, abortConfirmationText ?? "已停止", log);
+        const abortText = abortConfirmationText ?? "已停止";
+        const abortBlockList = [{ type: 0, markdown: abortText }];
+        const blockListJson = JSON.stringify(abortBlockList);
+
+        await commitAICardBlocks(currentAICard, {
+          blockListJson,
+          content: abortText,
+        }, log);
+
+        log?.debug?.(`[DingTalk] Abort card finalized via V2 API: card=${currentAICard.cardInstanceId}`);
       } catch (cardErr) {
         log?.warn?.(`[DingTalk] Abort card finalize failed: ${getErrorMessage(cardErr)}`);
         currentAICard.state = AICardStatus.FAILED;
@@ -1499,6 +1544,61 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
 
+  // ---- Pre-lock BTW: bypass session lock for /btw side questions ----
+  // /btw runs an isolated, tool-less side query in openclaw without polluting
+  // the main run's transcript. The dispatch must NOT acquire the session lock,
+  // otherwise it would queue behind the in-flight main task and lose its "side
+  // question" semantics.
+  //
+  // The `isBtwBypass` flag is computed once early (just after `content` is
+  // resolved, just before `createAICard`). The same constant gates `createAICard` above and
+  // drives this branch — single decision, two consequences. See the comment
+  // at the flag's definition for why /btw uses pre-OCR `content.text` while
+  // abort uses `inboundText`.
+  if (isBtwBypass) {
+    log?.info?.(
+      `[DingTalk] BTW request detected, bypassing session lock for session=${route.sessionKey}`,
+    );
+    // Empty fallback (NOT "Unknown" like the file's main `senderName` variable):
+    // when the nickname is missing we want the blockquote to render as
+    // `> /btw <question>` rather than `> Unknown: /btw <question>`. Read locally
+    // here so the existing `senderName` semantics elsewhere in the file are not
+    // affected.
+    const btwSenderName = data.senderNick || "";
+    try {
+      await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx,
+        cfg,
+        dispatcherOptions: {
+          responsePrefix: "",
+          deliver: async (payload) => {
+            if (!payload.text) {
+              log?.debug?.(`[DingTalk] BTW deliver received non-text payload, skipping`);
+              return;
+            }
+            await deliverBtwReply({
+              config: dingtalkConfig,
+              sessionWebhook,
+              conversationId: groupId,
+              to,
+              senderName: btwSenderName,
+              // Use pre-OCR content.text (consistent with isBtwBypass detection)
+              // so the blockquote shows the user's typed body, not body + OCR.
+              rawQuestion: content.text,
+              replyText: payload.text,
+              log,
+              accountId,
+              storePath: accountStorePath,
+            });
+          },
+        },
+      });
+    } catch (btwErr) {
+      log?.warn?.(`[DingTalk] BTW dispatch failed: ${getErrorMessage(btwErr)}`);
+    }
+    return;
+  }
+
   const ackReaction =
     typeof dingtalkConfig.ackReaction === "string"
       ? dingtalkConfig.ackReaction.trim()
@@ -1784,6 +1884,20 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       legacyCardStreamReasoning === undefined
         ? dingtalkConfig
         : { ...dingtalkConfig, cardStreamReasoning: legacyCardStreamReasoning };
+    const sessionTaskState = getSessionState(accountId, taskInfoConversationId);
+    const taskMeta = {
+      model: sessionTaskState?.model,
+      effort: sessionTaskState?.effort,
+      elapsedMs: typeof sessionTaskState?.taskStartTime === "number"
+        ? Math.max(0, Date.now() - sessionTaskState.taskStartTime)
+        : undefined,
+      agent: getAgentDisplayName({
+        subAgentOptions,
+        agentId: route.agentId,
+        agentsList: cfg.agents?.list,
+      }),
+    };
+
     const strategy = createReplyStrategy({
       config: strategyConfig,
       card: currentAICard,
@@ -1807,6 +1921,8 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       replyQuotedRef,
       deliverMedia: deliverMediaAttachments,
       isStopRequested: isCurrentCardStopRequested,
+      inboundText: rawInboundText,
+      taskMeta,
     });
 
     try {
@@ -1863,19 +1979,26 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         `queuedFinalType=${typeof bufferedFinal}`,
       );
 
-      if (deliveredFinalCount === 0 && typeof bufferedFinal === "string" && bufferedFinal.trim()) {
-        const inlineReplyPayload = parseInlineReplyPayloadText(bufferedFinal);
-        const richBufferedPayload = {
-          text: bufferedFinal,
-          mediaUrls: [],
-        } as ReplyStreamPayload;
-        await strategy.deliver({
-          text: inlineReplyPayload.text,
-          mediaUrls: extractMediaUrls(richBufferedPayload, inlineReplyPayload),
-          audioAsVoice: extractSharedAudioAsVoice(richBufferedPayload, inlineReplyPayload),
-          kind: "final",
-          isReasoning: false,
-        });
+      const bufferedFinalPayload =
+        typeof bufferedFinal === "string"
+          ? ({ text: bufferedFinal } satisfies ReplyStreamPayload)
+          : bufferedFinal && typeof bufferedFinal === "object"
+            ? (bufferedFinal as ReplyStreamPayload)
+            : undefined;
+
+      if (deliveredFinalCount === 0 && bufferedFinalPayload) {
+        const inlineReplyPayload = parseInlineReplyPayloadText(bufferedFinalPayload.text);
+        const mediaUrls = extractMediaUrls(bufferedFinalPayload, inlineReplyPayload);
+        const hasBufferedText = typeof bufferedFinalPayload.text === "string" && bufferedFinalPayload.text.trim().length > 0;
+        if (hasBufferedText || mediaUrls.length > 0) {
+          await strategy.deliver({
+            text: inlineReplyPayload.text,
+            mediaUrls,
+            audioAsVoice: extractSharedAudioAsVoice(bufferedFinalPayload, inlineReplyPayload),
+            kind: "final",
+            isReasoning: bufferedFinalPayload.isReasoning === true,
+          });
+        }
       }
     } catch (dispatchErr: unknown) {
       const error = dispatchErr instanceof Error ? dispatchErr : new Error(getErrorMessage(dispatchErr));

package/src/media-utils.ts

@@ -534,6 +534,12 @@ export function resolveOutboundMediaType(params: {
     return explicitType;
   }
 
+  // Audio files default to "file" (attachment) unless asVoice is explicitly set.
+  // This prevents mp3/wav/ogg/amr from being sent as voice messages unexpectedly.
+  if (detectedType === "voice") {
+    return "file";
+  }
+
   return detectedType;
 }
 

package/src/message-utils.ts

@@ -1,11 +1,18 @@
-import type { AtMention, DingTalkInboundMessage, MessageContent, QuotedInfo, SendMessageOptions } from "./types";
-
+import type {
+  AtMention,
+  DingTalkInboundMessage,
+  MessageContent,
+  QuotedInfo,
+  SendMessageOptions,
+} from "./types";
 
 interface DingTalkDocMeta {
   spaceId: string;
   fileId: string;
 }
 
+const UNKNOWN_PERSON_LABEL = "某人";
+
 function parseBizCustomActionUrl(url: string | undefined): DingTalkDocMeta | null {
   if (!url || typeof url !== "string") {
     return null;
@@ -76,7 +83,7 @@ function extractRichTextQuoteParts(
           ? part.atName
           : typeof textValue === "string"
             ? textValue
-            : "某人";
+            : UNKNOWN_PERSON_LABEL;
       textParts.push(`@${atName}`);
       continue;
     }
@@ -94,7 +101,8 @@ function extractRichTextQuoteParts(
   return {
     summary,
     pictureDownloadCode,
-    pictureDownloadCodes: uniquePictureDownloadCodes.length > 0 ? uniquePictureDownloadCodes : undefined,
+    pictureDownloadCodes:
+      uniquePictureDownloadCodes.length > 0 ? uniquePictureDownloadCodes : undefined,
   };
 }
 
@@ -115,7 +123,101 @@ function trimString(value: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
-function buildQuotedMessageTypePlaceholder(messageType: string | undefined, fileName?: string): string | undefined {
+const MAX_CHAT_RECORD_ENTRIES = 30;
+
+function stringifyChatRecordContentValue(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    return trimString(value);
+  }
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  const content = record.content;
+  const contentText =
+    typeof content === "string"
+      ? trimString(content)
+      : content && typeof content === "object"
+        ? trimString((content as Record<string, unknown>).text as string | undefined)
+        : undefined;
+
+  // Preserve DingTalk's observed chatRecord text priority: explicit text first,
+  // then nested content text, then the legacy message fallback.
+  return (
+    trimString(record.text as string | undefined) ||
+    contentText ||
+    trimString(record.message as string | undefined)
+  );
+}
+
+function getChatRecordEntriesSource(content: Record<string, unknown> | undefined): unknown {
+  return content?.chatRecord ?? content?.records ?? content?.messages;
+}
+
+function formatChatRecordEntries(rawRecord: unknown): string[] {
+  let entries = rawRecord;
+  if (typeof rawRecord === "string") {
+    const trimmed = rawRecord.trim();
+    if (!trimmed || trimmed === "[]") {
+      return [];
+    }
+    try {
+      entries = JSON.parse(trimmed);
+    } catch {
+      return [];
+    }
+  }
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  return entries
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") {
+        return undefined;
+      }
+      const record = entry as Record<string, unknown>;
+      const sender =
+        trimString(record.senderName as string | undefined) ||
+        trimString(record.senderNick as string | undefined) ||
+        trimString(record.sender as string | undefined) ||
+        trimString(record.senderId as string | undefined) ||
+        UNKNOWN_PERSON_LABEL;
+      const body = stringifyChatRecordContentValue(
+        record.content ?? record.text ?? record.message ?? record.body,
+      );
+      return body ? `${sender}: ${body}` : undefined;
+    })
+    .filter((line): line is string => Boolean(line))
+    .slice(0, MAX_CHAT_RECORD_ENTRIES);
+}
+
+function formatChatRecordPreview(
+  content: Record<string, unknown> | undefined,
+  options: { useTitleAsLabel?: boolean } = {},
+): string | undefined {
+  const summary = typeof content?.summary === "string" ? content.summary.trim() : "";
+  const title = typeof content?.title === "string" ? content.title.trim() : "";
+  const rawRecord = getChatRecordEntriesSource(content);
+  const recordLines = formatChatRecordEntries(rawRecord);
+  const parts: string[] = [];
+  if (summary && summary !== "[]") {
+    const label = options.useTitleAsLabel
+      ? title
+        ? `[${title}] `
+        : "[聊天记录] "
+      : "[聊天记录摘要] ";
+    parts.push(`${label}${summary}`);
+  }
+  if (recordLines.length > 0) {
+    parts.push(`[聊天记录内容]\n${recordLines.join("\n")}`);
+  }
+  return parts.join("\n\n") || undefined;
+}
+
+function buildQuotedMessageTypePlaceholder(
+  messageType: string | undefined,
+  fileName?: string,
+): string | undefined {
   switch (messageType) {
     case "text":
       return undefined;
@@ -147,8 +249,7 @@ function buildLegacyQuoteMessagePreview(message: DingTalkInboundMessage["quoteMe
   const previewMessageType = trimString(message?.msgtype);
   return {
     previewText:
-      trimString(message?.text?.content) ||
-      buildQuotedMessageTypePlaceholder(previewMessageType),
+      trimString(message?.text?.content) || buildQuotedMessageTypePlaceholder(previewMessageType),
     previewMessageType,
     previewSenderId: trimString(message?.senderId),
   };
@@ -202,7 +303,10 @@ function buildRepliedMessagePreview(params: {
     return {
       isQuotedFile: true,
       fileCreatedAt: repliedMsg.createdAt,
-      previewText: buildQuotedMessageTypePlaceholder(repliedMsgType, hasFileName ? fileName : undefined),
+      previewText: buildQuotedMessageTypePlaceholder(
+        repliedMsgType,
+        hasFileName ? fileName : undefined,
+      ),
       previewMessageType: repliedMsgType,
       ...(hasFileName ? { previewFileName: fileName } : {}),
       previewSenderId: trimString(repliedMsg.senderId),
@@ -235,11 +339,11 @@ function buildRepliedMessagePreview(params: {
   }
 
   if (repliedMsgType === "chatRecord") {
-    const summary = typeof content?.summary === "string" ? content.summary.trim() : "";
-    const title = typeof content?.title === "string" ? content.title.trim() : "";
-    const chatRecordLabel = title ? `[${title}] ` : "[聊天记录] ";
     return {
-      previewText: summary ? `${chatRecordLabel}${summary}` : buildQuotedMessageTypePlaceholder("chatRecord"),
+      previewText:
+        formatChatRecordPreview(content as Record<string, unknown> | undefined, {
+          useTitleAsLabel: true,
+        }) || buildQuotedMessageTypePlaceholder("chatRecord"),
       previewMessageType: "chatRecord",
       previewSenderId: trimString(repliedMsg.senderId),
     };
@@ -517,7 +621,10 @@ export function extractMessageContent(data: DingTalkInboundMessage): MessageCont
       mediaPath: pictureDownloadCode,
       mediaPaths: uniquePictureDownloadCodes.length > 0 ? uniquePictureDownloadCodes : undefined,
       mediaType: pictureDownloadCode ? "image" : undefined,
-      mediaTypes: uniquePictureDownloadCodes.length > 0 ? uniquePictureDownloadCodes.map(() => "image") : undefined,
+      mediaTypes:
+        uniquePictureDownloadCodes.length > 0
+          ? uniquePictureDownloadCodes.map(() => "image")
+          : undefined,
       messageType: "richText",
       quoted: quoted ?? undefined,
       atMentions,
@@ -605,7 +712,8 @@ export function extractMessageContent(data: DingTalkInboundMessage): MessageCont
   if (msgtype === "chatRecord") {
     const content = data.content as Record<string, unknown> | undefined;
     const summary = typeof content?.summary === "string" ? content.summary.trim() : "";
-    const rawRecord = content?.chatRecord;
+    const rawRecord = getChatRecordEntriesSource(content);
+    const chatRecordText = formatChatRecordPreview(content);
     if (
       summary === "[]" ||
       (typeof rawRecord === "string" && rawRecord.trim() === "[]") ||
@@ -619,9 +727,9 @@ export function extractMessageContent(data: DingTalkInboundMessage): MessageCont
         atUserDingtalkIds,
       };
     }
-    if (summary) {
+    if (chatRecordText) {
       return {
-        text: `[聊天记录摘要] ${summary}`,
+        text: chatRecordText,
         messageType: "chatRecord",
         quoted: quoted ?? undefined,
         atMentions,

package/src/messaging/btw-deliver.ts

@@ -0,0 +1,85 @@
+import { sendMessage } from "../send-service";
+import type { DingTalkConfig, Logger } from "../types";
+
+const MAX_QUESTION_LENGTH = 80;
+const LEADING_MENTIONS_RE = /^(?:@\S+\s+)*/u;
+
+/**
+ * Strip leading `@mention` tokens from inbound text. Used by both the abort and
+ * BTW bypass branches in `inbound-handler.ts` so that command detection works
+ * uniformly in DM and group chats.
+ */
+export function stripLeadingMentions(text: string): string {
+  return text.replace(LEADING_MENTIONS_RE, "");
+}
+
+export function buildBtwBlockquote(senderName: string, rawQuestion: string): string {
+  const stripped = stripLeadingMentions(rawQuestion);
+  // Iterate by Unicode code points (not UTF-16 code units) so emoji /
+  // surrogate pairs aren't sliced in half at the truncation boundary.
+  const codePoints = Array.from(stripped);
+  const truncated =
+    codePoints.length > MAX_QUESTION_LENGTH
+      ? `${codePoints.slice(0, MAX_QUESTION_LENGTH).join("")}…`
+      : stripped;
+  const senderPrefix = senderName ? `${senderName}: ` : "";
+  return `> ${senderPrefix}${truncated}\n\n`;
+}
+
+export interface DeliverBtwReplyArgs {
+  config: DingTalkConfig;
+  sessionWebhook: string | undefined;
+  conversationId: string;
+  to: string;
+  senderName: string;
+  rawQuestion: string;
+  replyText: string;
+  log: Logger | undefined;
+  accountId?: string;
+  storePath?: string;
+}
+
+/**
+ * Deliver a BTW reply through the unified `sendMessage` entry point.
+ *
+ * BTW is a special inbound trigger, but the *outbound* reply is still a regular
+ * markdown/text message and must inherit the standard send-service semantics:
+ * persistence into the message context store, delivery metadata tracking, and
+ * the single `{ ok, error, ... }` contract. We pass `forceMarkdown: true` so
+ * that `sendMessage` skips the card branch even when the channel is configured
+ * for card mode — BTW must never create or touch an AI Card (see CLAUDE.md
+ * anti-pattern: "Do not create multiple active AI Cards for the same
+ * `accountId:conversationId`").
+ *
+ * When `sessionWebhook` is present `sendMessage` internally dispatches via
+ * `sendBySession`; otherwise it falls back to the proactive text/markdown API.
+ * Either way the caller sees the same return shape, and failures propagate as
+ * `{ ok: false }` instead of being silently swallowed.
+ */
+export async function deliverBtwReply(
+  args: DeliverBtwReplyArgs,
+): Promise<{ ok: boolean; error?: string }> {
+  const blockquote = buildBtwBlockquote(args.senderName, args.rawQuestion);
+  const fullText = `${blockquote}${args.replyText}`;
+
+  try {
+    const result = await sendMessage(args.config, args.to, fullText, {
+      log: args.log,
+      accountId: args.accountId,
+      storePath: args.storePath,
+      conversationId: args.conversationId,
+      sessionWebhook: args.sessionWebhook,
+      forceMarkdown: true,
+    });
+    if (!result.ok) {
+      args.log?.warn?.(
+        `[DingTalk] BTW reply delivery returned not-ok: ${result.error ?? "unknown"}`,
+      );
+    }
+    return { ok: result.ok, error: result.error };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    args.log?.warn?.(`[DingTalk] BTW reply delivery threw: ${error}`);
+    return { ok: false, error };
+  }
+}