clawgram 2.18.0 → 2.19.0

package/README.md

@@ -32,6 +32,7 @@ Clawgram is a personal-Telegram channel plugin for [OpenClaw](https://github.com
 - **Read receipts** — mark messages as read
 - **Emoji reactions** — acknowledge a message with a reaction instead of a reply (`react` action)
 - **Chat metadata** — title, type, member count, description, forum flag and pinned message (`chatInfo` action)
+- **Attachments on demand** — fetch the photo or voice note on any message in read scope, as a reading, a file, or both (`fetch-media` action)
 - **Chat management** — create supergroups, add/remove members, promote/demote admins, transfer ownership, export invite links (`createGroup`, `addMembers`, `removeMember`, `promoteAdmin`, `demoteAdmin`, `transferOwnership`, `inviteLink`) — off until `manageChats` allows it
 - **User allowlist** — control which user has access to send messages for direct
 - **Chat allowlist** — control which chats the assistant can access
@@ -739,6 +740,53 @@ first. These errors are surfaced as-is rather than retried.
 }
 ```
 
+## Fetching attachments
+
+Inbound attachments are read as they arrive: a photo or a voice note sent while the agent is being
+addressed becomes text in the message body, and the bytes are dropped. History reads (`read`) carry
+attachment *metadata* — kind, file name, size, duration — and fetch nothing. That leaves two things
+out: an image posted in a chat before the agent was addressed, and any reuse of an image at all,
+because the file the inbound path read is deleted the moment the reading ends.
+
+`fetch-media` covers both. It takes one message and returns what is attached to it.
+
+| Parameter | Aliases | Notes |
+|---|---|---|
+| `chatId` | `target`, `to`, `chat` | Same targets as everywhere else: `@username`, numeric id, `me` |
+| `messageId` | `id`, `message`, `msgId` | The id `read` reported for the message |
+| `mode` | — | `both` (default), `read`, `file` |
+
+Modes differ in what happens to the bytes:
+
+- **`read`** — the attachment is turned into text (an image described, a voice note transcribed) and
+  the file is deleted, exactly the inbound contract. No path is returned.
+- **`file`** — the file is kept and its path returned, and no understanding model is called. This is
+  what forwarding through `upload-file` or attaching to a ticket needs.
+- **`both`** — the default: the reading *and* the path, from a single download.
+
+The action is confined by `readChats`, the same scope that gates history and membership: a chat the
+account may not read history from cannot be a source of bytes either. The action name also answers
+to `fetchMedia`, `download-media`, `downloadMedia` and `getMedia`.
+
+What comes back is `ok: true` with `media` (the same metadata `read` reports), `understanding`
+(`description` or `transcript`), and `text` and/or `filePath` per the mode. A fetch that yields
+nothing is not an error — it says which nothing it was:
+
+| `error` | Meaning |
+|---|---|
+| `message-not-found` | No such message, or it was deleted |
+| `no-media` | The message is text only |
+| `unsupported-media` | An attachment this channel does not read — video, a spreadsheet, a sticker |
+| `media-too-large` | Over the 25 MB inbound cap. Telegram reports no size for a compressed photo, so this is a document limit in practice |
+
+A reading that fails while the download succeeded still returns `ok: true`, with `readError` beside
+the path: the bytes are already there and can still be forwarded.
+
+**Fetched files live in the system temp directory** (`clawgram-fetched/`), named after the chat and
+message they came from, and are pruned after 24 hours by the next fetch. Nothing else removes them,
+and nothing sends them anywhere — putting a fetched file in a chat is an ordinary `upload-file`,
+with whatever confirmation the deployment requires for that.
+
 ## Security and privacy
 
 This plugin holds credentials for a real Telegram account and handles private correspondence. What
@@ -749,7 +797,7 @@ that means in practice, and what the code does about it:
 | `apiHash`, `sessionString` | `openclaw.json`, or a secret store | Written there by `--auth`. Never logged. Since 2.1.0 the session string is not printed after login either — only shown, behind an explicit warning, if you decline the automatic config write. Since 2.2.0 both accept a **SecretRef** instead of a literal, so the credential need not sit in the config file at all |
 | Proxy password | `accounts.*.proxy.password`, or a secret store | Also accepts a SecretRef since 2.2.0. Marked `sensitive` in `uiHints`; diagnostics say `socks4`/`socks5` and nothing more. An invalid proxy fails the account rather than falling back to a direct connection, which would leak the host IP to Telegram |
 | Message bodies | channel logs | **Not logged.** Outbound sends record recipient, ids and `textLength`. Until 2.1.0 the full outbound text was written to the channel log — if you ran 2.0.x, treat those journal entries as containing private correspondence |
-| Read scope | `accounts.*.readChats` | History and membership reads are confined to the listed chats. Absent means no restriction; an empty array denies everything |
+| Read scope | `accounts.*.readChats` | History, membership and attachment fetches are confined to the listed chats. Absent means no restriction; an empty array denies everything |
 | Manage scope | `accounts.*.manageChats` | Creating groups, changing membership, admin rights, ownership and invite links are confined to the listed chats — and **off entirely** when the key is absent or empty (opposite default to `readChats`, because these actions change chats rather than read them) |
 | 2FA password | `accounts.*.twoFaPassword`, or a secret store | Read only by `transferOwnership`, exchanged for an SRP proof in-process. Accepts a SecretRef since 2.12.0; `sensitive` in `uiHints`; on the forbidden-log-keys list the static tests enforce |
 | Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions |

package/dist/channel.js

@@ -12,6 +12,15 @@ const node_fs_1 = require("node:fs");
  *  a different conversation from a spoken line or a screenshot, and the
  *  transfer is not free. */
 const INBOUND_MEDIA_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * How long a file fetched by `fetch-media` stays on disk.
+ *
+ * Long enough for the turn that asked for it and the next one — forwarding a
+ * screenshot happens minutes after reading it, not days — and short enough
+ * that a chat full of images does not silently become a copy of itself in the
+ * temp directory.
+ */
+const FETCHED_MEDIA_TTL_MS = 24 * 60 * 60 * 1000;
 /**
  * What this channel promises the Gateway.
  *
@@ -43,6 +52,7 @@ const CHANNEL_CAPABILITIES = {
     },
 };
 const media_1 = require("./media");
+const fetch_media_1 = require("./fetch-media");
 const channel_runtime_1 = require("openclaw/plugin-sdk/channel-runtime");
 const param_readers_1 = require("openclaw/plugin-sdk/param-readers");
 const tool_send_1 = require("openclaw/plugin-sdk/tool-send");
@@ -239,6 +249,33 @@ function resolveAgentDirForMedia(cfg) {
     const dir = node_path_1.default.join(stateDir, "agents", agentId, "agent");
     return (0, node_fs_1.existsSync)(dir) ? dir : undefined;
 }
+/**
+ * Turns a downloaded attachment into text.
+ *
+ * Shared by the inbound path and by `fetch-media`: the backend choice lives in
+ * `runtime.mediaUnderstanding`, and both callers have to make exactly the same
+ * call — an image read on arrival and the same image read on request must not
+ * become two different readings because two call sites drifted.
+ */
+async function understandAttachmentFile(params) {
+    const media = params.runtime?.mediaUnderstanding;
+    if (!media)
+        return undefined;
+    const result = params.understanding === "transcript"
+        ? await media.transcribeAudioFile({
+            filePath: params.filePath,
+            cfg: params.cfg,
+            mime: params.mimeType,
+        })
+        : await media.describeImageFile({
+            filePath: params.filePath,
+            cfg: params.cfg,
+            mime: params.mimeType,
+            agentDir: resolveAgentDirForMedia(params.cfg),
+        });
+    const text = typeof result?.text === "string" ? result.text.trim() : "";
+    return text || undefined;
+}
 async function readInboundAttachment(params) {
     const media = params.runtime?.mediaUnderstanding;
     const message = params.event?.message;
@@ -267,19 +304,13 @@ async function readInboundAttachment(params) {
         return undefined;
     }
     try {
-        const result = downloaded.understanding === "transcript"
-            ? await media.transcribeAudioFile({
-                filePath: downloaded.path,
-                cfg: params.cfg,
-                mime: downloaded.mimeType,
-            })
-            : await media.describeImageFile({
-                filePath: downloaded.path,
-                cfg: params.cfg,
-                mime: downloaded.mimeType,
-                agentDir: resolveAgentDirForMedia(params.cfg),
-            });
-        const read = typeof result?.text === "string" ? result.text.trim() : "";
+        const read = await understandAttachmentFile({
+            runtime: params.runtime,
+            cfg: params.cfg,
+            filePath: downloaded.path,
+            mimeType: downloaded.mimeType,
+            understanding: downloaded.understanding,
+        });
         if (!read) {
             params.log?.info?.("clawgram attachment read empty", {
                 accountId: params.accountId,
@@ -377,6 +408,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "Use the `chatInfo` action to learn what a chat is — title, type, member count, description, pinned message — instead of guessing from its id.",
                 "Use the `topics` action to list a forum's topics by name (optional `query` narrows by title); that is where a `threadId` comes from when someone names a topic instead of quoting a message in it.",
                 "Pass that `threadId` to `read` as well: without it a forum read returns every topic interleaved rather than the one that was asked about.",
+                "Use the `fetch-media` action (chatId + messageId) to fetch the attachment on a message `read` reported: `mode: \"read\"` returns a description of an image or a transcript of a voice note, `\"file\"` returns a path to reuse, `\"both\"` (default) returns both. `read` only says an attachment exists; this is what brings it.",
                 "Use the `dialogs` action to find out which group chats this account is actually in — including ones nobody has configured yet. It reports id, title and type only, never direct chats, and only when the account enables `discoverChats`.",
                 "Use `createGroup` (title, optional about, optional users) to create a new Telegram supergroup; `addMembers`/`removeMember` change who is in a managed chat, `promoteAdmin`/`demoteAdmin` grant or revoke admin rights, `transferOwnership` hands the chat over, `inviteLink` issues an invite link for people Telegram refused to add directly.",
             ],
