@qwen-code/channel-dingtalk 0.23.1-preview.0 → 0.23.1-preview.2

package/dist/DingtalkAdapter.js

@@ -408,6 +408,15 @@ 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';
@@ -595,6 +604,24 @@ 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;
@@ -622,6 +649,7 @@ export class DingtalkChannel extends ChannelBase {
      */
     proactiveToken;
     interactiveCardConfig;
+    aggregateBackgroundAgentResponses;
     interactiveCardClient;
     statusCardController;
     questionCardController;
@@ -641,6 +669,10 @@ 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 =
@@ -661,6 +693,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.`);
         }
@@ -1078,11 +1117,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 +1132,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 +1150,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 +1207,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 +1262,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 +1284,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() {
@@ -1398,6 +1498,7 @@ export class DingtalkChannel extends ChannelBase {
             clearInterval(this.dedupTimer);
         }
         this.statusCardController?.dispose();
+        this.drainBackgroundResponseAggregations();
         this.activeReactionKeys.clear();
         this.sessionReactionKeys.clear();
         if (this.connectionManager) {
@@ -1495,6 +1596,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);
@@ -1514,6 +1620,9 @@ export class DingtalkChannel extends ChannelBase {
         }
         super.onSessionDied(sessionId);
     }
+    onSessionRetiring(sessionId) {
+        this.drainBackgroundResponseAggregations(sessionId);
+    }
     onTaskLifecycle(event) {
         if (event.type === 'started') {
             this.startReaction(event.chatId, event.messageId, event.sessionId);
@@ -1681,18 +1790,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 +2459,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);