@agent-wechat/agent-wechat 0.12.2 → 0.14.0

package/dist/index.js

@@ -1094,6 +1094,7 @@ function normalizeGroupPolicy(policy) {
 }
 var DEFAULT_POLL_INTERVAL_MS = 1e3;
 var DEFAULT_AUTH_POLL_INTERVAL_MS = 3e4;
+var DEFAULT_MEDIA_MAX_MB = 50;
 var DEFAULT_ACCOUNT_ID = "default";
 function resolveWeChatAccount(cfg, accountId) {
   const wechat = cfg.channels?.["agent-wechat"];
@@ -1109,7 +1110,8 @@ function resolveWeChatAccount(cfg, accountId) {
     groupAllowFrom: wechat.groupAllowFrom ?? [],
     groups: wechat.groups ?? {},
     pollIntervalMs: wechat.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
-    authPollIntervalMs: wechat.authPollIntervalMs ?? DEFAULT_AUTH_POLL_INTERVAL_MS
+    authPollIntervalMs: wechat.authPollIntervalMs ?? DEFAULT_AUTH_POLL_INTERVAL_MS,
+    mediaMaxMb: Number.isInteger(wechat.mediaMaxMb) && (wechat.mediaMaxMb ?? 0) > 0 && (wechat.mediaMaxMb ?? 0) <= 1024 ? wechat.mediaMaxMb : DEFAULT_MEDIA_MAX_MB
   };
 }
 
@@ -1154,16 +1156,16 @@ var WeChatClient = class {
     return this.base;
   }
   // ---- internal helpers ----