@@ -387,6 +419,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "clawgram can add and clear emoji reactions on messages. A plain Telegram account holds one reaction per message, so a new emoji replaces the previous one.",
                 "clawgram can describe a chat via `chatInfo`: title, type (direct/group/supergroup/channel), member count, description, whether it is a forum, and the pinned message id.",
                 "clawgram can list the topics of a forum supergroup via `topics`: id, title, last message, and whether a topic is closed, hidden or pinned.",
+                "clawgram can fetch the attachment on any message inside its read scope via `fetch-media`: images come back described, voice notes transcribed, and either can be returned as a file path for reuse.",
                 "clawgram can list the group chats the account belongs to via `dialogs`, when the account sets discoverChats. Metadata only, no direct chats — it answers \"where am I\", not \"what was said\".",
                 "clawgram can manage chats where the account's manageChats config allows it: create supergroups, add and remove members, promote and demote admins, transfer ownership, and export invite links.",
             ],
@@ -1356,6 +1389,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // file stays on disk. That is exactly what happened on 2026-08-07.
                     actions: [
                         "send", "read", "participants", "joins", "react", "chatInfo", "topics", "dialogs", "upload-file",
+                        // Reading an attachment that is already in a chat. `read` reports
+                        // that a photo exists; this is what turns it into something the
+                        // agent can look at or pass on.
+                        "fetch-media",
                         // Chat management (2.12.0) — gated by the account's manageChats
                         // scope; without it every one of these is refused.
                         "createGroup", "addMembers", "removeMember",
@@ -1416,6 +1453,166 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         messages: history.messages,
                     });
                 }
