@nanhara/hara 0.121.1 → 0.122.1

package/dist/gateway/signal.js

@@ -11,11 +11,11 @@
 // EXTERNAL DEPENDENCY: signal-cli is NOT bundled — it's a separate program the user installs and runs (it is the
 // only way to speak Signal's protocol; there is no official cloud API). The adapter just speaks HTTP/JSON-RPC to
 // the daemon the user has running. See setup notes at the bottom of this file.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, basename } from "node:path";
-import { homedir } from "node:os";
 import { chunkText } from "./telegram.js";
+import { INBOUND_MEDIA_MAX_BYTES, InboundMediaBudget, decodeBase64Media, readResponseBytesLimited, savePrivateMediaBytes, } from "./media.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Base64 expands by 4/3; leave a small fixed budget for the JSON-RPC envelope without permitting an unlimited body.
+const ATTACHMENT_RPC_MAX_BYTES = Math.ceil(INBOUND_MEDIA_MAX_BYTES / 3) * 4 + 64 * 1024;
 // E.164 phone numbers (+15551234567) anywhere in a string → +155****4567 (mirrors hermes' _redact_phone).
 const PHONE_RE = /\+[1-9]\d{6,14}/g;
 /** Redact phone numbers for logging. Keeps a 4/4 head+tail window; never logs the full E.164. (pure) */
@@ -85,7 +85,10 @@ export function parseSignalMessage(raw, selfNumber) {
     if (!data || typeof data !== "object")
         return null;
     const group = data.groupInfo;
-    const groupId = group?.groupId;
+    // signal-cli omits (or nulls) groupInfo for a direct envelope. A present non-null but malformed group object
+    // remains group-classified even without an id, which is the conservative behavior during protocol drift.
+    const isGroup = group != null;
+    const groupId = typeof group?.groupId === "string" && group.groupId.trim() ? group.groupId.trim() : undefined;
     const chatId = groupId ? `group:${groupId}` : String(sender);
     const atts = Array.isArray(data.attachments) ? data.attachments : [];
     const images = atts
@@ -100,6 +103,7 @@ export function parseSignalMessage(raw, selfNumber) {
             userId: String(sender),
             userName: env.sourceName || String(sender),
             text: text || "[图片]",
+            chatType: isGroup ? "group" : "p2p",
         },
         images,
     };
