clawgram 2.17.1 → 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
@@ -236,19 +237,42 @@ reconnect), not the whole Gateway.
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
 | `replyParseMode` | `"html"` \| `"markdown"` \| `"none"` | unset | Outbound format for replies, core-delivered text, captions and `send` calls that omit `parseMode` — see [Message formatting](#message-formatting) |
 | `twoFaPassword` | string \| SecretRef | unset | The account's Telegram 2FA password; read only by `transferOwnership` |
+| `reactionModel` | string | unset | Model ref or alias for the emoji pick on a silent mention. Unset = the agent's own model. Needs `plugins.entries.clawgram.llm.allowModelOverride: true` in the gateway config; without it the override is refused and the pick quietly falls back to the default model |
 
 Group config fields:
 
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | boolean | `true` | Enables or disables replies in the group |
-| `groupPolicy` | `"open"` \| `"mention"` | `"mention"` | `open` replies to any group message, `mention` only on @mention or reply-to-self |
+| `groupPolicy` | `"open"` \| `"mention"` \| `"tag"` | `"mention"` | What wakes the agent here — see [What wakes the agent in a group](#what-wakes-the-agent-in-a-group) |
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames inside that group |
 | `tools` | object | unset | `{ allow?, alsoAllow?, deny? }` — tool policy for this group; see [Per-group tools, skills and system prompt](#per-group-tools-skills-and-system-prompt) |
 | `toolsBySender` | object | unset | Per-sender tool policy inside this group, keys `id:<id>`, `username:<handle>`, `name:<display>` or `*` |
 | `skills` | string[] | unset | Skill allowlist for this group; `[]` = no skills here, unset = the agent's skills |
 | `systemPrompt` | string | unset | Trusted prompt block appended for messages from this group |
 
+### What wakes the agent in a group
+
+`groupPolicy` decides which messages start a turn at all. It is a ladder, widest
+first, and the rung is chosen per group:
+
+| Rung | Wakes on | Use it when |
+|---|---|---|
+| `open` | every message in the chat | the agent works as a member of the team and an address may carry no name at all |
+| `mention` | the name it answers to, an `@username`, or a reply to it | the default: the agent is a participant, not a fixture |
+| `tag` | an `@username` or a reply to it — **never the name** | the name occurs in conversation constantly, as it does in a large community |
+
+Two things are worth knowing before reaching for `open`:
+
+- it spends a **full turn on every message**, chatter included. Whether words
+  are owed is then the agent's decision, and most of the time the answer is no;
+- the typing indicator is shown only for messages that actually addressed the
+  agent. Under `open` the room would otherwise watch it "type" through
+  conversations it is merely reading, with nothing following.
+
+Emoji reactions are unaffected by the rung: the channel leaves one only where
+the agent was genuinely addressed, so background reading stays unmarked.
+
 ### Per-group tools, skills and system prompt
 
 Since 2.17.0 a group entry can narrow what the assistant does *in that chat*
@@ -716,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
@@ -726,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");
@@ -80,6 +90,22 @@ function readAccountReactionLevel(cfg, accountId) {
     }
     return cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionLevel;
 }
+/**
+ * Model ref for the emoji pick, when the account names one.
+ *
+ * Picking one emoji out of a fixed list of 68 is the cheapest judgement this
+ * channel makes and the only model call it makes on its own; running it on the
+ * agent's own head spends the expensive quota on a decision a small model
+ * makes just as well.
+ */
+function readAccountReactionModel(cfg, accountId) {
+    const resolvedAccountId = (0, helpers_1.resolveConfiguredAccountId)(cfg, accountId);
+    if (!resolvedAccountId) {
+        return undefined;
+    }
+    const raw = cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionModel;
+    return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
 /**
  * Wires `reactToSilentMention` to this account's runtime, config and log.
  *
@@ -96,6 +122,7 @@ async function reactToSilentMentionForAccount(params) {
     }
     await (0, silent_reaction_1.reactToSilentMention)({
         appetite: (0, reactions_1.resolveAgentReactionGuidance)(readAccountReactionLevel(params.cfg, params.accountId)),
+        model: readAccountReactionModel(params.cfg, params.accountId),
         wasMentioned: params.wasMentioned,
         chatId: params.chatId,
         messageId: params.messageId,
@@ -222,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;
@@ -250,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,
@@ -360,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.",
             ],
@@ -370,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.",
             ],
@@ -696,13 +746,19 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             // channelRuntime comes from the untyped ctx, so the generic route type falls
                             // back to the minimal RouteLike. The runtime value is a ResolvedAgentRoute.
                             const route = inboundRoute;
-                            const wasMentioned = (0, helpers_1.hasTelegramMention)({
-                                cfg,
-                                agentId: route.agentId,
-                                selfUsername,
-                                text,
-                                message: rawMessage,
-                            });
+                            // Under `tag` the name is not an address: in a chat of a thousand
+                            // people it occurs in conversation constantly and is aimed at her
+                            // almost never. Only the `@` counts, and it is the same fact the
+                            // stricter rung of the ladder is named after.
+                            const wasMentioned = groupConfig.groupPolicy === "tag"
+                                ? (0, helpers_1.hasExplicitTelegramMention)({ selfUsername, text, message: rawMessage })
+                                : (0, helpers_1.hasTelegramMention)({
+                                    cfg,
+                                    agentId: route.agentId,
+                                    selfUsername,
+                                    text,
+                                    message: rawMessage,
+                                });
                             const wasReplyToSelf = await (0, helpers_1.isReplyToSelfMessage)(rawMessage, selfId);
                             const mentionDecision = (0, channel_inbound_1.resolveInboundMentionDecision)({
                                 facts: {
@@ -712,7 +768,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 },
                                 policy: {
                                     isGroup: true,
-                                    requireMention: groupConfig.groupPolicy === "mention",
+                                    requireMention: groupConfig.groupPolicy !== "open",
                                     allowTextCommands: false,
                                     hasControlCommand: false,
                                     commandAuthorized: true,
@@ -723,6 +779,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 chatId: normalized.chatId,
                                 messageId: normalized.messageId,
                                 selfUsername,
+                                groupPolicy: groupConfig.groupPolicy,
                                 mentionedFlag: rawMessage?.mentioned === true,
                                 hasEntities: Array.isArray(rawMessage?.entities) ? rawMessage.entities.length : 0,
                                 wasMentioned,
@@ -730,7 +787,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 shouldSkip: mentionDecision.shouldSkip,
                                 text,
                             });
-                            if (groupConfig.groupPolicy === "mention" && mentionDecision.shouldSkip && !wasReplyToSelf) {
+                            if (groupConfig.groupPolicy !== "open" && mentionDecision.shouldSkip && !wasReplyToSelf) {
                                 log?.info?.("clawgram skipping group message without mention", {
                                     accountId,
                                     chatId: normalized.chatId,
@@ -993,6 +1050,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             }, {
                                 readMessageId: Number(normalized.messageId),
                                 messageThreadId,
+                                // The indicator is a promise of an answer, and it is owed only
+                                // to someone who addressed her. Under `open` the turn runs on
+                                // every message in the chat, so without this the whole room
+                                // watches her "type" through conversations she is only reading.
+                                typing: mentionDecision.effectiveWasMentioned || wasReplyToSelf,
                             });
                             log?.info?.("clawgram group inbound handled", {
                                 accountId,
@@ -1327,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",
@@ -1387,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
@@ -565,7 +582,29 @@ class GramJsClientManager {
         }
         await this.client.markAsRead(resolved.peer, messageId).catch(() => undefined);
     }
+    /**
+     * Runs `fn` while the chat shows "typing", and marks the message read.
+     *
+     * `typing: false` keeps the read receipt and drops the indicator. The two
+     * are separable because they promise different things: reading is what the
+     * agent did, typing is a promise that words are coming. Under
+     * `groupPolicy: "open"` every message starts a turn, and most of those turns
+     * end in silence — on 2026-08-17 the management chat watched «Тина
+     * печатает…» for 20–26 seconds on each of four messages that were never
+     * addressed to her, and nothing followed. An indicator that is not owed to
+     * anyone is worse than no indicator.
+     */
     async withTyping(target, fn, options) {
+        if (options?.typing === false) {
+            // Still a read receipt: she did read it, and the chat may show that.
+            const resolvedPeer = await this.resolvePeer(target).then((r) => r.peer).catch(() => undefined);
+            if (resolvedPeer) {
+                await this.markRead(resolvedPeer, options?.readMessageId, {
+                    messageThreadId: options?.messageThreadId,
+                }).catch(() => undefined);
+            }
+            return await fn();
+        }
         let peer;
         let readMarked = false;
         let stopped = false;

package/dist/helpers.js

@@ -27,6 +27,7 @@ exports.resolveActiveUsername = resolveActiveUsername;
 exports.normalizeAllowEntry = normalizeAllowEntry;
 exports.isSenderAllowed = isSenderAllowed;
 exports.hasTelegramMention = hasTelegramMention;
+exports.hasExplicitTelegramMention = hasExplicitTelegramMention;
 exports.toDisplayName = toDisplayName;
 exports.withTimeout = withTimeout;
 exports.stripSilentReplyToken = stripSilentReplyToken;
@@ -271,8 +272,17 @@ function resolveAllowFrom(value) {
     const entries = value.map((entry) => String(entry).trim()).filter(Boolean);
     return entries.length > 0 ? entries : ["*"];
 }
+/**
+ * Three rungs, widest first: `open` wakes on every message, `mention` on the
+ * name or an `@`, `tag` on the `@` alone. Anything unrecognised lands on
+ * `mention`, the rung this channel has always defaulted to.
+ */
 function resolveGroupPolicy(value) {
-    return value === "open" ? "open" : "mention";
+    if (value === "open")
+        return "open";
+    if (value === "tag")
+        return "tag";
+    return "mention";
 }
 /**
  * Per-group `skills` → core `replyOptions.skillFilter`, `systemPrompt` →
@@ -342,19 +352,27 @@ function isSenderAllowed(input) {
     ].filter((value) => Boolean(value)).map(normalizeAllowEntry);
     return input.allowFrom.map(normalizeAllowEntry).some((entry) => senderIds.includes(entry));
 }
-function hasTelegramMention(input) {
+/**
+ * Whether the message tags this account with `@username` — nothing else.
+ *
+ * The name the agent answers to (`Тина`, and whatever else core's mention
+ * regexes carry) is deliberately NOT consulted. In a thousand-person chat the
+ * name occurs in conversation constantly and almost never as an address; the
+ * `@` is the one form that is unambiguously aimed at her. This is the whole of
+ * `groupPolicy: "tag"`.
+ *
+ * `message.mentioned` is Telegram's own flag and stays in: the client sets it
+ * for an @-mention and for a reply to her, and both are addresses.
+ */
+function hasExplicitTelegramMention(input) {
     const normalizedText = input.text.trim();
     const message = input.message;
-    const mentionRegexes = (0, channel_inbound_1.buildMentionRegexes)(input.cfg, input.agentId);
     const selfUsername = input.selfUsername?.replace(/^@/, "").trim();
+    if (!selfUsername) {
+        return false;
+    }
     const entities = Array.isArray(message?.entities) ? message.entities : [];
-    const hasAnyMention = Boolean(message?.mentioned) ||
-        entities.some((entity) => {
-            const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
-            return kind === "MessageEntityMention" || kind === "mention" || kind === "MessageEntityMentionName" || kind === "InputMessageEntityMentionName";
-        }) ||
-        /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(normalizedText);
-    const entityExplicitMention = Boolean(selfUsername) && entities.some((entity) => {
+    const entityExplicitMention = entities.some((entity) => {
         const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
         if (kind !== "MessageEntityMention" && kind !== "mention") {
             return false;
@@ -366,10 +384,27 @@ function hasTelegramMention(input) {
         }
         return normalizedText.slice(offset, offset + length).replace(/^@/, "").trim().toLowerCase() === selfUsername.toLowerCase();
     });
-    const explicitlyMentioned = Boolean(selfUsername) &&
-        (message?.mentioned === true ||
-            entityExplicitMention ||
-            new RegExp(`(^|\\s)@${selfUsername?.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(normalizedText));
+    return message?.mentioned === true ||
+        entityExplicitMention ||
+        new RegExp(`(^|\\s)@${selfUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(normalizedText);
+}
+function hasTelegramMention(input) {
+    const normalizedText = input.text.trim();
+    const message = input.message;
+    const mentionRegexes = (0, channel_inbound_1.buildMentionRegexes)(input.cfg, input.agentId);
+    const selfUsername = input.selfUsername?.replace(/^@/, "").trim();
+    const entities = Array.isArray(message?.entities) ? message.entities : [];
+    const hasAnyMention = Boolean(message?.mentioned) ||
+        entities.some((entity) => {
+            const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
+            return kind === "MessageEntityMention" || kind === "mention" || kind === "MessageEntityMentionName" || kind === "InputMessageEntityMentionName";
+        }) ||
+        /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(normalizedText);
+    const explicitlyMentioned = hasExplicitTelegramMention({
+        selfUsername: input.selfUsername,
+        text: input.text,
+        message,
+    });
     return (0, channel_inbound_1.matchesMentionWithExplicit)({
         text: normalizedText,
         mentionRegexes,

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/dist/silent-reaction.js

@@ -151,6 +151,33 @@ function shouldReactToSilentTurn(params) {
 }
 /** The message text is truncated before it reaches the model; a mood needs no more. */
 const MAX_JUDGED_CHARS = 2000;
+/**
+ * Asks for the emoji on the configured model, falling back to the default one.
+ *
+ * The fallback is not defensive habit. Core refuses a plugin's model override
+ * unless `plugins.entries.clawgram.llm.allowModelOverride` is set, and the
+ * refusal is a throw — which this feature swallows by design. Without the
+ * retry, pointing `reactionModel` at a cheap model in a config that never
+ * granted the permission would not make reactions cheaper, it would make them
+ * disappear, and the log would say nothing about why.
+ */
+async function completeEmoji(params) {
+    const request = {
+        messages: [{ role: "user", content: params.content }],
+        systemPrompt: params.systemPrompt,
+        maxTokens: 8,
+        purpose: "clawgram: emoji reaction for a silent mention",
+    };
+    if (!params.model) {
+        return { answer: await params.deps.complete(request), fellBack: false };
+    }
+    try {
+        return { answer: await params.deps.complete({ ...request, model: params.model }), fellBack: false };
+    }
+    catch {
+        return { answer: await params.deps.complete(request), fellBack: true };
+    }
+}
 /**
  * Leaves an emoji on a message the agent was named in but chose not to answer.
  *
@@ -187,11 +214,11 @@ async function reactToSilentMention(params) {
         params.deps.onDecision?.({ messageId, appetite, chose: "none", allowedCount: 0 });
         return undefined;
     }
-    const answer = await params.deps.complete({
-        messages: [{ role: "user", content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS) }],
+    const { answer, fellBack } = await completeEmoji({
+        deps: params.deps,
+        model: params.model,
         systemPrompt: buildEmojiSystemPrompt(appetite, allowed),
-        maxTokens: 8,
-        purpose: "clawgram: emoji reaction for a silent mention",
+        content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS),
     });
     const emoji = parseEmojiChoice(answer?.text, allowed);
     params.deps.onDecision?.({
@@ -200,6 +227,8 @@ async function reactToSilentMention(params) {
         chose: emoji ? "emoji" : "none",
         emoji,
         allowedCount: allowed?.length,
+        ...params.model ? { model: params.model } : {},
+        ...fellBack ? { modelFellBack: true } : {},
     });
     if (!emoji) {
         return undefined;

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.17.1",
+  "version": "2.19.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -53,9 +53,11 @@
                   "type": "string",
                   "enum": [
                     "open",
-                    "mention"
+                    "mention",
+                    "tag"
                   ],
-                  "default": "mention"
+                  "default": "mention",
+                  "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message, the agent decides for itself whether words are owed; `tag` \u2014 only an explicit @username or a reply, for chats where the name occurs in conversation constantly."
                 },
                 "allowFrom": {
                   "type": "array",
@@ -358,9 +360,11 @@
                         "type": "string",
                         "enum": [
                           "open",
-                          "mention"
+                          "mention",
+                          "tag"
                         ],
-                        "default": "mention"
+                        "default": "mention",
+                        "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message; `tag` \u2014 only an explicit @username or a reply."
                       },
                       "allowFrom": {
                         "type": "array",
@@ -507,6 +511,10 @@
                   ],
                   "description": "How freely the agent may leave emoji reactions (2.8.0). Core injects its `## Reactions` prompt section only for `minimal` and `extensive`; `off` and `ack` leave the prompt silent about reactions, and the agent then effectively never reacts on its own. Absent means `minimal`. Mirrors the bundled Telegram channel's reactionLevel."
                 },
+                "reactionModel": {
+                  "type": "string",
+                  "description": "Model ref or alias for the emoji pick on a silent mention (2.18.0). Absent = the agent's own model, which is what every version before this used. Requires `plugins.entries.clawgram.llm.allowModelOverride: true` in the gateway config; without it core refuses the override and the pick falls back to the default model rather than losing the reaction."
+                },
                 "replyParseMode": {
                   "type": "string",
                   "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.17.1",
+  "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": {