+                // The attachment on a message that is already in a chat.
+                //
+                // `read` says a photo exists; it does not fetch it, and the inbound
+                // path only ever reads what arrives while the agent is being addressed.
+                // Everything else — a screenshot posted an hour ago, a diagram in a
+                // chat the agent reads but was not tagged in — was visible to the
+                // channel and unreachable to the agent. Same `readChats` scope as
+                // history: this must not become a way to pull bytes out of a chat the
+                // account was never allowed to read.
+                if (action === "fetch-media" || action === "fetchMedia" ||
+                    action === "download-media" || action === "downloadMedia" ||
+                    action === "getMedia") {
+                    const fetchParams = (0, fetch_media_1.parseFetchMediaParams)(params);
+                    const fetchAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!fetchAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    if (!(0, history_1.isChatReadable)(fetchParams.target, resolveAccountReadChats(cfg, fetchAccountId))) {
+                        actionLog.warn("clawgram fetch-media refused: chat outside read scope", {
+                            accountId: fetchAccountId,
+                            target: fetchParams.target,
+                        });
+                        throw new Error(`clawgram: not-allowed-chat ${fetchParams.target}`);
+                    }
+                    const fetchGram = runtimes.get(fetchAccountId);
+                    if (!fetchGram) {
+                        throw new Error(`clawgram: runtime not found for account ${fetchAccountId}`);
+                    }
+                    // Fetching is a read: a dry run answers for real, the same way `read`
+                    // does. Nothing leaves the machine — the file lands in a temp
+                    // directory this channel prunes — so a rehearsal that reported
+                    // "would fetch" would only teach the agent to ask twice.
+                    const found = await fetchGram.getMessageById(fetchParams.target, fetchParams.messageId);
+                    const fetchChatId = found.chatId ?? fetchParams.target;
+                    if (!found.message) {
+                        actionLog.info("clawgram fetch-media found no message", {
+                            accountId: fetchAccountId,
+                            chatId: fetchChatId,
+                            messageId: fetchParams.messageId,
+                        });
+                        return (0, core_1.jsonResult)({
+                            ok: false,
+                            accountId: fetchAccountId,
+                            chatId: fetchChatId,
+                            messageId: String(fetchParams.messageId),
+                            error: "message-not-found",
+                        });
+                    }
+                    // `read` throws the file away, so it gets a directory of its own —
+                    // the shared directory is keyed by chat and message, and deleting
+                    // that path would pull the file out from under an earlier `both`
+                    // fetch of the same message that handed the caller a path.
+                    const sharedFetchDir = node_path_1.default.join(node_os_1.default.tmpdir(), "clawgram-fetched");
+                    let fetchDir = sharedFetchDir;
+                    if (fetchParams.mode === "read") {
+                        const { mkdtemp } = await import("node:fs/promises");
+                        fetchDir = await mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "clawgram-media-"));
+                    }
+                    else {
+                        await (0, media_1.pruneFetchedMedia)(sharedFetchDir, FETCHED_MEDIA_TTL_MS, Date.now());
+                    }
+                    const downloaded = await (0, media_1.downloadMessageMediaToFile)({
+                        client: fetchGram.getClient(),
+                        message: found.message,
+                        maxBytes: INBOUND_MEDIA_MAX_BYTES,
+                        dir: fetchDir,
+                        fileNameFor: ({ media, extension }) => (0, fetch_media_1.fetchedMediaFileName)({
+                            chatId: fetchChatId,
+                            messageId: fetchParams.messageId,
+                            extension,
+                            fileName: media.fileName,
+                        }),
+                    });
+                    if (!downloaded) {
+                        // Three different nothings, and the agent has to be able to tell
+                        // them apart: a message with no attachment, an attachment this
+                        // channel does not read (a video, a spreadsheet), and one too
+                        // large to be worth the transfer. Saying "could not fetch" to all
+                        // three is how "she ignored the picture" starts.
+                        const described = (0, media_1.describeMedia)(found.message?.media);
+                        const tooLarge = typeof described?.size === "number" && described.size > INBOUND_MEDIA_MAX_BYTES;
+                        const error = !described
+                            ? "no-media"
+                            : tooLarge
+                                ? "media-too-large"
+                                : "unsupported-media";
+                        actionLog.info("clawgram fetch-media returned nothing", {
+                            accountId: fetchAccountId,
+                            chatId: fetchChatId,
+                            messageId: fetchParams.messageId,
+                            kind: described?.kind ?? null,
+                            error,
+                        });
+                        return (0, core_1.jsonResult)({
+                            ok: false,
+                            accountId: fetchAccountId,
+                            chatId: fetchChatId,
+                            messageId: String(fetchParams.messageId),
+                            media: described ?? null,
+                            error,
+                        });
+                    }
+                    let read;
+                    let readError;
+                    if (fetchParams.mode !== "file") {
+                        try {
+                            read = await understandAttachmentFile({
+                                runtime: pluginRuntime,
+                                cfg,
+                                filePath: downloaded.path,
+                                mimeType: downloaded.mimeType,
+                                understanding: downloaded.understanding,
+                            });
+                            if (!read) {
+                                readError = "read-empty";
+                            }
+                        }
+                        catch (err) {
+                            // The bytes are already here. A failed reading is worth
+                            // reporting, but it does not undo a successful fetch: the file
+                            // still exists and can still be forwarded.
+                            readError = String(err);
+                        }
+                    }
+                    // `read` mode is the inbound contract — the words, not the file — so
+                    // the bytes go away with the answer. Any other mode keeps them:
+                    // that is the whole point of asking for a path.
+                    if (fetchParams.mode === "read") {
+                        try {
+                            const { rm } = await import("node:fs/promises");
+                            await rm(fetchDir, { recursive: true, force: true });
+                        }
+                        catch {
+                            // A file left behind is pruned within a day; failing the call
+                            // over it would throw away a reading that already succeeded.
+                        }
+                    }
+                    actionLog.info("clawgram fetch-media completed", {
+                        accountId: fetchAccountId,
+                        chatId: fetchChatId,
+                        messageId: fetchParams.messageId,
+                        mode: fetchParams.mode,
+                        kind: downloaded.media.kind,
+                        understanding: downloaded.understanding,
+                        characters: read?.length ?? 0,
+                        readError: readError ?? null,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: fetchAccountId,
+                        chatId: fetchChatId,
+                        messageId: String(fetchParams.messageId),
+                        mode: fetchParams.mode,
+                        media: downloaded.media,
+                        understanding: downloaded.understanding,
+                        filePath: fetchParams.mode === "read" ? undefined : downloaded.path,
+                        text: read,
+                        readError,
+                    });
+                }
                 // Membership is a read, so the same `readChats` scope that gates history
                 // gates it too: this cannot become a way to enumerate chats the account
                 // was never allowed to read.