@@ -108,7 +112,7 @@ export function signalAdapter(rpcUrl, selfNumber) {
     const base = rpcUrl.replace(/\/+$/, ""); // trim trailing slashes
     let rpcSeq = 0;
     /** One JSON-RPC 2.0 call to the signal-cli daemon. Returns `result` (any) or null on error. */
-    async function rpc(method, params, signal) {
+    async function rpc(method, params, signal, responseLimit) {
         const id = `${method}_${++rpcSeq}`;
         try {
             const res = await fetch(`${base}/api/v1/rpc`, {
@@ -119,7 +123,9 @@ export function signalAdapter(rpcUrl, selfNumber) {
             });
             if (!res.ok)
                 return null;
-            const j = (await res.json());
+            const j = (responseLimit
+                ? JSON.parse((await readResponseBytesLimited(res, responseLimit, signal)).toString("utf8"))
+                : await res.json());
             if (j.error) {
                 console.error(`hara gateway[signal]: RPC ${method} error:`, redactPhone(JSON.stringify(j.error)));
                 return null;
@@ -132,28 +138,25 @@ export function signalAdapter(rpcUrl, selfNumber) {
             return null;
         }
     }
-    /** Recipient/group routing shared by send + sendFile (mirrors hermes). */
+    /** Recipient/group routing for outbound text sends (mirrors hermes). */
     const target = (chatId) => {
         const id = String(chatId);
         return id.startsWith("group:") ? { groupId: id.slice(6) } : { recipient: [id] };
     };
     /** Fetch a signal-cli attachment by id (base64 over JSON-RPC) → a local path under ~/.hara/signal/media. */
-    async function downloadAttachment(ref) {
+    async function downloadAttachment(ref, options) {
         try {
-            const result = await rpc("getAttachment", { account: selfNumber, id: ref.id });
+            const encodedLimit = Math.ceil(options.maxBytes / 3) * 4 + 64 * 1024;
+            const result = await rpc("getAttachment", { account: selfNumber, id: ref.id }, options.signal, Math.min(encodedLimit, ATTACHMENT_RPC_MAX_BYTES));
             // signal-cli returns either a raw base64 string or { data: "base64..." }
             const b64 = typeof result === "string" ? result : result && typeof result === "object" ? result.data : null;
             if (!b64 || typeof b64 !== "string")
                 return null;
-            const bytes = Buffer.from(b64, "base64");
+            const bytes = decodeBase64Media(b64, options.maxBytes);
             let ext = attachmentExt(ref.contentType, ref.filename);
             if (ext === ".bin")
                 ext = extFromBytes(bytes); // last-resort magic-byte sniff
-            const dir = join(homedir(), ".hara", "signal", "media");
-            mkdirSync(dir, { recursive: true });
-            const path = join(dir, `sig_${Date.now()}_${ref.id.slice(-12)}${ext}`);
-            writeFileSync(path, bytes);
-            return path;
+            return await savePrivateMediaBytes(bytes, { platform: "signal", filenameHint: `attachment${ext}`, ...options });
         }
         catch {
             return null;
@@ -166,15 +169,10 @@ export function signalAdapter(rpcUrl, selfNumber) {
                 await rpc("send", { account: selfNumber, message: part, ...target(chatId) });
             }
         },
-        async sendFile(chatId, filePath) {
-            // Signal has no separate photo/document endpoints — everything is an `attachments` path on `send`.
-            // signal-cli reads the file off the local disk by path, so we just hand it the path (no upload step).
-            await rpc("send", { account: selfNumber, message: "", attachments: [filePath], ...target(chatId) }).catch(() => { });
-            // (readFileSync/basename imported for parity with the other adapters' file plumbing; signal-cli reads by path.)
-            void readFileSync;
-            void basename;
-        },
-        async start(onMessage, signal) {
+        // signal-cli's JSON-RPC attachment API accepts only a server-side pathname. Exposing sendFile here would
+        // reopen the verified snapshot after the security boundary, so outbound files stay disabled for Signal
+        // until its daemon offers a byte-oriented upload API.
+        async start(onMessage, signal, shouldDownload) {
             console.error(`hara gateway[signal]: polling signal-cli daemon at ${base} as ${redactPhone(selfNumber)} (ensure \`signal-cli -a <number> daemon --http\` is running).`);
             while (!signal.aborted) {
                 try {
@@ -186,10 +184,15 @@ export function signalAdapter(rpcUrl, selfNumber) {
                         const parsed = parseSignalMessage(raw, selfNumber);
                         if (!parsed)
                             continue;
-                        for (const ref of parsed.images) {
-                            const path = await downloadAttachment(ref);
-                            if (path)
-                                (parsed.msg.images ??= []).push(path);
+                        if (shouldDownload?.(parsed.msg) === true) {
+                            const budget = new InboundMediaBudget("signal", signal);
+                            for (const ref of parsed.images) {
+                                const path = await budget.download((options) => downloadAttachment(ref, options));
+                                if (path) {
+                                    (parsed.msg.images ??= []).push(path);
+                                    (parsed.msg.transientFiles ??= []).push(path);
+                                }
+                            }
                         }
                         await onMessage(parsed.msg).catch(() => { });
                     }

package/dist/gateway/slack.js

@@ -4,9 +4,7 @@
 // API (bot token, xoxb-). Same ChatAdapter shape as Discord/Telegram, so all cross-platform gateway plumbing
 // (send_file, in-chat system context, stuck-guard, image attach/describe) works unchanged. Two tokens are
 // required because Socket Mode (xapp-) and the Web API (xoxb-) are separate auth scopes.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, basename } from "node:path";
-import { homedir } from "node:os";
+import { InboundMediaBudget, savePrivateResponse } from "./media.js";
 import { chunkText } from "./telegram.js";
 const WEB = "https://slack.com/api";
 const WSImpl = globalThis.WebSocket;
@@ -34,16 +32,12 @@ async function slackApi(method, token, body) {
 }
 /** Slack file url_private is gated — it needs the BOT token as a Bearer header (a plain GET returns the login
  *  page HTML, not the bytes). Download into ~/.hara/slack/media so the agent can SEE it. */
-async function downloadSlackFile(url, name, botToken) {
+async function downloadSlackFile(url, name, botToken, options) {
     try {
-        const r = await fetch(url, { headers: { Authorization: `Bearer ${botToken}` } });
+        const r = await fetch(url, { headers: { Authorization: `Bearer ${botToken}` }, signal: options.signal });
         if (!r.ok)
             return null;
-        const dir = join(homedir(), ".hara", "slack", "media");
-        mkdirSync(dir, { recursive: true });
-        const path = join(dir, `sl_${Date.now()}_${basename(name) || "file.bin"}`);
-        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
-        return path;
+        return await savePrivateResponse(r, { platform: "slack", filenameHint: name, ...options });
     }
     catch {
         return null;
@@ -52,6 +46,13 @@ async function downloadSlackFile(url, name, botToken) {
 /** Parse a Slack Events API `event` (the inner `payload.event`) → InboundMsg + its image file refs (pure;
  *  download happens in start()). null = ignore (not a user message / our own / an edit/delete subtype / empty).
  *  Mirrors discord.ts's parseDiscordMessage so it's unit-testable without the network. */
+export function slackChatType(event) {
+    const channel = String(event?.channel ?? "").trim();
+    // Slack reserves D-prefixed ids for direct-message channels. It is stronger than a contradictory event field.
+    if (channel.startsWith("D"))
+        return "p2p";
+    return String(event?.channel_type ?? "").trim().toLowerCase() === "im" ? "p2p" : "group";
+}
 export function parseSlackEvent(event, selfId) {
     if (event?.type !== "message")
         return null;
@@ -76,6 +77,7 @@ export function parseSlackEvent(event, selfId) {
             userId: String(event.user),
             userName: String(event.user), // Slack events carry only the id; users.info would resolve a name (skipped for zero extra calls)
             text: text || "[图片]",
+            chatType: slackChatType(event),
         },
         imageUrls,
     };
@@ -89,16 +91,16 @@ export function slackAdapter(appToken, botToken) {
                 await slackApi("chat.postMessage", botToken, { channel: chatId, text: part });
             }
         },
-        async sendFile(chatId, filePath) {
+        async sendFile(chatId, file) {
             // 3-step external-upload flow (getUploadURLExternal → PUT bytes → completeUploadExternal): the current,
             // non-deprecated path that works with just files:write (the old files.upload can 404/missing_scope).
             try {
-                const bytes = readFileSync(filePath);
-                const name = basename(filePath);
+                const bytes = file.bytes;
+                const name = file.safeName;
                 const url = await slackApi("files.getUploadURLExternal", botToken, { filename: name, length: bytes.length });
                 if (!url?.ok || !url.upload_url || !url.file_id)
                     return;
-                const up = await fetch(url.upload_url, { method: "POST", body: new Blob([bytes]) }); // presigned URL: no auth header
+                const up = await fetch(url.upload_url, { method: "POST", body: new Blob([new Uint8Array(bytes)]) }); // presigned URL: no auth header
                 if (!up.ok)
                     return;
                 await slackApi("files.completeUploadExternal", botToken, { files: [{ id: url.file_id, title: name }], channel_id: String(chatId) });
@@ -107,7 +109,7 @@ export function slackAdapter(appToken, botToken) {
                 /* upload/send failed — surfaced upstream as "no file delivered" */
             }
         },
-        async start(onMessage, signal) {
+        async start(onMessage, signal, shouldDownload) {
             if (!WSImpl) {
                 console.error("hara gateway: Slack needs Node ≥ 22 (global WebSocket). Upgrade Node.");
                 return;
@@ -118,7 +120,7 @@ export function slackAdapter(appToken, botToken) {
             while (!signal.aborted) {
                 const wss = await openSocketUrl(appToken);
                 if (wss)
-                    await connectOnce(wss, botToken, selfId, onMessage, signal);
+                    await connectOnce(wss, botToken, selfId, onMessage, signal, shouldDownload);
                 if (!signal.aborted)
                     await sleep(3000, signal); // reconnect backoff (and re-open: each URL is single-use)
             }
@@ -133,7 +135,7 @@ async function openSocketUrl(appToken) {
 /** One Socket Mode connection: receive envelopes, ACK each by echoing its envelope_id, and dispatch message
  *  events. Resolves on close/disconnect/abort; the caller re-opens a new URL and reconnects. v1 keeps it simple —
  *  no buffered-payload backpressure (the daemon spawns one hara per message anyway). */
-function connectOnce(url, botToken, selfId, onMessage, signal) {
+function connectOnce(url, botToken, selfId, onMessage, signal, shouldDownload) {
     return new Promise((resolve) => {
         const ws = new WSImpl(url);
         const stop = () => {
@@ -176,10 +178,15 @@ function connectOnce(url, botToken, selfId, onMessage, signal) {
             if (p.type === "events_api") {
                 const parsed = parseSlackEvent(p.payload?.event, selfId);
                 if (parsed) {
-                    for (const im of parsed.imageUrls) {
-                        const path = await downloadSlackFile(im.url, im.name, botToken);
-                        if (path)
-                            (parsed.msg.images ??= []).push(path);
+                    if (shouldDownload?.(parsed.msg) === true) {
+                        const budget = new InboundMediaBudget("slack", signal);
+                        for (const im of parsed.imageUrls) {
+                            const path = await budget.download((options) => downloadSlackFile(im.url, im.name, botToken, options));
+                            if (path) {
+                                (parsed.msg.images ??= []).push(path);
+                                (parsed.msg.transientFiles ??= []).push(path);
+                            }
+                        }
                     }
                     await onMessage(parsed.msg).catch(() => { });
                 }

package/dist/gateway/telegram.js

@@ -1,9 +1,7 @@
 // Telegram adapter for `hara gateway` — long-poll getUpdates + sendMessage over the Bot API (built-in
 // fetch, zero new dep). Token from HARA_TELEGRAM_TOKEN. The generic `ChatAdapter` shape is what WeChat(iLink)
 // / Feishu plug into next.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, basename } from "node:path";
-import { homedir } from "node:os";
+import { InboundMediaBudget, savePrivateResponse } from "./media.js";
 const API = "https://api.telegram.org";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Extract an InboundMsg from a Telegram getUpdates result item (pure). Accepts text and photo messages
@@ -21,6 +19,7 @@ export function parseTelegramUpdate(u) {
         userId: m.from?.id ?? 0,
         userName: m.from?.username || m.from?.first_name || String(m.from?.id ?? ""),
         text: text || "[图片]",
+        ...(m.chat?.type === "private" ? { chatType: "p2p" } : ["group", "supergroup"].includes(m.chat?.type) ? { chatType: "group" } : {}),
     };
 }
 /** The largest photo's file_id (Telegram sends `photo` as an ascending size array) (pure). null if none. */
@@ -29,21 +28,17 @@ export function photoFileId(u) {
     return Array.isArray(photo) && photo.length ? (photo[photo.length - 1]?.file_id ?? null) : null;
 }
 /** Download a Telegram file by file_id → a local path under ~/.hara/telegram/media (getFile then the file CDN). */
-async function downloadTelegramFile(base, token, fileId) {
+async function downloadTelegramFile(base, token, fileId, options) {
     try {
-        const r = await fetch(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`);
+        const r = await fetch(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`, { signal: options.signal });
         const j = (await r.json());
         const fp = j?.result?.file_path;
         if (!fp)
             return null;
-        const dl = await fetch(`${API}/file/bot${token}/${fp}`);
+        const dl = await fetch(`${API}/file/bot${token}/${fp}`, { signal: options.signal });
         if (!dl.ok)
             return null;
-        const dir = join(homedir(), ".hara", "telegram", "media");
-        mkdirSync(dir, { recursive: true });
-        const path = join(dir, `tg_${Date.now()}_${basename(fp)}`);
-        writeFileSync(path, Buffer.from(await dl.arrayBuffer()));
-        return path;
+        return await savePrivateResponse(dl, { platform: "telegram", filenameHint: fp, ...options });
     }
     catch {
         return null;
@@ -60,27 +55,41 @@ export function chunkText(text, max = 4000) {
 }
 export function telegramAdapter(token) {
     const base = `${API}/bot${token}`;
+    const request = async (method, init) => {
+        const response = await fetch(`${base}/${method}`, init);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        if (!response.ok || body?.ok === false) {
+            throw new Error(`Telegram ${method} failed: HTTP ${response.status}${body?.description ? ` · ${body.description}` : ""}`);
+        }
+        return body;
+    };
     return {
         name: "telegram",
         async send(chatId, text) {
             for (const part of chunkText(text || "(empty)")) {
-                await fetch(`${base}/sendMessage`, {
+                await request("sendMessage", {
                     method: "POST",
                     headers: { "content-type": "application/json" },
                     body: JSON.stringify({ chat_id: chatId, text: part }),
-                }).catch(() => { });
+                });
             }
         },
-        async sendFile(chatId, filePath) {
+        async sendFile(chatId, file) {
             // images → sendPhoto (inline preview); everything else → sendDocument (keeps the filename)
-            const name = basename(filePath);
+            const name = file.safeName;
             const isImg = /\.(png|jpe?g|gif|webp)$/i.test(name);
             const form = new FormData();
             form.append("chat_id", String(chatId));
-            form.append(isImg ? "photo" : "document", new Blob([readFileSync(filePath)]), name);
-            await fetch(`${base}/${isImg ? "sendPhoto" : "sendDocument"}`, { method: "POST", body: form }).catch(() => { });
+            form.append(isImg ? "photo" : "document", new Blob([new Uint8Array(file.bytes)]), name);
+            await request(isImg ? "sendPhoto" : "sendDocument", { method: "POST", body: form });
         },
-        async start(onMessage, signal) {
+        async start(onMessage, signal, shouldDownload) {
             let offset = 0;
             while (!signal.aborted) {
                 try {
@@ -96,10 +105,13 @@ export function telegramAdapter(token) {
                         if (!msg)
                             continue;
                         const fid = photoFileId(u); // a photo message → download it so the agent can SEE it
-                        if (fid) {
-                            const path = await downloadTelegramFile(base, token, fid);
-                            if (path)
+                        if (fid && shouldDownload?.(msg) === true) {
+                            const budget = new InboundMediaBudget("telegram", signal);
+                            const path = await budget.download((options) => downloadTelegramFile(base, token, fid, options));
+                            if (path) {
                                 msg.images = [path];
+                                msg.transientFiles = [path];
+                            }
                         }
                         await onMessage(msg).catch(() => { });
                     }

package/dist/gateway/tmux-routes.js

@@ -6,7 +6,7 @@
 //
 // Safety: the daemon only reaches this AFTER its allow-list gate (so only the owner can trigger it), and it
 // ONLY injects into panes that opted in by registering — never an arbitrary pane.
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { chmodSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -26,8 +26,16 @@ function load() {
     }
 }
 function save(routes) {
-    mkdirSync(dir(), { recursive: true });
-    writeFileSync(storePath(), JSON.stringify({ routes }, null, 2));
+    mkdirSync(dir(), { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir(), 0o700);
+    }
+    catch { /* best effort */ }
+    writeFileSync(storePath(), JSON.stringify({ routes }, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(storePath(), 0o600);
+    }
+    catch { /* best effort */ }
 }
 /** Register (or refresh) a pane as awaiting a reply. De-dups by pane. mode "once" (default) = consumed after one
  *  reply; "bind" = persistent (every reply injects until unbound). */

package/dist/gateway/wecom.js

@@ -10,11 +10,10 @@
 // chunked protocol → AES-256-CBC decrypt inbound media that carries an `aeskey`. Every request frame carries a
 // `headers.req_id` and the server echoes it back so request/response are correlated. v1 limitations are documented
 // at the bottom of this file (the public spec is thin — fields are best-effort and tolerant of shape drift).
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, basename, extname } from "node:path";
-import { homedir } from "node:os";
+import { basename, extname } from "node:path";
 import { randomUUID, createDecipheriv, createHash } from "node:crypto";
 import { chunkText } from "./telegram.js";
+import { InboundMediaBudget, decodeBase64Media, readResponseBytesLimited, savePrivateMediaBytes } from "./media.js";
 const DEFAULT_WS_URL = "wss://openws.work.weixin.qq.com";
 const WSImpl = globalThis.WebSocket;
 // app-level command verbs on the AI Bot gateway (mirror the Hermes constants)
@@ -153,45 +152,48 @@ export function parseWecomMessage(payload, selfBotId) {
     const media = extractWecomMedia(body);
     if (!text && !media.length)
         return null; // unsupported type or empty
+    // WeCom AI Bot callbacks use chattype="single" or "group". Only the explicit single value proves a DM;
+    // missing/unknown types fail closed as group even when chatid happens to be absent.
+    const chatType = String(body.chattype ?? "").trim().toLowerCase() === "single" ? "p2p" : "group";
     return {
         msg: {
             chatId,
             userId: senderId || chatId,
             userName: String(sender.name ?? sender.userid ?? senderId ?? chatId),
             text: text || "[图片]",
+            chatType,
         },
         media,
     };
 }
 /** Download (and AES-decrypt if needed) a WeCom inbound media ref → a local path under ~/.hara/wecom/media. null on
  *  failure. Inline base64 and remote (optionally encrypted) urls are both handled. */
-async function downloadWecomMedia(ref) {
+async function downloadWecomMedia(ref, options) {
     try {
         let data = null;
         if (ref.base64) {
-            data = Buffer.from(ref.base64.split(",").pop().trim(), "base64");
+            data = decodeBase64Media(ref.base64, options.maxBytes);
         }
         else if (ref.url) {
-            const r = await fetch(ref.url);
+            const r = await fetch(ref.url, { signal: options.signal });
             if (!r.ok)
                 return null;
-            let buf = Buffer.from(await r.arrayBuffer());
-            if (buf.length > ABSOLUTE_MAX_BYTES)
-                return null;
-            if (ref.aesKeyB64)
-                buf = decryptWecomMedia(buf, ref.aesKeyB64);
-            data = buf;
+            data = await readResponseBytesLimited(r, options.maxBytes, options.signal);
         }
         if (!data || !data.length)
             return null;
-        const dir = join(homedir(), ".hara", "wecom", "media");
-        mkdirSync(dir, { recursive: true });
+        if (ref.aesKeyB64)
+            data = decryptWecomMedia(data, ref.aesKeyB64);
+        if (!data.length || data.length > options.maxBytes)
+            return null;
         let name = ref.fileName ? basename(ref.fileName) : "";
         if (!name || (ref.kind === "image" && !extname(name)))
             name = `image${imageExtFromBytes(data)}`;
-        const path = join(dir, `wc_${Date.now()}_${name || "file.bin"}`);
-        writeFileSync(path, data);
-        return path;
+        return await savePrivateMediaBytes(data, {
+            platform: "wecom",
+            filenameHint: name || "file.bin",
+            ...options,
+        });
     }
     catch {
         return null;
@@ -201,17 +203,17 @@ export function wecomAdapter(botId, secret, wsUrl = DEFAULT_WS_URL) {
     // per-connection request/response correlation lives inside connectOnce; send/sendFile use the live socket handle
     // it publishes through `conn`.
     const conn = { send: null };
-    // Upload a local file to WeCom via the 3-step chunked protocol → its media_id. Throws on any step error.
-    async function uploadMedia(filePath, mediaType) {
+    // Upload already-verified bytes to WeCom via the 3-step chunked protocol → its media_id.
+    async function uploadMedia(file, mediaType) {
         if (!conn.send)
             throw new Error("WeCom socket not connected");
-        const data = readFileSync(filePath);
+        const data = file.bytes;
         if (data.length > ABSOLUTE_MAX_BYTES)
             throw new Error(`file exceeds WeCom 20MB limit: ${data.length} bytes`);
         const totalChunks = Math.max(1, Math.ceil(data.length / UPLOAD_CHUNK_SIZE));
         const init = await conn.send(CMD_UPLOAD_INIT, {
             type: mediaType,
-            filename: basename(filePath),
+            filename: file.safeName,
             total_size: data.length,
             total_chunks: totalChunks,
             md5: createHash("md5").update(data).digest("hex"),
@@ -242,25 +244,25 @@ export function wecomAdapter(botId, secret, wsUrl = DEFAULT_WS_URL) {
                     .catch(() => { });
             }
         },
-        async sendFile(chatId, filePath) {
+        async sendFile(chatId, file) {
             if (!conn.send)
                 return;
-            const mediaType = isImageName(filePath) ? "image" : "file";
+            const mediaType = isImageName(file.safeName) ? "image" : "file";
             try {
-                const mediaId = await uploadMedia(filePath, mediaType);
+                const mediaId = await uploadMedia(file, mediaType);
                 await conn.send(CMD_SEND, { chatid: String(chatId), msgtype: mediaType, [mediaType]: { media_id: mediaId } });
             }
             catch {
                 /* upload/send failed — caller surfaces a generic failure; nothing else to do */
             }
         },
-        async start(onMessage, signal) {
+        async start(onMessage, signal, shouldDownload) {
             if (!WSImpl) {
                 console.error("hara gateway: WeCom needs Node ≥ 22 (global WebSocket). Upgrade Node.");
                 return;
             }
             while (!signal.aborted) {
-                await connectOnce(botId, secret, wsUrl, conn, onMessage, signal);
+                await connectOnce(botId, secret, wsUrl, conn, onMessage, signal, shouldDownload);
                 if (!signal.aborted)
                     await sleep(3000, signal); // reconnect backoff
             }
@@ -270,7 +272,7 @@ export function wecomAdapter(botId, secret, wsUrl = DEFAULT_WS_URL) {
 /** One gateway connection: open WS → `aibot_subscribe` auth → correlate request/response by req_id, dispatch
  *  `aibot_msg_callback` events, heartbeat with `ping`. Resolves on close/abort; the caller reconnects (fresh
  *  subscribe each time — v1 keeps it simple, no resume). */
-function connectOnce(botId, secret, wsUrl, conn, onMessage, signal) {
+function connectOnce(botId, secret, wsUrl, conn, onMessage, signal, shouldDownload) {
     return new Promise((resolve) => {
         const ws = new WSImpl(wsUrl);
         let hb = null;
@@ -371,10 +373,15 @@ function connectOnce(botId, secret, wsUrl, conn, onMessage, signal) {
             }
             const parsed = parseWecomMessage(p, botId);
             if (parsed) {
-                for (const ref of parsed.media) {
-                    const path = await downloadWecomMedia(ref);
-                    if (path)
-                        (parsed.msg.images ??= []).push(path);
+                if (shouldDownload?.(parsed.msg) === true) {
+                    const budget = new InboundMediaBudget("wecom", signal);
+                    for (const ref of parsed.media) {
+                        const path = await budget.download((options) => downloadWecomMedia(ref, options));
+                        if (path) {
+                            (parsed.msg.images ??= []).push(path);
+                            (parsed.msg.transientFiles ??= []).push(path);
+                        }
+                    }
                 }
                 await onMessage(parsed.msg).catch(() => { });
             }