@kyan-du/agent-wechat-openclaw 0.14.3 → 0.14.5

package/dist/index.js

@@ -5304,6 +5304,15 @@ var downloadFileParamsSchema = external_exports.object({
 var downloadFileResultSchema = openChatResultSchema.extend({
   clicked: external_exports.boolean().optional()
 });
+var materializeChatHistoryParamsSchema = external_exports.object({
+  chatId: external_exports.string().min(1),
+  title: external_exports.string().min(1).optional(),
+  localId: external_exports.number().int().optional(),
+  executionTimeoutMs: external_exports.number().int().positive().optional()
+});
+var materializeChatHistoryResultSchema = openChatResultSchema.extend({
+  clicked: external_exports.boolean().optional()
+});
 var idempotencyKeySchema = external_exports.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/);
 var forwardedMessageNodeSchema = external_exports.lazy(() => external_exports.object({
   sender: external_exports.string().optional(),
@@ -5417,7 +5426,8 @@ var mediaResultSchema = external_exports.object({
   format: external_exports.string(),
   filename: external_exports.string(),
   source: external_exports.enum(["original", "thumbnail"]).optional(),
-  errorCode: external_exports.string().optional()
+  errorCode: external_exports.string().optional(),
+  items: external_exports.array(external_exports.lazy(() => mediaResultSchema)).optional()
 });
 var agentConfigSchema = external_exports.object({
   maxTurns: external_exports.number().int().positive().default(30),
@@ -5501,6 +5511,17 @@ var WeChatClient = class {
       await throwHttpError(res);
     return res.json();
   }
+  async put(path, body, signal) {
+    const res = await fetch(`${this.base}${path}`, {
+      method: "PUT",
+      headers: this.headers,
+      body: body != null ? JSON.stringify(body) : void 0,
+      signal
+    });
+    if (!res.ok)
+      await throwHttpError(res);
+    return res.json();
+  }
   // ---- Status ----
   async status() {
     return this.get("/api/status");
@@ -5522,12 +5543,18 @@ var WeChatClient = class {
     return this.post("/api/status/auth/reset");
   }
   // ---- Chats ----
-  async listChatsPage(limit, cursor, unreadOnly) {
-    const page = await this.get(`/api/chats${qs({ limit, cursor, unreadOnly })}`);
+  async listChatsPage(limit, cursor, unreadOnly, interestOnly) {
+    const page = await this.get(`/api/chats${qs({ limit, cursor, unreadOnly, interestOnly })}`);
     if (page.errorCode)
       throw new WeChatHttpError(400, "Bad Request", page.errorCode, page.errorCode);
     return page;
   }
+  async getMonitorInterest() {
+    return this.get("/api/interest");
+  }
+  async setMonitorInterest(interest) {
+    return this.put("/api/interest", interest);
+  }
   async listChats(limit) {
     return (await this.listChatsPage(limit)).items;
   }
@@ -5546,6 +5573,10 @@ var WeChatClient = class {
   async downloadFile(chatId, filename, signal, executionTimeoutMs) {
     return this.post(`/api/chats/${encodeURIComponent(chatId)}/download-file${qs({ filename, executionTimeoutMs })}`, void 0, signal);
   }
+  async materializeChatHistory(chatId, options, signal) {
+    const { title, localId, executionTimeoutMs } = options ?? {};
+    return this.post(`/api/chats/${encodeURIComponent(chatId)}/materialize-chat-history${qs({ title, localId, executionTimeoutMs })}`, void 0, signal);
+  }
   async listGroupMembersPage(groupId, limit, cursor) {
     const page = groupMembersPageSchema.parse(await this.get(`/api/groups/${encodeURIComponent(groupId)}/members${qs({ limit, cursor })}`));
     if (page.errorCode)
@@ -5671,6 +5702,65 @@ var WeChatClient = class {
 // src/monitor.ts
 import { createChannelMessageReplyPipeline as createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-outbound";
 
+// src/monitor-interest.ts
+function normalizeAllowFrom(values) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of values ?? []) {
+    let id = String(entry).trim();
+    if (!id) continue;
+    if (id !== "*") {
+      id = id.replace(/^(agent-wechat|wechat):/i, "").trim();
+    }
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+function buildMonitorInterest(account) {
+  return {
+    dmPolicy: account.dmPolicy ?? "disabled",
+    dmAllowFrom: normalizeAllowFrom(account.allowFrom),
+    groupPolicy: account.groupPolicy ?? "allowlist",
+    groupAllowFrom: normalizeAllowFrom(account.groupAllowFrom),
+    includeSystemFeeds: true
+  };
+}
+function monitorInterestFingerprint(interest) {
+  return JSON.stringify({
+    dmPolicy: interest.dmPolicy,
+    dmAllowFrom: [...interest.dmAllowFrom ?? []].sort(),
+    groupPolicy: interest.groupPolicy ?? "allowlist",
+    groupAllowFrom: [...interest.groupAllowFrom ?? []].sort(),
+    includeSystemFeeds: interest.includeSystemFeeds !== false
+  });
+}
+function shouldListChatsInterestOnly(interest) {
+  return interest.dmPolicy === "allowlist" || interest.dmPolicy === "disabled";
+}
+async function ensureMonitorInterestSynced(client, account, log) {
+  const interest = buildMonitorInterest(account);
+  const desiredFp = monitorInterestFingerprint(interest);
+  try {
+    const current = await client.getMonitorInterest();
+    const serverInterest = current.interest;
+    if (serverInterest && monitorInterestFingerprint(serverInterest) === desiredFp) {
+      return { interest, synced: true };
+    }
+    await client.setMonitorInterest(interest);
+    log?.info?.(
+      `[wechat:${account.accountId}] Synced monitor interest to agent-server (dmPolicy=${interest.dmPolicy}, dmAllowFrom=${interest.dmAllowFrom.length})`
+    );
+    return { interest, synced: true };
+  } catch (err) {
+    log?.error?.(
+      `[wechat:${account.accountId}] Failed to sync monitor interest: ${err}`
+    );
+    return { interest, synced: false };
+  }
+}
+
 // src/catch-up.ts
 function recoveryCursor(selection) {
   return selection.cursor;
@@ -5824,7 +5914,7 @@ async function listInitialMonitorChatSnapshot(client, state, pageBudget = DEFAUL
   const chats = [];
   let cursor;
   for (let pages = 0; pages < pageBudget; pages += 1) {
-    const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, cursor);
+    const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, cursor, void 0, state.interestOnly);
     chats.push(...page.items);
     cursor = page.nextCursor;
     if (!cursor) {
@@ -5837,7 +5927,7 @@ async function listInitialMonitorChatSnapshot(client, state, pageBudget = DEFAUL
 }
 async function listNextMonitorChatPage(client, state) {
   const isInitialSnapshot = !state.initialScanComplete;
-  const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, state.cursor);
+  const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, state.cursor, void 0, state.interestOnly);
   state.cursor = page.nextCursor;
   if (!page.nextCursor) {
     state.initialScanComplete = true;
@@ -6520,9 +6610,12 @@ function safeInboundFilename(raw) {
   const cleaned = [...base].filter((char) => char >= " " && char !== "\x7F" && char !== "/" && char !== "\\").slice(0, MAX_FILENAME_CHARS).join("").replace(/^[.\s]+|[.\s]+$/g, "");
   return cleaned || void 0;
 }
-var SUPPORTED_FILE_FORMATS = /* @__PURE__ */ new Set(["pdf"]);
+var SUPPORTED_FILE_FORMATS = /* @__PURE__ */ new Set(["pdf", "docx"]);
 function documentMimeFromMagic(buf) {
   if (buf.length >= 5 && buf.toString("ascii", 0, 5) === "%PDF-") return "application/pdf";
+  if (buf.length >= 4 && buf[0] === 80 && buf[1] === 75 && (buf[2] === 3 || buf[2] === 5 || buf[2] === 7) && buf[3] === 4 && buf.includes(Buffer.from("word/document.xml", "ascii"))) {
+    return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+  }
   return void 0;
 }
 function binaryMimeFromMagic(buf) {
@@ -6778,7 +6871,11 @@ async function validateInboundMedia(result) {
     if (buffer.length > MAX_FILE_BYTES) return { ok: false, code: "MEDIA_FILE_TOO_LARGE" };
     if (!safeInboundFilename(result.filename)) return { ok: false, code: "MEDIA_FILENAME_INVALID" };
     if (!SUPPORTED_FILE_FORMATS.has(format)) return { ok: false, code: "MEDIA_FILE_TYPE_MISMATCH" };
-    if (documentMimeFromMagic(buffer) !== "application/pdf") {
+    const detected = documentMimeFromMagic(buffer);
+    if (format === "pdf" && detected !== "application/pdf") {
+      return { ok: false, code: "MEDIA_FILE_TYPE_MISMATCH" };
+    }
+    if (format === "docx" && detected !== "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
       return { ok: false, code: "MEDIA_FILE_TYPE_MISMATCH" };
     }
   }
@@ -6787,20 +6884,71 @@ async function validateInboundMedia(result) {
 function safeBodyAfterKnownMediaFailure(baseType, content) {
   return baseType === 3 ? "[Image unavailable]" : content;
 }
+function formatType49MediaFailureBody(content, mediaErrorCode) {
+  const text = content || "File attachment";
+  return `${text}
+[Attachment unavailable: ${mediaErrorCode}]`;
+}
 
 // src/inbound-media-poll.ts
+var DOWNLOADABLE_MEDIA_TYPES = /* @__PURE__ */ new Set([3, 34, 43]);
+var CHAT_HISTORY_APPMSG_TYPE = 19;
+function isWeChatChatHistoryMessage(msg) {
+  if (msg.forwarded) return true;
+  const content = msg.content ?? "";
+  if (content.startsWith("[Chat History]")) return true;
+  const baseType = msg.type & 2147483647;
+  if (baseType !== 49) return false;
+  const packedSubtype = Math.floor(msg.type / 4294967296);
+  if (packedSubtype === CHAT_HISTORY_APPMSG_TYPE) return true;
+  return /<type>\s*19\s*<\/type>/.test(content);
+}
+function shouldPollInboundMedia(msg) {
+  const baseType = msg.type & 2147483647;
+  if (DOWNLOADABLE_MEDIA_TYPES.has(baseType)) return true;
+  return baseType === 49;
+}
+function nestedChatHistoryMedia(result) {
+  return (result?.items ?? []).filter(
+    (item) => Boolean(item?.data) && Boolean(item?.type) && item.type !== "unsupported"
+  );
+}
+function isUnsupportedInboundMedia(result) {
+  return result?.type === "unsupported";
+}
+function mediaFlagsFromPollResult(result, baseType) {
+  if (nestedChatHistoryMedia(result).length > 0) {
+    return { hasMedia: true };
+  }
+  if (result && result.data && result.type !== "unsupported") {
+    return { hasMedia: true };
+  }
+  if (isUnsupportedInboundMedia(result)) {
+    return { hasMedia: false };
+  }
+  if (result?.errorCode || result && result.type !== "unsupported" || DOWNLOADABLE_MEDIA_TYPES.has(baseType)) {
+    return {
+      hasMedia: true,
+      mediaErrorCode: result?.errorCode ?? "MEDIA_DOWNLOAD_UNAVAILABLE"
+    };
+  }
+  return { hasMedia: false };
+}
 var RETRYABLE_MEDIA_ERRORS = /* @__PURE__ */ new Set([
   "MEDIA_NOT_DOWNLOADED",
   "IMAGE_RESOURCE_UNAVAILABLE",
   "FILE_NOT_DOWNLOADED",
   "FILE_NOT_STABLE",
   "VOICE_NOT_DOWNLOADED",
-  "IMAGE_NOT_STABLE"
+  "IMAGE_NOT_STABLE",
+  "CHAT_HISTORY_NOT_MATERIALIZED"
 ]);
 var DEFAULT_MEDIA_POLL_ATTEMPTS = 6;
 var DEFAULT_MEDIA_POLL_INTERVAL_MS = 500;
+var CHAT_HISTORY_MEDIA_POLL_INTERVAL_MS = 1e3;
 var IMAGE_MATERIALIZATION_OPEN_CHAT_TIMEOUT_MS = 400;
 var FILE_MATERIALIZATION_CLICK_TIMEOUT_MS = 8e3;
+var CHAT_HISTORY_MATERIALIZATION_CLICK_TIMEOUT_MS = 25e3;
 function shouldTriggerMediaMaterialization(result) {
   return result.type === "image" || result.type === "file" || result.type === "pending";
 }
@@ -6834,9 +6982,58 @@ function triggerFileBubbleClick(client, chatId, result, attempt, options) {
   const clicked = Promise.resolve(client.downloadFile(chatId, filename, void 0, timeoutMs));
   void clicked.catch(() => void 0);
 }
+function shouldTriggerChatHistoryMaterialization(result) {
+  if (result.errorCode === "CHAT_HISTORY_NOT_MATERIALIZED") return true;
+  if (result.type === "pending" && result.errorCode === "IMAGE_RESOURCE_UNAVAILABLE") return true;
+  if (result.type === "pending" && !result.items?.some((item) => item?.data)) return true;
+  return false;
+}
+function triggerChatHistoryMaterialize(client, chatId, result, attempt, options) {
+  const timeoutMs = options?.timeoutMs ?? CHAT_HISTORY_MATERIALIZATION_CLICK_TIMEOUT_MS;
+  options?.log?.info?.(
+    `[wechat:media] triggering chat-history materialize attempt=${attempt} title=${options?.title ?? ""} localId=${options?.localId ?? ""} skipOpen=${options?.skipOpen === true}`
+  );
+  if (!client.materializeChatHistory) {
+    throw Object.assign(new Error("CHAT_HISTORY_MATERIALIZE_TRIGGER_UNAVAILABLE"), {
+      code: "CHAT_HISTORY_MATERIALIZE_TRIGGER_UNAVAILABLE"
+    });
+  }
+  const clicked = Promise.resolve(
+    client.materializeChatHistory(
+      chatId,
+      {
+        title: options?.title,
+        localId: options?.localId,
+        executionTimeoutMs: timeoutMs
+      },
+      void 0
+    )
+  );
+  void clicked.catch(() => void 0);
+}
+function createChatHistoryMaterializationTrigger(client, chatId, options) {
+  return async (result, attempt) => {
+    if (!shouldTriggerChatHistoryMaterialization(result) || !options?.title?.trim()) return;
+    triggerChatHistoryMaterialize(client, chatId, result, attempt, options);
+  };
+}
+function chatHistoryTitleFromMessage(msg) {
+  const fromForwarded = msg.forwarded?.title?.trim();
+  if (fromForwarded) return fromForwarded;
+  const content = msg.content ?? "";
+  const en = content.match(/^\[Chat History\]\s*([^\n]+)/);
+  if (en?.[1]?.trim()) return en[1].trim();
+  const zh = content.match(/^\[聊天记录\]\s*([^\n]+)/);
+  return zh?.[1]?.trim() || void 0;
+}
 function createMediaMaterializationTrigger(client, chatId, options) {
   const timeoutMs = options?.timeoutMs ?? IMAGE_MATERIALIZATION_OPEN_CHAT_TIMEOUT_MS;
   return async (result, attempt) => {
+    if (result.errorCode === "CHAT_HISTORY_NOT_MATERIALIZED") {
+      if (!options?.title?.trim()) return;
+      triggerChatHistoryMaterialize(client, chatId, result, attempt, options);
+      return;
+    }
     if (!shouldTriggerMediaMaterialization(result)) return;
     if (isFileMaterialization(result)) {
       triggerFileBubbleClick(client, chatId, result, attempt, options);
@@ -6847,6 +7044,16 @@ function createMediaMaterializationTrigger(client, chatId, options) {
 }
 function mediaMaterializationTriggerForMessage(opts) {
   const baseType = opts.messageType & 2147483647;
+  if (opts.chatHistory) {
+    const extra = typeof opts.chatHistory === "object" ? opts.chatHistory : {};
+    return createChatHistoryMaterializationTrigger(opts.client, opts.chatId, {
+      log: opts.log,
+      timeoutMs: opts.timeoutMs ?? CHAT_HISTORY_MATERIALIZATION_CLICK_TIMEOUT_MS,
+      skipOpen: opts.skipOpen,
+      title: extra.title,
+      localId: extra.localId
+    });
+  }
   if (baseType !== 3 && baseType !== 49) return void 0;
   return createMediaMaterializationTrigger(opts.client, opts.chatId, {
     log: opts.log,
@@ -6878,6 +7085,15 @@ function isRetryable(result) {
   if (result.errorCode !== void 0) return RETRYABLE_MEDIA_ERRORS.has(result.errorCode);
   return result.type === "pending";
 }
+function chatHistoryMediaPollWindow(opts) {
+  const intervalMs = Math.max(1, opts?.intervalMs ?? CHAT_HISTORY_MEDIA_POLL_INTERVAL_MS);
+  const timeoutMs = opts?.timeoutMs ?? CHAT_HISTORY_MATERIALIZATION_CLICK_TIMEOUT_MS;
+  const maxAttempts = Math.max(
+    DEFAULT_MEDIA_POLL_ATTEMPTS,
+    Math.ceil(timeoutMs / intervalMs) + 1
+  );
+  return { maxAttempts, intervalMs };
+}
 async function pollMedia(client, chatId, localId, log, maxAttempts = DEFAULT_MEDIA_POLL_ATTEMPTS, intervalMs = DEFAULT_MEDIA_POLL_INTERVAL_MS, onRetryTrigger) {
   let lastResult;
   let triggerUsed = false;
@@ -7159,6 +7375,9 @@ function loadFile(path) {
 function inboundEventId(accountId, chatId, message) {
   return createHash("sha256").update(`${accountId}\0${chatId}\0${cursorMessageKey(message)}`).digest("hex");
 }
+function nestedMediaEventId(parentEventId, item) {
+  return createHash("sha256").update(JSON.stringify(["nested-media", parentEventId, item.type ?? "", item.filename ?? ""])).digest("hex");
+}
 var InboundEventLedger = class {
   path;
   entries = /* @__PURE__ */ new Map();
@@ -7533,9 +7752,29 @@ function applyEmptyUnreadSkip(chatId, opts) {
   opts.backoff.set(chatId, { nextRetryAt: now + backoffMs, retryCount });
   return { seededLastSeen, backoffMs };
 }
+function stickyUnreadTip(chat) {
+  return `${chat.lastMsgLocalId ?? ""}:${chat.unreadCount ?? 0}`;
+}
+function isStickyUnclearedAcked(chat, acked) {
+  const chatId = chat.username ?? chat.id;
+  return acked.get(chatId) === stickyUnreadTip(chat);
+}
+function ackStickyUnclearedUnread(chatId, chat, acked, backoff, now = Date.now()) {
+  const tip = stickyUnreadTip(chat);
+  acked.set(chatId, tip);
+  const retryCount = (backoff.get(chatId)?.retryCount ?? 0) + 1;
+  const backoffMs = Math.min(
+    EMPTY_UNREAD_BACKOFF_MAX_MS,
+    EMPTY_UNREAD_BACKOFF_MS * 2 ** Math.min(retryCount - 1, 6)
+  );
+  backoff.set(chatId, { nextRetryAt: now + backoffMs, retryCount });
+  return { tip, backoffMs };
+}
+function isOpenImChat(chatId) {
+  return chatId.includes("@openim");
+}
 
 // src/monitor.ts
-var MEDIA_TYPES = /* @__PURE__ */ new Set([3, 34, 43]);
 var HISTORY_CONTEXT_MARKER = "[Chat messages since your last reply - for context]";
 var CURRENT_MESSAGE_MARKER = "[Current message - respond to this]";
 function sleep(ms, signal) {
@@ -7589,6 +7828,7 @@ async function startWeChatMonitor(opts) {
   };
   trimPendingResetRetries(retryState);
   const newsappHandled = /* @__PURE__ */ new Map();
+  const stickyUnreadAck = /* @__PURE__ */ new Map();
   const groupHistory = /* @__PURE__ */ new Map();
   const GROUP_HISTORY_LIMIT = 50;
   let lastAuthCheck = 0;
@@ -7604,6 +7844,13 @@ async function startWeChatMonitor(opts) {
   while (!abortSignal.aborted) {
     try {
       const cfg = getWeChatRuntime().config.current();
+      const liveAccountForInterest = resolveWeChatAccount(cfg, account.accountId) ?? account;
+      const { interest: nextInterest, synced: interestSynced } = await ensureMonitorInterestSynced(
+        client,
+        liveAccountForInterest,
+        log
+      );
+      chatScanState.interestOnly = shouldListChatsInterestOnly(nextInterest) && interestSynced;
       const now = Date.now();
       if (now - lastMediaCleanup >= MEDIA_RETENTION_MS / 4) {
         lastMediaCleanup = now;
@@ -7689,6 +7936,7 @@ async function startWeChatMonitor(opts) {
       const unreadChats = chats.filter((c) => {
         const chatId = c.username ?? c.id;
         if (isEmptyUnreadBackoffActive(emptyUnreadBackoff, chatId)) return false;
+        if (isStickyUnclearedAcked(c, stickyUnreadAck)) return false;
         if (c.unreadCount <= 0) return false;
         if (isNewsappChat(c)) return true;
         return !isOfficialAccount(chatId);
@@ -7703,16 +7951,23 @@ async function startWeChatMonitor(opts) {
         chats,
         retryState,
         Date.now(),
-        (chat) => !isNewsappChat(chat) || newsappHandled.get(chat.username ?? chat.id) !== `${chat.lastMsgLocalId ?? ""}:${chat.lastMessagePreview?.trim() ?? ""}`
+        (chat) => {
+          if (isStickyUnclearedAcked(chat, stickyUnreadAck)) return false;
+          if (!isNewsappChat(chat)) return true;
+          return newsappHandled.get(chat.username ?? chat.id) !== `${chat.lastMsgLocalId ?? ""}:${chat.lastMessagePreview?.trim() ?? ""}`;
+        }
       );
       for (const chatId of chatsToProcess.keys()) {
         if (isOfficialAccount(chatId) && chatId !== "newsapp" || isEmptyUnreadBackoffActive(emptyUnreadBackoff, chatId)) {
           chatsToProcess.delete(chatId);
         }
       }
-      if (unreadChats.length > 0) {
+      const actionableUnread = unreadChats.filter(
+        (c) => chatsToProcess.has(c.username ?? c.id)
+      );
+      if (actionableUnread.length > 0) {
         log?.info?.(
-          `[wechat:${account.accountId}] ${unreadChats.length} chat(s) with unreads`
+          `[wechat:${account.accountId}] ${actionableUnread.length} chat(s) with unreads`
         );
       }
       let deferredThisTick = 0;
@@ -7731,6 +7986,7 @@ async function startWeChatMonitor(opts) {
             inboundLedger,
             mediaPipeline,
             emptyUnreadBackoff,
+            stickyUnreadAck,
             account,
             cfg,
             log,
@@ -7780,6 +8036,7 @@ async function startWeChatMonitor(opts) {
           inboundLedger,
           mediaPipeline,
           emptyUnreadBackoff,
+          stickyUnreadAck,
           account,
           cfg,
           log,
@@ -7849,30 +8106,75 @@ async function prepareMessage(client, mediaPipeline, msg, chatId, chat, liveAcco
   let mediaMime;
   let mediaHash;
   let mediaPreviewPath;
+  let mediaPaths;
+  let mediaMimes;
   let mediaSource;
   let mediaErrorCode;
   let hasMedia = false;
   const baseType = msg.type & 2147483647;
-  const mayHaveMedia = MEDIA_TYPES.has(baseType) || baseType === 49;
+  const isChatHistory = isWeChatChatHistoryMessage(msg);
+  const mayHaveMedia = shouldPollInboundMedia(msg);
   if (mayHaveMedia) {
     log?.info?.(`[wechat:${liveAccount.accountId}] Checking media for msg ${msg.localId} (type ${baseType})`);
     try {
+      const chatHistoryPoll = isChatHistory ? chatHistoryMediaPollWindow() : void 0;
       const result = await pollMedia(
         client,
         chatId,
         msg.localId,
         log,
-        void 0,
-        void 0,
+        chatHistoryPoll?.maxAttempts,
+        chatHistoryPoll?.intervalMs,
         mediaMaterializationTriggerForMessage({
           client,
           chatId,
           messageType: baseType,
           log,
-          skipOpen
+          skipOpen,
+          chatHistory: isChatHistory ? {
+            title: chatHistoryTitleFromMessage(msg),
+            localId: msg.localId
+          } : void 0
         })
       );
-      if (result && result.data && result.type !== "unsupported") {
+      const nestedItems = nestedChatHistoryMedia(result);
+      if (nestedItems.length > 0) {
+        const savedPaths = [];
+        const savedMimes = [];
+        for (const [index, item] of nestedItems.entries()) {
+          const saved = await mediaPipeline.process(
+            item,
+            {
+              eventId: nestedMediaEventId(inboundEventId(liveAccount.accountId, chatId, msg), item),
+              chatId,
+              localId: msg.localId
+            },
+            async (buffer, mime, filename) => core.channel.media.saveMediaBuffer(buffer, mime, "inbound", void 0, filename),
+            async (buffer, mime, filename) => core.channel.media.saveMediaBuffer(buffer, mime, "inbound", void 0, filename),
+            async (path) => unlink(path)
+          );
+          if (!saved.ok) {
+            log?.error?.(`[wechat:media] nested chat-history media rejected index=${index} code=${saved.code}`);
+            continue;
+          }
+          if (!saved.originalPath || savedPaths.includes(saved.originalPath)) continue;
+          savedPaths.push(saved.originalPath);
+          savedMimes.push(saved.mime);
+          if (!mediaPath) {
+            mediaPath = saved.originalPath;
+            mediaMime = saved.mime;
+            mediaHash = saved.hash;
+            mediaPreviewPath = saved.previewPath;
+            mediaSource = item.source;
+          }
+        }
+        if (savedPaths.length > 0) {
+          hasMedia = true;
+          mediaPaths = savedPaths;
+          mediaMimes = savedMimes;
+          log?.info?.(`[wechat:media] nested chat-history media saved count=${savedPaths.length}`);
+        }
+      } else if (result && result.data && result.type !== "unsupported") {
         hasMedia = true;
         mediaSource = result.source;
         log?.info?.(`[wechat:media] inbound media received type=${result.type} format=${result.format}`);
@@ -7893,15 +8195,22 @@ async function prepareMessage(client, mediaPipeline, msg, chatId, chat, liveAcco
           mediaPreviewPath = saved.previewPath;
           log?.info?.(`[wechat:media] inbound media saved hash=${saved.hash}${saved.previewPath ? " preview=present" : ""}`);
         }
-      } else if (result?.errorCode || result && result.type !== "unsupported" || MEDIA_TYPES.has(baseType)) {
-        hasMedia = true;
-        mediaErrorCode = result?.errorCode ?? "MEDIA_DOWNLOAD_UNAVAILABLE";
-        log?.info?.(`[wechat:media] inbound media unavailable code=${mediaErrorCode}`);
+      } else {
+        const flags = mediaFlagsFromPollResult(result, baseType);
+        hasMedia = flags.hasMedia;
+        mediaErrorCode = isChatHistory ? void 0 : flags.mediaErrorCode;
+        if (mediaErrorCode) {
+          log?.info?.(`[wechat:media] inbound media unavailable code=${mediaErrorCode}`);
+        }
       }
     } catch (err) {
-      hasMedia = true;
-      mediaErrorCode = "MEDIA_DOWNLOAD_FAILED";
-      log?.error?.("[wechat:media] inbound media failed code=MEDIA_DOWNLOAD_FAILED");
+      if (isChatHistory) {
+        log?.error?.("[wechat:media] nested chat-history media failed code=MEDIA_DOWNLOAD_FAILED");
+      } else {
+        hasMedia = true;
+        mediaErrorCode = "MEDIA_DOWNLOAD_FAILED";
+        log?.error?.("[wechat:media] inbound media failed code=MEDIA_DOWNLOAD_FAILED");
+      }
     }
   }
   const timestamp = new Date(msg.timestamp).getTime();
@@ -7918,10 +8227,8 @@ async function prepareMessage(client, mediaPipeline, msg, chatId, chat, liveAcco
     } else if (!mediaMime.startsWith("image/") && !mediaMime.startsWith("audio/")) {
       rawBody = `[File: ${rawBody}]`;
     }
-  } else if (mediaErrorCode && baseType === 49) {
-    const text = msg.content || "File attachment";
-    rawBody = `${text}
-[Attachment unavailable: ${mediaErrorCode}]`;
+  } else if (mediaErrorCode && baseType === 49 && !isChatHistory) {
+    rawBody = formatType49MediaFailureBody(msg.content || "", mediaErrorCode);
   }
   if (mediaSource === "thumbnail") {
     rawBody = rawBody ? `${rawBody}
@@ -7950,6 +8257,8 @@ ${replyBlock}` : replyBlock;
     mediaMime,
     mediaHash,
     mediaPreviewPath,
+    mediaPaths,
+    mediaMimes,
     senderName,
     senderId,
     isGroup,
@@ -7981,9 +8290,11 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
   const core = getWeChatRuntime();
   const lastMsg = segment[segment.length - 1];
   const { isGroup, senderId, senderName, timestamp, rawBody, commandBody, msg } = lastMsg;
-  const mediaMsg = segment.find((pm) => pm.mediaPath);
-  const mediaPath = mediaMsg?.mediaPath;
-  const mediaMime = mediaMsg?.mediaMime;
+  const mediaMsg = segment.find((pm) => pm.mediaPath || pm.mediaPaths && pm.mediaPaths.length > 0);
+  const mediaPaths = mediaMsg?.mediaPaths?.length ? mediaMsg.mediaPaths : mediaMsg?.mediaPath ? [mediaMsg.mediaPath] : [];
+  const mediaMimes = mediaMsg?.mediaMimes?.length ? mediaMsg.mediaMimes : mediaMsg?.mediaMime ? [mediaMsg.mediaMime] : [];
+  const mediaPath = mediaPaths[0];
+  const mediaMime = mediaMimes[0];
   log?.info?.(
     `[wechat:${liveAccount.accountId}] Dispatching segment: ${segment.length} msg(s), last=${msg.localId}${mediaPath ? " media=present" : ""}`
   );
@@ -8119,9 +8430,9 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
         MediaPath: mediaPath,
         MediaUrl: mediaPath,
         MediaType: mediaMime,
-        MediaPaths: [mediaPath],
-        MediaUrls: [mediaPath],
-        MediaTypes: mediaMime ? [mediaMime] : [],
+        MediaPaths: mediaPaths,
+        MediaUrls: mediaPaths,
+        MediaTypes: mediaMimes,
         ...mediaMsg?.mediaHash ? { MediaHash: mediaMsg.mediaHash } : {},
         ...mediaMsg?.mediaPreviewPath ? { MediaPreviewPath: mediaMsg.mediaPreviewPath } : {}
       } : {},
@@ -8250,7 +8561,7 @@ function bufferGroupHistory(groupHistory, chatId, pm, limit) {
     if (first) groupHistory.delete(first);
   }
 }
-async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHandled, startupBaselines, pendingMessageScans, persistRetryState, inboundLedger, mediaPipeline, emptyUnreadBackoff, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit, catchup) {
+async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHandled, startupBaselines, pendingMessageScans, persistRetryState, inboundLedger, mediaPipeline, emptyUnreadBackoff, stickyUnreadAck, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit, catchup) {
   const core = getWeChatRuntime();
   const liveAccount = resolveWeChatAccount(cfg, account.accountId) ?? account;
   const chatId = chat.username ?? chat.id;
@@ -8417,11 +8728,26 @@ async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHand
       );
     }
     if (chat.unreadCount > 0 && !isNewsappChat(chat)) {
-      await openChatIfNeeded();
+      const sticky = ackStickyUnclearedUnread(
+        chatId,
+        chat,
+        stickyUnreadAck,
+        emptyUnreadBackoff
+      );
+      log?.info?.(
+        `[wechat:${liveAccount.accountId}] ${chatId}: ignoring sticky unread after catch-up (unreadCount=${chat.unreadCount}, tip=${sticky.tip}, openim=${isOpenImChat(chatId)}); badge kept; backoff=${sticky.backoffMs}ms`
+      );
     }
     return "skipped";
   }
-  if (!isNewsappChat(chat)) await openChatIfNeeded();
+  const anyAllowlistedInbound = newMessages.some((msg) => {
+    if (msg.isSelf) return false;
+    if (shouldBypassNewsappAuthorization(chat)) return true;
+    const isGroup2 = chatId.includes("@chatroom");
+    const senderId = msg.sender ?? chatId;
+    return resolveWeChatInboundAccessDecision({ isGroup: isGroup2, senderId, policy }).allowed;
+  });
+  if (anyAllowlistedInbound && !isNewsappChat(chat)) await openChatIfNeeded();
   const catchUpLimits = {
     maxMessages: liveAccount.catchUpMaxMessages,
     maxAgeMs: liveAccount.catchUpMaxAgeMs
@@ -8517,6 +8843,8 @@ async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHand
               ...processed[i],
               mediaPath: void 0,
               mediaMime: void 0,
+              mediaPaths: void 0,
+              mediaMimes: void 0,
               hasMedia: false
             };
           }
@@ -8618,6 +8946,17 @@ async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHand
   }
   const maxId = Math.max(...newMessages.map((m) => m.localId));
   advanceLastSeen(newMessages.filter((message) => message.localId <= maxId));
+  if (chat.unreadCount > 0 && !isNewsappChat(chat)) {
+    const sticky = ackStickyUnclearedUnread(
+      chatId,
+      chat,
+      stickyUnreadAck,
+      emptyUnreadBackoff
+    );
+    log?.info?.(
+      `[wechat:${liveAccount.accountId}] ${chatId}: ignoring sticky unread after filtered window (tip=${sticky.tip}, openim=${isOpenImChat(chatId)}); badge kept; backoff=${sticky.backoffMs}ms`
+    );
+  }
   return "skipped";
 }
 
@@ -9295,7 +9634,7 @@ var wechatPlugin = {
       allowFrom: account.allowFrom ?? [],
       allowFromPath: `channels.${OPENCLAW_CHANNEL_ID}.allowFrom`,
       policyPath: `channels.${OPENCLAW_CHANNEL_ID}.dmPolicy`,
-      approveHint: `Add the wxid to channels.${OPENCLAW_CHANNEL_ID}.allowFrom`,
+      approveHint: `Add the wxid or enterprise @openim id to channels.${OPENCLAW_CHANNEL_ID}.allowFrom`,
       normalizeEntry: (raw) => raw.replace(/^(agent-wechat|wechat):/i, "").trim()
     })
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyan-du/agent-wechat-openclaw",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "type": "module",
   "files": [
     "dist",