@yanhaidao/wecom 2.3.270 → 2.4.120

package/src/agent/handler.event-filter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { shouldProcessAgentInboundMessage } from "./handler.js";
+import { shouldProcessAgentInboundMessage, shouldSuppressAgentReplyText } from "./handler.js";
 
 describe("shouldProcessAgentInboundMessage", () => {
     it("allows enter_agent/subscribe through the filter (handled earlier by static welcome)", () => {
@@ -31,6 +31,41 @@ describe("shouldProcessAgentInboundMessage", () => {
         expect(unknown.reason).toBe("event:some_random_event");
     });
 
+    it("blocks event processing when eventEnabled is false", () => {
+        const disabled = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "click",
+            fromUser: "zhangsan",
+            eventEnabled: false,
+        });
+        expect(disabled.shouldProcess).toBe(false);
+        expect(disabled.reason).toBe("event_disabled");
+    });
+
+    it("allows configured custom event types", () => {
+        const custom = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "click",
+            fromUser: "zhangsan",
+            eventEnabled: true,
+            allowedEventTypes: ["click"],
+        });
+        expect(custom.shouldProcess).toBe(true);
+        expect(custom.reason).toBe("allowed_event:click");
+    });
+
+    it("normalizes configured event type values before matching", () => {
+        const custom = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "view_miniprogram",
+            fromUser: "zhangsan",
+            eventEnabled: true,
+            allowedEventTypes: [" VIEW_MINIPROGRAM "],
+        });
+        expect(custom.shouldProcess).toBe(true);
+        expect(custom.reason).toBe("allowed_event:view_miniprogram");
+    });
+
     it("skips system sender callbacks", () => {
         const systemSender = shouldProcessAgentInboundMessage({
             msgType: "text",
@@ -69,3 +104,32 @@ describe("shouldProcessAgentInboundMessage", () => {
         expect(normalMessage.reason).toBe("user_message");
     });
 });
+
+describe("shouldSuppressAgentReplyText", () => {
+    it("keeps plain text replies when no media reply has been seen", () => {
+        expect(
+            shouldSuppressAgentReplyText({
+                text: "这里是正常文本",
+                mediaReplySeen: false,
+            }),
+        ).toBe(false);
+    });
+
+    it("suppresses companion text once the reply flow includes media", () => {
+        expect(
+            shouldSuppressAgentReplyText({
+                text: "文件已发送，请查收",
+                mediaReplySeen: true,
+            }),
+        ).toBe(true);
+    });
+
+    it("does not suppress empty text even after media replies", () => {
+        expect(
+            shouldSuppressAgentReplyText({
+                text: "   ",
+                mediaReplySeen: true,
+            }),
+        ).toBe(false);
+    });
+});

package/src/agent/handler.ts

@@ -15,6 +15,7 @@ import {
   shouldUseDynamicAgent,
   ensureDynamicAgentListed,
 } from "../dynamic-agent.js";
+import { setPeerContext } from "../context-store.js";
 import { getWecomRuntime } from "../runtime.js";
 import { registerWecomSourceSnapshot } from "../runtime/source-registry.js";
 import {
@@ -30,16 +31,28 @@ import {
   extractMsgId,
   extractFileName,
   extractAgentId,
+  extractToUser,
 } from "../shared/xml-parser.js";
-import { downloadAgentApiMedia, sendAgentApiText } from "../transport/agent-api/client.js";
+import { routeAgentInboundEvent } from "./event-router.js";
+import { resolveOutboundMediaAsset } from "../shared/media-asset.js";
+import {
+  downloadAgentApiMedia,
+  downloadUpstreamAgentApiMedia,
+  sendAgentApiText,
+  sendUpstreamAgentApiText,
+} from "../transport/agent-api/client.js";
+import { deliverAgentApiMedia } from "../transport/agent-api/delivery.js";
+import { deliverUpstreamAgentApiMedia } from "../transport/agent-api/upstream-delivery.js";
 import type {
   ResolvedAgentAccount,
+  ReplyPayload,
   UnifiedInboundEvent,
   WecomInboundKind,
 } from "../types/index.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import type { TransportSessionPatch } from "../types/index.js";
 import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
+import { detectUpstreamUser, createUpstreamAgentConfig, resolveUpstreamCorpConfig } from "../upstream/index.js";
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
@@ -123,6 +136,11 @@ function buildTextFilePreview(buffer: Buffer, maxChars: number): string | undefi
   return truncated;
 }
 
+function readContextSessionId(ctx: { SessionId?: string } | Record<string, unknown>): string | undefined {
+  const sessionId = "SessionId" in ctx ? ctx.SessionId : undefined;
+  return typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : undefined;
+}
+
 /**
  * **AgentWebhookParams (Webhook 处理器参数)**
  *
@@ -175,6 +193,8 @@ export function shouldProcessAgentInboundMessage(params: {
   fromUser: string;
   chatId?: string;
   eventType?: string;
+  eventEnabled?: boolean;
+  allowedEventTypes?: string[];
 }): AgentInboundProcessDecision {
   const msgType = String(params.msgType ?? "")
     .trim()
@@ -187,7 +207,8 @@ export function shouldProcessAgentInboundMessage(params: {
     .toLowerCase();
 
   if (msgType === "event") {
-    const allowedEvents = [
+    // 兼容旧行为：未配置 event 策略时，继续沿用历史白名单
+    const compatibilityAllowedEvents = [
       "subscribe",
       "enter_agent",
       "batch_job_result",
@@ -203,6 +224,26 @@ export function shouldProcessAgentInboundMessage(params: {
       "smartsheet_field_change",
       "smartsheet_view_change",
     ];
+    const configuredAllowedEvents = Array.isArray(params.allowedEventTypes)
+      ? params.allowedEventTypes
+          .map((entry) => String(entry ?? "").trim().toLowerCase())
+          .filter(Boolean)
+      : [];
+    const hasEventConfig = params.eventEnabled !== undefined || configuredAllowedEvents.length > 0;
+
+    // 显式关闭 event 时直接拒绝，优先级最高
+    if (params.eventEnabled === false) {
+      return {
+        shouldProcess: false,
+        reason: "event_disabled",
+      };
+    }
+
+    // 配置存在时：历史白名单 + 配置白名单并集，保证平滑迁移
+    const allowedEvents = hasEventConfig
+      ? Array.from(new Set([...compatibilityAllowedEvents, ...configuredAllowedEvents]))
+      : compatibilityAllowedEvents;
+
     if (
       allowedEvents.includes(eventType) ||
       eventType.startsWith("doc_") ||
@@ -246,6 +287,13 @@ export function shouldProcessAgentInboundMessage(params: {
   };
 }
 
+export function shouldSuppressAgentReplyText(params: {
+  text: string;
+  mediaReplySeen: boolean;
+}): boolean {
+  return params.mediaReplySeen && Boolean(params.text.trim());
+}
+
 function normalizeAgentId(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isFinite(value)) return value;
   const raw = String(value ?? "").trim();
@@ -254,6 +302,72 @@ function normalizeAgentId(value: unknown): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+function resolveAgentReplyTransportContext(params: {
+  agent: ResolvedAgentAccount;
+  msg: WecomAgentInboundMessage;
+  fromUser: string;
+  chatId?: string;
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+}): {
+  upstreamAgent?: ResolvedAgentAccount;
+  primaryAgentForUpstream?: ResolvedAgentAccount;
+  upstreamReplyTarget?: { toUser: string | undefined; chatId: string | undefined };
+  effectiveReplyTarget: { toUser: string | undefined; chatId: string | undefined };
+} {
+  // 事件路由也可能需要即时回包，这里复用普通消息的上下游目标判定逻辑
+  const { agent, msg, fromUser, chatId, log, error } = params;
+  const isGroup = Boolean(chatId);
+  const peerId = isGroup ? chatId! : fromUser;
+  const replyTarget = isGroup
+    ? ({ toUser: undefined, chatId: peerId } as const)
+    : ({ toUser: fromUser, chatId: undefined } as const);
+  const toUserName = extractToUser(msg);
+  const isUpstreamUser = detectUpstreamUser({
+    messageToUserName: toUserName,
+    primaryCorpId: agent.corpId,
+  });
+
+  if (!isUpstreamUser) {
+    return {
+      upstreamAgent: undefined,
+      primaryAgentForUpstream: undefined,
+      upstreamReplyTarget: undefined,
+      effectiveReplyTarget: replyTarget,
+    };
+  }
+
+  log?.(`[wecom-agent] detected upstream user during event routing: from=${fromUser} toCorpId=${toUserName}`);
+  const upstreamConfig = resolveUpstreamCorpConfig({
+    upstreamCorpId: toUserName,
+    upstreamCorps: agent.config.upstreamCorps,
+  });
+  if (!upstreamConfig) {
+    error?.(
+      `[wecom-agent] upstream event detected but no upstream config for corpId=${toUserName}; fallback to primary agent target`,
+    );
+    return {
+      upstreamAgent: undefined,
+      primaryAgentForUpstream: undefined,
+      upstreamReplyTarget: undefined,
+      effectiveReplyTarget: replyTarget,
+    };
+  }
+
+  const upstreamAgent = createUpstreamAgentConfig({
+    baseAgent: agent,
+    upstreamCorpId: toUserName,
+    upstreamAgentId: upstreamConfig.agentId,
+  });
+
+  return {
+    upstreamAgent,
+    primaryAgentForUpstream: agent,
+    upstreamReplyTarget: replyTarget,
+    effectiveReplyTarget: replyTarget,
+  };
+}
+
 /**
  * **resolveQueryParams (解析查询参数)**
  *
@@ -367,6 +481,8 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
       fromUser,
       chatId,
       eventType,
+      eventEnabled: agent.eventEnabled,
+      allowedEventTypes: agent.allowedEventTypes,
     });
     if (!decision.shouldProcess) {
       log?.(
@@ -375,6 +491,57 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
       return true;
     }
 
+    const routedEvent = await routeAgentInboundEvent({
+      agent,
+      msgType,
+      eventType,
+      fromUser,
+      chatId,
+      msg,
+      log,
+      auditSink,
+    });
+    // 路由器返回文本时，先即时回包给用户/群，再决定是否进入默认 AI 流程
+    if (routedEvent.handled && routedEvent.replyText?.trim()) {
+      const replyContext = resolveAgentReplyTransportContext({
+        agent,
+        msg,
+        fromUser,
+        chatId,
+        log,
+        error,
+      });
+      try {
+        if (replyContext.upstreamAgent && replyContext.primaryAgentForUpstream) {
+          await sendUpstreamAgentApiText({
+            upstreamAgent: replyContext.upstreamAgent,
+            primaryAgent: replyContext.primaryAgentForUpstream,
+            ...(replyContext.upstreamReplyTarget ?? replyContext.effectiveReplyTarget),
+            text: routedEvent.replyText,
+          });
+        } else {
+          await sendAgentApiText({
+            agent,
+            ...replyContext.effectiveReplyTarget,
+            text: routedEvent.replyText,
+          });
+        }
+        params.touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+        log?.(
+          `[wecom-agent] event route reply delivered routeId=${routedEvent.matchedRouteId ?? "N/A"} to=${chatId ? `chat:${chatId}` : fromUser}`,
+        );
+      } catch (err) {
+        error?.(`[wecom-agent] event route reply failed: ${String(err)}`);
+      }
+    }
+    // routedEvent 已完全消费该事件时，终止后续默认处理链
+    if (routedEvent.handled && !routedEvent.chainToAgent) {
+      log?.(
+        `[wecom-agent] event route handled routeId=${routedEvent.matchedRouteId ?? "N/A"} reason=${routedEvent.reason}`,
+      );
+      return true;
+    }
+
     // 异步处理消息
     processAgentMessage({
       agent,
@@ -396,9 +563,11 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
     return true;
   } catch (err) {
     error?.(`[wecom-agent] callback failed: ${String(err)}`);
-    res.statusCode = 400;
-    res.setHeader("Content-Type", "text/plain; charset=utf-8");
-    res.end(`error - 回调处理失败${ERROR_HELP}`);
+    if (!res.headersSent && !res.writableEnded) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end(`error - 回调处理失败${ERROR_HELP}`);
+    }
     return true;
   }
 }
@@ -448,10 +617,48 @@ async function processAgentMessage(params: {
   const replyTarget = isGroup
     ? ({ toUser: undefined, chatId: peerId } as const)
     : ({ toUser: fromUser, chatId: undefined } as const);
+  let upstreamAgent: typeof agent | undefined;
+  let upstreamReplyTarget: typeof replyTarget | undefined;
+  let primaryAgentForUpstream: typeof agent | undefined;
   const eventType = String(msg.Event ?? "")
     .trim()
     .toLowerCase();
 
+  // 检测是否是上下游用户
+  const toUserName = extractToUser(msg);
+  const isUpstreamUser = detectUpstreamUser({
+    messageToUserName: toUserName,
+    primaryCorpId: agent.corpId,
+  });
+  
+  if (isUpstreamUser) {
+    log?.(
+      `[wecom-agent] detected upstream user: from=${fromUser} toCorpId=${toUserName}`,
+    );
+
+    // 查找上下游配置，构建上游 Agent 配置
+    const upstreamConfig = resolveUpstreamCorpConfig({
+      upstreamCorpId: toUserName,
+      upstreamCorps: agent.config.upstreamCorps,
+    });
+    if (upstreamConfig) {
+      upstreamAgent = createUpstreamAgentConfig({
+        baseAgent: agent,
+        upstreamCorpId: toUserName,
+        upstreamAgentId: upstreamConfig.agentId,
+      });
+      primaryAgentForUpstream = agent;
+      // 上下游的 replyTarget 与普通 DM 一致（toUser = fromUser）
+      upstreamReplyTarget = isGroup
+        ? ({ toUser: undefined, chatId: peerId } as const)
+        : ({ toUser: fromUser, chatId: undefined } as const);
+    } else {
+      error?.(
+        `[wecom-agent] upstream user detected but no upstream config for corpId=${toUserName}; fallback to primary agent target`,
+      );
+    }
+  }
+
   const resolveInboundKind = (): WecomInboundKind => {
     if (msgType === "event") {
       if (eventType === "subscribe" || eventType === "enter_agent") return "welcome";
@@ -497,7 +704,15 @@ async function processAgentMessage(params: {
           buffer,
           contentType,
           filename: headerFileName,
-        } = await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
+        } =
+          upstreamAgent && primaryAgentForUpstream
+            ? await downloadUpstreamAgentApiMedia({
+                upstreamAgent,
+                primaryAgent: primaryAgentForUpstream,
+                mediaId,
+                maxBytes: mediaMaxBytes,
+              })
+            : await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
         const xmlFileName = extractFileName(msg);
         const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
         const heuristic = analyzeTextHeuristic(buffer);
@@ -633,7 +848,16 @@ async function processAgentMessage(params: {
       `[wecom-agent] routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`,
     );
     try {
-      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      if (upstreamAgent) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream!,
+          ...(upstreamReplyTarget ?? replyTarget),
+          text: prompt,
+        });
+      } else {
+        await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      }
       touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
       log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
     } catch (err: unknown) {
@@ -710,7 +934,16 @@ async function processAgentMessage(params: {
       scope: "agent",
     });
     try {
-      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      if (upstreamAgent) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream!,
+          ...(upstreamReplyTarget ?? replyTarget),
+          text: prompt,
+        });
+      } else {
+        await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      }
       touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
       log?.(
         `[wecom-agent] unauthorized command: replied to ${isGroup ? `chat:${peerId}` : fromUser}`,
@@ -756,6 +989,27 @@ async function processAgentMessage(params: {
     MediaType: mediaType,
     MediaUrl: mediaPath,
   });
+  const sessionId = readContextSessionId(ctxPayload);
+
+  log?.(
+    `[wecom-agent] session bound: sessionKey=${ctxPayload.SessionKey ?? route.sessionKey} sessionId=${sessionId ?? "N/A"} peer=${peerId} upstream=${String(Boolean(upstreamAgent))}`,
+  );
+
+  registerWecomSourceSnapshot({
+    accountId: agent.accountId,
+    source: "agent-callback",
+    messageId: extractMsgId(msg) ?? undefined,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    sessionId,
+    peerKind: isGroup ? "group" : "direct",
+    peerId,
+    upstreamCorpId: upstreamAgent?.corpId,
+  });
+  setPeerContext(agent.accountId, peerId, {
+    peerKind: isGroup ? "group" : "direct",
+    lastSeen: Date.now(),
+    upstreamCorpId: upstreamAgent?.corpId,
+  });
 
   // 记录会话
   await core.channel.session.recordInboundSession({
@@ -769,14 +1023,25 @@ async function processAgentMessage(params: {
 
   // 5秒无响应自动回复进度提示
   let hasResponseSent = false;
+  const effectiveAgent = upstreamAgent ?? agent;
+  const effectiveReplyTarget = upstreamReplyTarget ?? replyTarget;
   const processingTimer = setTimeout(async () => {
     if (hasResponseSent) return;
     try {
-      await sendAgentApiText({
-        agent,
-        ...replyTarget,
-        text: "正在处理中，请稍候...",
-      });
+      if (upstreamAgent && primaryAgentForUpstream) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream,
+          ...effectiveReplyTarget,
+          text: "正在处理中，请稍候...",
+        });
+      } else {
+        await sendAgentApiText({
+          agent: effectiveAgent,
+          ...effectiveReplyTarget,
+          text: "正在处理中，请稍候...",
+        });
+      }
       log?.(
         `[wecom-agent] sent processing notification to ${isGroup ? `chat:${peerId}` : fromUser}`,
       );
@@ -787,6 +1052,25 @@ async function processAgentMessage(params: {
 
   // 发送队列锁：确保所有 deliver 调用（以及内部的分片发送）严格串行执行
   let messageSendQueue = Promise.resolve();
+  let deferredMediaUrls: string[] = [];
+
+  const mergeDeferredMediaUrls = (mediaUrls: string[]): string[] => {
+    if (mediaUrls.length === 0) {
+      return deferredMediaUrls;
+    }
+    const merged = [...deferredMediaUrls];
+    for (const mediaUrl of mediaUrls) {
+      if (!merged.includes(mediaUrl)) {
+        merged.push(mediaUrl);
+      }
+    }
+    deferredMediaUrls = merged;
+    return deferredMediaUrls;
+  };
+
+  const replyWecomTarget = effectiveReplyTarget.chatId
+    ? ({ chatid: effectiveReplyTarget.chatId } as const)
+    : ({ touser: effectiveReplyTarget.toUser } as const);
 
   try {
     // 调度回复
@@ -797,10 +1081,20 @@ async function processAgentMessage(params: {
         disableBlockStreaming: false,
       },
       dispatcherOptions: {
-        deliver: async (payload: { text?: string }, info: { kind: string }) => {
+        deliver: async (payload: ReplyPayload, info: { kind: string }) => {
           const text = payload.text ?? "";
-          // 忽略空文本消息
-          if (!text || !text.trim()) {
+          const incomingMediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+          if (info.kind !== "final" && incomingMediaUrls.length > 0) {
+            mergeDeferredMediaUrls(incomingMediaUrls);
+          }
+          const mediaUrls =
+            info.kind === "final"
+              ? mergeDeferredMediaUrls(incomingMediaUrls)
+              : incomingMediaUrls;
+
+          const outboundText = text;
+
+          if ((!outboundText || !outboundText.trim()) && mediaUrls.length === 0) {
             return;
           }
 
@@ -813,18 +1107,27 @@ async function processAgentMessage(params: {
           const currentTask = async () => {
             const MAX_CHUNK_SIZE = 600;
             // 确保分片顺序发送
-            for (let i = 0; i < text.length; i += MAX_CHUNK_SIZE) {
-              const chunk = text.slice(i, i + MAX_CHUNK_SIZE);
+            for (let i = 0; i < outboundText.length; i += MAX_CHUNK_SIZE) {
+              const chunk = outboundText.slice(i, i + MAX_CHUNK_SIZE);
 
               try {
-                await sendAgentApiText({ agent, ...replyTarget, text: chunk });
+                if (upstreamAgent) {
+                  await sendUpstreamAgentApiText({
+                    upstreamAgent,
+                    primaryAgent: primaryAgentForUpstream!,
+                    ...effectiveReplyTarget,
+                    text: chunk,
+                  });
+                } else {
+                  await sendAgentApiText({ agent: effectiveAgent, ...effectiveReplyTarget, text: chunk });
+                }
                 touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
                 log?.(
-                  `[wecom-agent] reply chunk delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, len=${chunk.length}`,
+                  `[wecom-agent] reply chunk delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, len=${chunk.length}, sessionKey=${ctxPayload.SessionKey ?? route.sessionKey}, sessionId=${sessionId ?? "N/A"}`,
                 );
 
                 // 强制延时：确保企业微信有足够时间处理顺序（优化：200ms → 50ms）
-                if (i + MAX_CHUNK_SIZE < text.length) {
+                if (i + MAX_CHUNK_SIZE < outboundText.length) {
                   await new Promise((resolve) => setTimeout(resolve, 50));
                 }
               } catch (err: unknown) {
@@ -847,6 +1150,57 @@ async function processAgentMessage(params: {
               }
             }
 
+            if (info.kind === "final") {
+              for (const mediaUrl of mediaUrls) {
+                try {
+                  const media = await resolveOutboundMediaAsset({
+                    mediaUrl,
+                    network: effectiveAgent.network,
+                  });
+                  if (upstreamAgent) {
+                    await deliverUpstreamAgentApiMedia({
+                      upstreamAgent,
+                      primaryAgent: primaryAgentForUpstream!,
+                      target: replyWecomTarget,
+                      buffer: media.buffer,
+                      filename: media.filename,
+                      contentType: media.contentType,
+                    });
+                  } else {
+                    await deliverAgentApiMedia({
+                      agent: effectiveAgent,
+                      target: replyWecomTarget,
+                      buffer: media.buffer,
+                      filename: media.filename,
+                      contentType: media.contentType,
+                    });
+                  }
+                  touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+                  log?.(
+                    `[wecom-agent] reply media delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, media=${media.filename}, sessionKey=${ctxPayload.SessionKey ?? route.sessionKey}, sessionId=${sessionId ?? "N/A"}`,
+                  );
+                } catch (err: unknown) {
+                  const message =
+                    err instanceof Error
+                      ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}`
+                      : String(err);
+                  error?.(`[wecom-agent] media reply failed: ${message}`);
+                  auditSink?.({
+                    transport: "agent-callback",
+                    category: "fallback-delivery-failed",
+                    summary: `agent callback media reply failed user=${fromUser} kind=${info.kind}`,
+                    raw: {
+                      transport: "agent-callback",
+                      envelopeType: "xml",
+                      body: msg,
+                    },
+                    error: message,
+                  });
+                }
+              }
+              deferredMediaUrls = [];
+            }
+
             // 不同 Block 之间也增加一点间隔（优化：200ms → 50ms）
             if (info.kind !== "final") {
               await new Promise((resolve) => setTimeout(resolve, 50));