@qwen-code/channel-dingtalk 0.23.1-preview.1 → 0.23.1

package/dist/DingtalkAdapter.js

@@ -13,6 +13,7 @@ import { DingtalkConnectionManager, } from './DingtalkConnectionManager.js';
 import { DingtalkCardRequestError, DingtalkInteractiveCardClient, } from './interactive-card-client.js';
 import { parseDingtalkCardActorId, parseDingtalkCardCallback, parseDingtalkInteractiveCardConfig, } from './interactive-card-types.js';
 import { StatusCardController } from './status-card-controller.js';
+import { isChinesePresentationLanguage, lifecyclePresentationPhase, presentationPhaseLabel, } from './presentation-phase.js';
 import { QuestionCardController } from './question-card-controller.js';
 import { DingtalkInteractionPresenter } from './interaction-presenter.js';
 function nonEmptyString(value) {
@@ -408,12 +409,27 @@ function formatChatRecord(content, budget = MAX_CHAT_RECORD_CHARS) {
 }
 /** Track seen msgIds to deduplicate retried callbacks. */
 const DEDUP_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const BACKGROUND_RESPONSE_AGGREGATION_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * A failed aggregation delivery is retried rather than dropped: aggregating
+ * concentrates a whole turn into one send, and the burst that makes a send
+ * fail (several agents finishing at once against one chat quota) is exactly
+ * when the whole result would be lost.
+ */
+const BACKGROUND_RESPONSE_AGGREGATION_RETRY_MS = 30 * 1000;
+const BACKGROUND_RESPONSE_AGGREGATION_MAX_RETRIES = 3;
 const ACK_REACTION_NAME = '👀';
 const ACK_EMOTION_ID = '2659900';
 const ACK_EMOTION_BG_ID = 'im_bg_1';
+const STATUS_EMOTION_ID = '34019';
+const STATUS_EMOTION_BG_ID = 'im_bg_6';
+const DONE_EMOTION_ID = '54054';
+const DONE_EMOTION_BG_ID = 'im_bg_5';
 const EMOTION_API = 'https://api.dingtalk.com/v1.0/robot/emotion';
 const EMOTION_MAX_ATTEMPTS = 3;
 const EMOTION_RETRY_BASE_DELAY_MS = 250;
+const EMOTION_FETCH_TIMEOUT_MS = 15_000;
+const EMOTION_FINISH_MAX_ATTEMPTS = 3;
 const GROUP_MSG_API = 'https://api.dingtalk.com/v1.0/robot/groupMessages/send';
 const DIRECT_MSG_API = 'https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend';
 const PROACTIVE_MSG_KEY = 'sampleMarkdown'; // DingTalk's built-in {title, text} markdown template key
@@ -553,6 +569,25 @@ const FILE_INSTRUCTIONS = [
     'File paths containing ] are not supported.',
     'Do not claim delivery succeeded; DingTalk shows successful files separately and reports failures in the final text.',
 ].join('\n');
+function statusEmotionTag(name) {
+    return {
+        name,
+        emotionId: STATUS_EMOTION_ID,
+        backgroundId: STATUS_EMOTION_BG_ID,
+    };
+}
+const EYE_TAG = {
+    name: ACK_REACTION_NAME,
+    emotionId: ACK_EMOTION_ID,
+    backgroundId: ACK_EMOTION_BG_ID,
+};
+const DONE_TAG = {
+    name: '✅ Done',
+    emotionId: DONE_EMOTION_ID,
+    backgroundId: DONE_EMOTION_BG_ID,
+};
+const FAILED_TAG = statusEmotionTag('❌ Failed');
+const STOPPED_TAG = statusEmotionTag('⏹️ Stopped');
 function collectNonBotMentionIds(data) {
     if (!Array.isArray(data.atUsers) || typeof data.chatbotUserId !== 'string') {
         return [];
@@ -595,9 +630,28 @@ async function withConnectLoggingSuppressed(connect) {
         }
     }
 }
+class ProactiveTextDeliveryError extends Error {
+    plan;
+    retryable;
+    constructor(plan, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.plan = plan;
+        if (cause instanceof DingtalkCardRequestError) {
+            this.retryable = cause.retryable;
+        }
+    }
+}
+class ReplyTextDeliveryError extends Error {
+    plan;
+    constructor(plan, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.plan = plan;
+    }
+}
 export class DingtalkChannel extends ChannelBase {
     client;
     atSender;
+    displayLanguage;
     connectionManager;
     seenMessages = new Map();
     mentionTargets = new Map();
@@ -608,8 +662,11 @@ export class DingtalkChannel extends ChannelBase {
     /** Map conversationId → latest sessionWebhook URL for sending replies. */
     webhooks = new Map();
     activeReactionKeys = new Set();
+    reactionStates = new Map();
     /** sessionId → reaction keys, so a dead session's reactions can be recalled. */
     sessionReactionKeys = new Map();
+    /** Settles when the reaction cleanup queued by disconnect() has run. */
+    disconnectDrain;
     /**
      * Real inbound message ids (insertion-ordered, size-capped). Unlike the
      * TTL-swept seenMessages dedup map, entries survive long queue waits, so a
@@ -622,6 +679,7 @@ export class DingtalkChannel extends ChannelBase {
      */
     proactiveToken;
     interactiveCardConfig;
+    aggregateBackgroundAgentResponses;
     interactiveCardClient;
     statusCardController;
     questionCardController;
@@ -641,10 +699,15 @@ export class DingtalkChannel extends ChannelBase {
     // must be dropped, because recreating state would post the tail of a
     // force-split [FILE: ...] marker verbatim.
     blockProjectionArmed = new Set();
+    backgroundResponseAggregations = new Map();
+    detachedBackgroundResponseAggregations = new Set();
+    pendingBackgroundResponseTerminals = new Map();
+    detachedPendingBackgroundResponseTerminals = new Set();
     constructor(name, config, bridge, options) {
         super(name, config, bridge, options);
         this.atSender =
             config['atSender'] === true;
+        this.displayLanguage = options?.displayLanguage;
         if (!this.config.instructions) {
             this.config.instructions = [
                 '## DingTalk Channel',
@@ -661,6 +724,13 @@ export class DingtalkChannel extends ChannelBase {
             this.config.instructions += FILE_INSTRUCTIONS;
         }
         this.interactiveCardConfig = parseDingtalkInteractiveCardConfig(config.interactiveCards);
+        const rawAggregateBackgroundAgentResponses = config.aggregateBackgroundAgentResponses;
+        if (rawAggregateBackgroundAgentResponses !== undefined &&
+            typeof rawAggregateBackgroundAgentResponses !== 'boolean') {
+            throw new Error(`Channel "${name}" aggregateBackgroundAgentResponses must be a boolean.`);
+        }
+        this.aggregateBackgroundAgentResponses =
+            rawAggregateBackgroundAgentResponses === true;
         if (!config.clientId || !config.clientSecret) {
             throw new Error(`Channel "${name}" requires clientId and clientSecret for DingTalk.`);
         }
@@ -688,6 +758,9 @@ export class DingtalkChannel extends ChannelBase {
                     client: this.interactiveCardClient,
                     cancelRun: (sessionId, runId) => this.requestPromptRunCancellation(sessionId, runId),
                     ...(config.model ? { model: config.model } : {}),
+                    ...(options?.displayLanguage
+                        ? { language: options.displayLanguage }
+                        : {}),
                     onError: (operation, error) => {
                         process.stderr.write(`[DingTalk:${this.name}] ${operation} failed: ${sanitizeLogText(String(error), 300)}\n`);
                     },
@@ -708,6 +781,9 @@ export class DingtalkChannel extends ChannelBase {
                 this.interactionPresenter = new DingtalkInteractionPresenter({
                     statusCards: this.statusCardController,
                     questionCards: this.questionCardController,
+                    ...(options?.displayLanguage
+                        ? { language: options.displayLanguage }
+                        : {}),
                     ...(config.blockStreaming !== 'on'
                         ? {
                             sendFallback: (chatId, text, sessionId, sourceLabel) => this.sendFallbackReply(chatId, text, sessionId, sourceLabel),
@@ -1078,11 +1154,14 @@ export class DingtalkChannel extends ChannelBase {
         }
         return replaceImageMarkers(text, markers, replacements);
     }
-    async sendReply(chatId, text, atUserId, sourceLabel, prepared = false) {
+    async sendReply(chatId, text, atUserId, sourceLabel, prepared = false, failOnHttpError = false) {
         // chatId is a conversationId — resolve to the latest sessionWebhook.
         const webhook = this.webhooks.get(chatId);
         if (!webhook) {
             process.stderr.write(`[DingTalk:${this.name}] No webhook for chatId ${chatId}, cannot send.\n`);
+            if (failOnHttpError) {
+                throw new Error('DingTalk session webhook unavailable');
+            }
             return;
         }
         const outgoingText = prepared
@@ -1090,6 +1169,15 @@ export class DingtalkChannel extends ChannelBase {
             : await this.prepareReplyOutput(chatId, text);
         if (!outgoingText.trim())
             return;
+        const plan = this.createReplyTextDelivery(outgoingText, atUserId, sourceLabel);
+        try {
+            await this.deliverReplyText(chatId, plan, failOnHttpError);
+        }
+        catch (error) {
+            throw new ReplyTextDeliveryError(plan, error);
+        }
+    }
+    createReplyTextDelivery(outgoingText, atUserId, sourceLabel) {
         const mentionPrefix = atUserId ? `@${atUserId}\n\n` : '';
         const sourcePrefix = sourceLabel && outgoingText.trim().length > 0
             ? `${escapeDingTalkMarkdown(sourceLabel)}\n\n`
@@ -1099,17 +1187,32 @@ export class DingtalkChannel extends ChannelBase {
             throw new Error('DingTalk source label exceeds the message limit.');
         }
         const chunks = normalizeDingTalkMarkdown(outgoingText, contentLimit).map((chunk, index) => `${index === 0 ? mentionPrefix : ''}${sourcePrefix}${chunk}`);
-        const title = extractTitle(outgoingText);
-        for (let i = 0; i < chunks.length; i++) {
-            const chunk = chunks[i];
-            const isMention = i === 0 && atUserId !== undefined;
+        return {
+            title: extractTitle(outgoingText),
+            chunks,
+            nextChunk: 0,
+            ...(atUserId ? { atUserId } : {}),
+        };
+    }
+    async deliverReplyText(chatId, plan, failOnHttpError = false) {
+        const webhook = this.webhooks.get(chatId);
+        if (!webhook) {
+            if (failOnHttpError) {
+                throw new Error('DingTalk session webhook unavailable');
+            }
+            return;
+        }
+        while (plan.nextChunk < plan.chunks.length) {
+            const index = plan.nextChunk;
+            const chunk = plan.chunks[index];
+            const isMention = index === 0 && plan.atUserId !== undefined;
             const body = {
                 msgtype: 'markdown',
                 markdown: {
-                    title: i === 0 ? title : `${title} (cont.)`,
+                    title: index === 0 ? plan.title : `${plan.title} (cont.)`,
                     text: chunk,
                 },
-                ...(isMention ? { at: { atUserIds: [atUserId] } } : {}),
+                ...(isMention ? { at: { atUserIds: [plan.atUserId] } } : {}),
             };
             let resp;
             try {
@@ -1141,7 +1244,26 @@ export class DingtalkChannel extends ChannelBase {
             if (!resp.ok) {
                 const detail = await resp.text().catch(() => '');
                 process.stderr.write(`[DingTalk:${this.name}] sendMessage failed: HTTP ${resp.status} ${detail}\n`);
+                if (failOnHttpError) {
+                    throw new Error(`DingTalk reply send failed: HTTP ${resp.status} ${detail}`);
+                }
             }
+            else if (failOnHttpError) {
+                const payload = (await resp
+                    .clone()
+                    .json()
+                    .catch(() => undefined));
+                const response = payload && typeof payload === 'object'
+                    ? payload
+                    : undefined;
+                const value = response?.['errcode'] ?? response?.['code'];
+                if (value !== undefined && String(value) !== '0') {
+                    const detail = sanitizeLogText(String(response?.['errmsg'] ?? response?.['message'] ?? value), 300);
+                    process.stderr.write(`[DingTalk:${this.name}] sendMessage failed: ${detail}\n`);
+                    throw new Error(`DingTalk reply send failed: ${detail}`);
+                }
+            }
+            plan.nextChunk++;
         }
     }
     async sendMessage(chatId, text) {
@@ -1177,9 +1299,20 @@ export class DingtalkChannel extends ChannelBase {
     async pushProactive(target, text, sourceLabel) {
         if (!text.trim())
             return;
+        const plan = await this.createProactiveTextDelivery(target, text, sourceLabel);
+        if (!plan)
+            return;
+        try {
+            await this.deliverProactiveText(target, plan);
+        }
+        catch (error) {
+            throw new ProactiveTextDeliveryError(plan, error);
+        }
+    }
+    async createProactiveTextDelivery(target, text, sourceLabel) {
         const outgoingText = await this.prepareFileOutput(text, (file, mediaId) => this.sendProactiveFile(target, file, mediaId));
         if (!outgoingText.trim())
-            return;
+            return undefined;
         const sourcePrefix = sourceLabel
             ? `${escapeDingTalkMarkdown(sourceLabel)}\n\n`
             : '';
@@ -1188,9 +1321,13 @@ export class DingtalkChannel extends ChannelBase {
             throw new Error('DingTalk source label exceeds the message limit.');
         }
         const chunks = normalizeDingTalkMarkdown(outgoingText, contentLimit).map((chunk) => `${sourcePrefix}${chunk}`);
-        const title = extractTitle(outgoingText);
-        for (let i = 0; i < chunks.length; i++) {
-            await this.sendProactiveChunk(target, i === 0 ? title : `${title} (cont.)`, chunks[i], `chunk ${i + 1}/${chunks.length}`);
+        return { title: extractTitle(outgoingText), chunks, nextChunk: 0 };
+    }
+    async deliverProactiveText(target, plan) {
+        while (plan.nextChunk < plan.chunks.length) {
+            const index = plan.nextChunk;
+            await this.sendProactiveChunk(target, index === 0 ? plan.title : `${plan.title} (cont.)`, plan.chunks[index], `chunk ${index + 1}/${plan.chunks.length}`);
+            plan.nextChunk++;
         }
     }
     async getProactiveToken() {
@@ -1339,16 +1476,16 @@ export class DingtalkChannel extends ChannelBase {
     getAccessToken() {
         return this.client.getConfig().access_token;
     }
-    async emotionApi(endpoint, msgId, conversationId) {
+    async emotionApi(endpoint, msgId, conversationId, tag) {
         const robotCode = this.config.clientId;
         if (!robotCode || !msgId || !conversationId)
-            return;
+            return false;
         try {
             const token = this.config.clientSecret
                 ? await this.getProactiveToken()
                 : this.getAccessToken();
             if (!token)
-                return;
+                return false;
             for (let attempt = 0; attempt < EMOTION_MAX_ATTEMPTS; attempt++) {
                 const resp = await fetch(`${EMOTION_API}/${endpoint}`, {
                     method: 'POST',
@@ -1361,17 +1498,18 @@ export class DingtalkChannel extends ChannelBase {
                         openMsgId: msgId,
                         openConversationId: conversationId,
                         emotionType: 2,
-                        emotionName: ACK_REACTION_NAME,
+                        emotionName: tag.name,
                         textEmotion: {
-                            emotionId: ACK_EMOTION_ID,
-                            emotionName: ACK_REACTION_NAME,
-                            text: ACK_REACTION_NAME,
-                            backgroundId: ACK_EMOTION_BG_ID,
+                            emotionId: tag.emotionId,
+                            emotionName: tag.name,
+                            text: tag.name,
+                            backgroundId: tag.backgroundId,
                         },
                     }),
+                    signal: AbortSignal.timeout(EMOTION_FETCH_TIMEOUT_MS),
                 });
                 if (resp.ok)
-                    return;
+                    return true;
                 const isTransient = resp.status === 429 || resp.status >= 500;
                 if (isTransient && attempt < EMOTION_MAX_ATTEMPTS - 1) {
                     await resp.body?.cancel();
@@ -1380,26 +1518,33 @@ export class DingtalkChannel extends ChannelBase {
                 }
                 const detail = sanitizeLogText(await resp.text().catch(() => ''), 500);
                 process.stderr.write(`[DingTalk:${this.name}] emotion/${endpoint} failed after ${attempt + 1}/${EMOTION_MAX_ATTEMPTS} attempts: ${resp.status} ${detail}\n`);
-                return;
+                return false;
             }
         }
         catch {
             // best-effort, don't break message flow
         }
+        return false;
     }
-    async attachReaction(msgId, conversationId) {
-        await this.emotionApi('reply', msgId, conversationId);
+    async attachReaction(msgId, conversationId, tag = EYE_TAG) {
+        return this.emotionApi('reply', msgId, conversationId, tag);
     }
-    async recallReaction(msgId, conversationId) {
-        await this.emotionApi('recall', msgId, conversationId);
+    async recallReaction(msgId, conversationId, tag = EYE_TAG) {
+        return this.emotionApi('recall', msgId, conversationId, tag);
     }
     disconnect() {
         if (this.dedupTimer) {
             clearInterval(this.dedupTimer);
         }
+        const reactionStates = [...this.reactionStates.values()];
+        for (const state of reactionStates) {
+            this.finishReaction(state.chatId, state.messageId, state.sessionId);
+        }
         this.statusCardController?.dispose();
+        this.drainBackgroundResponseAggregations();
         this.activeReactionKeys.clear();
         this.sessionReactionKeys.clear();
+        this.reactionStates.clear();
         if (this.connectionManager) {
             this.connectionManager.stop();
         }
@@ -1407,6 +1552,10 @@ export class DingtalkChannel extends ChannelBase {
             this.client.disconnect();
         }
         process.stderr.write(`[DingTalk:${this.name}] Disconnected.\n`);
+        this.disconnectDrain = Promise.allSettled(reactionStates.map((state) => state.tail)).then(() => undefined);
+    }
+    waitForDisconnect() {
+        return this.disconnectDrain ?? Promise.resolve();
     }
     /** Stable API targets are conversation or user IDs, never webhook URLs. */
     isStableTargetId(chatId) {
@@ -1415,6 +1564,133 @@ export class DingtalkChannel extends ChannelBase {
     reactionKey(messageId, conversationId) {
         return `${conversationId}:${messageId}`;
     }
+    forgetReactionState(state) {
+        this.activeReactionKeys.delete(state.key);
+        if (this.reactionStates.get(state.key) === state) {
+            this.reactionStates.delete(state.key);
+        }
+        if (!state.sessionId)
+            return;
+        const keys = this.sessionReactionKeys.get(state.sessionId);
+        keys?.delete(state.key);
+        if (keys?.size === 0)
+            this.sessionReactionKeys.delete(state.sessionId);
+    }
+    enqueueReaction(state, operation) {
+        state.tail = state.tail.then(operation).catch((err) => {
+            this.logReactionFailure('lifecycle tag update', err);
+        });
+    }
+    scheduleReactionDrain(state) {
+        if (state.drainScheduled)
+            return;
+        state.drainScheduled = true;
+        this.enqueueReaction(state, async () => {
+            try {
+                await this.drainReactionState(state);
+            }
+            finally {
+                state.drainScheduled = false;
+                if (this.reactionStates.get(state.key) === state &&
+                    (state.finishing
+                        ? !state.finishBlocked
+                        : this.activeReactionKeys.has(state.key) &&
+                            state.desiredStatusTag &&
+                            state.desiredStatusTag.name !== state.statusTag?.name)) {
+                    this.scheduleReactionDrain(state);
+                }
+            }
+        });
+    }
+    async drainReactionState(state) {
+        while (true) {
+            if (state.finishing) {
+                await this.finishReactionState(state);
+                return;
+            }
+            if (this.reactionStates.get(state.key) !== state ||
+                !this.activeReactionKeys.has(state.key)) {
+                return;
+            }
+            const desired = state.desiredStatusTag;
+            if (!desired || desired.name === state.statusTag?.name)
+                return;
+            const latched = state.failedTransition;
+            if (state.statusTag) {
+                const from = state.statusTag.name;
+                if (latched && latched.from === from && latched.to === desired.name) {
+                    // This exact replacement already failed; re-issuing it once per
+                    // lifecycle event hammers a failing emotion API on every streamed
+                    // chunk. A different desired tag retries the recall.
+                    state.desiredStatusTag = state.statusTag;
+                    return;
+                }
+                const revision = state.revision;
+                if ((await this.recallReaction(state.messageId, state.chatId, state.statusTag)) === false) {
+                    state.failedTransition = { from, to: desired.name };
+                    if (state.revision !== revision)
+                        continue;
+                    state.desiredStatusTag = state.statusTag;
+                    return;
+                }
+                state.failedTransition = undefined;
+                state.statusTag = undefined;
+                continue;
+            }
+            if (latched &&
+                latched.from === undefined &&
+                latched.to === desired.name) {
+                state.desiredStatusTag = undefined;
+                return;
+            }
+            const revision = state.revision;
+            if ((await this.attachReaction(state.messageId, state.chatId, desired)) ===
+                false) {
+                state.failedTransition = { from: undefined, to: desired.name };
+                if (state.revision !== revision)
+                    continue;
+                state.desiredStatusTag = undefined;
+                return;
+            }
+            state.failedTransition = undefined;
+            state.statusTag = desired;
+        }
+    }
+    async finishReactionState(state) {
+        let statusCleared = true;
+        if (state.statusTag) {
+            statusCleared =
+                (await this.recallReaction(state.messageId, state.chatId, state.statusTag)) !== false;
+            if (statusCleared)
+                state.statusTag = undefined;
+        }
+        const eyeCleared = !state.eyeAttached ||
+            (await this.recallReaction(state.messageId, state.chatId, EYE_TAG)) !==
+                false;
+        if (eyeCleared)
+            state.eyeAttached = false;
+        let terminalAttached = true;
+        if (state.terminalTag && statusCleared && eyeCleared) {
+            terminalAttached =
+                (await this.attachReaction(state.messageId, state.chatId, state.terminalTag)) !== false;
+        }
+        if (!statusCleared || !eyeCleared || !terminalAttached) {
+            // Keep the state registered: forgetting it here would leave a stale
+            // phase tag nothing can ever recall. finishReaction re-arms the drain
+            // (disconnect, session death) so the cleanup gets a second chance.
+            state.finishAttempts = (state.finishAttempts ?? 0) + 1;
+            if (state.finishAttempts >= EMOTION_FINISH_MAX_ATTEMPTS) {
+                // A permanently failing emotion API (robot removed, expired token)
+                // would otherwise hold the entry for the process lifetime.
+                this.logReactionFailure('reaction cleanup', `abandoned after ${state.finishAttempts} attempts`);
+                this.forgetReactionState(state);
+                return;
+            }
+            state.finishBlocked = true;
+            return;
+        }
+        this.forgetReactionState(state);
+    }
     rememberInboundMessageId(msgId) {
         this.inboundMessageIds.delete(msgId);
         this.inboundMessageIds.add(msgId);
@@ -1439,6 +1715,19 @@ export class DingtalkChannel extends ChannelBase {
         if (this.activeReactionKeys.has(key))
             return;
         this.activeReactionKeys.add(key);
+        const state = {
+            key,
+            messageId,
+            chatId,
+            ...(sessionId ? { sessionId } : {}),
+            desiredStatusTag: this.phaseReactionTag('thinking'),
+            finishing: false,
+            drainScheduled: false,
+            eyeAttached: false,
+            revision: 0,
+            tail: Promise.resolve(),
+        };
+        this.reactionStates.set(key, state);
         if (sessionId) {
             let keys = this.sessionReactionKeys.get(sessionId);
             if (!keys) {
@@ -1447,36 +1736,75 @@ export class DingtalkChannel extends ChannelBase {
             }
             keys.set(key, { messageId, chatId });
         }
-        this.attachReaction(messageId, chatId)
-            .then(() => {
-            if (!this.activeReactionKeys.has(key)) {
-                void this.recallReaction(messageId, chatId).catch((err) => {
-                    this.logReactionFailure('late reaction recall', err);
-                });
+        this.enqueueReaction(state, async () => {
+            try {
+                if ((await this.attachReaction(messageId, chatId, EYE_TAG)) === false) {
+                    this.forgetReactionState(state);
+                    return;
+                }
+                state.eyeAttached = true;
+                this.scheduleReactionDrain(state);
+            }
+            catch (err) {
+                this.forgetReactionState(state);
+                this.logReactionFailure('reaction attach', err);
             }
-        })
-            .catch((err) => {
-            this.activeReactionKeys.delete(key);
-            this.logReactionFailure('reaction attach', err);
         });
     }
-    stopReaction(chatId, messageId, sessionId) {
+    replaceStatusReaction(chatId, messageId, tag) {
+        if (!messageId)
+            return;
+        const state = this.reactionStates.get(this.reactionKey(messageId, chatId));
+        if (!state || !this.activeReactionKeys.has(state.key))
+            return;
+        state.desiredStatusTag = tag;
+        state.revision++;
+        this.scheduleReactionDrain(state);
+    }
+    phaseReactionTag(phase) {
+        return statusEmotionTag(presentationPhaseLabel(phase, this.displayLanguage));
+    }
+    terminalReactionTag(type) {
+        if (!isChinesePresentationLanguage(this.displayLanguage)) {
+            return type === 'completed'
+                ? DONE_TAG
+                : type === 'failed'
+                    ? FAILED_TAG
+                    : STOPPED_TAG;
+        }
+        if (type === 'completed') {
+            return { ...DONE_TAG, name: '✅ 已完成' };
+        }
+        return statusEmotionTag(type === 'failed' ? '❌ 失败' : '⏹️ 已停止');
+    }
+    finishReaction(chatId, messageId, sessionId, terminalTag) {
         if (!messageId || !this.isStableTargetId(chatId))
             return;
         const key = this.reactionKey(messageId, chatId);
-        if (sessionId) {
-            const keys = this.sessionReactionKeys.get(sessionId);
-            if (keys) {
-                keys.delete(key);
-                if (keys.size === 0)
-                    this.sessionReactionKeys.delete(sessionId);
-            }
+        const state = this.reactionStates.get(key);
+        if (!state)
+            return;
+        if (state.finishing) {
+            // A finish is either draining or blocked on a failed recall; only the
+            // blocked case needs this trigger to retry the cleanup.
+            if (!state.finishBlocked)
+                return;
+            state.finishBlocked = false;
+            if (terminalTag)
+                state.terminalTag = terminalTag;
+            this.scheduleReactionDrain(state);
+            return;
         }
         if (!this.activeReactionKeys.delete(key))
             return;
-        this.recallReaction(messageId, chatId).catch((err) => {
-            this.logReactionFailure('reaction recall', err);
-        });
+        state.finishing = true;
+        state.desiredStatusTag = undefined;
+        state.terminalTag = terminalTag;
+        state.revision++;
+        this.scheduleReactionDrain(state);
+    }
+    stopReaction(chatId, messageId, sessionId) {
+        this.finishReaction(chatId, messageId, sessionId);
     }
     /** Recall reactions left behind when a session dies without terminal lifecycle events. */
     onSessionDied(sessionId) {
@@ -1495,6 +1823,11 @@ export class DingtalkChannel extends ChannelBase {
             }
         }
         this.sessionMentionTargets.delete(sessionId);
+        // A session dying after segments arrived but before the terminal signal is
+        // precisely the case the partial-card fallback exists for; dropping the
+        // buffer here would lose text the agent already produced, which the
+        // pre-aggregation code always delivered on arrival.
+        this.drainBackgroundResponseAggregations(sessionId);
         const cardRunId = this.cardRunBySession.get(sessionId);
         if (cardRunId) {
             this.cardRunBySession.delete(sessionId);
@@ -1504,16 +1837,35 @@ export class DingtalkChannel extends ChannelBase {
         const keys = this.sessionReactionKeys.get(sessionId);
         if (keys) {
             this.sessionReactionKeys.delete(sessionId);
-            for (const [key, { messageId, chatId }] of keys) {
-                if (this.activeReactionKeys.delete(key)) {
-                    void this.recallReaction(messageId, chatId).catch((err) => {
-                        this.logReactionFailure('session-death reaction recall', err);
-                    });
-                }
+            for (const { messageId, chatId } of keys.values()) {
+                this.finishReaction(chatId, messageId, sessionId);
             }
         }
         super.onSessionDied(sessionId);
     }
+    /**
+     * A crashed standalone bridge never settles its in-flight turns, so their
+     * transient tags and ticking status cards would otherwise assert a live
+     * turn forever. Finish the tags without a terminal result and terminalize
+     * the cards as interrupted. Session state stays: crash recovery restores
+     * the sessions on a fresh bridge.
+     */
+    onBridgeDisconnected() {
+        for (const [sessionId, keys] of this.sessionReactionKeys) {
+            this.sessionReactionKeys.delete(sessionId);
+            for (const { messageId, chatId } of keys.values()) {
+                this.finishReaction(chatId, messageId, sessionId);
+            }
+        }
+        for (const [sessionId, runId] of this.cardRunBySession) {
+            this.cardRunBySession.delete(sessionId);
+            this.interactionPresenter?.terminalizeRun(runId, 'cancelled');
+            this.cardRuns.delete(runId);
+        }
+    }
+    onSessionRetiring(sessionId) {
+        this.drainBackgroundResponseAggregations(sessionId);
+    }
     onTaskLifecycle(event) {
         if (event.type === 'started') {
             this.startReaction(event.chatId, event.messageId, event.sessionId);
@@ -1533,10 +1885,18 @@ export class DingtalkChannel extends ChannelBase {
             }
             return;
         }
+        const presentationPhase = lifecyclePresentationPhase(event);
+        if (event.runId && presentationPhase) {
+            this.interactionPresenter?.updateStatusCardPhase(event.runId, presentationPhase);
+        }
+        if (presentationPhase) {
+            this.replaceStatusReaction(event.chatId, event.messageId, this.phaseReactionTag(presentationPhase));
+            return;
+        }
         if (isTerminalTaskLifecycleType(event.type)) {
             if (event.messageId)
                 this.mentionTargets.delete(event.messageId);
-            this.stopReaction(event.chatId, event.messageId, event.sessionId);
+            this.finishReaction(event.chatId, event.messageId, event.sessionId, this.terminalReactionTag(event.type));
             if (event.runId) {
                 this.deleteFileProjectorsForRun(event.runId);
                 if (event.type === 'failed') {
@@ -1681,18 +2041,659 @@ export class DingtalkChannel extends ChannelBase {
             process.stderr.write(`[DingTalk:${this.name}] projector tail delivery failed for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}\n`);
         });
     }
+    /** Deliver every Agent segment immediately unless aggregation is enabled. */
+    async dispatchBackgroundResponse(sessionId, text, context) {
+        const target = this.router.getTarget(sessionId);
+        if (!target ||
+            target.channelName !== this.name ||
+            (context !== undefined && context.kind !== 'agent')) {
+            return super.dispatchBackgroundResponse(sessionId, text, context);
+        }
+        const canAggregate = this.aggregateBackgroundAgentResponses &&
+            context?.kind === 'agent' &&
+            typeof context.turnComplete === 'boolean';
+        if (!canAggregate) {
+            if (text.trim().length === 0) {
+                return super.dispatchBackgroundResponse(sessionId, text, context);
+            }
+            return super.dispatchBackgroundResponse(sessionId, this.formatBackgroundAgentResponse(text, context?.label), context);
+        }
+        const key = JSON.stringify([sessionId, context.taskId, context.turnId]);
+        let current = this.backgroundResponseAggregations.get(key);
+        let parked = this.pendingBackgroundResponseTerminals.get(key);
+        if (current?.turnComplete === true) {
+            this.detachedBackgroundResponseAggregations.add(current);
+            this.backgroundResponseAggregations.delete(key);
+            current = undefined;
+        }
+        if (!current &&
+            (parked?.turnEnded === true ||
+                (parked?.turnComplete === true &&
+                    (parked.retryTimer || parked.retryInFlight || parked.resolvers > 0)))) {
+            if (!parked.turnEnded) {
+                this.detachedPendingBackgroundResponseTerminals.add(parked);
+            }
+            parked = { sessionId, target, resolvers: 0, held: [] };
+            this.pendingBackgroundResponseTerminals.set(key, parked);
+        }
+        if (!current && text.trim().length === 0) {
+            // The first segment's target resolution can suspend (named-session owner
+            // lock), so a turn's terminal marker may arrive before the aggregation
+            // exists. Park it instead of routing it to the empty-text early return,
+            // or the completed turn only surfaces via the bounded wait, mislabeled.
+            if (!parked ||
+                (parked.resolvers === 0 &&
+                    !parked.retryTimer &&
+                    !parked.retryInFlight &&
+                    !parked.resolutionDropped &&
+                    !parked.turnComplete)) {
+                if (parked)
+                    this.pendingBackgroundResponseTerminals.delete(key);
+                return super.dispatchBackgroundResponse(sessionId, text, context);
+            }
+            if (context.turnComplete) {
+                parked.turnComplete = true;
+                parked.status = context.status;
+                parked.label = context.label ?? parked.label;
+                parked.completionPartial = context.partial === true;
+                if (parked.resolvers === 0 &&
+                    !parked.retryTimer &&
+                    !parked.retryInFlight &&
+                    (parked.retryAttempts ?? 0) >=
+                        BACKGROUND_RESPONSE_AGGREGATION_MAX_RETRIES) {
+                    parked.turnEnded = true;
+                    this.pendingBackgroundResponseTerminals.delete(key);
+                }
+            }
+            return;
+        }
+        if (!current) {
+            parked ??= { sessionId, target, resolvers: 0, held: [] };
+            this.pendingBackgroundResponseTerminals.set(key, parked);
+            this.holdPendingBackgroundResponse(parked, text, context);
+            parked.resolvers++;
+            try {
+                let delivery;
+                try {
+                    delivery = await this.resolveBackgroundResponseDelivery(sessionId);
+                }
+                catch (error) {
+                    if (parked.resolvers === 1 &&
+                        !this.backgroundResponseAggregations.has(key)) {
+                        this.scheduleBackgroundResponseResolutionRetry(key, sessionId, parked);
+                    }
+                    else {
+                        const existing = this.backgroundResponseAggregations.get(key);
+                        if (existing) {
+                            if (parked.held.length > 0) {
+                                this.applyHeldBackgroundResponses(existing, parked);
+                            }
+                            this.applyPendingBackgroundResponseTerminal(existing, parked);
+                            if (parked.resolvers === 1) {
+                                if (existing.turnComplete) {
+                                    await this.completeBackgroundResponseAggregation(key, existing);
+                                }
+                                else {
+                                    this.scheduleBackgroundResponseAggregationFlush(key, existing);
+                                }
+                            }
+                        }
+                    }
+                    throw error;
+                }
+                if (!delivery || this.router.getTarget(sessionId) !== delivery.target) {
+                    if (parked.resolvers === 1 &&
+                        !this.backgroundResponseAggregations.has(key)) {
+                        this.scheduleBackgroundResponseResolutionRetry(key, sessionId, parked);
+                    }
+                    else {
+                        const existing = this.backgroundResponseAggregations.get(key);
+                        if (existing) {
+                            if (parked.held.length > 0) {
+                                this.applyHeldBackgroundResponses(existing, parked);
+                            }
+                            this.applyPendingBackgroundResponseTerminal(existing, parked);
+                            if (parked.resolvers === 1) {
+                                if (existing.turnComplete) {
+                                    await this.completeBackgroundResponseAggregation(key, existing);
+                                }
+                                else {
+                                    this.scheduleBackgroundResponseAggregationFlush(key, existing);
+                                }
+                            }
+                        }
+                    }
+                    return;
+                }
+                if (parked.retiring ||
+                    this.pendingBackgroundResponseTerminals.get(key) !== parked) {
+                    await this.flushDetachedBackgroundResponse(key, sessionId, parked, delivery);
+                    return;
+                }
+                if (parked.retryTimer) {
+                    clearTimeout(parked.retryTimer);
+                    parked.retryTimer = undefined;
+                }
+                current =
+                    this.backgroundResponseAggregations.get(key) ??
+                        this.createBackgroundResponseAggregation(key, sessionId, parked.held[0]?.context ?? context, delivery.target, delivery.sourceLabel);
+                this.applyHeldBackgroundResponses(current, parked);
+                this.applyPendingBackgroundResponseTerminal(current, parked);
+                if (parked.resolutionDropped) {
+                    current.resolutionDropped = true;
+                    parked.resolutionDropped = undefined;
+                }
+            }
+            finally {
+                parked.resolvers--;
+                if (this.pendingBackgroundResponseTerminals.get(key) === parked &&
+                    parked.resolvers === 0 &&
+                    !parked.retryTimer &&
+                    parked.held.length === 0 &&
+                    (!parked.resolutionDropped || parked.turnEnded)) {
+                    this.pendingBackgroundResponseTerminals.delete(key);
+                }
+            }
+            if (!current)
+                return;
+            if (current.turnComplete && parked.resolvers > 0)
+                return;
+            if (!current.turnComplete) {
+                this.scheduleBackgroundResponseAggregationFlush(key, current);
+            }
+            else {
+                await this.completeBackgroundResponseAggregation(key, current);
+            }
+            return;
+        }
+        current.status = context.status;
+        current.label = context.label ?? current.label;
+        if (text.trim().length > 0)
+            current.parts.push(text);
+        if (context.turnComplete && parked && parked.resolvers > 0) {
+            parked.turnComplete = true;
+            parked.status = context.status;
+            parked.label = context.label ?? parked.label;
+            parked.completionPartial = context.partial === true;
+        }
+        else if (context.turnComplete) {
+            current.turnComplete = true;
+            current.completionPartial = context.partial === true;
+        }
+        else if (parked?.turnComplete && parked.resolvers === 0) {
+            current.turnComplete = true;
+            current.status = parked.status ?? current.status;
+            current.label = parked.label ?? current.label;
+            current.completionPartial = parked.completionPartial === true;
+        }
+        current.resolutionDropped ||= parked?.resolutionDropped;
+        if (!current.turnComplete) {
+            this.scheduleBackgroundResponseAggregationFlush(key, current);
+            return;
+        }
+        await this.completeBackgroundResponseAggregation(key, current);
+    }
+    async flushBackgroundResponseAggregation(key, aggregation) {
+        if ((this.backgroundResponseAggregations.get(key) !== aggregation &&
+            !this.detachedBackgroundResponseAggregations.has(aggregation)) ||
+            aggregation.flushing) {
+            return;
+        }
+        this.refreshBackgroundResponseDelivery(aggregation);
+        if (aggregation.retryTimer)
+            clearTimeout(aggregation.retryTimer);
+        aggregation.retryTimer = undefined;
+        let delivery = aggregation.delivery;
+        if (!delivery) {
+            if (aggregation.parts.length === 0) {
+                // A turn whose text was already drained by the bounded wait still owes
+                // the user its completion: the last card it saw reads `（部分）`.
+                if (!this.owesTerminalBackgroundResponseCard(aggregation)) {
+                    if (aggregation.retiring || aggregation.turnComplete) {
+                        this.removeBackgroundResponseAggregation(key, aggregation);
+                    }
+                    else {
+                        this.scheduleBackgroundResponseAggregationFlush(key, aggregation);
+                    }
+                    return;
+                }
+            }
+            if (aggregation.timeoutTimer)
+                clearTimeout(aggregation.timeoutTimer);
+            aggregation.timeoutTimer = undefined;
+            const parts = aggregation.parts.splice(0);
+            delivery = {
+                status: aggregation.status,
+                label: aggregation.label,
+                parts,
+                partial: this.isPartialBackgroundResponseDelivery(aggregation, parts.length),
+                attempts: 0,
+                composedTurnComplete: aggregation.turnComplete === true,
+            };
+            aggregation.delivery = delivery;
+        }
+        const body = this.formatBackgroundResponseAggregation(delivery);
+        aggregation.flushing = true;
+        let error;
+        try {
+            if (delivery.proactivePlan) {
+                await this.deliverProactiveText(aggregation.target, delivery.proactivePlan);
+            }
+            else if (delivery.replyPlan) {
+                await this.deliverReplyText(aggregation.target.chatId, delivery.replyPlan, true);
+            }
+            else if (this.supportsProactiveSend() &&
+                this.supportsProactiveTarget(aggregation.target)) {
+                await this.deliverBackgroundResponseToTarget(aggregation.sessionId, body, {
+                    target: aggregation.target,
+                    sourceLabel: aggregation.sourceLabel,
+                });
+            }
+            else {
+                delivery.preparedReplyBody ??= await this.prepareReplyOutput(aggregation.target.chatId, body);
+                await this.deliverBackgroundReply(aggregation.target.chatId, delivery.preparedReplyBody, aggregation.sessionId, aggregation.sourceLabel, true, true);
+            }
+        }
+        catch (caught) {
+            error = caught;
+            if (caught instanceof ProactiveTextDeliveryError) {
+                delivery.proactivePlan = caught.plan;
+            }
+            else if (caught instanceof ReplyTextDeliveryError) {
+                delivery.replyPlan = caught.plan;
+            }
+        }
+        finally {
+            aggregation.flushing = false;
+        }
+        if (error === undefined) {
+            aggregation.delivery = undefined;
+            aggregation.delivered = true;
+            if (delivery.composedTurnComplete === true &&
+                aggregation.turnComplete &&
+                delivery.partial !== true &&
+                !aggregation.retiring) {
+                aggregation.completionDelivered = true;
+            }
+            if (aggregation.retiring || aggregation.turnComplete) {
+                await this.flushBackgroundResponseAggregation(key, aggregation);
+            }
+            else {
+                // The turn is still open: keep the entry so its later segments re-join
+                // this one (and stay labelled `（部分）`), and re-arm the bounded wait
+                // so a silent turn is still reaped.
+                this.scheduleBackgroundResponseAggregationFlush(key, aggregation);
+            }
+            return;
+        }
+        delivery.attempts++;
+        process.stderr.write(`[DingTalk:${this.name}] background response delivery failed (attempt ${delivery.attempts}): ${sanitizeLogText(error instanceof Error ? error.message : String(error), 300)}\n`);
+        if (delivery.attempts >= BACKGROUND_RESPONSE_AGGREGATION_MAX_RETRIES ||
+            // A permanently rejected send (an invalid appkey, a missing app) cannot
+            // succeed later; retrying it only spends the chat's send quota.
+            (error instanceof ProactiveTextDeliveryError && error.retryable === false)) {
+            aggregation.delivery = undefined;
+            aggregation.dropped = true;
+            if (aggregation.parts.length === 0) {
+                if (aggregation.retiring || aggregation.turnComplete) {
+                    this.removeBackgroundResponseAggregation(key, aggregation);
+                }
+                else {
+                    this.scheduleBackgroundResponseAggregationFlush(key, aggregation);
+                }
+            }
+            else if (aggregation.retiring || aggregation.turnComplete) {
+                await this.flushBackgroundResponseAggregation(key, aggregation);
+            }
+            else {
+                this.scheduleBackgroundResponseAggregationFlush(key, aggregation);
+            }
+            return;
+        }
+        aggregation.retryTimer = setTimeout(() => {
+            aggregation.retryTimer = undefined;
+            void this.flushBackgroundResponseAggregation(key, aggregation);
+        }, BACKGROUND_RESPONSE_AGGREGATION_RETRY_MS);
+        aggregation.retryTimer.unref?.();
+    }
+    /**
+     * A card carries `（部分）` whenever it is not the turn's whole output: the
+     * turn is still open, earlier text already went out (or was given up on),
+     * or the turn itself ended early.
+     */
+    isPartialBackgroundResponseDelivery(aggregation, partCount) {
+        return (partCount > 0 &&
+            (aggregation.delivered === true ||
+                aggregation.dropped === true ||
+                aggregation.resolutionDropped === true ||
+                aggregation.retiring === true ||
+                aggregation.completionPartial === true ||
+                aggregation.turnComplete !== true));
+    }
+    /**
+     * A turn that outran the bounded wait had its text delivered under the
+     * `（部分）` label. When it then completes normally with nothing buffered,
+     * a header-only card is the only way the chat ever learns it finished.
+     */
+    owesTerminalBackgroundResponseCard(aggregation) {
+        return (aggregation.turnComplete === true &&
+            aggregation.delivered === true &&
+            aggregation.completionDelivered !== true &&
+            aggregation.retiring !== true &&
+            aggregation.completionPartial !== true &&
+            aggregation.dropped !== true &&
+            aggregation.resolutionDropped !== true);
+    }
+    refreshBackgroundResponseDelivery(aggregation) {
+        const delivery = aggregation.delivery;
+        if (!delivery || aggregation.flushing)
+            return;
+        const plan = delivery.proactivePlan ?? delivery.replyPlan;
+        if (plan && plan.nextChunk > 0)
+            return;
+        const body = this.formatBackgroundResponseAggregation(delivery);
+        const header = body.split('\n', 1)[0];
+        const replaceHeader = (text) => text.replace(/## (?:✅|❌|⏹️) Agent · [^\n]+/, () => header);
+        if (plan) {
+            plan.title = extractTitle(body);
+            plan.chunks[0] = replaceHeader(plan.chunks[0]);
+        }
+        if (delivery.preparedReplyBody) {
+            delivery.preparedReplyBody = replaceHeader(delivery.preparedReplyBody);
+        }
+        delivery.composedTurnComplete = aggregation.turnComplete === true;
+    }
+    removeBackgroundResponseAggregation(key, aggregation) {
+        if (this.backgroundResponseAggregations.get(key) === aggregation) {
+            this.backgroundResponseAggregations.delete(key);
+        }
+        this.detachedBackgroundResponseAggregations.delete(aggregation);
+    }
+    drainBackgroundResponseAggregations(sessionId) {
+        for (const [key, pending] of this.pendingBackgroundResponseTerminals) {
+            if (sessionId !== undefined && pending.sessionId !== sessionId)
+                continue;
+            if (pending.retryTimer)
+                clearTimeout(pending.retryTimer);
+            pending.retryTimer = undefined;
+            pending.retiring = true;
+            pending.turnComplete = true;
+            pending.completionPartial = true;
+            this.pendingBackgroundResponseTerminals.delete(key);
+            this.detachedPendingBackgroundResponseTerminals.add(pending);
+        }
+        for (const pending of this.detachedPendingBackgroundResponseTerminals) {
+            if (sessionId !== undefined && pending.sessionId !== sessionId)
+                continue;
+            if (pending.retryTimer)
+                clearTimeout(pending.retryTimer);
+            pending.retryTimer = undefined;
+            pending.retiring = true;
+            pending.turnComplete = true;
+            pending.completionPartial = true;
+            if (pending.held.length > 0 &&
+                this.router.getTarget(pending.sessionId) === pending.target) {
+                void this.flushDetachedBackgroundResponse('', pending.sessionId, pending, { target: pending.target }).catch((error) => {
+                    process.stderr.write(`[DingTalk:${this.name}] background response delivery failed during drain: ${sanitizeLogText(error instanceof Error ? error.message : String(error), 300)}\n`);
+                });
+            }
+            else if (pending.held.length > 0) {
+                process.stderr.write(`[DingTalk:${this.name}] background response target unavailable during drain; ${pending.held.length} buffered segment(s) discarded\n`);
+                pending.held.length = 0;
+                this.detachedPendingBackgroundResponseTerminals.delete(pending);
+            }
+            else if (pending.held.length === 0) {
+                this.detachedPendingBackgroundResponseTerminals.delete(pending);
+            }
+        }
+        const aggregations = new Set([
+            ...this.backgroundResponseAggregations.values(),
+            ...this.detachedBackgroundResponseAggregations,
+        ]);
+        for (const aggregation of aggregations) {
+            if (sessionId !== undefined && aggregation.sessionId !== sessionId) {
+                continue;
+            }
+            if (aggregation.timeoutTimer)
+                clearTimeout(aggregation.timeoutTimer);
+            if (aggregation.retryTimer)
+                clearTimeout(aggregation.retryTimer);
+            aggregation.timeoutTimer = undefined;
+            aggregation.retryTimer = undefined;
+            aggregation.retiring = true;
+            aggregation.turnComplete = true;
+            aggregation.completionPartial = true;
+            if (!aggregation.flushing) {
+                void this.flushBackgroundResponseAggregation(aggregation.key, aggregation);
+            }
+        }
+    }
+    createBackgroundResponseAggregation(key, sessionId, context, target, sourceLabel) {
+        const aggregation = {
+            key,
+            sessionId,
+            target,
+            sourceLabel,
+            status: context.status,
+            label: context.label,
+            parts: [],
+        };
+        this.backgroundResponseAggregations.set(key, aggregation);
+        return aggregation;
+    }
+    scheduleBackgroundResponseResolutionRetry(key, sessionId, pending) {
+        if (pending.retiring)
+            return;
+        if (pending.retryTimer)
+            return;
+        pending.retryAttempts = (pending.retryAttempts ?? 0) + 1;
+        if (pending.retryAttempts >= BACKGROUND_RESPONSE_AGGREGATION_MAX_RETRIES) {
+            pending.resolutionDropped = true;
+            pending.turnEnded = pending.turnComplete === true;
+            pending.held.length = 0;
+            pending.turnComplete = undefined;
+            pending.status = undefined;
+            pending.label = undefined;
+            pending.completionPartial = undefined;
+            if (pending.turnEnded) {
+                this.detachedPendingBackgroundResponseTerminals.delete(pending);
+            }
+            return;
+        }
+        pending.retryTimer = setTimeout(() => {
+            pending.retryTimer = undefined;
+            pending.retryInFlight = true;
+            void this.retryBackgroundResponseResolution(key, sessionId, pending)
+                .catch((error) => {
+                process.stderr.write(`[DingTalk:${this.name}] background response target resolution failed: ${sanitizeLogText(error instanceof Error ? error.message : String(error), 300)}\n`);
+            })
+                .finally(() => {
+                pending.retryInFlight = false;
+                if (pending.retiring ||
+                    (!pending.retryTimer && !pending.resolutionDropped)) {
+                    this.detachedPendingBackgroundResponseTerminals.delete(pending);
+                }
+                if (this.pendingBackgroundResponseTerminals.get(key) === pending &&
+                    pending.resolvers === 0 &&
+                    !pending.retryTimer &&
+                    pending.held.length === 0 &&
+                    (!pending.resolutionDropped || pending.turnEnded)) {
+                    this.pendingBackgroundResponseTerminals.delete(key);
+                }
+            });
+        }, BACKGROUND_RESPONSE_AGGREGATION_RETRY_MS);
+        pending.retryTimer.unref?.();
+        const active = this.pendingBackgroundResponseTerminals.get(key);
+        if (!active || active === pending) {
+            this.pendingBackgroundResponseTerminals.set(key, pending);
+        }
+    }
+    async retryBackgroundResponseResolution(key, sessionId, pending) {
+        let delivery;
+        try {
+            delivery = await this.resolveBackgroundResponseDelivery(sessionId);
+        }
+        catch (error) {
+            if ((this.pendingBackgroundResponseTerminals.get(key) === pending &&
+                !this.backgroundResponseAggregations.has(key)) ||
+                this.detachedPendingBackgroundResponseTerminals.has(pending)) {
+                this.scheduleBackgroundResponseResolutionRetry(key, sessionId, pending);
+            }
+            throw error;
+        }
+        if (!delivery || this.router.getTarget(sessionId) !== delivery.target) {
+            if (pending.retiring) {
+                if (pending.held.length > 0) {
+                    process.stderr.write(`[DingTalk:${this.name}] background response target unavailable during drain; ${pending.held.length} buffered segment(s) discarded\n`);
+                }
+                pending.held.length = 0;
+                this.detachedPendingBackgroundResponseTerminals.delete(pending);
+                return;
+            }
+            if ((this.pendingBackgroundResponseTerminals.get(key) === pending &&
+                !this.backgroundResponseAggregations.has(key)) ||
+                this.detachedPendingBackgroundResponseTerminals.has(pending)) {
+                this.scheduleBackgroundResponseResolutionRetry(key, sessionId, pending);
+            }
+            return;
+        }
+        if (pending.retiring ||
+            this.pendingBackgroundResponseTerminals.get(key) !== pending ||
+            pending.turnComplete) {
+            await this.flushDetachedBackgroundResponse(key, sessionId, pending, delivery);
+            return;
+        }
+        const first = pending.held[0];
+        if (!first)
+            return;
+        const aggregation = this.createBackgroundResponseAggregation(key, sessionId, first.context, delivery.target, delivery.sourceLabel);
+        this.applyHeldBackgroundResponses(aggregation, pending);
+        if (pending.resolutionDropped) {
+            aggregation.resolutionDropped = true;
+            pending.resolutionDropped = undefined;
+        }
+        if (this.pendingBackgroundResponseTerminals.get(key) === pending) {
+            this.pendingBackgroundResponseTerminals.delete(key);
+        }
+        this.scheduleBackgroundResponseAggregationFlush(key, aggregation);
+    }
+    holdPendingBackgroundResponse(pending, text, context) {
+        if (text.trim().length > 0)
+            pending.held.push({ text, context });
+        if (context.turnComplete) {
+            pending.turnComplete = true;
+            pending.status = context.status;
+            pending.label = context.label ?? pending.label;
+            pending.completionPartial = context.partial === true;
+        }
+    }
+    applyHeldBackgroundResponses(aggregation, pending) {
+        for (const { text, context } of pending.held.splice(0)) {
+            aggregation.status = context.status;
+            aggregation.label = context.label ?? aggregation.label;
+            aggregation.parts.push(text);
+            if (context.turnComplete) {
+                aggregation.turnComplete = true;
+                aggregation.completionPartial = context.partial === true;
+            }
+        }
+    }
+    applyPendingBackgroundResponseTerminal(aggregation, pending) {
+        if (!pending.turnComplete)
+            return;
+        aggregation.turnComplete = true;
+        aggregation.status = pending.status ?? aggregation.status;
+        aggregation.label = pending.label ?? aggregation.label;
+        aggregation.completionPartial = pending.completionPartial === true;
+        pending.turnComplete = undefined;
+        pending.status = undefined;
+        pending.label = undefined;
+        pending.completionPartial = undefined;
+    }
+    async completeBackgroundResponseAggregation(key, aggregation) {
+        if (aggregation.delivery) {
+            aggregation.delivery.status = aggregation.status;
+            aggregation.delivery.label =
+                aggregation.label ?? aggregation.delivery.label;
+            aggregation.delivery.partial =
+                this.isPartialBackgroundResponseDelivery(aggregation, aggregation.delivery.parts.length) || aggregation.parts.length > 0;
+        }
+        if (aggregation.timeoutTimer)
+            clearTimeout(aggregation.timeoutTimer);
+        aggregation.timeoutTimer = undefined;
+        await this.flushBackgroundResponseAggregation(key, aggregation);
+    }
+    async flushDetachedBackgroundResponse(key, sessionId, pending, delivery) {
+        const first = pending.held[0];
+        if (!first) {
+            this.detachedPendingBackgroundResponseTerminals.delete(pending);
+            return;
+        }
+        const aggregation = {
+            key,
+            sessionId,
+            target: delivery.target,
+            sourceLabel: delivery.sourceLabel,
+            status: first.context.status,
+            label: first.context.label,
+            parts: [],
+            turnComplete: pending.turnComplete,
+            completionPartial: pending.completionPartial,
+            resolutionDropped: pending.resolutionDropped,
+        };
+        this.applyHeldBackgroundResponses(aggregation, pending);
+        aggregation.status = pending.status ?? aggregation.status;
+        aggregation.label = pending.label ?? aggregation.label;
+        if (this.pendingBackgroundResponseTerminals.get(key) === pending) {
+            this.pendingBackgroundResponseTerminals.delete(key);
+        }
+        this.detachedPendingBackgroundResponseTerminals.delete(pending);
+        this.detachedBackgroundResponseAggregations.add(aggregation);
+        await this.flushBackgroundResponseAggregation(key, aggregation);
+    }
+    scheduleBackgroundResponseAggregationFlush(key, aggregation) {
+        if (aggregation.timeoutTimer || aggregation.delivery)
+            return;
+        aggregation.timeoutTimer = setTimeout(() => {
+            aggregation.timeoutTimer = undefined;
+            void this.flushBackgroundResponseAggregation(key, aggregation);
+        }, BACKGROUND_RESPONSE_AGGREGATION_TIMEOUT_MS);
+        aggregation.timeoutTimer.unref?.();
+    }
+    formatBackgroundResponseAggregation(delivery) {
+        const icon = delivery.status === 'completed'
+            ? '✅'
+            : delivery.status === 'failed'
+                ? '❌'
+                : '⏹️';
+        const label = this.formatBackgroundAgentLabel(delivery.label);
+        const header = `## ${icon} Agent · ${label}${delivery.partial ? '（部分）' : ''}`;
+        if (delivery.parts.length === 0)
+            return header;
+        return `${header}\n\n${delivery.parts.join('\n\n')}`;
+    }
+    formatBackgroundAgentResponse(text, label) {
+        return `## 🤖 Agent · ${this.formatBackgroundAgentLabel(label)}\n\n${text}`;
+    }
+    formatBackgroundAgentLabel(label) {
+        const normalized = label
+            ?.replace(/\p{Cc}+/gu, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        return escapeDingTalkMarkdown(normalized || '后台任务');
+    }
     /**
      * Out-of-turn one-shot sends (background responses) must not flow through
      * the session's block-streaming projector: a second sender interleaving with
      * mid-projection state can swallow the send or split a held marker.
      */
-    async deliverBackgroundReply(chatId, text, sessionId, sourceLabel) {
+    async deliverBackgroundReply(chatId, text, sessionId, sourceLabel, prepared = false, failOnHttpError = false) {
         if (this.config.blockStreaming !== 'on') {
-            return super.deliverBackgroundReply(chatId, text, sessionId, sourceLabel);
+            return this.sendResponseMessage(chatId, text, sessionId, sourceLabel, prepared, failOnHttpError);
         }
-        await this.sendReply(chatId, text, undefined, sourceLabel);
+        await this.sendReply(chatId, text, undefined, sourceLabel, prepared, failOnHttpError);
     }
-    async sendResponseMessage(chatId, text, sessionId, sourceLabel, prepared = false) {
+    async sendResponseMessage(chatId, text, sessionId, sourceLabel, prepared = false, failOnHttpError = false) {
         let outgoingText = text;
         let consumesMention = true;
         if (this.config.blockStreaming === 'on') {
@@ -1709,7 +2710,7 @@ export class DingtalkChannel extends ChannelBase {
             : undefined;
         if (atUserId)
             this.sessionMentionTargets.delete(sessionId);
-        await this.sendReply(chatId, outgoingText, atUserId, sourceLabel ?? this.getResponseSourceLabel(sessionId), prepared);
+        await this.sendReply(chatId, outgoingText, atUserId, sourceLabel ?? this.getResponseSourceLabel(sessionId), prepared, failOnHttpError);
     }
     projectBlockStreamChunk(text, sessionId) {
         let state = this.blockFileProjectors.get(sessionId);