-  async get(path) {
-    const res = await fetch(`${this.base}${path}`, {
+  async get(path2) {
+    const res = await fetch(`${this.base}${path2}`, {
       headers: this.headers
     });
     if (!res.ok)
       throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`);
     return res.json();
   }
-  async post(path, body) {
-    const res = await fetch(`${this.base}${path}`, {
+  async post(path2, body) {
+    const res = await fetch(`${this.base}${path2}`, {
       method: "POST",
       headers: this.headers,
       body: body != null ? JSON.stringify(body) : void 0
@@ -1172,8 +1174,8 @@ var WeChatClient = class {
       throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`);
     return res.json();
   }
-  async del(path) {
-    const res = await fetch(`${this.base}${path}`, {
+  async del(path2) {
+    const res = await fetch(`${this.base}${path2}`, {
       method: "DELETE",
       headers: this.headers
     });
@@ -1222,8 +1224,8 @@ var WeChatClient = class {
   async listMessages(chatId, limit, offset) {
     return this.get(`/api/messages/${encodeURIComponent(chatId)}${qs({ limit, offset })}`);
   }
-  async getMedia(chatId, localId) {
-    return this.get(`/api/messages/${encodeURIComponent(chatId)}/media/${localId}`);
+  async getMedia(chatId, localId, quality) {
+    return this.get(`/api/messages/${encodeURIComponent(chatId)}/media/${localId}${qs({ quality })}`);
   }
   async sendMessage(params) {
     return this.post("/api/messages/send", params);
@@ -1775,8 +1777,8 @@ function getErrorMap() {
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path, errorMaps, issueData } = params;
-  const fullPath = [...path, ...issueData.path || []];
+  const { data, path: path2, errorMaps, issueData } = params;
+  const fullPath = [...path2, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -1892,11 +1894,11 @@ var errorUtil;
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path, key) {
+  constructor(parent, value, path2, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path;
+    this._path = path2;
     this._key = key;
   }
   get path() {
@@ -5495,10 +5497,11 @@ var sendResultSchema = external_exports.object({
 });
 var getMediaParamsSchema = external_exports.object({
   chatId: external_exports.string().min(1),
-  localId: external_exports.number().int()
+  localId: external_exports.number().int(),
+  quality: external_exports.enum(["full", "thumbnail"]).optional()
 });
 var mediaResultSchema = external_exports.object({
-  type: external_exports.enum(["image", "emoji", "voice", "video", "unsupported"]),
+  type: external_exports.enum(["image", "emoji", "voice", "video", "file", "pending", "unsupported"]),
   data: external_exports.string().optional(),
   url: external_exports.string().optional(),
   format: external_exports.string(),
@@ -5513,6 +5516,269 @@ var agentConfigSchema = external_exports.object({
 // src/monitor.ts
 import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
 
+// src/media-delivery.ts
+var MIME_BY_FORMAT = {
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  mp3: "audio/mpeg",
+  silk: "audio/silk",
+  mp4: "video/mp4",
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip",
+  txt: "text/plain"
+};
+function attachmentKindForMessageType(baseType) {
+  if (baseType === 3) return "image";
+  if (baseType === 34) return "audio";
+  if (baseType === 43) return "video";
+  if (baseType === 49) return "file";
+  return void 0;
+}
+function attachmentKindForResult(result, fallback) {
+  if (result.type === "image" || result.type === "emoji") return "image";
+  if (result.type === "voice") return "audio";
+  if (result.type === "video") return "video";
+  if (result.type === "file") return "file";
+  return fallback;
+}
+function mediaMime(format, kind) {
+  const normalized = format.toLowerCase().replace(/^\./, "");
+  return MIME_BY_FORMAT[normalized] ?? (kind === "image" ? "image/*" : kind === "audio" ? "audio/*" : kind === "video" ? "video/*" : "application/octet-stream");
+}
+function appendReference(body, reference) {
+  return body ? `${body}
+${reference}` : reference;
+}
+function safeDisplayName(name) {
+  return name.replace(/[\r\n\0]/g, " ").trim() || "attachment";
+}
+function attachmentFallbackFilename(kind, localId, originalBody = "") {
+  if (kind === "file" && originalBody && !originalBody.trimStart().startsWith("<")) {
+    return safeDisplayName(originalBody);
+  }
+  const extension = kind === "image" ? "jpg" : kind === "audio" ? "mp3" : kind === "video" ? "mp4" : "bin";
+  return `message-${localId}.${extension}`;
+}
+function attachmentSourceBody(originalBody, kind) {
+  if (!kind || kind === "file") return originalBody;
+  return originalBody.trimStart().startsWith("<") ? "" : originalBody;
+}
+function renderAttachmentBody(originalBody, attachment, exposeNonVisualPath = true) {
+  if (!attachment) return originalBody;
+  const name = safeDisplayName(attachment.filename);
+  if (attachment.status !== "ready" || !attachment.path) {
+    const label = attachment.kind === "file" ? "File" : attachment.kind === "image" ? "Image" : attachment.kind === "audio" ? "Voice message" : "Video";
+    if (attachment.status === "pending") {
+      return appendReference(originalBody, `[${label} pending: ${name}]`);
+    }
+    return appendReference(originalBody, `[${label} unavailable: ${name} (${attachment.status})]`);
+  }
+  if (attachment.kind === "file") {
+    const prefix = originalBody.trim() === name ? "" : originalBody;
+    return appendReference(prefix, `[File: ${name}]
+[Local file: ${attachment.path}]`);
+  }
+  if (exposeNonVisualPath) {
+    if (attachment.kind === "audio") {
+      return appendReference(originalBody || "<media:audio>", `[Voice message file: ${attachment.path}]`);
+    }
+    if (attachment.kind === "video") {
+      return appendReference(originalBody || "<media:video>", `[Video file: ${attachment.path}]`);
+    }
+  }
+  if (!originalBody) return attachment.kind === "image" ? "<media:image>" : originalBody;
+  return originalBody;
+}
+function applyLiveAttachment(message, originalBody, attachment) {
+  const attachable = attachment?.status === "ready" && attachment.path && attachment.kind !== "file";
+  return {
+    ...message,
+    rawBody: renderAttachmentBody(originalBody, attachment),
+    attachment,
+    mediaPath: attachable ? attachment.path : void 0,
+    mediaMime: attachable ? attachment.mime : void 0,
+    hasMedia: attachment !== void 0
+  };
+}
+function applyCatchupAttachmentPolicy(messages) {
+  let latestImage = -1;
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const attachment = messages[index].attachment;
+    if (attachment?.kind === "image" && attachment.status === "ready" && attachment.path) {
+      latestImage = index;
+      break;
+    }
+  }
+  return messages.map((message, index) => {
+    const attachment = message.attachment;
+    if (!attachment) return { ...message, mediaPath: void 0, mediaMime: void 0 };
+    const selectImage = index === latestImage;
+    let rawBody = renderAttachmentBody(message.rawBody, void 0);
+    if (attachment.kind === "file") {
+      rawBody = message.rawBody;
+    } else if (!selectImage && attachment.status === "ready" && attachment.path) {
+      const label = attachment.kind === "image" ? "Image file" : attachment.kind === "audio" ? "Voice message file" : "Video file";
+      const reference = `[${label}: ${attachment.path}]`;
+      rawBody = message.rawBody.includes(reference) ? message.rawBody : appendReference(message.rawBody, reference);
+    }
+    return {
+      ...message,
+      rawBody,
+      mediaPath: selectImage ? attachment.path : void 0,
+      mediaMime: selectImage ? attachment.mime : void 0,
+      hasMedia: attachment !== void 0
+    };
+  });
+}
+function buildMediaSegments(messages) {
+  const segments = [];
+  let batch = [];
+  let hasAttachedMedia = false;
+  for (const message of messages) {
+    if (message.mediaPath && hasAttachedMedia) {
+      segments.push(batch);
+      batch = [message];
+      hasAttachedMedia = true;
+    } else {
+      batch.push(message);
+      if (message.mediaPath) hasAttachedMedia = true;
+    }
+  }
+  if (batch.length > 0) segments.push(batch);
+  return segments;
+}
+
+// src/attachment-store.ts
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+var AttachmentTooLargeError = class extends Error {
+};
+function decodedSize(base64) {
+  if (!base64 || base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {
+    throw new Error("Invalid attachment encoding");
+  }
+  const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+  return base64.length / 4 * 3 - padding;
+}
+async function saveManagedAttachment(params) {
+  const size = decodedSize(params.data);
+  if (size > params.maxBytes) {
+    throw new AttachmentTooLargeError(`Attachment exceeds configured ${params.maxBytes} byte limit`);
+  }
+  const buffer = Buffer.from(params.data, "base64");
+  if (buffer.byteLength !== size) throw new Error("Attachment decoding length mismatch");
+  const sha256 = createHash("sha256").update(buffer).digest("hex");
+  const saved = await params.saveMediaBuffer(
+    buffer,
+    params.mime,
+    "inbound",
+    params.maxBytes,
+    params.filename
+  );
+  return { path: saved.path, size, sha256, filename: params.filename };
+}
+async function attachmentPathExists(filePath) {
+  if (!filePath) return false;
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// src/monitor-state.ts
+import { createHash as createHash2, randomUUID } from "node:crypto";
+import fs2 from "node:fs/promises";
+import path from "node:path";
+var emptyState = () => ({
+  version: 1,
+  lastSeen: /* @__PURE__ */ Object.create(null),
+  groupHistory: /* @__PURE__ */ Object.create(null)
+});
+var MonitorStateStore = class {
+  filePath;
+  constructor(stateDir, accountId) {
+    const account = createHash2("sha256").update(accountId).digest("hex").slice(0, 16);
+    this.filePath = path.join(stateDir, "agent-wechat", "monitor", `${account}.json`);
+  }
+  async load(validateItem) {
+    let parsed;
+    try {
+      parsed = JSON.parse(await fs2.readFile(this.filePath, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT") return emptyState();
+      throw error;
+    }
+    if (!parsed || typeof parsed !== "object" || parsed.version !== 1) {
+      throw new Error("Unsupported WeChat monitor state");
+    }
+    const input = parsed;
+    const state = emptyState();
+    if (input.lastSeen && typeof input.lastSeen === "object") {
+      for (const [chatId, localId] of Object.entries(input.lastSeen)) {
+        if (typeof localId === "number" && Number.isSafeInteger(localId) && localId >= 0) {
+          state.lastSeen[chatId] = localId;
+        }
+      }
+    }
+    if (input.groupHistory && typeof input.groupHistory === "object") {
+      for (const [chatId, items] of Object.entries(input.groupHistory)) {
+        if (Array.isArray(items) && items.every(validateItem)) state.groupHistory[chatId] = items;
+      }
+    }
+    return state;
+  }
+  async save(lastSeen, groupHistory) {
+    const directory = path.dirname(this.filePath);
+    await fs2.mkdir(directory, { recursive: true, mode: 448 });
+    const state = {
+      version: 1,
+      lastSeen: Object.fromEntries(lastSeen),
+      groupHistory: Object.fromEntries(groupHistory)
+    };
+    const temporary = path.join(directory, `.${path.basename(this.filePath)}.${randomUUID()}.tmp`);
+    try {
+      await fs2.writeFile(temporary, JSON.stringify(state), { flag: "wx", mode: 384 });
+      await fs2.rename(temporary, this.filePath);
+    } finally {
+      await fs2.rm(temporary, { force: true }).catch(() => void 0);
+    }
+  }
+};
+
+// src/polling.ts
+async function listAllChats(client) {
+  const pageSize = 100;
+  const chats = [];
+  for (let offset = 0; ; offset += pageSize) {
+    const page = await client.listChats(pageSize, offset);
+    chats.push(...page);
+    if (page.length < pageSize) return chats;
+  }
+}
+async function listMessageWindow(client, chatId, previousLastSeen, firstPoll, unreadCount) {
+  const pageSize = 200;
+  const messages = [];
+  const firstPollTarget = Math.max(unreadCount, 20);
+  for (let offset = 0; ; offset += pageSize) {
+    const page = await client.listMessages(chatId, pageSize, offset);
+    messages.push(...page);
+    if (page.length < pageSize) break;
+    if (firstPoll && messages.length >= firstPollTarget) break;
+    if (!firstPoll && page.some((message) => message.localId <= previousLastSeen)) break;
+  }
+  return messages;
+}
+
 // src/access-control.ts
 import {
   buildChannelKeyCandidates,
@@ -5721,9 +5987,13 @@ function resolveWeChatMentionGate(params) {
 }
 
 // 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 isProcessedMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const message = value;
+  return !!message.msg && typeof message.rawBody === "string" && typeof message.commandBody === "string" && typeof message.senderName === "string" && typeof message.senderId === "string" && typeof message.isGroup === "boolean" && typeof message.timestamp === "number" && typeof message.hasMedia === "boolean" && typeof message.isMentioned === "boolean" && typeof message.sourceBody === "string";
+}
 function isOfficialAccount(chatId) {
   return chatId.startsWith("gh_");
 }
@@ -5737,10 +6007,12 @@ function sleep(ms, signal) {
   });
 }
 async function pollMedia(client, chatId, localId, log, maxAttempts = 15, intervalMs = 1e3) {
+  let lastResult = null;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    const result = await client.getMedia(chatId, localId);
+    const result = await client.getMedia(chatId, localId, "full");
+    lastResult = result;
     if (result.type === "unsupported") {
-      return null;
+      return result;
     }
     if (result.data) {
       return result;
@@ -5750,7 +6022,7 @@ async function pollMedia(client, chatId, localId, log, maxAttempts = 15, interva
       await new Promise((r) => setTimeout(r, intervalMs));
     }
   }
-  return null;
+  return lastResult;
 }
 function enqueueWeChatSystemEvent(text, contextKey) {
   try {
@@ -5762,12 +6034,72 @@ function enqueueWeChatSystemEvent(text, contextKey) {
   } catch {
   }
 }
+async function retrieveAttachment(client, chatId, msg, liveAccount, log, maxAttempts = 15) {
+  const baseType = msg.type & 2147483647;
+  const expectedKind = attachmentKindForMessageType(baseType);
+  if (!expectedKind) return void 0;
+  const fallbackFilename = attachmentFallbackFilename(expectedKind, msg.localId, msg.content);
+  try {
+    const result = await pollMedia(client, chatId, msg.localId, log, maxAttempts);
+    if (!result) {
+      return { kind: expectedKind, status: "unavailable", filename: fallbackFilename };
+    }
+    if (result.type === "unsupported") {
+      if (baseType === 49) return void 0;
+      return { kind: expectedKind, status: "unsupported", filename: fallbackFilename };
+    }
+    const kind = attachmentKindForResult(result, expectedKind);
+    const filename = result.filename || fallbackFilename;
+    if (!result.data) {
+      return { kind, status: result.type === "pending" ? "pending" : "unavailable", filename };
+    }
+    const mime = mediaMime(result.format, kind);
+    const saved = await saveManagedAttachment({
+      data: result.data,
+      mime,
+      filename,
+      maxBytes: liveAccount.mediaMaxMb * 1024 * 1024,
+      saveMediaBuffer: getWeChatRuntime().channel.media.saveMediaBuffer
+    });
+    log?.info?.(
+      `[wechat:${liveAccount.accountId}] Saved ${kind} attachment for msg ${msg.localId} (${saved.size} bytes)`
+    );
+    return { kind, status: "ready", filename: saved.filename, mime, path: saved.path };
+  } catch (error) {
+    const status = error instanceof AttachmentTooLargeError ? "too_large" : "error";
+    log?.error?.(
+      `[wechat:${liveAccount.accountId}] Attachment retrieval failed for msg ${msg.localId} (${status})`
+    );
+    return {
+      kind: expectedKind,
+      status,
+      filename: fallbackFilename,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 async function startWeChatMonitor(opts) {
   const { account, abortSignal, setStatus, log } = opts;
   const client = new WeChatClient({ baseUrl: account.serverUrl, token: account.token });
-  const lastSeenId = /* @__PURE__ */ new Map();
-  const groupHistory = /* @__PURE__ */ new Map();
+  const runtimeStateDir = getWeChatRuntime().state.resolveStateDir(process.env);
+  const stateStore = new MonitorStateStore(runtimeStateDir, account.accountId);
+  let savedState;
+  try {
+    savedState = await stateStore.load(isProcessedMessage);
+  } catch (error) {
+    log?.error?.(`[wechat:${account.accountId}] Ignoring unreadable monitor state: ${String(error)}`);
+    savedState = { version: 1, lastSeen: {}, groupHistory: {} };
+  }
+  const lastSeenId = new Map(Object.entries(savedState.lastSeen));
+  const groupHistory = new Map(Object.entries(savedState.groupHistory));
   const GROUP_HISTORY_LIMIT = 50;
+  const persistState = async () => {
+    try {
+      await stateStore.save(lastSeenId, groupHistory);
+    } catch (error) {
+      log?.error?.(`[wechat:${account.accountId}] Failed to persist monitor state: ${String(error)}`);
+    }
+  };
   let lastAuthCheck = 0;
   let prevStatus = void 0;
   setStatus({
@@ -5831,7 +6163,7 @@ async function startWeChatMonitor(opts) {
       }
       let chats;
       try {
-        chats = await client.listChats(50);
+        chats = await listAllChats(client);
       } catch (err) {
         log?.error?.(
           `[wechat:${account.accountId}] Failed to list chats: ${err}`
@@ -5859,7 +6191,8 @@ async function startWeChatMonitor(opts) {
             log,
             void 0,
             groupHistory,
-            GROUP_HISTORY_LIMIT
+            GROUP_HISTORY_LIMIT,
+            persistState
           );
         }
       }
@@ -5874,7 +6207,7 @@ async function startWeChatMonitor(opts) {
         log?.info?.(
           `[wechat:${account.accountId}] Catch-up: ${chatId} lastMsgLocalId=${chat.lastMsgLocalId} > lastSeenId=${prevSeen}`
         );
-        await processUnreadChat(client, chat, lastSeenId, account, cfg, log, true, groupHistory, GROUP_HISTORY_LIMIT);
+        await processUnreadChat(client, chat, lastSeenId, account, cfg, log, true, groupHistory, GROUP_HISTORY_LIMIT, persistState);
       }
     } catch (err) {
       log?.error?.(
@@ -5890,7 +6223,6 @@ async function startWeChatMonitor(opts) {
   });
 }
 async function prepareMessage(client, msg, chatId, chat, liveAccount, policy, log) {
-  const core = getWeChatRuntime();
   if (msg.isSelf) {
     log?.info?.(`[wechat:${liveAccount.accountId}] Skipping self-sent msg ${msg.localId}`);
     return null;
@@ -5910,113 +6242,68 @@ async function prepareMessage(client, msg, chatId, chat, liveAccount, policy, lo
     );
     return null;
   }
-  let mediaPath;
-  let mediaMime;
-  let hasMedia = false;
   const baseType = msg.type & 2147483647;
-  const mayHaveMedia = MEDIA_TYPES.has(baseType) || baseType === 49;
-  if (mayHaveMedia) {
+  const messageAttachmentKind = attachmentKindForMessageType(baseType);
+  let attachment;
+  if (messageAttachmentKind) {
     log?.info?.(`[wechat:${liveAccount.accountId}] Checking media for msg ${msg.localId} (type ${baseType})`);
-    try {
-      const result = await pollMedia(client, chatId, msg.localId, log);
-      if (result && result.data && result.type !== "unsupported") {
-        hasMedia = true;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Media result: type=${result.type}, format=${result.format}, hasData=${!!result.data}, filename=${result.filename}`);
-        const mimeMap = {
-          jpeg: "image/jpeg",
-          jpg: "image/jpeg",
-          png: "image/png",
-          gif: "image/gif",
-          mp3: "audio/mpeg",
-          pdf: "application/pdf",
-          doc: "application/msword",
-          docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-          xls: "application/vnd.ms-excel",
-          xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-          ppt: "application/vnd.ms-powerpoint",
-          pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-          zip: "application/zip",
-          txt: "text/plain"
-        };
-        mediaMime = mimeMap[result.format] ?? `application/${result.format || "octet-stream"}`;
-        const buf = Buffer.from(result.data, "base64");
-        const saved = await core.channel.media.saveMediaBuffer(
-          buf,
-          mediaMime,
-          "inbound",
-          void 0,
-          result.filename
-        );
-        mediaPath = saved?.path;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Saved media to ${mediaPath}`);
-      } else if (MEDIA_TYPES.has(baseType)) {
-        hasMedia = true;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Media not available after retries for msg ${msg.localId}`);
-      }
-    } catch (err) {
-      log?.error?.(`[wechat:${liveAccount.accountId}] Media download failed: ${err}`);
-    }
+    attachment = await retrieveAttachment(client, chatId, msg, liveAccount, log);
   }
   const timestamp = new Date(msg.timestamp).getTime();
-  let rawBody = msg.content || "";
-  if (mediaPath && mediaMime) {
-    if (!rawBody) {
-      if (mediaMime.startsWith("audio/")) {
-        rawBody = "<media:audio>";
-      } else if (mediaMime.startsWith("image/")) {
-        rawBody = "<media:image>";
-      } else {
-        rawBody = "<media:file>";
-      }
-    } else if (!mediaMime.startsWith("image/") && !mediaMime.startsWith("audio/")) {
-      rawBody = `[File: ${rawBody}]`;
-    }
-  }
+  let sourceBody = attachmentSourceBody(msg.content || "", messageAttachmentKind);
   if (msg.reply) {
     const replySender = msg.reply.sender ?? "unknown sender";
     const quotedBody = msg.reply.content.length > 50 ? msg.reply.content.slice(0, 50) + "..." : msg.reply.content;
     const replyBlock = `[Replying to ${replySender}]
 ${quotedBody}
 [/Replying]`;
-    rawBody = rawBody ? `${rawBody}
+    sourceBody = sourceBody ? `${sourceBody}
 
 ${replyBlock}` : replyBlock;
   }
-  return {
+  const prepared = applyLiveAttachment({
     msg,
-    rawBody,
-    commandBody: normalizeWeChatCommandBody(rawBody, {
-      isGroup,
-      wasMentioned
-    }),
-    mediaPath,
-    mediaMime,
+    rawBody: sourceBody,
+    sourceBody,
+    commandBody: "",
     senderName,
     senderId,
     isGroup,
     timestamp,
-    hasMedia,
+    hasMedia: false,
     isMentioned: wasMentioned
-  };
+  }, sourceBody, attachment);
+  prepared.commandBody = normalizeWeChatCommandBody(prepared.rawBody, {
+    isGroup,
+    wasMentioned
+  });
+  return prepared;
 }
-function buildSegments(processed) {
-  const segments = [];
-  let currentBatch = [];
-  let mediaCount = 0;
-  for (const pm of processed) {
-    if (pm.hasMedia && mediaCount >= 1) {
-      segments.push(currentBatch);
-      currentBatch = [pm];
-      mediaCount = 1;
-    } else {
-      if (pm.hasMedia) mediaCount++;
-      currentBatch.push(pm);
+async function refreshAttachment(message, client, chatId, liveAccount, log) {
+  if (!message.attachment) return message;
+  if (message.attachment.status === "ready" && await attachmentPathExists(message.attachment.path)) {
+    return message;
+  }
+  log?.info?.(`[wechat:${liveAccount.accountId}] Retrying attachment for msg ${message.msg.localId}`);
+  const attachment = await retrieveAttachment(client, chatId, message.msg, liveAccount, log, 3);
+  const refreshed = applyLiveAttachment(message, message.sourceBody, attachment);
+  refreshed.commandBody = normalizeWeChatCommandBody(refreshed.rawBody, {
+    isGroup: refreshed.isGroup,
+    wasMentioned: refreshed.isMentioned
+  });
+  return refreshed;
+}
+async function refreshAttachments(messages, client, chatId, liveAccount, log) {
+  const output = [...messages];
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < messages.length) {
+      const index = cursor++;
+      output[index] = await refreshAttachment(messages[index], client, chatId, liveAccount, log);
     }
-  }
-  if (currentBatch.length > 0) {
-    segments.push(currentBatch);
-  }
-  return segments;
+  };
+  await Promise.all(Array.from({ length: Math.min(3, messages.length) }, worker));
+  return output;
 }
 async function dispatchSegment(segment, client, chatId, chat, liveAccount, policy, storeAllowFrom, allowTextCommands, cfg, log, remainingSegments) {
   const core = getWeChatRuntime();
@@ -6024,9 +6311,18 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
   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 mediaMime2 = mediaMsg?.mediaMime;
+  const attachmentPaths = segment.flatMap(
+    (pm) => pm.attachment?.status === "ready" && pm.attachment.path ? [{
+      path: pm.attachment.path,
+      filename: pm.attachment.filename,
+      kind: pm.attachment.kind,
+      messageId: pm.msg.localId,
+      sender: pm.senderName
+    }] : []
+  );
   log?.info?.(
-    `[wechat:${liveAccount.accountId}] Dispatching segment: ${segment.length} msg(s), last=${msg.localId}${mediaPath ? ` media=${mediaPath}` : ""}`
+    `[wechat:${liveAccount.accountId}] Dispatching segment: ${segment.length} msg(s), last=${msg.localId}${mediaPath ? " with model media" : ""} attachments=${attachmentPaths.length}`
   );
   const hasControlCommand = allowTextCommands && core.channel.commands.isControlCommandMessage(commandBody, cfg);
   const commandAuthorized = await resolveWeChatCommandAuthorization({
@@ -6046,7 +6342,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
     log?.info?.(
       `[wechat:${liveAccount.accountId}] Dropping unauthorized group control command from ${senderId} in ${chatId}`
     );
-    return false;
+    return "ignored";
   }
   const mentionGate = resolveWeChatMentionGate({
     isGroup,
@@ -6061,7 +6357,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
     log?.info?.(
       `[wechat:${liveAccount.accountId}] Skipping group segment (mention required) in ${chatId}`
     );
-    return false;
+    return "ignored";
   }
   try {
     const route = core.channel.routing.resolveAgentRoute({
@@ -6153,7 +6449,8 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
       CommandAuthorized: commandAuthorized,
       OriginatingChannel: "agent-wechat",
       OriginatingTo: `wechat:${chatId}`,
-      ...mediaPath ? { MediaPath: mediaPath, MediaUrl: mediaPath, MediaType: mediaMime } : {},
+      Attachments: attachmentPaths,
+      ...mediaPath ? { MediaPath: mediaPath, MediaUrl: mediaPath, MediaType: mediaMime2 } : {},
       ...msg.reply ? {
         ReplyToBody: msg.reply.content.length > 50 ? msg.reply.content.slice(0, 50) + "..." : msg.reply.content,
         ReplyToSender: msg.reply.sender
@@ -6175,6 +6472,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
       channel: "agent-wechat",
       accountId: liveAccount.accountId
     });
+    let replyFailed = false;
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
       ctx: ctxPayload,
       cfg,
@@ -6238,6 +6536,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
           }
         },
         onError: (err, info) => {
+          replyFailed = true;
           log?.error?.(
             `[wechat:${liveAccount.accountId}] ${info.kind} reply failed: ${String(err)}`
           );
@@ -6247,18 +6546,19 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
         onModelSelected
       }
     });
+    if (replyFailed) return "failed";
     core.channel.activity?.record?.({
       channel: "agent-wechat",
       accountId: liveAccount.accountId,
       direction: "inbound",
       at: timestamp
     });
-    return true;
+    return "delivered";
   } catch (err) {
     log?.error?.(
       `[wechat:${liveAccount.accountId}] Failed to dispatch segment (last msg ${msg.localId}): ${err}`
     );
-    return false;
+    return "failed";
   }
 }
 function bufferGroupHistory(groupHistory, chatId, pm, limit) {
@@ -6274,7 +6574,7 @@ function bufferGroupHistory(groupHistory, chatId, pm, limit) {
     if (first) groupHistory.delete(first);
   }
 }
-async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit) {
+async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit, persistState) {
   const core = getWeChatRuntime();
   const liveAccount = resolveWeChatAccount(cfg, account.accountId) ?? account;
   const chatId = chat.username ?? chat.id;
@@ -6292,8 +6592,12 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
   if (!skipOpen) {
     log?.info?.(`[wechat:${liveAccount.accountId}] Opening chat ${chatId}...`);
     try {
-      await client.openChat(chatId, true);
-      log?.info?.(`[wechat:${liveAccount.accountId}] Opened chat ${chatId}`);
+      const opened = await client.openChat(chatId, true);
+      if (opened.ok) {
+        log?.info?.(`[wechat:${liveAccount.accountId}] Opened chat ${chatId}`);
+      } else {
+        log?.error?.(`[wechat:${liveAccount.accountId}] Chat selection did not complete for ${chatId}: ${opened.error ?? "unknown error"}`);
+      }
     } catch (err) {
       log?.error?.(
         `[wechat:${liveAccount.accountId}] Failed to open chat ${chatId}: ${err}`
@@ -6302,10 +6606,9 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
   }
   const firstPoll = !lastSeenId.has(chatId);
   const prevLastSeen = lastSeenId.get(chatId) ?? 0;
-  const fetchLimit = Math.max(chat.unreadCount, 20);
   let messages;
   try {
-    messages = await client.listMessages(chatId, fetchLimit);
+    messages = await listMessageWindow(client, chatId, prevLastSeen, firstPoll, chat.unreadCount ?? 0);
   } catch (err) {
     log?.error?.(
       `[wechat:${liveAccount.accountId}] Failed to list messages for ${chatId}: ${err}`
@@ -6324,11 +6627,13 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
       newMessages = messages.slice(-unread);
       const seenMax = messages[messages.length - unread - 1].localId;
       lastSeenId.set(chatId, seenMax);
+      await persistState?.();
     } else if (unread >= messages.length) {
       newMessages = messages;
     } else {
       const maxId2 = messages[messages.length - 1].localId;
       lastSeenId.set(chatId, maxId2);
+      await persistState?.();
       return;
     }
   } else {
@@ -6344,7 +6649,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
   const processed = [];
   for (const msg of newMessages) {
     log?.info?.(
-      `[wechat:${liveAccount.accountId}] Processing msg ${msg.localId}: type=${msg.type}, sender=${msg.sender}, isSelf=${msg.isSelf}, content=${(msg.content || "").slice(0, 50)}`
+      `[wechat:${liveAccount.accountId}] Processing msg ${msg.localId}: type=${msg.type}, sender=${msg.sender}, isSelf=${msg.isSelf}`
     );
     const pm = await prepareMessage(client, msg, chatId, chat, liveAccount, policy, log);
     if (pm) {
@@ -6365,51 +6670,35 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
         log?.info?.(`[wechat:${liveAccount.accountId}] Buffered ${processed.length} msg(s) for group history in ${chatId}`);
         const maxId2 = Math.max(...newMessages.map((m) => m.localId));
         lastSeenId.set(chatId, maxId2);
+        await persistState?.();
         return;
       }
       if (hasMention) {
         clearBufferedHistory = true;
         const buffered = groupHistory.get(chatId) ?? [];
         if (buffered.length > 0) {
-          for (const pm of buffered) {
-            pm.isMentioned = true;
-          }
-          processed.unshift(...buffered);
+          processed.unshift(...buffered.map((pm) => ({ ...pm, isMentioned: true })));
           log?.info?.(
             `[wechat:${liveAccount.accountId}] Injected ${buffered.length} buffered msg(s) as history in ${chatId}`
           );
         }
-        let latestMediaIdx = -1;
-        for (let i = processed.length - 1; i >= 0; i--) {
-          if (processed[i].mediaPath) {
-            latestMediaIdx = i;
-            break;
-          }
-        }
-        for (let i = 0; i < processed.length; i++) {
-          if (processed[i].mediaPath && i !== latestMediaIdx) {
-            processed[i] = {
-              ...processed[i],
-              mediaPath: void 0,
-              mediaMime: void 0,
-              hasMedia: false
-            };
-          }
-        }
+        processed.splice(0, processed.length, ...await refreshAttachments(processed, client, chatId, liveAccount, log));
+        processed.splice(0, processed.length, ...applyCatchupAttachmentPolicy(processed));
       }
     } else {
       clearBufferedHistory = true;
     }
   }
   if (processed.length > 0) {
-    const segments = hasControlCommandInWindow ? processed.map((pm) => [pm]) : buildSegments(processed);
+    const segments = hasControlCommandInWindow ? processed.map((pm) => [pm]) : buildMediaSegments(processed);
     log?.info?.(
       `[wechat:${liveAccount.accountId}] ${chatId}: ${processed.length} dispatchable msg(s) in ${segments.length} segment(s)`
     );
     let allDispatched = true;
+    let allHandled = true;
     for (let i = 0; i < segments.length; i++) {
       const remaining = segments.length - i - 1;
-      const dispatched = await dispatchSegment(
+      const outcome = await dispatchSegment(
         segments[i],
         client,
         chatId,
@@ -6422,16 +6711,22 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
         log,
         hasControlCommandInWindow ? void 0 : remaining
       );
-      if (!dispatched) {
+      if (outcome !== "delivered") {
         allDispatched = false;
       }
+      if (outcome === "failed") allHandled = false;
     }
     if (clearBufferedHistory && allDispatched && groupHistory) {
       groupHistory.set(chatId, []);
     }
+    if (!allHandled) {
+      await persistState?.();
+      return;
+    }
   }
   const maxId = Math.max(...newMessages.map((m) => m.localId));
   lastSeenId.set(chatId, maxId);
+  await persistState?.();
 }
 
 // src/status.ts
@@ -6926,7 +7221,8 @@ var wechatPlugin = {
           }
         },
         pollIntervalMs: { type: "integer", minimum: 100 },
-        authPollIntervalMs: { type: "integer", minimum: 1e3 }
+        authPollIntervalMs: { type: "integer", minimum: 1e3 },
+        mediaMaxMb: { type: "integer", minimum: 1, maximum: 1024 }
       }
     }
   },
@@ -6950,7 +7246,8 @@ var wechatPlugin = {
           groupAllowFrom: [],
           groups: {},
           pollIntervalMs: 1e3,
-          authPollIntervalMs: 3e4
+          authPollIntervalMs: 3e4,
+          mediaMaxMb: 50
         };
       }
       return account;

package/openclaw.plugin.json

@@ -91,6 +91,11 @@
           "authPollIntervalMs": {
             "type": "integer",
             "minimum": 1000
+          },
+          "mediaMaxMb": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1024
           }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-wechat/agent-wechat",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "type": "module",
   "files": [
     "dist",
@@ -11,7 +11,7 @@
     "esbuild": "^0.25.0",
     "openclaw": "^2026.8.1",
     "typescript": "^5.4.5",
-    "@agent-wechat/shared": "0.1.0"
+    "@agent-wechat/shared": "0.2.0"
   },
   "openclaw": {
     "extensions": [
@@ -106,6 +106,11 @@
             "authPollIntervalMs": {
               "type": "integer",
               "minimum": 1000
+            },
+            "mediaMaxMb": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1024
             }
           }
         }