@sunnoy/wecom 2.0.2 → 2.1.0

package/README.md

@@ -9,6 +9,8 @@
 
 > **⚠️ 从 HTTP 回调迁移到长连接：** 2.0 版本完全采用企业微信 [AI 机器人 WebSocket 长连接模式](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)。如果你之前使用 HTTP 回调（Token + EncodingAESKey + 回调 URL），需要在企业微信管理后台将机器人切换到长连接模式，然后删除旧的回调配置。切换后只需 `botId` 和 `secret` 即可接入。
 
+> **2.1 新增：** 在 WS 长连接之外，2.1 版本新增了企业微信**自建应用"接收消息"HTTP 回调**作为可选入站通道。在 `channels.wecom.agent` 下配置 `callback.token`、`callback.encodingAESKey`、`callback.path` 即可同时启用，与 WS 通道并行运行，互不影响。
+
 ## 相比官方插件的增强特性
 
 下表列出了本插件相比 [官方 WeCom OpenClaw 插件](https://github.com/WecomTeam/wecom-openclaw-plugin)（[npm](https://www.npmjs.com/package/@wecom/wecom-openclaw-plugin)）额外提供的能力：
@@ -42,6 +44,9 @@
 | **入站图文混排**（`mixed` 消息拆解为文本 + 图片） | ❌ | ✅ |
 | **入站语音转写**（`voice.content` 自动提取） | ❌ | ✅ |
 | **入站引用消息**（`quote` 上下文透传） | ❌ | ✅ |
+| **自建应用回调入站**（HTTP 回调作为独立入站通道，与 WS 并行） | ❌ | ✅ |
+| **Agent API Markdown 回复**（回调入站回复默认 markdown 格式） | ❌ | ✅ |
+| **入站/出站信息日志**（WS / CB 收发日志，便于追踪消息流） | ❌ | ✅ |
 
 ## 目录
 
@@ -55,6 +60,7 @@
 - [企业微信侧配置](#企业微信侧配置)
 - [消息能力与投递策略](#消息能力与投递策略)
 - [动态 Agent 与路由](#动态-agent-与路由)
+- [自建应用回调入站](#自建应用回调入站)
 - [常见问题](#常见问题)
 - [项目结构](#项目结构)
 - [自定义 Skills 配合沙箱使用实践](#自定义-skills-配合沙箱使用实践)
@@ -209,11 +215,15 @@ npm test
 | `channels.wecom.agent.corpId` | string | 否 | 自建应用 CorpID |
 | `channels.wecom.agent.corpSecret` | string | 否 | 自建应用 Secret |
 | `channels.wecom.agent.agentId` | number | 否 | 自建应用 AgentId |
+| `channels.wecom.agent.replyFormat` | string | 否 | 回调入站回复格式，`"markdown"`（默认）或 `"text"` |
+| `channels.wecom.agent.callback.token` | string | 否 | 回调验签 Token |
+| `channels.wecom.agent.callback.encodingAESKey` | string | 否 | 回调消息解密密钥（43 位） |
+| `channels.wecom.agent.callback.path` | string | 否 | 回调 HTTP 路由路径，如 `"/webhooks/app"` |
 | `channels.wecom.webhooks` | object | 否 | 群机器人 webhook 映射 |
 | `channels.wecom.network.egressProxyUrl` | string | 否 | Agent / Webhook 出站代理 |
 | `channels.wecom.network.apiBaseUrl` | string | 否 | 企业微信 API 基础地址覆盖，默认官方地址 |
 
-Agent 增强出站不需要 `token`、`encodingAesKey`、回调 URL。
+Agent 增强出站不需要 `token`、`encodingAesKey`、回调 URL；只有需要同时启用**回调入站**时才需配置 `agent.callback.*`。
 
 ### 多账号示例
 
@@ -295,14 +305,19 @@ Agent 增强出站不需要 `token`、`encodingAesKey`、回调 URL。
 
 长连接模式下不需要配置 HTTP 回调 URL、Token、EncodingAESKey。
 
-### 2. 创建自建应用（Agent 增强出站，可选）
+### 2. 创建自建应用（Agent 增强出站 + 可选回调入站）
 
-Agent 在本项目里只承担增强出站：
+自建应用承担两个可选职责：
 
+**增强出站**（主动推送消息）：
 - 主动给用户 / 群 / 部门 / 标签发消息
 - 上传图片和文件
 - 当 WS 断连时作为回复后备通道
 
+**回调入站**（可选，与 WS 并行）：
+- 企业微信将用户消息以 HTTP POST 推送到你的服务器
+- 适合需要独立入站 URL 或不方便使用 WS 长连接的场景
+
 创建步骤：
 
 1. 在企业微信后台创建自建应用
@@ -311,8 +326,7 @@ Agent 在本项目里只承担增强出站：
    - `channels.wecom.agent.corpId`
    - `channels.wecom.agent.agentId`
    - `channels.wecom.agent.corpSecret`
-
-不需要配置接收消息回调。
+4. **仅启用回调入站时**，额外在应用的「接收消息」中配置回调 URL，并填入对应的 `agent.callback.*` 配置（见[自建应用回调入站](#自建应用回调入站)）
 
 ### 3. 配置群机器人（Webhook 增强出站，可选）
 
@@ -329,8 +343,8 @@ Webhook 只负责群通知。
 
 | 能力 | Bot（WS） | Agent API | Webhook |
 | --- | :---: | :---: | :---: |
-| 私聊接收 | ✅ | — | — |
-| 群聊接收（可配置 @ 触发） | ✅ | — | — |
+| 私聊接收 | ✅ | ✅（回调入站） | — |
+| 群聊接收（可配置 @ 触发） | ✅ | ✅（回调入站） | — |
 | 被动流式回复 | ✅ | — | — |
 | 被动最终帧图片 | ✅ | ✅ | ✅ |
 | 主动发送文本 | ✅ | ✅ | ✅ |
@@ -431,6 +445,63 @@ Webhook 只负责群通知。
 
 如果 OpenClaw 配置了 `bindings`，则优先按 binding 路由，不会被动态 Agent 覆盖。
 
+## 自建应用回调入站
+
+自建应用的「接收消息」HTTP 回调可作为额外的入站通道，与 WS 长连接并行运行，互不干扰。适合已有自建应用的场景，或需要独立回调 URL 的情况。
+
+### 配置
+
+在 `channels.wecom.agent` 下增加 `callback` 子对象：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "botId": "aib-xxx",
+      "secret": "bot-secret-xxx",
+      "agent": {
+        "corpId": "wwxxxxxxxxxxxx",
+        "corpSecret": "app-secret-xxx",
+        "agentId": 1000002,
+        "replyFormat": "markdown",
+        "callback": {
+          "token": "YourToken",
+          "encodingAESKey": "43位密钥",
+          "path": "/webhooks/app"
+        }
+      }
+    }
+  }
+}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `agent.callback.token` | 企业微信「接收消息」里配置的 Token |
+| `agent.callback.encodingAESKey` | 43 位 EncodingAESKey |
+| `agent.callback.path` | Gateway 监听的 HTTP 路径，需与企业微信后台填写的 URL 一致 |
+| `agent.replyFormat` | 回复格式，`"markdown"`（默认）或 `"text"` |
+
+### 企业微信侧配置
+
+1. 进入自建应用 → 「接收消息」
+2. 填写 URL：`https://<your-gateway-host>:<port><path>`（例如 `https://example.com:18789/webhooks/app`）
+3. 填写 Token 和 EncodingAESKey（与配置保持一致）
+4. 点击「保存」，企业微信将发送 GET 请求验证（gateway 会自动回复 echostr）
+5. 验证通过后，用户发给自建应用的消息将通过 HTTP POST 推送到 gateway
+
+### 支持的消息类型
+
+| 类型 | 说明 |
+| --- | --- |
+| `text` | 文本消息 |
+| `image` | 图片（通过 Agent API 下载） |
+| `voice` | 语音文件 |
+| `file` | 文件 |
+| `video` | 视频文件 |
+
+事件类消息（关注、进入会话等）会被静默忽略。
+
 ## 常见问题
 
 ### Q: 2.0 和之前最大的区别是什么？
@@ -500,6 +571,9 @@ openclaw-plugin-wecom/
 │   ├── accounts.js               # 多账号管理与配置继承
 │   ├── agent-api.js              # Agent API（Token、发送、上传）
 │   ├── allow-from.js             # allowlist 规范化与匹配
+│   ├── callback-crypto.js        # 回调 AES 解密与签名验证
+│   ├── callback-inbound.js       # 自建应用回调入站处理
+│   ├── callback-media.js         # 回调媒体下载
 │   ├── channel-plugin.js         # 核心通道（sendNotice / sendMedia）
 │   ├── commands.js               # 指令白名单与命令拦截
 │   ├── constants.js              # 常量定义
@@ -518,6 +592,8 @@ openclaw-plugin-wecom/
 └── tests/
     ├── accounts-reserved-keys.test.js
     ├── api-base-url.test.js
+    ├── callback-crypto.test.js
+    ├── callback-inbound.test.js
     ├── channel-plugin.media-type.test.js
     ├── channel-plugin.notice.test.js
     ├── dynamic-agent.test.js

package/index.js

@@ -3,6 +3,8 @@ import { logger } from "./logger.js";
 import { wecomChannelPlugin } from "./wecom/channel-plugin.js";
 import { setOpenclawConfig, setRuntime } from "./wecom/state.js";
 import { buildReplyMediaGuidance } from "./wecom/ws-monitor.js";
+import { listAccountIds, resolveAccount } from "./wecom/accounts.js";
+import { createCallbackHandler } from "./wecom/callback-inbound.js";
 
 const plugin = {
   id: "wecom",
@@ -15,6 +17,20 @@ const plugin = {
     setOpenclawConfig(api.config);
     api.registerChannel({ plugin: wecomChannelPlugin });
 
+    // Register HTTP callback endpoints for all accounts that have callback config
+    for (const accountId of listAccountIds(api.config)) {
+      const account = resolveAccount(api.config, accountId);
+      if (!account?.callbackConfig) continue;
+      const { path: cbPath } = account.callbackConfig;
+      logger.info(`[CB] Registering callback endpoint for account=${accountId} path=${cbPath}`);
+      api.registerHttpRoute({
+        path: cbPath,
+        auth: "plugin",
+        match: "prefix",
+        handler: createCallbackHandler({ account, config: api.config, runtime: api.runtime }),
+      });
+    }
+
     api.on("before_prompt_build", (_event, ctx) => {
       if (ctx.channelId !== "wecom") {
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "2.0.2",
+    "version": "2.1.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",

package/wecom/accounts.js

@@ -157,6 +157,14 @@ function buildAccount(accountId, config, meta = {}) {
   const configured = Boolean(botId && secret);
   const agentConfigured = Boolean(agent.corpId && agent.corpSecret && agent.agentId);
 
+  const callbackRaw = isPlainObject(agent.callback) ? agent.callback : {};
+  const callbackToken = String(callbackRaw.token ?? "").trim();
+  const callbackAESKey = String(callbackRaw.encodingAESKey ?? "").trim();
+  const callbackPath = String(callbackRaw.path ?? "").trim() || "/api/channels/wecom/callback";
+  const callbackConfigured = Boolean(callbackToken && callbackAESKey && agent.corpId);
+  // "markdown" enables WeCom markdown format for agent API replies; default "markdown"
+  const agentReplyFormat = String(agent.replyFormat ?? "markdown").trim() === "text" ? "text" : "markdown";
+
   return {
     accountId,
     name: String(safeConfig.name ?? accountId ?? DEFAULT_ACCOUNT_ID).trim() || accountId,
@@ -171,7 +179,9 @@ function buildAccount(accountId, config, meta = {}) {
     storageMode: meta.storageMode ?? "dictionary",
     entryKey: meta.entryKey ?? accountId,
     agentConfigured,
+    callbackConfigured,
     webhooksConfigured: isPlainObject(safeConfig.webhooks) && Object.keys(safeConfig.webhooks).length > 0,
+    agentReplyFormat,
     agentCredentials: agentConfigured
       ? {
           corpId: String(agent.corpId),
@@ -179,6 +189,14 @@ function buildAccount(accountId, config, meta = {}) {
           agentId: agent.agentId,
         }
       : null,
+    callbackConfig: callbackConfigured
+      ? {
+          token: callbackToken,
+          encodingAESKey: callbackAESKey,
+          path: callbackPath,
+          corpId: String(agent.corpId),
+        }
+      : null,
   };
 }
 

package/wecom/agent-api.js

@@ -76,7 +76,8 @@ export async function getAccessToken(agent) {
  * @param {string} params.text
  */
 export async function agentSendText(params) {
-  const { agent, toUser, toParty, toTag, chatId, text } = params;
+  const { agent, toUser, toParty, toTag, chatId, text, format = "text" } = params;
+  const msgtype = format === "markdown" ? "markdown" : "text";
   const token = await getAccessToken(agent);
 
   const useChat = Boolean(chatId);
@@ -85,14 +86,14 @@ export async function agentSendText(params) {
     : `${AGENT_API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
 
   const body = useChat
-    ? { chatid: chatId, msgtype: "text", text: { content: text } }
+    ? { chatid: chatId, msgtype, [msgtype]: { content: text } }
     : {
         touser: toUser,
         toparty: toParty,
         totag: toTag,
-        msgtype: "text",
+        msgtype,
         agentid: agent.agentId,
-        text: { content: text },
+        [msgtype]: { content: text },
       };
 
   const res = await wecomFetch(url, {
@@ -103,7 +104,7 @@ export async function agentSendText(params) {
   const json = await res.json();
 
   if (json?.errcode !== 0) {
-    throw new Error(`agent send text failed: ${json?.errcode} ${json?.errmsg}`);
+    throw new Error(`agent send ${msgtype} failed: ${json?.errcode} ${json?.errmsg}`);
   }
 
   if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
@@ -114,7 +115,7 @@ export async function agentSendText(params) {
     ]
       .filter(Boolean)
       .join(", ");
-    throw new Error(`agent send text partial failure: ${details}`);
+    throw new Error(`agent send ${msgtype} partial failure: ${details}`);
   }
 }
 

package/wecom/callback-crypto.js

@@ -0,0 +1,80 @@
+/**
+ * WeCom self-built app callback cryptography utilities.
+ *
+ * Implements the signature verification and AES-256-CBC decryption required
+ * by the WeCom callback protocol:
+ *   https://developer.work.weixin.qq.com/document/path/90239
+ */
+
+import crypto from "node:crypto";
+
+/**
+ * Verify a WeCom callback request signature.
+ *
+ * Signature algorithm:
+ *   SHA1( sort([token, timestamp, nonce, msgEncrypt]).join("") )
+ * The result must equal the `msg_signature` query parameter.
+ *
+ * @param {object} params
+ * @param {string} params.token          - Callback token from account config
+ * @param {string} params.timestamp      - `timestamp` query parameter
+ * @param {string} params.nonce          - `nonce` query parameter
+ * @param {string} params.msgEncrypt     - The ciphertext extracted from the XML body
+ * @param {string} params.signature      - `msg_signature` query parameter to verify against
+ * @returns {boolean}
+ */
+export function verifyCallbackSignature({ token, timestamp, nonce, msgEncrypt, signature }) {
+  const items = [String(token), String(timestamp), String(nonce), String(msgEncrypt)].sort();
+  const digest = crypto.createHash("sha1").update(items.join("")).digest("hex");
+  return digest === String(signature);
+}
+
+/**
+ * Decrypt a WeCom AES-256-CBC encrypted callback message.
+ *
+ * Key derivation:
+ *   key = Base64Decode(encodingAESKey + "=")  → 32 bytes
+ *   iv  = key.slice(0, 16)
+ *
+ * Plaintext layout (after PKCS7 unpad):
+ *   [ 16 random bytes | 4-byte msgLen (big-endian) | msgXml | corpId ]
+ *
+ * @param {object} params
+ * @param {string} params.encodingAESKey - 43-char key from WeCom config
+ * @param {string} params.encrypted      - Base64-encoded ciphertext
+ * @returns {{ xml: string, corpId: string }}
+ */
+export function decryptCallbackMessage({ encodingAESKey, encrypted }) {
+  const key = Buffer.from(encodingAESKey + "=", "base64"); // 32 bytes
+  const iv = key.subarray(0, 16);
+  const ciphertext = Buffer.from(encrypted, "base64");
+
+  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+  decipher.setAutoPadding(false);
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+  // Strip PKCS7 padding
+  const padLen = decrypted[decrypted.length - 1];
+  if (padLen < 1 || padLen > 32) {
+    throw new Error(`Invalid PKCS7 padding byte: ${padLen}`);
+  }
+  const content = decrypted.subarray(0, decrypted.length - padLen);
+
+  // Strip 16-byte random prefix
+  const withoutRandom = content.subarray(16);
+
+  // Read 4-byte big-endian message length
+  if (withoutRandom.length < 4) {
+    throw new Error("Decrypted content too short");
+  }
+  const msgLen = withoutRandom.readUInt32BE(0);
+
+  if (withoutRandom.length < 4 + msgLen) {
+    throw new Error(`Decrypted content shorter than declared msgLen (${msgLen})`);
+  }
+
+  const xml = withoutRandom.subarray(4, 4 + msgLen).toString("utf8");
+  const corpId = withoutRandom.subarray(4 + msgLen).toString("utf8");
+
+  return { xml, corpId };
+}

package/wecom/callback-inbound.js

@@ -0,0 +1,618 @@
+/**
+ * WeCom self-built app HTTP callback inbound channel.
+ *
+ * Registers an HTTP endpoint that:
+ *   - Answers WeCom's GET URL-verification requests
+ *   - Receives POST message callbacks, decrypts them, and dispatches to the LLM
+ *
+ * Reply is sent via the Agent API (agentSendText / agentSendMedia) instead of
+ * the WebSocket, so this path works independently of the AI Bot WS connection.
+ */
+
+import path from "node:path";
+import { logger } from "../logger.js";
+import { agentSendText, agentUploadMedia, agentSendMedia } from "./agent-api.js";
+import { checkDmPolicy } from "./dm-policy.js";
+import { checkGroupPolicy } from "./group-policy.js";
+import { resolveWecomCommandAuthorized } from "./allow-from.js";
+import { checkCommandAllowlist, getCommandConfig, isWecomAdmin } from "./commands.js";
+import {
+  extractGroupMessageContent,
+  generateAgentId,
+  getDynamicAgentConfig,
+  shouldTriggerGroupResponse,
+  shouldUseDynamicAgent,
+} from "../dynamic-agent.js";
+import { ensureDynamicAgentListed } from "./workspace-template.js";
+import { normalizeThinkingTags } from "../think-parser.js";
+import { MessageDeduplicator, splitTextByByteLimit } from "../utils.js";
+import { recordInboundMessage, recordOutboundActivity } from "./runtime-telemetry.js";
+import { setConfigProxyUrl } from "./http.js";
+import { setApiBaseUrl } from "./constants.js";
+import { dispatchLocks, streamContext } from "./state.js";
+import {
+  CHANNEL_ID,
+  CALLBACK_INBOUND_MAX_BODY_BYTES,
+  CALLBACK_TIMESTAMP_TOLERANCE_S,
+  TEXT_CHUNK_LIMIT,
+  MESSAGE_PROCESS_TIMEOUT_MS,
+  MEDIA_IMAGE_PLACEHOLDER,
+  MEDIA_DOCUMENT_PLACEHOLDER,
+} from "./constants.js";
+import { verifyCallbackSignature, decryptCallbackMessage } from "./callback-crypto.js";
+import { downloadCallbackMedia } from "./callback-media.js";
+import {
+  buildInboundContext,
+  resolveChannelCore,
+  normalizeReplyPayload,
+  resolveReplyMediaLocalRoots,
+} from "./ws-monitor.js";
+
+const callbackDeduplicator = new MessageDeduplicator();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function withCallbackTimeout(promise, timeoutMs, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(label ?? `timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+  promise.catch(() => {});
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Read the POST body up to maxBytes. Returns null if the body exceeded the limit.
+ */
+async function readBody(req, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let oversize = false;
+
+    req.on("data", (chunk) => {
+      if (oversize) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        oversize = true;
+        req.destroy();
+        resolve(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => {
+      if (!oversize) {
+        resolve(Buffer.concat(chunks).toString("utf8"));
+      }
+    });
+
+    req.on("error", () => resolve(null));
+  });
+}
+
+/**
+ * Extract a CDATA or plain element value from a simple WeCom XML string.
+ * WeCom callback XML is well-defined; a full parser is not required.
+ */
+function extractXmlValue(xml, tag) {
+  const cdata = xml.match(new RegExp(`<${tag}><!\\[CDATA\\[([\\s\\S]*?)\\]\\]><\\/${tag}>`));
+  if (cdata) return cdata[1];
+  const plain = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`));
+  return plain ? plain[1] ?? null : null;
+}
+
+/**
+ * Parse a decrypted WeCom callback XML message into a normalised structure.
+ * Returns null for event frames (enter_chat, etc.) that carry no user content.
+ *
+ * @param {string} xml - Decrypted inner XML
+ * @returns {{ msgId, senderId, chatId, isGroupChat, text, mediaId, mediaType, voiceRecognition } | null}
+ */
+export function parseCallbackMessageXml(xml) {
+  const msgType = extractXmlValue(xml, "MsgType");
+
+  // Events (subscribe, click, enter_chat …) are not user messages
+  if (!msgType || msgType === "event") {
+    return null;
+  }
+
+  const msgId = extractXmlValue(xml, "MsgId") ?? String(Date.now());
+  const senderId = extractXmlValue(xml, "FromUserName") ?? "";
+  if (!senderId) return null;
+
+  // Self-built app basic callback: group chats are not natively supported;
+  // treat every message as a direct message.
+  const isGroupChat = false;
+  const chatId = senderId;
+
+  let text = null;
+  let mediaId = null;
+  let mediaType = null;
+  let voiceRecognition = null;
+
+  if (msgType === "text") {
+    text = extractXmlValue(xml, "Content") ?? "";
+  } else if (msgType === "image") {
+    mediaId = extractXmlValue(xml, "MediaId");
+    mediaType = "image";
+  } else if (msgType === "voice") {
+    mediaId = extractXmlValue(xml, "MediaId");
+    mediaType = "voice";
+    // `Recognition` is populated when WeCom ASR is enabled for the app
+    voiceRecognition = extractXmlValue(xml, "Recognition");
+    text = voiceRecognition || null;
+  } else if (msgType === "file") {
+    mediaId = extractXmlValue(xml, "MediaId");
+    mediaType = "file";
+  } else if (msgType === "video") {
+    mediaId = extractXmlValue(xml, "MediaId");
+    mediaType = "file"; // treat video as generic file attachment
+  } else {
+    // Unknown type: log and skip
+    logger.debug(`[CB] Unsupported callback MsgType="${msgType}", ignoring`);
+    return null;
+  }
+
+  return { msgId, senderId, chatId, isGroupChat, text, mediaId, mediaType, voiceRecognition };
+}
+
+// ---------------------------------------------------------------------------
+// Load a local reply-media file (LLM-generated MEDIA:/FILE: directives)
+// ---------------------------------------------------------------------------
+
+async function loadLocalReplyMedia(mediaUrl, config, agentId, runtime) {
+  const normalized = String(mediaUrl ?? "").trim();
+  if (!normalized.startsWith("/") && !normalized.startsWith("sandbox:")) {
+    throw new Error(`Unsupported callback reply media URL scheme: ${mediaUrl}`);
+  }
+
+  if (typeof runtime?.media?.loadWebMedia === "function") {
+    const localRoots = resolveReplyMediaLocalRoots(config, agentId);
+    const loaded = await runtime.media.loadWebMedia(normalized.replace(/^sandbox:\/{0,2}/, "/"), { localRoots });
+    const filename = loaded.fileName || path.basename(normalized.replace(/^sandbox:\/+/, "")) || "file";
+    return { buffer: loaded.buffer, filename, contentType: loaded.contentType || "" };
+  }
+
+  // Fallback when runtime.media is unavailable
+  const { readFile } = await import("node:fs/promises");
+  const localPath = normalized.replace(/^sandbox:\/{0,2}/, "");
+  const buffer = await readFile(localPath);
+  return { buffer, filename: path.basename(localPath) || "file", contentType: "" };
+}
+
+// ---------------------------------------------------------------------------
+// Core dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a parsed callback message: route, dispatch to LLM, and reply via
+ * Agent API.
+ *
+ * @param {object} params
+ * @param {object} params.parsedMsg  - Output of parseCallbackMessageXml()
+ * @param {object} params.account    - Resolved account object (from accounts.js)
+ * @param {object} params.config     - Full OpenClaw config
+ * @param {object} params.runtime    - OpenClaw runtime
+ */
+async function processCallbackMessage({ parsedMsg, account, config, runtime }) {
+  const { msgId, senderId, chatId, isGroupChat, text: rawText, mediaId, mediaType } = parsedMsg;
+  const core = resolveChannelCore(runtime);
+
+  // Deduplication (separate namespace from WS deduplicator to avoid cross-path conflicts)
+  const dedupKey = `cb:${account.accountId}:${msgId}`;
+  if (callbackDeduplicator.isDuplicate(dedupKey)) {
+    logger.debug(`[CB:${account.accountId}] Duplicate message ignored`, { msgId, senderId });
+    return;
+  }
+
+  recordInboundMessage({ accountId: account.accountId, chatId });
+
+  logger.info(`[CB:${account.accountId}] ← inbound`, {
+    senderId,
+    chatId,
+    msgId,
+    mediaType: mediaId ? mediaType : null,
+    textLength: rawText?.length ?? 0,
+    preview: rawText?.slice(0, 80) || (mediaId ? `[${mediaType}]` : ""),
+  });
+
+  // --- Policy checks ---
+
+  if (isGroupChat) {
+    const groupResult = checkGroupPolicy({ chatId, senderId, account, config });
+    if (!groupResult.allowed) return;
+  }
+
+  const dmResult = await checkDmPolicy({
+    senderId,
+    isGroup: isGroupChat,
+    account,
+    wsClient: null,
+    frame: null,
+    core,
+    sendReply: async ({ text }) => {
+      if (account.agentCredentials) {
+        await agentSendText({ agent: account.agentCredentials, toUser: senderId, text }).catch((err) =>
+          logger.warn(`[CB:${account.accountId}] DM policy reply failed: ${err.message}`),
+        );
+      }
+    },
+  });
+  if (!dmResult.allowed) return;
+
+  let text = rawText ?? "";
+
+  // Group mention gating (not typically reached since isGroupChat=false, but kept for future)
+  if (isGroupChat) {
+    if (!shouldTriggerGroupResponse(text, account.config)) {
+      return;
+    }
+    text = extractGroupMessageContent(text, account.config);
+  }
+
+  // --- Command allowlist ---
+  const senderIsAdmin = isWecomAdmin(senderId, account.config);
+  const commandAuthorized = resolveWecomCommandAuthorized({
+    cfg: config,
+    accountId: account.accountId,
+    senderId,
+  });
+  const commandCheck = checkCommandAllowlist(text, account.config);
+  if (commandCheck.isCommand && !commandCheck.allowed && !senderIsAdmin) {
+    if (account.agentCredentials) {
+      const blockMsg = getCommandConfig(account.config).blockMessage;
+      await agentSendText({ agent: account.agentCredentials, toUser: senderId, text: blockMsg }).catch(
+        (err) => logger.warn(`[CB:${account.accountId}] Command block reply failed: ${err.message}`),
+      );
+    }
+    return;
+  }
+
+  // --- Inbound media download ---
+  const mediaList = [];
+  if (mediaId && account.agentCredentials) {
+    try {
+      const downloaded = await downloadCallbackMedia({
+        agent: account.agentCredentials,
+        mediaId,
+        type: mediaType === "image" ? "image" : mediaType === "voice" ? "voice" : "file",
+        runtime,
+        config,
+      });
+      mediaList.push(downloaded);
+    } catch (error) {
+      logger.error(`[CB:${account.accountId}] Inbound media download failed: ${error.message}`);
+    }
+  }
+
+  const effectiveText = text;
+
+  // --- Route resolution ---
+  const peerKind = isGroupChat ? "group" : "dm";
+  const peerId = isGroupChat ? chatId : senderId;
+  const dynamicConfig = getDynamicAgentConfig(account.config);
+  const dynamicAgentId =
+    dynamicConfig.enabled &&
+    shouldUseDynamicAgent({ chatType: peerKind, config: account.config, senderIsAdmin })
+      ? generateAgentId(peerKind, peerId, account.accountId)
+      : null;
+
+  if (dynamicAgentId) {
+    await ensureDynamicAgentListed(dynamicAgentId, account.config.workspaceTemplate);
+  }
+
+  const route = core.routing.resolveAgentRoute({
+    cfg: config,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: { kind: peerKind, id: peerId },
+  });
+
+  const hasExplicitBinding =
+    Array.isArray(config?.bindings) &&
+    config.bindings.some(
+      (b) => b.match?.channel === CHANNEL_ID && b.match?.accountId === account.accountId,
+    );
+  if (dynamicAgentId && !hasExplicitBinding) {
+    route.agentId = dynamicAgentId;
+    route.sessionKey = `agent:${dynamicAgentId}:${peerKind}:${peerId}`;
+  }
+
+  // Build a body object that mirrors the WS frame.body structure expected by
+  // buildInboundContext, so we can reuse that shared helper directly.
+  const syntheticBody = {
+    msgid: msgId,
+    from: { userid: senderId },
+    chatid: isGroupChat ? chatId : senderId,
+    chattype: isGroupChat ? "group" : "single",
+    text: effectiveText ? { content: effectiveText } : undefined,
+  };
+
+  const { ctxPayload, storePath } = buildInboundContext({
+    runtime,
+    config,
+    account,
+    frame: null, // no WS frame on callback path
+    body: syntheticBody,
+    text: effectiveText,
+    mediaList,
+    route,
+    senderId,
+    chatId,
+    isGroupChat,
+  });
+  ctxPayload.CommandAuthorized = commandAuthorized;
+
+  void core.session
+    .recordSessionMetaFromInbound({
+      storePath,
+      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      ctx: ctxPayload,
+    })
+    .catch((err) => logger.error(`[CB] Session meta record failed: ${err.message}`));
+
+  // --- Dispatch ---
+  const state = { accumulatedText: "", replyMediaUrls: [] };
+  const streamId = `cb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  const runDispatch = async () => {
+    try {
+      await streamContext.run(
+        { streamId, streamKey: peerId, agentId: route.agentId, accountId: account.accountId },
+        async () => {
+          await core.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg: config,
+            // Disable block-streaming since Agent API replies are sent atomically
+            replyOptions: { disableBlockStreaming: true },
+            dispatcherOptions: {
+              deliver: async (payload) => {
+                const normalized = normalizeReplyPayload(payload);
+                state.accumulatedText += normalized.text;
+                for (const mediaUrl of normalized.mediaUrls) {
+                  if (!state.replyMediaUrls.includes(mediaUrl)) {
+                    state.replyMediaUrls.push(mediaUrl);
+                  }
+                }
+              },
+              onError: (error, info) => {
+                logger.error(`[CB] ${info.kind} reply block failed: ${error.message}`);
+              },
+            },
+          });
+        },
+      );
+
+      const finalText = normalizeThinkingTags(state.accumulatedText.trim()) || "模型暂时无法响应，请稍后重试。";
+
+      if (!account.agentCredentials) {
+        logger.warn(`[CB:${account.accountId}] No agent credentials configured; callback reply skipped`);
+        return;
+      }
+
+      const target = isGroupChat ? { chatId } : { toUser: senderId };
+
+      // Send reply text (chunked to stay within WeCom message size limits)
+      const chunks = splitTextByByteLimit(finalText, TEXT_CHUNK_LIMIT);
+      logger.info(`[CB:${account.accountId}] → outbound`, {
+        senderId,
+        chatId,
+        format: account.agentReplyFormat,
+        chunks: chunks.length,
+        totalLength: finalText.length,
+        preview: finalText.slice(0, 80),
+      });
+      for (const chunk of chunks) {
+        await agentSendText({
+          agent: account.agentCredentials,
+          ...target,
+          text: chunk,
+          format: account.agentReplyFormat,
+        });
+      }
+      recordOutboundActivity({ accountId: account.accountId });
+
+      // Send any LLM-generated media (MEDIA:/FILE: directives in reply)
+      for (const mediaUrl of state.replyMediaUrls) {
+        try {
+          const { buffer, filename, contentType } = await loadLocalReplyMedia(
+            mediaUrl,
+            config,
+            route.agentId,
+            runtime,
+          );
+          const agentMediaType = contentType.startsWith("image/") ? "image" : "file";
+          const uploadedMediaId = await agentUploadMedia({
+            agent: account.agentCredentials,
+            type: agentMediaType,
+            buffer,
+            filename,
+          });
+          await agentSendMedia({
+            agent: account.agentCredentials,
+            ...target,
+            mediaId: uploadedMediaId,
+            mediaType: agentMediaType,
+          });
+          recordOutboundActivity({ accountId: account.accountId });
+        } catch (mediaError) {
+          logger.error(`[CB:${account.accountId}] Failed to send reply media: ${mediaError.message}`);
+        }
+      }
+    } catch (error) {
+      logger.error(`[CB:${account.accountId}] Dispatch error: ${error.message}`);
+      if (account.agentCredentials) {
+        const target = isGroupChat ? { chatId } : { toUser: senderId };
+        try {
+          await agentSendText({
+            agent: account.agentCredentials,
+            ...target,
+            text: "处理消息时出错，请稍后再试。",
+            format: "text",
+          });
+        } catch (sendErr) {
+          logger.error(`[CB:${account.accountId}] Error fallback reply failed: ${sendErr.message}`);
+        }
+      }
+    }
+  };
+
+  // Serialise per-sender to prevent concurrent replies to the same user
+  const lockKey = `${account.accountId}:${peerId}`;
+  const previous = dispatchLocks.get(lockKey) ?? Promise.resolve();
+  const current = previous.then(runDispatch, runDispatch);
+  dispatchLocks.set(lockKey, current);
+  current.finally(() => {
+    if (dispatchLocks.get(lockKey) === current) {
+      dispatchLocks.delete(lockKey);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP handler factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an HTTP handler for a single WeCom account's callback endpoint.
+ *
+ * The handler is registered via `api.registerHttpRoute({ auth: "plugin" })` so
+ * WeCom's servers can POST to it directly without gateway authentication.
+ *
+ * @param {object} params
+ * @param {object} params.account  - Resolved account object with callbackConfig
+ * @param {object} params.config   - Full OpenClaw config
+ * @param {object} params.runtime  - OpenClaw runtime
+ * @returns {Function} HTTP handler: (req, res) => Promise<boolean|void>
+ */
+export function createCallbackHandler({ account, config, runtime }) {
+  const { token, encodingAESKey, corpId } = account.callbackConfig;
+
+  // Apply network config so wecomFetch uses the right proxy/base URL
+  const network = account.config.network ?? {};
+  setConfigProxyUrl(network.egressProxyUrl ?? "");
+  setApiBaseUrl(network.apiBaseUrl ?? "");
+
+  return async function callbackHandler(req, res) {
+    const rawUrl = req.url ?? "/";
+    const urlObj = new URL(rawUrl, "http://localhost");
+
+    const signature = urlObj.searchParams.get("msg_signature") ?? "";
+    const timestamp = urlObj.searchParams.get("timestamp") ?? "";
+    const nonce = urlObj.searchParams.get("nonce") ?? "";
+
+    // --- GET: WeCom URL ownership verification ---
+    if (req.method === "GET") {
+      const echostrCipher = urlObj.searchParams.get("echostr") ?? "";
+      if (!echostrCipher) {
+        res.writeHead(400);
+        res.end("missing echostr");
+        return true;
+      }
+      if (!verifyCallbackSignature({ token, timestamp, nonce, msgEncrypt: echostrCipher, signature })) {
+        logger.warn(`[CB:${account.accountId}] GET signature mismatch`);
+        res.writeHead(403);
+        res.end("forbidden");
+        return true;
+      }
+      try {
+        const { xml: plainEchostr } = decryptCallbackMessage({ encodingAESKey, encrypted: echostrCipher });
+        res.writeHead(200, { "Content-Type": "text/plain" });
+        res.end(plainEchostr);
+      } catch (err) {
+        logger.error(`[CB:${account.accountId}] GET echostr decrypt failed: ${err.message}`);
+        res.writeHead(500);
+        res.end("error");
+      }
+      return true;
+    }
+
+    // --- POST: message callback ---
+    if (req.method !== "POST") {
+      res.writeHead(405);
+      res.end("method not allowed");
+      return true;
+    }
+
+    const body = await readBody(req, CALLBACK_INBOUND_MAX_BODY_BYTES);
+    if (body === null) {
+      res.writeHead(413);
+      res.end("request body too large");
+      return true;
+    }
+
+    // Extract the encrypted payload from the outer XML wrapper
+    const encryptMatch = body.match(/<Encrypt><!\[CDATA\[([\s\S]*?)\]\]><\/Encrypt>/);
+    const msgEncrypt = encryptMatch?.[1];
+    if (!msgEncrypt) {
+      logger.warn(`[CB:${account.accountId}] No <Encrypt> field in POST body`);
+      res.writeHead(400);
+      res.end("bad request");
+      return true;
+    }
+
+    // Replay-attack protection: reject requests older than 5 minutes
+    const tsNum = Number(timestamp);
+    if (!Number.isFinite(tsNum) || Math.abs(Date.now() / 1000 - tsNum) > CALLBACK_TIMESTAMP_TOLERANCE_S) {
+      logger.warn(`[CB:${account.accountId}] Timestamp out of tolerance`, { timestamp });
+      res.writeHead(403);
+      res.end("forbidden");
+      return true;
+    }
+
+    // Signature verification
+    if (!verifyCallbackSignature({ token, timestamp, nonce, msgEncrypt, signature })) {
+      logger.warn(`[CB:${account.accountId}] POST signature mismatch`);
+      res.writeHead(403);
+      res.end("forbidden");
+      return true;
+    }
+
+    // Decrypt
+    let decryptedXml;
+    let callbackCorpId;
+    try {
+      const result = decryptCallbackMessage({ encodingAESKey, encrypted: msgEncrypt });
+      decryptedXml = result.xml;
+      callbackCorpId = result.corpId;
+    } catch (err) {
+      logger.error(`[CB:${account.accountId}] Decryption failed: ${err.message}`);
+      res.writeHead(400);
+      res.end("bad request");
+      return true;
+    }
+
+    // CorpId integrity check
+    if (callbackCorpId !== corpId) {
+      logger.warn(`[CB:${account.accountId}] CorpId mismatch (expected=${corpId} got=${callbackCorpId})`);
+      res.writeHead(403);
+      res.end("forbidden");
+      return true;
+    }
+
+    // Respond to WeCom immediately (WeCom requires a fast HTTP response)
+    res.writeHead(200, { "Content-Type": "text/plain" });
+    res.end("success");
+
+    // Process asynchronously so we don't block the HTTP response
+    const parsedMsg = parseCallbackMessageXml(decryptedXml);
+    if (!parsedMsg) {
+      // Event frame or unsupported type, already logged in parseCallbackMessageXml
+      return true;
+    }
+
+    withCallbackTimeout(
+      processCallbackMessage({ parsedMsg, account, config, runtime }),
+      MESSAGE_PROCESS_TIMEOUT_MS,
+      `Callback message processing timed out (msgId=${parsedMsg.msgId})`,
+    ).catch((err) => {
+      logger.error(`[CB:${account.accountId}] Failed to process callback message: ${err.message}`);
+    });
+
+    return true;
+  };
+}

package/wecom/callback-media.js

@@ -0,0 +1,76 @@
+/**
+ * WeCom self-built app callback media downloader.
+ *
+ * Downloads inbound media (image/voice/file) from WeCom via the
+ * Agent API `/cgi-bin/media/get` endpoint using the access token
+ * obtained from the self-built app credentials.
+ */
+
+import path from "node:path";
+import { logger } from "../logger.js";
+import { getAccessToken } from "./agent-api.js";
+import { wecomFetch } from "./http.js";
+import { AGENT_API_ENDPOINTS, CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS } from "./constants.js";
+
+/**
+ * Download a WeCom media file (image / voice / file) by MediaId via the
+ * self-built app access token and save it through the core media runtime.
+ *
+ * @param {object} params
+ * @param {object} params.agent   - { corpId, corpSecret, agentId }
+ * @param {string} params.mediaId - WeCom MediaId
+ * @param {"image"|"voice"|"file"} params.type - media type hint
+ * @param {object} params.runtime - OpenClaw runtime (for saveMediaBuffer)
+ * @param {object} params.config  - OpenClaw config (for mediaMaxMb)
+ * @returns {Promise<{ path: string, contentType: string }>}
+ */
+export async function downloadCallbackMedia({ agent, mediaId, type, runtime, config }) {
+  const token = await getAccessToken(agent);
+  const url = `${AGENT_API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+
+  const mediaMaxMb = config?.agents?.defaults?.mediaMaxMb ?? 5;
+  const maxBytes = mediaMaxMb * 1024 * 1024;
+
+  let response;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS);
+  try {
+    response = await wecomFetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  if (!response.ok) {
+    throw new Error(`WeCom media download failed: HTTP ${response.status} for mediaId=${mediaId}`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  const contentType =
+    response.headers.get("content-type") ||
+    (type === "image" ? "image/jpeg" : "application/octet-stream");
+
+  // Try to extract the filename from Content-Disposition
+  const disposition = response.headers.get("content-disposition") ?? "";
+  const filenameMatch = disposition.match(/filename[*\s]*=\s*(?:UTF-8''|")?([^";]+)/i);
+  const filename =
+    filenameMatch?.[1]?.trim() ||
+    (type === "image" ? `${mediaId}.jpg` : type === "voice" ? `${mediaId}.amr` : mediaId);
+
+  // Save via core media runtime when available
+  if (typeof runtime?.media?.saveMediaBuffer === "function") {
+    const saved = await runtime.media.saveMediaBuffer(buffer, contentType, "inbound", maxBytes, filename);
+    return { path: saved.path, contentType: saved.contentType };
+  }
+
+  // Fallback: write to OS temp dir
+  const { tmpdir } = await import("node:os");
+  const { writeFile } = await import("node:fs/promises");
+  const ext = path.extname(filename) || (type === "image" ? ".jpg" : ".bin");
+  const tempPath = path.join(
+    tmpdir(),
+    `wecom-cb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`,
+  );
+  await writeFile(tempPath, buffer);
+  logger.debug(`[CB] Media saved to temp path: ${tempPath}`);
+  return { path: tempPath, contentType };
+}

package/wecom/channel-plugin.js

@@ -308,6 +308,22 @@ export const wecomChannelPlugin = {
         allowFrom: { type: "array", items: { type: "string" } },
         groupPolicy: { enum: ["open", "allowlist", "disabled"] },
         groupAllowFrom: { type: "array", items: { type: "string" } },
+        agent: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            replyFormat: { enum: ["text", "markdown"] },
+            callback: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                token: { type: "string" },
+                encodingAESKey: { type: "string" },
+                path: { type: "string" },
+              },
+            },
+          },
+        },
       },
     },
     uiHints: {
@@ -316,6 +332,10 @@ export const wecomChannelPlugin = {
       websocketUrl: { label: "WebSocket URL", placeholder: DEFAULT_WS_URL },
       welcomeMessage: { label: "Welcome Message" },
       "agent.corpSecret": { sensitive: true, label: "Application Secret" },
+      "agent.replyFormat": { label: "Reply Format", placeholder: "text" },
+      "agent.callback.token": { label: "Callback Token" },
+      "agent.callback.encodingAESKey": { label: "Callback Encoding AES Key", sensitive: true },
+      "agent.callback.path": { label: "Callback Path", placeholder: "/api/channels/wecom/callback" },
     },
   },
   config: {
@@ -324,7 +344,8 @@ export const wecomChannelPlugin = {
     defaultAccountId: (cfg) => resolveDefaultAccountId(cfg),
     setAccountEnabled: ({ cfg, accountId, enabled }) => updateAccountConfig(cfg, accountId, { enabled }),
     deleteAccount: ({ cfg, accountId }) => deleteAccountConfig(cfg, accountId),
-    isConfigured: (account) => Boolean(account.botId && account.secret),
+    isConfigured: (account) =>
+      Boolean((account.botId && account.secret) || account.callbackConfigured),
     describeAccount,
     resolveAllowFrom: ({ cfg, accountId }) => resolveAllowFromForAccount(cfg, accountId),
     formatAllowFrom: ({ allowFrom }) => normalizeAllowFromEntries(allowFrom.map((entry) => String(entry))),

package/wecom/constants.js

@@ -90,6 +90,11 @@ export const TOKEN_REFRESH_BUFFER_MS = 60 * 1000;
 export const AGENT_API_REQUEST_TIMEOUT_MS = 15 * 1000;
 export const MAX_REQUEST_BODY_SIZE = 1024 * 1024;
 
+// Callback (self-built app HTTP inbound) constants
+export const CALLBACK_INBOUND_MAX_BODY_BYTES = 1 * 1024 * 1024;
+export const CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const CALLBACK_TIMESTAMP_TOLERANCE_S = 300;
+
 export function getWebhookBotSendUrl() {
   return `${resolveApiBaseUrl()}/cgi-bin/webhook/send`;
 }

package/wecom/ws-monitor.js

@@ -877,8 +877,9 @@ function buildInboundContext({
     OriginatingChannel: CHANNEL_ID,
     OriginatingTo: isGroupChat ? `${CHANNEL_ID}:group:${chatId}` : `${CHANNEL_ID}:${senderId}`,
     CommandAuthorized: true,
-    ReqId: frame.headers.req_id,
-    WeComFrame: frame,
+    // frame is null for callback-inbound path; use body.msgid as fallback
+    ReqId: frame?.headers?.req_id ?? body?.msgid ?? "",
+    WeComFrame: frame ?? null,
   };
 
   if (mediaList.length > 0) {
@@ -932,6 +933,17 @@ async function processWsMessage({ frame, account, config, runtime, wsClient }) {
   const originalText = textParts.join("\n").trim();
   let text = originalText;
 
+  logger.info(`[WS:${account.accountId}] ← inbound`, {
+    senderId,
+    chatId,
+    isGroupChat,
+    messageId,
+    textLength: originalText.length,
+    imageCount: imageUrls.length,
+    fileCount: fileUrls.length,
+    preview: originalText.slice(0, 80) || (imageUrls.length ? "[image]" : fileUrls.length ? "[file]" : ""),
+  });
+
   if (!text && quoteContent) {
     text = quoteContent;
   }
@@ -1542,3 +1554,11 @@ export const wsMonitorTesting = {
 };
 
 export { buildReplyMediaGuidance };
+
+// Shared internals used by callback-inbound.js
+export {
+  buildInboundContext,
+  resolveChannelCore,
+  normalizeReplyPayload,
+  resolveReplyMediaLocalRoots,
+};