@workclaw/openclaw-workchat 1.0.4 → 1.1.0

package/src/messaging/inbound.ts

@@ -23,6 +23,10 @@ export type ParseWorkChatFrameResult = {
     openConversationId: string;
     messageId: string;
     agentId?: string;
+    /** "image"/"audio" for media messages (backend message.type / chatType). */
+    mediaType?: string;
+    /** Media URL from message.content JSON or the DTO fileUrl list. */
+    mediaUrl?: string;
   };
   pongData?: unknown;
   eventData?: AgentEventPayload;
@@ -83,11 +87,28 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
   if (type === "CALLBACK" && String(envelope?.metadata?.topic || "").trim().toUpperCase() === "AGENT_MESSAGE") {
     const payload = (parseMaybeJson(envelope?.data) ?? {}) as AgentMessagePayload;
     const message = payload?.message;
-    const text = typeof message === "string"
+    const messageType = typeof message === "object" && message !== null
+      ? String((message as { type?: unknown }).type ?? "").trim().toLowerCase()
+      : "";
+    const rawContent = typeof message === "string"
       ? message
       : typeof message?.content === "string"
         ? message.content
         : "";
+
+    // Media messages: content is JSON {"url", ...} (image) or {"url","duration"} (audio);
+    // the backend DTO also carries a fileUrl list. Surface the URL for the AI
+    // pipeline while keeping a descriptive text body.
+    let mediaUrl: string | undefined;
+    let text = rawContent;
+    if (messageType === "image" || messageType === "audio") {
+      mediaUrl = extractMediaUrl(rawContent) ?? firstFileUrl(payload);
+      text = messageType === "image" ? "[用户发送了一张图片]" : "[用户发送了一条语音]";
+    } else if (!text.trim()) {
+      mediaUrl = firstFileUrl(payload);
+      if (mediaUrl) text = "[用户发送了一个文件]";
+    }
+
     return {
       type: "agent_message",
       message: {
@@ -96,6 +117,7 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
         openConversationId: String(payload?.conversationId ?? ""),
         messageId: String(payload?.msgId ?? ""),
         ...(payload?.agentId !== undefined ? { agentId: String(payload.agentId) } : {}),
+        ...(mediaUrl ? { mediaUrl, mediaType: messageType || "file" } : {}),
       },
     };
   }
@@ -103,6 +125,23 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
   return { type: "ignored", ignoredKind: `${type}/${topicLower || "(no topic)"}` };
 }
 