package/dist/fetch-media.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Fetching an attachment that is already sitting in a chat.
+ *
+ * Inbound attachments are read as they arrive: a photo sent to the agent
+ * becomes `[изображение] …` in the message body and the bytes are dropped.
+ * That covers being shown something, and nothing else. It does not cover
+ * "посмотри картинку, которую Женя кидал вчера" — history reads carry
+ * metadata only (`media.ts`), so a screenshot posted before the agent was
+ * addressed exists to it as the word "photo" and no more. It also does not
+ * cover reuse: the file the agent read is deleted the moment the read ends,
+ * so an image cannot be forwarded, attached to a ticket, or looked at twice.
+ *
+ * This module is the pure half of the `fetch-media` action: parameter
+ * parsing and file naming, testable without a Telegram client. The transport
+ * lives in `GramJsClientManager.getMessageById`, the dispatch in `channel.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFetchMediaMode = parseFetchMediaMode;
+exports.parseFetchMediaParams = parseFetchMediaParams;
+exports.sanitizeFileName = sanitizeFileName;
+exports.fetchedMediaFileName = fetchedMediaFileName;
+const history_1 = require("./history");
+/**
+ * A caller that guessed a neighbouring word is not refused: these are all
+ * unambiguous, and an error over vocabulary costs a turn to say nothing.
+ */
+const MODE_ALIASES = {
+    read: "read",
+    describe: "read",
+    description: "read",
+    transcript: "read",
+    transcribe: "read",
+    text: "read",
+    file: "file",
+    download: "file",
+    path: "file",
+    bytes: "file",
+    both: "both",
+    all: "both",
+};
+function parseFetchMediaMode(value) {
+    if (value === undefined || value === null || value === "")
+        return "both";
+    if (typeof value !== "string") {
+        throw new Error("clawgram: mode must be one of read, file, both");
+    }
+    const mode = MODE_ALIASES[value.trim().toLowerCase()];
+    if (!mode) {
+        throw new Error(`clawgram: unknown mode ${value} — expected read, file or both`);
+    }
+    return mode;
+}
+function parseFetchMediaParams(params) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: fetch-media requires a chatId");
+    }
+    const rawMessageId = params.messageId ?? params.id ?? params.message ?? params.msgId;
+    const messageId = (0, history_1.parseMessageId)(rawMessageId, "messageId");
+    if (messageId === undefined) {
+        throw new Error("clawgram: fetch-media requires a messageId");
+    }
+    return { target, messageId, mode: parseFetchMediaMode(params.mode) };
+}
+/**
+ * A file name that survives a round trip through a shell, a log line and a
+ * second tool: Telegram file names carry spaces, Cyrillic, quotes and the
+ * occasional path separator, and the last of those is the one that matters —
+ * `../../x.jpg` as a name must not decide where the file lands.
+ */
+function sanitizeFileName(name) {
+    if (typeof name !== "string")
+        return undefined;
+    const flattened = name.replace(/[/\\]/g, "_").replace(/\s+/g, "_").trim();
+    const cleaned = flattened
+        .replace(/[^\p{L}\p{N}._-]/gu, "")
+        // A run of dots survives the separator strip as `..`, which is harmless in
+        // a basename but reads like a traversal in every log it lands in.
+        .replace(/\.{2,}/g, ".")
+        .replace(/^[._-]+/, "");
+    return cleaned.slice(0, 80) || undefined;
+}
+/**
+ * Deterministic on purpose: fetching the same message twice writes the same
+ * path instead of scattering copies of one screenshot across the temp
+ * directory. The chat and message ids are in the name so two fetches in
+ * flight at once cannot land on each other.
+ */
+function fetchedMediaFileName(params) {
+    const own = sanitizeFileName(params.fileName);
+    const chat = params.chatId.replace(/[^0-9a-zA-Z_-]/g, "");
+    const stem = `${chat || "chat"}-${params.messageId}`;
+    return own ? `${stem}-${own}` : `${stem}.${params.extension}`;
+}

package/dist/gramjs-client.js

@@ -495,6 +495,23 @@ class GramJsClientManager {
             truncated: raw.length >= args.limit,
         };
     }
+    /**
+     * One message by id, for the sake of the attachment on it.
+     *
+     * `listMessages` reads a window and reports metadata; this reads a single
+     * message and hands the raw GramJS object back, because `downloadMedia`
+     * needs the message itself, not a summary of it. Telegram answers a missing
+     * or deleted id with a hole in the array rather than an error, so the caller
+     * gets `undefined` and says "no such message" instead of throwing something
+     * that reads like a transport failure.
+     */
+    async getMessageById(target, messageId) {
+        const resolved = await this.resolvePeer(target);
+        const fetched = await this.client.getMessages(resolved.peer, { ids: [messageId] });
+        const raw = Array.isArray(fetched) ? fetched : [];
+        const message = raw.find((entry) => entry && entry.className !== "MessageEmpty");
+        return { chatId: resolved.chatId, message };
+    }
     /**
      * Chat membership, ids only. The caller needs to answer "do we share a group
      * with this person" — an id answers that and a full profile does not, so

package/dist/media.js

@@ -15,6 +15,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeMedia = describeMedia;
 exports.inboundMediaUnderstanding = inboundMediaUnderstanding;
 exports.downloadInboundMediaToTempFile = downloadInboundMediaToTempFile;
+exports.downloadMessageMediaToFile = downloadMessageMediaToFile;
+exports.pruneFetchedMedia = pruneFetchedMedia;
 /**
  * GramJS carries numbers as `big-integer` objects as often as native numbers —
  * the same shape that once made `senderId` silently undefined. Anything that
@@ -130,6 +132,37 @@ function inboundMediaUnderstanding(media) {
  * and is responsible for removing it.
  */
 async function downloadInboundMediaToTempFile(params) {
+    const { mkdtemp } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const described = describeMedia(params.message?.media);
+    const understanding = inboundMediaUnderstanding(described);
+    if (!described || !understanding) {
+        return undefined;
+    }
+    // Both gates run before `mkdtemp`: a directory created for an attachment
+    // that is never fetched is litter nobody comes back to remove, and the
+    // caller only deletes what it was handed.
+    if (typeof described.size === "number" && described.size > params.maxBytes) {
+        return undefined;
+    }
+    const dir = await mkdtemp(join(params.tmpDir, "clawgram-media-"));
+    return downloadMessageMediaToFile({
+        client: params.client,
+        message: params.message,
+        maxBytes: params.maxBytes,
+        dir,
+        fileNameFor: ({ extension }) => `attachment.${extension}`,
+    });
+}
+/**
+ * Downloads an attachment into a directory the caller names and owns.
+ *
+ * Split out of the inbound path for `fetch-media`, where the file is the
+ * point: it has to outlive the read so the agent can forward it or attach it
+ * somewhere. The inbound path keeps deleting its temp directory — nothing
+ * about that changed.
+ */
+async function downloadMessageMediaToFile(params) {
     const described = describeMedia(params.message?.media);
     const understanding = inboundMediaUnderstanding(described);
     if (!described || !understanding) {
@@ -137,7 +170,8 @@ async function downloadInboundMediaToTempFile(params) {
     }
     // A cap belongs here rather than in the caller: an oversized attachment
     // should be reported as such, not fetched and then discarded after the
-    // transfer cost.
+    // transfer cost. Telegram reports no size for a compressed photo, so this
+    // guards documents in practice — which is where the large files are.
     if (typeof described.size === "number" && described.size > params.maxBytes) {
         return undefined;
     }
@@ -145,13 +179,49 @@ async function downloadInboundMediaToTempFile(params) {
     if (!buffer || !(buffer instanceof Buffer) || buffer.length === 0) {
         return undefined;
     }
-    const extension = extensionFor(described, understanding);
-    const { mkdtemp, writeFile } = await import("node:fs/promises");
+    const { mkdir, writeFile } = await import("node:fs/promises");
     const { join } = await import("node:path");
-    const dir = await mkdtemp(join(params.tmpDir, "clawgram-media-"));
-    const path = join(dir, `attachment.${extension}`);
+    await mkdir(params.dir, { recursive: true });
+    const extension = extensionFor(described, understanding);
+    const path = join(params.dir, params.fileNameFor({ media: described, extension }));
     await writeFile(path, buffer);
-    return { path, mimeType: described.mimeType, understanding };
+    return { path, mimeType: described.mimeType, understanding, media: described };
+}
+/**
+ * Removes fetched files older than `maxAgeMs` from `dir`.
+ *
+ * `fetch-media` writes files that deliberately outlive the call, and nothing
+ * else would ever delete them: a chat full of screenshots would accumulate in
+ * the temp directory until the box was rebooted. Pruning on the way in keeps
+ * the sweep in the one place that knows the directory exists, and failure is
+ * ignored — a stale file is not a reason to fail a fetch the agent is waiting
+ * for.
+ */
+async function pruneFetchedMedia(dir, maxAgeMs, now) {
+    const { readdir, stat, rm } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        const path = join(dir, entry);
+        try {
+            const info = await stat(path);
+            if (now - info.mtimeMs > maxAgeMs) {
+                await rm(path, { recursive: true, force: true });
+                removed += 1;
+            }
+        }
+        catch {
+            // A file that vanished between readdir and stat is already pruned.
+        }
+    }
+    return removed;
 }
 function extensionFor(media, understanding) {
     if (understanding === "description") {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {