clawgram 2.19.0 → 2.19.1

package/README.md

@@ -748,11 +748,12 @@ attachment *metadata* — kind, file name, size, duration — and fetch nothing.
 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.
+`fetch-media` covers both. It takes one message and returns what is attached to it. The action
+also answers to **`download-file`**, core's own name for it — see the note on naming below.
 
 | Parameter | Aliases | Notes |
 |---|---|---|
-| `chatId` | `target`, `to`, `chat` | Same targets as everywhere else: `@username`, numeric id, `me` |
+| `chatId` | `chat` | The chat: `@username`, numeric id, `me`. **Not `target`** — core reserves that for actions in its own vocabulary and refuses it here |
 | `messageId` | `id`, `message`, `msgId` | The id `read` reported for the message |
 | `mode` | — | `both` (default), `read`, `file` |
 
@@ -768,6 +769,15 @@ The action is confined by `readChats`, the same scope that gates history and mem
 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`.
 
+**On the two names.** Core keys its target policy by its own action vocabulary
+(`CHANNEL_MESSAGE_ACTION_NAMES`), and an action outside it is treated as both *requiring* a target
+and *not accepting* one — the same lookup returns `undefined` for the first check and defaults to
+`"none"` for the second. A caller then gets `Action fetch-media requires a target.` without a
+target and `Action fetch-media does not accept a target.` with one, whatever it tries.
+`download-file` is in that vocabulary and maps to `"none"`, so the contradiction does not arise;
+`fetch-media` is made usable by declaring `chatId` as its destination param
+(`messageActionTargetAliases`). Both names run the same code.
+
 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:

package/dist/channel.js

@@ -408,7 +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 `download-file` action (or its alias `fetch-media`) to fetch the attachment on a message `read` reported. Name the chat with `chatId` and the message with `messageId`; do not pass `target` — core refuses it for this action: `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.",
             ],
@@ -1392,7 +1392,20 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         // 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",
+                        //
+                        // Two names on purpose. `download-file` is core's own vocabulary
+                        // (`CHANNEL_MESSAGE_ACTION_NAMES`), and core's target policy is
+                        // keyed by that vocabulary: an action it does not know is both
+                        // "requires a target" (`MESSAGE_ACTION_TARGET_MODE[action] !==
+                        // "none"` is true for `undefined`) and "does not accept a target"
+                        // (the same lookup defaults to `"none"` when a target is passed).
+                        // That contradiction is unresolvable from the caller's side —
+                        // measured on 2026-08-24, when the agent tried every combination
+                        // and got one of the two errors each time. `download-file` is
+                        // mapped to `"none"`, so it has no such contradiction;
+                        // `fetch-media` stays as the descriptive name and is made usable
+                        // by the alias declaration below.
+                        "fetch-media", "download-file",
                         // Chat management (2.12.0) — gated by the account's manageChats
                         // scope; without it every one of these is refused.
                         "createGroup", "addMembers", "removeMember",
@@ -1404,6 +1417,16 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     },
                 };
             },
+            // Core asks the channel which params name a destination when the action
+            // is not one of its own. Without this, `chatId` is invisible to
+            // `actionHasTarget` and the call is refused as targetless before it ever
+            // reaches `handleAction`. The chat is named by `chatId` rather than
+            // `target` because core reserves `target` for actions in its own
+            // vocabulary and throws on it for everything else.
+            messageActionTargetAliases: {
+                "fetch-media": { aliases: ["chatId"] },
+                "download-file": { aliases: ["chatId"] },
+            },
             extractToolSend: ({ args }) => (0, tool_send_1.extractToolSend)(args, "sendMessage"),
             handleAction: async ({ action, params, cfg, accountId, dryRun: dryRunFlag, toolContext }) => {
                 // Core passes the flag beside `params`; callers write it inside.
@@ -1464,7 +1487,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // account was never allowed to read.
                 if (action === "fetch-media" || action === "fetchMedia" ||
                     action === "download-media" || action === "downloadMedia" ||
-                    action === "getMedia") {
+                    action === "getMedia" || action === "download-file") {
                     const fetchParams = (0, fetch_media_1.parseFetchMediaParams)(params);
                     const fetchAccountId = resolveRuntimeAccountId(cfg, accountId);
                     if (!fetchAccountId) {

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.19.0",
+  "version": "2.19.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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