+/** Extract `url` from a media message content JSON string, if parseable. */
+function extractMediaUrl(content: string): string | undefined {
+  if (!content.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(content) as { url?: unknown };
+    return typeof parsed?.url === "string" && parsed.url.trim() ? parsed.url.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** First entry of the backend DTO fileUrl list, when present. */
+function firstFileUrl(payload: AgentMessagePayload): string | undefined {
+  const url = Array.isArray(payload?.fileUrl) ? payload.fileUrl[0] : undefined;
+  return typeof url === "string" && url.trim() ? url.trim() : undefined;
+}
+
 /** Build the pong response frame for a SYSTEM ping. */
 export function buildPongFrame(pongData: unknown): string {
   return JSON.stringify({
@@ -139,6 +178,12 @@ export type WorkChatMsgContext = {
   ConversationId?: string;
   /** Cloud agent id this message was addressed to. */
   AgentId?: string;
+  /** Media URL for inbound image/audio/file messages (WorkChat-hosted). */
+  MediaUrl?: string;
+  /** Media kind for inbound media messages ("image" | "audio" | "file"). */
+  MediaType?: string;
+  /** Local path after the media is persisted into the framework media store. */
+  MediaPath?: string;
 };
 
 function generateMessageSid(): string {
@@ -151,8 +196,13 @@ export function workChatMessageToMsgContext(
   accountId: string,
 ): WorkChatMsgContext {
   const fromUserId = message.userId ?? "";
+  // Media messages carry a placeholder body; append the URL so the model can
+  // see and describe the actual asset.
+  const body = message.mediaUrl
+    ? `${message.text ?? ""}\n[media] ${message.mediaUrl}`
+    : message.text ?? "";
   const ctx: WorkChatMsgContext = {
-    Body: message.text ?? "",
+    Body: body,
     From: fromUserId,
     To: fromUserId,
     AccountId: accountId,
@@ -170,5 +220,9 @@ export function workChatMessageToMsgContext(
   if (message.agentId) {
     ctx.AgentId = message.agentId;
   }
+  if (message.mediaUrl) {
+    ctx.MediaUrl = message.mediaUrl;
+    ctx.MediaType = message.mediaType ?? "file";
+  }
   return ctx;
 }

package/src/messaging/process-message.ts

@@ -12,7 +12,7 @@ import {
   registerWorkChatAccountId,
   saveWorkChatAccount,
   triggerWorkChatChannelReload,
-  pruneStaleWorkChatAccounts,
+  pruneOtherWorkChatAccounts,
   removeWorkChatAccountBinding,
 } from "../auth/accounts.js";
 import type { ResolvedWorkChatAccount } from "../auth/accounts.js";
@@ -33,10 +33,44 @@ function loadWorkChatOutboundHooks() {
   return workchatOutboundHooksPromise;
 }
 
+/** Max inbound media size persisted to the framework media store. */
+const WORKCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+
+/**
+ * Download an inbound media URL. Prefers the framework's fetchRemoteMedia
+ * (SSRF guard + size limit); falls back to plain fetch.
+ */
+async function downloadInboundMedia(
+  url: string,
+  deps: ProcessFrameDeps,
+): Promise<{ buffer: Buffer; contentType?: string } | null> {
+  try {
+    if (deps.channelRuntime?.media?.fetchRemoteMedia) {
+      const fetched = await deps.channelRuntime.media.fetchRemoteMedia({
+        url,
+        maxBytes: WORKCHAT_MEDIA_MAX_BYTES,
+      });
+      return { buffer: fetched.buffer, contentType: fetched.contentType };
+    }
+  } catch (err) {
+    logger.warn(`fetchRemoteMedia failed, trying plain fetch: ${String(err)}`);
+  }
+  const res = await globalThis.fetch(url);
+  if (!res.ok) {
+    throw new Error(`inbound media download failed: HTTP ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  if (buffer.length > WORKCHAT_MEDIA_MAX_BYTES) {
+    throw new Error(`inbound media exceeds limit (${buffer.length} bytes)`);
+  }
+  return { buffer, contentType: res.headers.get("content-type") ?? undefined };
+}
+
 async function applyWorkChatMessageSendingHook(params: {
   to: string;
   text: string;
   accountId?: string;
+  mediaUrl?: string;
 }): Promise<{ cancelled: boolean; text: string }> {
   try {
     const hooks = await loadWorkChatOutboundHooks();
@@ -79,48 +113,41 @@ async function handleAgentLifecycleEvent(
   const eventData = result.eventData;
   if (!eventData) return;
 
-  const agentId = String(eventData.id ?? eventData.agentId ?? "");
+  const agentId = String(eventData.id ?? eventData.agentId ?? "").trim();
   if (!agentId) {
     logger.warn(`${frameType}: missing agent id, ignoring`);
     return;
   }
-  const userId = String(eventData.futureId ?? eventData.userId ?? "");
+  const userId = String(eventData.futureId ?? eventData.userId ?? "").trim();
 
   logger.info(`${frameType}: agentId=${agentId} userId=${userId ? "present" : "missing"}`);
   deps.log(`${frameType}: agentId=${agentId}`);
 
-  // Rebind detection must happen BEFORE pruning empties the index (see the
-  // matching note in the binding listener): a rebind always registers under a
-  // FRESH agent-scoped key so the gateway restarts it — the QR login flow
-  // force-stops the channel with a manual-stop mark, and a reused account id
-  // would stay stopped after the config reload.
-  const isRebind = listWorkChatAccountIdsCount() > 0;
+  // One active agent per host: every binding (first scan included) registers
+  // under the agent-scoped key `agent-${agentId}`, and every OTHER registered
+  // account is removed before persisting. A reused account id would also stay
+  // stopped after the QR flow's manual-stop mark, so rebinds always land on
+  // the fresh key and the gateway restarts it via the channel reload below.
+  const { completeWorkChatBinding } = await import("../auth/login-qr.js");
+  const accountId = frameType === "init_agent"
+    ? `agent-${agentId}`
+    : deps.accountId;
 
-  // Rebind semantics: one active agent per host. Before persisting the new
-  // binding, remove every registered account bound to a different agent
-  // (a re-scan creates a new platform agent; the old one is deleted there).
   try {
-    const removed = await pruneStaleWorkChatAccounts(agentId);
+    const removed = await pruneOtherWorkChatAccounts(accountId);
     if (removed.length > 0) {
-      deps.log(`rebind: removed stale account(s): ${removed.join(", ")}`);
+      deps.log(`rebind: removed previous account(s): ${removed.join(", ")}`);
     }
   } catch (err) {
     logger.error(`rebind cleanup failed: ${String(err)}`);
   }
 
-  // The bound agent becomes the account: `default` for the primary install,
-  // or a fresh agent-scoped key on rebind.
-  const { completeWorkChatBinding } = await import("../auth/login-qr.js");
-  const accountId = frameType === "init_agent"
-    ? (isRebind ? `agent-${agentId}` : "default")
-    : deps.accountId;
-
   try {
     saveWorkChatAccount(accountId, {
       agentId,
       ...(userId ? { userId } : {}),
     });
-    registerWorkChatAccountId(accountId);
+    await registerWorkChatAccountId(accountId);
     // Bind the account to the incoming agent for message routing. agentId
     // comes from the event; userId (futureId) is the WorkChat user.
     const { bindAgentToAccount } = await import("../auth/bind-agent.js");
@@ -149,10 +176,6 @@ async function handleAgentLifecycleEvent(
   }
 }
 
-function listWorkChatAccountIdsCount(): number {
-  return listIndexedWorkChatAccountIds().length;
-}
-
 // Typing-indicator helper versions: the host renamed the subpath between
 // releases (2026.3.x exports openclaw/plugin-sdk/channel-runtime, 2026.8.x
 // exports openclaw/plugin-sdk/channel-message). Load whichever resolves —
@@ -261,6 +284,17 @@ export async function processOneFrame(
     return;
   }
 
+  // --- Dedup: platform redelivery / monitor restart can replay frames; a
+  // known msgId is dropped before any dispatch side-effect.
+  if (message.messageId) {
+    const { isDuplicateMessage, recordMessageProcessed } = await import("../storage/seen-msgids.js");
+    if (isDuplicateMessage(deps.accountId, message.messageId)) {
+      logger.info(`inbound: duplicate msgId=${message.messageId}, dropping`);
+      return;
+    }
+    recordMessageProcessed(deps.accountId, message.messageId);
+  }
+
   const receivedAt = Date.now();
   const debug = isDebugMode(deps.accountId);
   const debugTrace: string[] = [];
@@ -268,7 +302,7 @@ export async function processOneFrame(
 
   const ctx = workChatMessageToMsgContext(message, deps.accountId);
   logger.info(
-    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"}`,
+    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"} hasMedia=${Boolean(ctx.MediaUrl)}`,
   );
   logger.debug(`inbound raw frame: ${rawFrame.slice(0, 200)}`);
 
@@ -286,6 +320,30 @@ export async function processOneFrame(
     }
   }
 
+  // --- Inbound media persistence: download the WorkChat-hosted file into the
+  // framework media store so the AI sees a local MediaPath (vision-capable
+  // models can actually read the image) instead of just a URL in the body.
+  // Runs after the slash gate so commands never trigger media downloads.
+  if (ctx.MediaUrl && deps.channelRuntime?.media?.saveMediaBuffer) {
+    try {
+      const media = await downloadInboundMedia(ctx.MediaUrl, deps);
+      if (media) {
+        const saved = await deps.channelRuntime.media.saveMediaBuffer(
+          media.buffer,
+          media.contentType,
+          "inbound",
+          WORKCHAT_MEDIA_MAX_BYTES,
+        );
+        ctx.MediaPath = saved.path;
+        ctx.MediaType = media.contentType ?? ctx.MediaType;
+        logger.info(`inbound media saved: path=${saved.path} type=${media.contentType}`);
+      }
+    } catch (err) {
+      // Non-fatal: the URL is already in Body; the AI can still reference it.
+      deps.errLog(`inbound media download failed url=${redactBody(ctx.MediaUrl)}: ${String(err)}`);
+    }
+  }
+
   // --- Framework command authorization ---
   const rawBody = ctx.Body?.trim() ?? "";
   ctx.CommandBody = rawBody;
@@ -406,8 +464,11 @@ export async function processOneFrame(
         const rawText = String(payload.text ?? "");
         const f = new StreamingMarkdownFilter();
         let text = f.feed(rawText) + f.flush();
+        const mediaUrl = payload.mediaUrl ?? payload.mediaUrls?.[0];
 
-        logger.info(`outbound: to=${ctx.To} textLen=${text.length}`);
+        logger.info(
+          `outbound: to=${ctx.To} textLen=${text.length} mediaUrl=${mediaUrl ? "present" : "none"}`,
+        );
 
         if (debug) {
           debugDeliveries.push({
@@ -421,6 +482,7 @@ export async function processOneFrame(
           to: ctx.To,
           text,
           accountId: deps.accountId,
+          mediaUrl,
         });
         if (sendingResult.cancelled) {
           logger.info(`outbound: cancelled by message_sending hook to=${ctx.To}`);
@@ -429,6 +491,43 @@ export async function processOneFrame(
         text = sendingResult.text;
 
         try {
+          // Media payloads ride the upload-then-card pipeline (same as the
+          // channel outbound sendMedia path); text-only payloads reply directly.
+          if (mediaUrl) {
+            const { isLocalMediaSource, resolveLocalMediaPath, downloadRemoteMediaToTemp, sendWorkChatMediaFile } =
+              await import("./send-media.js");
+            let filePath: string;
+            if (isLocalMediaSource(mediaUrl)) {
+              filePath = resolveLocalMediaPath(mediaUrl);
+              logger.debug(`outbound: local media resolved filePath=${filePath}`);
+            } else if (mediaUrl.startsWith("http://") || mediaUrl.startsWith("https://")) {
+              logger.debug(`outbound: downloading remote mediaUrl=${mediaUrl.slice(0, 80)}...`);
+              filePath = await downloadRemoteMediaToTemp(mediaUrl);
+            } else {
+              logger.warn(
+                `outbound: unrecognized mediaUrl scheme, sending text only mediaUrl=${mediaUrl.slice(0, 80)}`,
+              );
+              filePath = "";
+            }
+            if (filePath) {
+              await sendWorkChatMediaFile({
+                account: {
+                  ...deps.account,
+                  agentId: ctx.AgentId ?? deps.account.agentId,
+                  userId: ctx.From || deps.account.userId,
+                },
+                to: ctx.To,
+                filePath,
+                text,
+                replyToMessageId: ctx.MessageSid,
+                conversationId: ctx.ConversationId,
+                agentId: ctx.AgentId,
+              });
+              emitWorkChatMessageSent({ to: ctx.To, content: text, success: true, accountId: deps.accountId });
+              logger.info(`outbound: media reply sent OK to=${ctx.To}`);
+              return;
+            }
+          }
           const result = await replyWorkChatMessage({
             account: {
               ...deps.account,
@@ -453,7 +552,14 @@ export async function processOneFrame(
       onError: (err, info) => {
         deps.errLog(`workchat reply ${info.kind}: ${String(err)}`);
         const errMsg = err instanceof Error ? err.message : String(err);
-        const notice = `⚠️ 消息发送失败：${errMsg}`;
+        let notice: string;
+        if (errMsg.includes("remote media download failed")) {
+          notice = `⚠️ 媒体文件下载失败，请检查链接是否可访问。`;
+        } else if (errMsg.includes("file upload response") || errMsg.includes("upload failed")) {
+          notice = `⚠️ 媒体文件上传失败，请稍后重试。`;
+        } else {
+          notice = `⚠️ 消息发送失败：${errMsg}`;
+        }
         void sendWorkChatErrorNotice({
           account: deps.account,
           to: ctx.To,

package/src/messaging/send-media.ts

@@ -0,0 +1,201 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import type { WorkChatApiOptions } from "../api/api.js";
+import { sendWorkChatMessage, sendWorkChatReplyMessage, uploadWorkChatFile } from "../api/api.js";
+import { assertSessionActive, pauseOnPermanentError } from "../api/session-guard.js";
+import { WorkChatMsgType } from "../api/types.js";
+import type { ResolvedWorkChatAccount } from "../auth/accounts.js";
+import { logger } from "../util/logger.js";
+import { generateId } from "../util/random.js";
+
+import { buildApiOptions, pushWorkChatMessage } from "./send.js";
+
+/** Backend FileType whitelist (tuzai FileServiceImpl rejects unknown suffixes). */
+const AUDIO_EXTENSIONS = new Set(["wav", "m4a", "mp3"]);
+
+/** True when mediaUrl refers to a local filesystem path (not a remote URL). */
+export function isLocalMediaSource(mediaUrl: string): boolean {
+  const trimmed = mediaUrl.trim();
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) return false;
+  return trimmed.startsWith("/")
+    || trimmed.startsWith("./")
+    || trimmed.startsWith("../")
+    || trimmed.startsWith("~")
+    || trimmed.startsWith("file://")
+    || path.isAbsolute(trimmed);
+}
+
+export function resolveLocalMediaPath(mediaUrl: string): string {
+  if (mediaUrl.startsWith("file://")) {
+    const parsed = new URL(mediaUrl);
+    return process.platform === "win32" ? parsed.pathname.replace(/^\/([A-Za-z]:)/, "$1") : parsed.pathname;
+  }
+  if (mediaUrl.startsWith("~")) {
+    return path.join(os.homedir(), mediaUrl.slice(1));
+  }
+  return path.resolve(mediaUrl);
+}
+
+/**
+ * Map a file path to the message type the WorkChat client renders as a card.
+ * The backend ChatType enum has Video/Voice/Link codes, but the open send API
+ * documents only text/image/audio — audio extensions ride "audio", everything
+ * else (images, and files outside the documented set) rides "image".
+ */
+function resolveMediaMsgType(filePath: string): "image" | "audio" {
+  const ext = path.extname(filePath).replace(/^\./, "").toLowerCase();
+  return AUDIO_EXTENSIONS.has(ext) ? "audio" : "image";
+}
+
+interface MediaSendParams {
+  account: ResolvedWorkChatAccount;
+  to: string;
+  text?: string;
+  replyToMessageId?: string;
+  conversationId?: string;
+  agentId?: string;
+}
+
+function requireAgentId(account: ResolvedWorkChatAccount, agentId?: string): string {
+  const resolved = agentId ?? account.agentId;
+  if (!resolved) {
+    throw new Error("workchat: agentId is required — complete the binding QR flow first");
+  }
+  return resolved;
+}
+
+async function sendMediaRequest(params: {
+  account: ResolvedWorkChatAccount;
+  to: string;
+  msgType: string;
+  content: string;
+  replyToMessageId?: string;
+  conversationId?: string;
+  agentId?: string;
+}): Promise<{ messageId: string }> {
+  const agentId = requireAgentId(params.account, params.agentId);
+  assertSessionActive(params.account.accountId);
+  const opts = buildApiOptions(params.account);
+  const body: {
+    agentId: string;
+    receiveId: string;
+    msgType: string;
+    content: string;
+    conversationId?: string;
+    is_last?: boolean;
+  } = {
+    agentId,
+    receiveId: params.account.userId ?? params.to,
+    msgType: params.msgType,
+    content: params.content,
+    ...(params.conversationId ? { conversationId: params.conversationId } : {}),
+  };
+  // is_last closes the streamed reply placeholder; media replies are single
+  // messages, so the media card itself is always the final frame.
+  if (params.replyToMessageId) body.is_last = true;
+  try {
+    if (params.replyToMessageId) {
+      const result = await sendWorkChatReplyMessage({ opts, messageId: params.replyToMessageId, body });
+      logger.info(`reply media sent to=${params.to} messageId=${result.msgId}`);
+      return { messageId: result.msgId };
+    }
+    const result = await sendWorkChatMessage({ opts, body });
+    logger.info(`push media sent to=${params.to} messageId=${result.msgId}`);
+    return { messageId: result.msgId };
+  } catch (err) {
+    pauseOnPermanentError(params.account.accountId, err instanceof Error ? err.message : String(err));
+    throw err;
+  }
+}
+
+/**
+ * Upload a local file and send it as a WorkChat image/audio message:
+ *   audio (wav/m4a/mp3) → msgType "audio", content {"url"}
+ *   everything else     → msgType "image", content {"url"}
+ * The media content JSON cannot carry a caption, so a text caption (when
+ * present) is sent as its own message right before the media card.
+ */
+export async function sendWorkChatMediaFile(params: MediaSendParams & {
+  filePath: string;
+}): Promise<{ messageId: string }> {
+  const { account, to, filePath } = params;
+  const opts: WorkChatApiOptions = buildApiOptions(account);
+
+  logger.info(`sendMedia: uploading filePath=${filePath} to=${to}`);
+  const uploaded = await uploadWorkChatFile({ opts, filePath, userId: account.userId ?? to });
+  logger.info(`sendMedia: upload done urlLen=${uploaded.url.length} suffix=${uploaded.suffix ?? "(none)"}`);
+
+  const caption = params.text?.trim() ?? "";
+  if (caption) {
+    await pushWorkChatMessage({
+      account,
+      to,
+      text: caption,
+      conversationId: params.conversationId,
+      agentId: params.agentId,
+    });
+  }
+
+  const msgType = resolveMediaMsgType(filePath) === "audio" ? WorkChatMsgType.Audio : WorkChatMsgType.Image;
+  return sendMediaRequest({
+    account,
+    to,
+    msgType,
+    content: JSON.stringify({ url: uploaded.url }),
+    replyToMessageId: params.replyToMessageId,
+    conversationId: params.conversationId,
+    agentId: params.agentId,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Remote URL relay
+// ---------------------------------------------------------------------------
+
+const REMOTE_MEDIA_DIR = path.join(os.tmpdir(), "openclaw", "workchat", "media");
+const REMOTE_MEDIA_DOWNLOAD_TIMEOUT_MS = 60_000;
+
+function tempMediaPath(ext: string): string {
+  return path.join(REMOTE_MEDIA_DIR, `${generateId("remote").replace(/:/g, "-")}${ext}`);
+}
+
+function extensionFromUrlOrContentType(contentType: string | null, url: string): string {
+  const fromUrl = path.extname(new URL(url).pathname).toLowerCase();
+  if (fromUrl) return fromUrl;
+  if (contentType?.startsWith("audio/mpeg")) return ".mp3";
+  if (contentType?.startsWith("audio/wav")) return ".wav";
+  if (contentType?.startsWith("audio/mp4")) return ".m4a";
+  if (contentType?.startsWith("image/")) return ".png";
+  return ".bin";
+}
+
+/**
+ * Download a remote media URL to a local temp file so the send pipeline can
+ * re-upload it to WorkChat file storage — clients render only WorkChat-hosted
+ * image/audio cards, never bare links. Bounded by a 60s abort so a hung
+ * remote never stalls the reply pipeline.
+ */
+export async function downloadRemoteMediaToTemp(url: string): Promise<string> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), REMOTE_MEDIA_DOWNLOAD_TIMEOUT_MS);
+  let response: Response;
+  try {
+    response = (await globalThis.fetch(url, { signal: controller.signal })) as Response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+  if (!response.ok) {
+    throw new Error(
+      `remote media download failed: ${response.status} ${response.statusText} url=${url.slice(0, 80)}`,
+    );
+  }
+  const buf = Buffer.from(await response.arrayBuffer());
+  const ext = extensionFromUrlOrContentType(response.headers.get("content-type"), url);
+  await mkdir(REMOTE_MEDIA_DIR, { recursive: true });
+  const filePath = tempMediaPath(ext);
+  await writeFile(filePath, buf);
+  logger.debug(`downloadRemoteMediaToTemp: saved ${buf.length} bytes to ${filePath}`);
+  return filePath;
+}

package/src/messaging/send.ts

@@ -6,6 +6,7 @@ import {
   sendWorkChatReplyMessage,
 } from "../api/api.js";
 import type { WorkChatApiOptions } from "../api/api.js";
+import { pauseOnPermanentError } from "../api/session-guard.js";
 import type { ResolvedWorkChatAccount } from "../auth/accounts.js";
 import { logger } from "../util/logger.js";
 
@@ -38,6 +39,8 @@ function buildApiOptions(account: ResolvedWorkChatAccount): WorkChatApiOptions {
   };
 }
 
+export { buildApiOptions };
+
 /**
  * Send a reply to a specific inbound message.
  * POST /open-apis/im/v1/messages/{messageId}/reply
@@ -74,6 +77,7 @@ export async function replyWorkChatMessage(params: {
     logger.info(`reply sent to=${to} messageId=${result.msgId}`);
     return { messageId: result.msgId };
   } catch (err) {
+    pauseOnPermanentError(account.accountId, err instanceof Error ? err.message : String(err));
     logger.error(`replyWorkChatMessage: failed to=${to} err=${String(err)}`);
     throw err;
   }
@@ -113,6 +117,7 @@ export async function pushWorkChatMessage(params: {
     logger.info(`push sent to=${to} messageId=${result.msgId}`);
     return { messageId: result.msgId };
   } catch (err) {
+    pauseOnPermanentError(account.accountId, err instanceof Error ? err.message : String(err));
     logger.error(`pushWorkChatMessage: failed to=${to} err=${String(err)}`);
     throw err;
   }

package/src/storage/seen-msgids.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveStateDir } from "./state-dir.js";
+import { logger } from "../util/logger.js";
+
+/**
+ * Persistent inbound message-id buffer (weixin sync-buf analogue): remembers
+ * the most recently processed AGENT_MESSAGE msgIds per account so a monitor
+ * restart / platform redelivery never double-dispatches a user message.
+ */
+
+const SEEN_LIMIT = 500;
+
+function resolveSeenFilePath(accountId: string): string {
+  const safe = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(resolveStateDir(), "openclaw-workchat", "accounts", `${safe}.seen-msgids.json`);
+}
+
+type SeenCache = { ids: string[]; index: Set<string> };
+const cache = new Map<string, SeenCache>();
+
+function loadSeen(accountId: string): SeenCache {
+  const cached = cache.get(accountId);
+  if (cached) return cached;
+  let ids: string[] = [];
+  try {
+    const raw = fs.readFileSync(resolveSeenFilePath(accountId), "utf-8");
+    const parsed = JSON.parse(raw) as { msgIds?: unknown };
+    if (Array.isArray(parsed.msgIds)) {
+      ids = parsed.msgIds.filter((x): x is string => typeof x === "string" && x !== "");
+    }
+  } catch {
+    // missing or corrupt file — start empty
+  }
+  const entry: SeenCache = { ids, index: new Set(ids) };
+  cache.set(accountId, entry);
+  return entry;
+}
+
+function persistSeen(accountId: string, seen: SeenCache): void {
+  try {
+    const filePath = resolveSeenFilePath(accountId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ msgIds: seen.ids }), "utf-8");
+  } catch (err) {
+    logger.warn(`seen-msgids persist failed accountId=${accountId}: ${String(err)}`);
+  }
+}
+
+/** Returns true when msgId was already recorded (duplicate delivery). */
+export function isDuplicateMessage(accountId: string, msgId: string): boolean {
+  if (!msgId) return false;
+  const seen = loadSeen(accountId);
+  return seen.index.has(msgId);
+}
+
+/**
+ * Record msgId as processed. Returns true the first time (not a duplicate);
+ * false when it was already known.
+ */
+export function recordMessageProcessed(accountId: string, msgId: string): boolean {
+  if (!msgId) return true;
+  const seen = loadSeen(accountId);
+  if (seen.index.has(msgId)) return false;
+  seen.index.add(msgId);
+  seen.ids.push(msgId);
+  if (seen.ids.length > SEEN_LIMIT) {
+    const drop = seen.ids.length - SEEN_LIMIT;
+    for (const old of seen.ids.splice(0, drop)) seen.index.delete(old);
+  }
+  persistSeen(accountId, seen);
+  return true;
+}
+
+/** Clear state — only for tests. @internal */
+export function _resetSeenMsgIdsForTest(): void {
+  cache.clear();
+}