clawgram 2.28.0 → 2.29.0

package/README.md

@@ -31,6 +31,7 @@ Clawgram is a personal-Telegram channel plugin for [OpenClaw](https://github.com
 - **@Mention detection** — respond only when mentioned in groups (text, caption, and ID-based mentions)
 - **Read receipts** — mark messages as read
 - **Emoji reactions** — acknowledge a message with a reaction instead of a reply (`react` action)
+- **Editing what was sent** — rewrite the account's own message in place instead of posting a correction beneath it (`edit` 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
@@ -260,7 +261,7 @@ loud where it does occur.
 | `groups` | object | `{}` | Allowed groups map keyed by explicit group id or `*` |
 | `proxy` | object | unset | Optional SOCKS4/SOCKS5 proxy for this account — see [Proxy (SOCKS4/SOCKS5)](#proxy-socks4socks5) |
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
-| `sendChats` | string[] | unset | Chats the assistant may **send to** — `send`, `upload-file`, `react` and core's own delivery path (`--deliver`, sub-agent announcements). Absent = every chat; `[]` = none. Phone-number targets are refused regardless (2.18.0; core delivery covered since 2.25.0) |
+| `sendChats` | string[] | unset | Chats the assistant may **send to** — `send`, `upload-file`, `react`, `edit` and core's own delivery path (`--deliver`, sub-agent announcements). Absent = every chat; `[]` = none. Phone-number targets are refused regardless (2.18.0; core delivery covered since 2.25.0) |
 | `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 |

package/dist/actions-read.js

@@ -141,11 +141,13 @@ async function handleReadAction(ctx) {
         else {
             await (0, media_1.pruneFetchedMedia)(sharedFetchDir, FETCHED_MEDIA_TTL_MS, Date.now());
         }
+        const described = (0, media_1.describeMedia)(found.message?.media);
         const downloaded = await (0, media_1.downloadMessageMediaToFile)({
             client: fetchGram.getClient(),
             message: found.message,
             maxBytes: attachments_1.INBOUND_MEDIA_MAX_BYTES,
             dir: fetchDir,
+            understanding: (0, media_1.fetchMediaUnderstanding)(described),
             fileNameFor: ({ media, extension }) => (0, fetch_media_1.fetchedMediaFileName)({
                 chatId: fetchChatId,
                 messageId: fetchParams.messageId,
@@ -159,7 +161,6 @@ async function handleReadAction(ctx) {
             // 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 > attachments_1.INBOUND_MEDIA_MAX_BYTES;
             const error = !described
                 ? "no-media"
@@ -192,6 +193,7 @@ async function handleReadAction(ctx) {
                     filePath: downloaded.path,
                     mimeType: downloaded.mimeType,
                     understanding: downloaded.understanding,
+                    fileName: downloaded.media.fileName,
                 });
                 if (!read) {
                     readError = "read-empty";
@@ -207,7 +209,8 @@ async function handleReadAction(ctx) {
         // `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") {
+        const pdfNeedsFile = downloaded.understanding === "pdf";
+        if (fetchParams.mode === "read" && !pdfNeedsFile) {
             try {
                 const { rm } = await import("node:fs/promises");
                 await rm(fetchDir, { recursive: true, force: true });
@@ -217,6 +220,7 @@ async function handleReadAction(ctx) {
                 // over it would throw away a reading that already succeeded.
             }
         }
+        const finalReadError = pdfNeedsFile ? "use the PDF tool on filePath to read this PDF" : readError;
         actionLog.info("clawgram fetch-media completed", {
             accountId: fetchAccountId,
             chatId: fetchChatId,
@@ -225,7 +229,7 @@ async function handleReadAction(ctx) {
             kind: downloaded.media.kind,
             understanding: downloaded.understanding,
             characters: read?.length ?? 0,
-            readError: readError ?? null,
+            readError: finalReadError ?? null,
         });
         return (0, core_1.jsonResult)({
             ok: true,
@@ -235,9 +239,9 @@ async function handleReadAction(ctx) {
             mode: fetchParams.mode,
             media: downloaded.media,
             understanding: downloaded.understanding,
-            filePath: fetchParams.mode === "read" ? undefined : downloaded.path,
+            filePath: fetchParams.mode === "read" && !pdfNeedsFile ? undefined : downloaded.path,
             text: read,
-            readError,
+            readError: finalReadError,
         });
     }
     /**

package/dist/actions-send.js

@@ -4,6 +4,7 @@ exports.handleSendAction = handleSendAction;
 const core_1 = require("openclaw/plugin-sdk/core");
 const param_readers_1 = require("openclaw/plugin-sdk/param-readers");
 const account_scopes_1 = require("./account-scopes");
+const edits_1 = require("./edits");
 const group_reply_address_1 = require("./group-reply-address");
 const group_visible_reply_guard_1 = require("./group-visible-reply-guard");
 const helpers_1 = require("./helpers");
@@ -62,6 +63,66 @@ async function handleSendAction(ctx) {
             removed: reactionParams.remove,
         });
     }
+    // Rewriting a message already sent. Gated exactly like `react`: it is a
+    // visible act in someone else's chat under this account's name, so it takes
+    // the outbound scope check and honours `dryRun`, which reading does not need.
+    if (canonical === "edit") {
+        const editParams = (0, edits_1.parseEditParams)(params, toolContext);
+        const editAccountId = resolveRuntimeAccountId(cfg, accountId);
+        if (!editAccountId) {
+            throw new Error("clawgram: no configured account found");
+        }
+        if (!(0, send_scope_1.isChatSendable)(editParams.target, (0, account_scopes_1.resolveAccountSendChats)(cfg, editAccountId))) {
+            (0, account_scopes_1.refuseOutboundOutsideScope)("edit", editAccountId, editParams.target);
+        }
+        // The same sentinel guard as `send`, for the same reason: `NO_REPLY` is
+        // OpenClaw's "say nothing", and an explicit tool call is not a path that
+        // strips it. Editing a real answer down to the token would replace a good
+        // message with what looks like a malfunction — worse than the send case,
+        // because the original text is gone.
+        if ((0, helpers_1.isSilentReplyText)(editParams.text)) {
+            throw new Error("clawgram: edit refuses a silent-reply sentinel as the new text");
+        }
+        // No reply-address prefix, no visible-reply memory, no turn-send memory:
+        // those three exist to shape and de-duplicate NEW messages. An edit
+        // addresses nobody afresh and adds nothing to the chat, so recording it as
+        // "this turn has spoken" would suppress a later genuine answer.
+        const editParseMode = (0, helpers_1.resolveOutboundParseMode)(params, cfg, editAccountId);
+        actionLog.info("clawgram handleAction edit", {
+            accountId: editAccountId,
+            dryRun: dryRun === true,
+            target: editParams.target,
+            messageId: editParams.messageId,
+        });
+        if (dryRun === true) {
+            return (0, core_1.jsonResult)({
+                ok: true,
+                dryRun: true,
+                accountId: editAccountId,
+                chatId: editParams.target,
+                messageId: editParams.messageId,
+            });
+        }
+        const editGram = requireRuntimeFor(editAccountId);
+        await editGram.editText({
+            target: editParams.target,
+            messageId: editParams.messageId,
+            text: editParams.text,
+            parseMode: editParseMode,
+        });
+        actionLog.info("clawgram handleAction edit completed", {
+            accountId: editAccountId,
+            target: editParams.target,
+            messageId: editParams.messageId,
+        });
+        return (0, core_1.jsonResult)({
+            ok: true,
+            edited: true,
+            accountId: editAccountId,
+            chatId: editParams.target,
+            messageId: editParams.messageId,
+        });
+    }
     // Core normalizes whichever of these it filled in to a local path (see
     // `mediaSourceParams` above); `mediaUrl` stays a URL, which GramJS
     // accepts as well.

package/dist/actions.js

@@ -30,6 +30,14 @@ const ACTION_ALIASES = {
     list: "read",
     react: "react",
     joins: "joins",
+    // Rewriting a message already sent (2.29.0). Core has always known the name
+    // — it is in `CHANNEL_MESSAGE_ACTION_NAMES` — so the call reached this
+    // channel and was refused as unsupported, and a wrong answer could only be
+    // followed by a second message correcting it.
+    edit: "edit",
+    editMessage: "edit",
+    "edit-message": "edit",
+    update: "edit",
     "upload-file": "upload-file",
     sendAttachment: "upload-file",
     "fetch-media": "fetch-media",
@@ -108,6 +116,11 @@ function canonicalAction(action) {
  * call fell through to the current chat and answered about the wrong one.
  * `readChatTargetParam` is the single list of accepted spellings now.
  *
+ * `edit` (2.29.0) is the third shape: core resolves it as a *message* target,
+ * so both the chat and `messageId` arrive named. It needs no synonym — the
+ * name core uses is the name this channel uses — and it is listed here only so
+ * the suite asserts core still knows it.
+ *
  * These spellings are derived from `ACTION_ALIASES` rather than kept beside
  * it; that core actually knows each of them is asserted against the installed
  * core in `core-action-synonyms.test.ts`.
@@ -115,6 +128,7 @@ function canonicalAction(action) {
 const CORE_VOCABULARY_SPELLINGS = [
     "thread-list", "channel-list", "channel-info", "member-info", "download-file",
     "channel-create", "addParticipant", "kick", "role-add", "role-remove",
+    "edit",
 ];
 exports.CORE_ACTION_SYNONYMS = Object.fromEntries(CORE_VOCABULARY_SPELLINGS.map((name) => [name, ACTION_ALIASES[name]]));
 /** Canonical actions that go through the chat-management gate. */

package/dist/attachments.js

@@ -15,6 +15,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
 const media_1 = require("./media");
+const docx_text_1 = require("./docx-text");
 const state_dir_1 = require("./state-dir");
 /** Attachments above this are left unread: a long recording or a huge image is
  *  a different conversation from a spoken line or a screenshot, and the
@@ -46,6 +47,16 @@ function resolveAgentDirForMedia(cfg) {
  * become two different readings because two call sites drifted.
  */
 async function understandAttachmentFile(params) {
+    if (params.understanding === "document") {
+        const { readFile } = await import("node:fs/promises");
+        const input = await readFile(params.filePath);
+        return (0, docx_text_1.isDocxDocument)(params.mimeType, params.fileName)
+            ? (0, docx_text_1.extractDocxText)(input)
+            : (0, docx_text_1.extractPlainText)(input);
+    }
+    if (params.understanding === "pdf") {
+        return undefined;
+    }
     const media = params.runtime?.mediaUnderstanding;
     if (!media)
         return undefined;
@@ -98,6 +109,7 @@ async function readInboundAttachment(params) {
             filePath: downloaded.path,
             mimeType: downloaded.mimeType,
             understanding: downloaded.understanding,
+            fileName: undefined,
         });
         if (!read) {
             params.log?.info?.("clawgram attachment read empty", {

package/dist/channel.js

@@ -148,7 +148,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "Use the `thread-list` 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. Name the chat with `chatId` and do not pass `target` — core refuses it for this action. `topics` is the same call under a name core does not know, and is only reachable through the gateway RPC.",
                 "Name the chat for `read` with `target`, never `chatId`: `read` is in core's own vocabulary, so core resolves the destination itself and reads only `to`/`target` — `chatId` is silently ignored and the call is refused as targetless. The chat-shaped reads next to it (`thread-list`, `channel-info`, `member-info`) are the opposite, because core does not know them; that asymmetry is core's, not a typo, and it cost 745 refused reads in the week before 2026-09-04.",
                 "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 `download-file` action 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 `download-file` action 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: images and audio return a description or transcript; DOCX and UTF-8 text documents (.txt, .md, .csv, .json, YAML, XML, HTML, RTF) return text; PDFs return a retained `filePath` for the PDF tool. `mode: \"file\"` returns a path to reuse and `\"both\"` (default) returns both. `read` only says an attachment exists; this is what brings it.",
                 "Use the `channel-list` 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 `member-info` with a `chatId` to list who is in a chat, and `kick` with a `chatId` and `userId` to remove someone from a managed chat. The rest of the chat-management family and `joins` have no name core knows, so they are reachable only through the gateway RPC, not from this tool.",
                 "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.",
@@ -160,7 +160,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 `channel-info`: 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 `thread-list`: 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 `download-file`: images come back described, voice notes transcribed, and either can be returned as a file path for reuse.",
+                "clawgram can fetch an explicitly named attachment inside its read scope via `download-file`: images come back described, voice notes transcribed, DOCX and UTF-8 text documents as text, and PDFs as a private file path for the PDF tool.",
                 "clawgram can list the group chats the account belongs to via `channel-list`, 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.",
             ],
@@ -454,6 +454,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // one. `joins` likewise.
                     actions: [
                         "send", "read", "react", "upload-file",
+                        // Rewriting a message this account already sent (2.29.0). Core
+                        // knows the name, so it needs no synonym — unlike the reads below.
+                        "edit",
                         // 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.

package/dist/docx-text.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDocxText = extractDocxText;
+exports.isDocxDocument = isDocxDocument;
+exports.isTextDocument = isTextDocument;
+exports.extractPlainText = extractPlainText;
+const node_zlib_1 = require("node:zlib");
+const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
+const LOCAL_FILE_SIGNATURE = 0x04034b50;
+const WORD_DOCUMENT_PATH = "word/document.xml";
+const MAX_DOCUMENT_XML_BYTES = 2 * 1024 * 1024;
+const TEXT_DOCUMENT_EXTENSIONS = new Set([
+    "txt", "md", "markdown", "csv", "tsv", "json", "jsonl", "yaml", "yml",
+    "toml", "ini", "cfg", "conf", "xml", "html", "htm", "log", "rtf",
+]);
+function findEndOfCentralDirectory(input) {
+    // The optional ZIP comment is at most 65,535 bytes, so scanning this tail
+    // avoids treating a matching four-byte sequence in compressed data as a
+    // directory record.
+    const start = Math.max(0, input.length - 65_557);
+    for (let offset = input.length - 22; offset >= start; offset -= 1) {
+        if (input.readUInt32LE(offset) === END_OF_CENTRAL_DIRECTORY_SIGNATURE) {
+            return offset;
+        }
+    }
+    throw new Error("clawgram: attachment is not a valid DOCX zip");
+}
+function wordDocumentEntry(input) {
+    if (input.length < 22) {
+        throw new Error("clawgram: attachment is not a valid DOCX zip");
+    }
+    const end = findEndOfCentralDirectory(input);
+    const entryCount = input.readUInt16LE(end + 10);
+    let offset = input.readUInt32LE(end + 16);
+    for (let index = 0; index < entryCount; index += 1) {
+        if (offset + 46 > input.length || input.readUInt32LE(offset) !== CENTRAL_DIRECTORY_SIGNATURE) {
+            throw new Error("clawgram: attachment is not a valid DOCX zip");
+        }
+        const flags = input.readUInt16LE(offset + 8);
+        const compressionMethod = input.readUInt16LE(offset + 10);
+        const compressedSize = input.readUInt32LE(offset + 20);
+        const uncompressedSize = input.readUInt32LE(offset + 24);
+        const nameLength = input.readUInt16LE(offset + 28);
+        const extraLength = input.readUInt16LE(offset + 30);
+        const commentLength = input.readUInt16LE(offset + 32);
+        const localHeaderOffset = input.readUInt32LE(offset + 42);
+        const nameEnd = offset + 46 + nameLength;
+        if (nameEnd > input.length) {
+            throw new Error("clawgram: attachment is not a valid DOCX zip");
+        }
+        const name = input.subarray(offset + 46, nameEnd).toString("utf8");
+        if (name === WORD_DOCUMENT_PATH) {
+            if ((flags & 0x1) !== 0) {
+                throw new Error("clawgram: encrypted DOCX attachments are not supported");
+            }
+            return { compressionMethod, compressedSize, uncompressedSize, localHeaderOffset };
+        }
+        offset = nameEnd + extraLength + commentLength;
+    }
+    throw new Error("clawgram: DOCX has no word/document.xml");
+}
+function decodeXmlText(value) {
+    return value
+        .replaceAll("&amp;", "&")
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replace(/&#(x[0-9a-f]+|\d+);/gi, (_whole, source) => {
+        const codePoint = String(source).toLowerCase().startsWith("x")
+            ? Number.parseInt(String(source).slice(1), 16)
+            : Number.parseInt(String(source), 10);
+        const valid = Number.isInteger(codePoint)
+            && codePoint >= 0
+            && codePoint <= 0x10ffff
+            && (codePoint < 0xd800 || codePoint > 0xdfff);
+        return valid ? String.fromCodePoint(codePoint) : "";
+    });
+}
+function textFromWordXml(xml) {
+    const withBreaks = xml
+        .replace(/<w:tab\b[^>]*\/>/gi, "\t")
+        .replace(/<w:br\b[^>]*\/>/gi, "\n")
+        .replace(/<w:cr\b[^>]*\/>/gi, "\n")
+        .replace(/<\/w:p>/gi, "\n")
+        .replace(/<[^>]*>/g, "");
+    return decodeXmlText(withBreaks)
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+/g, " ").trim())
+        .filter(Boolean)
+        .join("\n")
+        .trim();
+}
+/** Extracts plain text from the DOCX part the user explicitly asked to read. */
+function extractDocxText(input) {
+    const entry = wordDocumentEntry(input);
+    if (entry.uncompressedSize > MAX_DOCUMENT_XML_BYTES) {
+        throw new Error("clawgram: DOCX text is too large to read");
+    }
+    const local = entry.localHeaderOffset;
+    if (local + 30 > input.length || input.readUInt32LE(local) !== LOCAL_FILE_SIGNATURE) {
+        throw new Error("clawgram: attachment is not a valid DOCX zip");
+    }
+    const nameLength = input.readUInt16LE(local + 26);
+    const extraLength = input.readUInt16LE(local + 28);
+    const start = local + 30 + nameLength + extraLength;
+    const end = start + entry.compressedSize;
+    if (start > input.length || end > input.length) {
+        throw new Error("clawgram: attachment is not a valid DOCX zip");
+    }
+    const compressed = input.subarray(start, end);
+    const xml = entry.compressionMethod === 0
+        ? compressed
+        : entry.compressionMethod === 8
+            ? (0, node_zlib_1.inflateRawSync)(compressed, { maxOutputLength: MAX_DOCUMENT_XML_BYTES })
+            : undefined;
+    if (!xml) {
+        throw new Error(`clawgram: DOCX compression method ${entry.compressionMethod} is not supported`);
+    }
+    return textFromWordXml(xml.toString("utf8"));
+}
+function isDocxDocument(mimeType, fileName) {
+    return mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        || fileName?.toLowerCase().endsWith(".docx") === true;
+}
+function isTextDocument(mimeType, fileName) {
+    if (mimeType?.startsWith("text/"))
+        return true;
+    const extension = fileName?.trim().split(".").pop()?.toLowerCase();
+    return extension ? TEXT_DOCUMENT_EXTENSIONS.has(extension) : false;
+}
+/**
+ * Plain-text attachments are kept as UTF-8. They are never silently decoded
+ * as binary data, because replacement glyphs hide a wrong file type from the
+ * agent and make its answer look trustworthy when it is not.
+ */
+function extractPlainText(input) {
+    if (input.length > MAX_DOCUMENT_XML_BYTES) {
+        throw new Error("clawgram: text document is too large to read");
+    }
+    if (input.includes(0)) {
+        throw new Error("clawgram: attachment is binary, not a text document");
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(input);
+    }
+    catch {
+        throw new Error("clawgram: text attachment is not valid UTF-8");
+    }
+    return text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").trim();
+}

package/dist/edits.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Editing a message already sent — the `edit` action of OpenClaw's message
+ * tool.
+ *
+ * Telegram lets an account rewrite its own message in place, and until 2.29.0
+ * this channel had no way to ask for it: a wrong answer could only be followed
+ * by a second message correcting the first, which leaves both standing in the
+ * chat. `edit` is in core's `CHANNEL_MESSAGE_ACTION_NAMES`, so the name was
+ * reachable from the tool the whole time and simply arrived at a channel that
+ * refused it.
+ *
+ * Parsing lives here, apart from the network, so the argument handling can be
+ * tested without a Telegram connection — the same split as `reactions.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEditParams = parseEditParams;
+const helpers_1 = require("./helpers");
+const history_1 = require("./history");
+function parseEditParams(params, toolContext) {
+    const rawTarget = (0, helpers_1.readChatTargetParam)(params, toolContext);
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: edit requires a chatId");
+    }
+    // No fall-back to `currentMessageId`, and that is the difference from
+    // `react`. The current message is the one being answered — someone else's.
+    // Reacting to it is the normal case; editing it is never a thing this
+    // account may do, so a missing id is a caller mistake and not an invitation
+    // to guess. Telegram would refuse it, but the refusal would arrive as
+    // MESSAGE_AUTHOR_REQUIRED on a call nobody meant to make.
+    const messageId = (0, history_1.parseMessageId)(params.messageId ?? params.msgId ?? params.message_id, "edit messageId");
+    if (messageId === undefined) {
+        throw new Error("clawgram: edit requires a messageId — the id of the message to rewrite");
+    }
+    // `readMessageText` reads `message` then `text`, exactly as `send` does, so
+    // the same call shape works for both actions.
+    const text = (0, helpers_1.readMessageText)(params).replaceAll("\\n", "\n");
+    if (!text.trim()) {
+        // Telegram has no "edit to nothing": an empty edit is refused server-side,
+        // and a caller who meant to remove the message asked for the wrong action.
+        // Saying so here beats an MTProto error about message content.
+        throw new Error("clawgram: edit requires the new text — an empty edit is not a deletion");
+    }
+    return { target, messageId, text };
+}

package/dist/gramjs-client.js

@@ -427,6 +427,36 @@ class GramJsClientManager {
             ...replyParams,
         });
     }
+    /**
+     * Rewrites a message this account already sent.
+     *
+     * Rendering mirrors `sendText` deliberately: an edit that parsed its text
+     * differently from the send would change the formatting of a message nobody
+     * asked to reformat — markdown shipped as literal asterisks is exactly the
+     * failure that made `sendText` render HTML itself.
+     *
+     * No chunking here, unlike `sendText`. A send too long for Telegram becomes
+     * several messages; an edit cannot — there is one message to rewrite. Over
+     * the limit the call fails, and that is the honest outcome.
+     *
+     * Telegram's own refusals are left to reach the caller as they are:
+     * MESSAGE_AUTHOR_REQUIRED (not this account's message),
+     * MESSAGE_EDIT_TIME_EXPIRED (past the window Telegram allows) and
+     * MESSAGE_NOT_MODIFIED (the new text equals the old one). None of them is
+     * retryable, and dressing them up would hide which one happened.
+     */
+    async editText(args) {
+        const resolved = await this.resolvePeer(args.target);
+        return this.client.editMessage(resolved.peer, {
+            message: args.messageId,
+            text: args.parseMode === "html" ? (0, html_render_1.renderTelegramHtml)(args.text) : args.text,
+            ...(args.parseMode === "none"
+                ? { parseMode: false }
+                : args.parseMode
+                    ? { parseMode: args.parseMode === "markdown" ? "md" : "html" }
+                    : {}),
+        });
+    }
     /**
      * Reads what a chat is: title, type, member count, description, pinned
      * message.

package/dist/media.js

@@ -17,6 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeMedia = describeMedia;
 exports.inboundMediaUnderstanding = inboundMediaUnderstanding;
+exports.fetchMediaUnderstanding = fetchMediaUnderstanding;
 exports.downloadInboundMediaToTempFile = downloadInboundMediaToTempFile;
 exports.describePrivateDirProblem = describePrivateDirProblem;
 exports.ensurePrivateDir = ensurePrivateDir;
@@ -125,6 +126,26 @@ function inboundMediaUnderstanding(media) {
         return "description";
     return undefined;
 }
+/** A document is downloaded only after the agent explicitly names its message. */
+function fetchMediaUnderstanding(media) {
+    const inbound = inboundMediaUnderstanding(media);
+    if (inbound)
+        return inbound;
+    const fileName = media?.fileName?.toLowerCase() ?? "";
+    if (media?.kind === "document" && (media.mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        || fileName.endsWith(".docx"))) {
+        return "document";
+    }
+    if (media?.kind === "document" && (media.mimeType === "application/pdf" || fileName.endsWith(".pdf"))) {
+        return "pdf";
+    }
+    if (media?.kind === "document" && (media.mimeType?.startsWith("text/")
+        || ["txt", "md", "markdown", "csv", "tsv", "json", "jsonl", "yaml", "yml", "toml", "ini", "cfg", "conf", "xml", "html", "htm", "log", "rtf"]
+            .some((extension) => fileName.endsWith(`.${extension}`)))) {
+        return "document";
+    }
+    return undefined;
+}
 /**
  * Downloads an inbound attachment to a temporary file.
  *
@@ -147,13 +168,24 @@ async function downloadInboundMediaToTempFile(params) {
         return undefined;
     }
     const dir = await mkdtemp(join(params.tmpDir, "clawgram-media-"));
-    return downloadMessageMediaToFile({
+    const downloaded = await downloadMessageMediaToFile({
         client: params.client,
         message: params.message,
         maxBytes: params.maxBytes,
         dir,
         fileNameFor: ({ extension }) => `attachment.${extension}`,
     });
+    // This path asks only for `inboundMediaUnderstanding`, so a document cannot
+    // get here. Keep the runtime guard as the public downloader also serves the
+    // explicit `fetch-media` action, which is allowed to request DOCX files.
+    if (!downloaded || downloaded.understanding === "document" || downloaded.understanding === "pdf") {
+        return undefined;
+    }
+    return {
+        path: downloaded.path,
+        mimeType: downloaded.mimeType,
+        understanding: downloaded.understanding,
+    };
 }
 /**
  * Why a directory that merely exists is not good enough.
@@ -238,7 +270,7 @@ async function ensurePrivateDir(dir) {
  */
 async function downloadMessageMediaToFile(params) {
     const described = describeMedia(params.message?.media);
-    const understanding = inboundMediaUnderstanding(described);
+    const understanding = params.understanding ?? inboundMediaUnderstanding(described);
     if (!described || !understanding) {
         return undefined;
     }
@@ -316,6 +348,11 @@ function extensionFor(media, understanding) {
         return "mp3";
     if (media.mimeType === "audio/mp4")
         return "m4a";
+    if (understanding === "pdf")
+        return "pdf";
+    if (understanding === "document") {
+        return media.mimeType?.startsWith("text/") ? "txt" : "docx";
+    }
     return "ogg";
 }
 /**

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.28.0",
+  "version": "2.29.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -468,7 +468,7 @@
                   "items": {
                     "type": "string"
                   },
-                  "description": "Chat ids the account may SEND to (2.18.0): send, upload-file, react and core's delivery path. Same shape as readChats — absent means no restriction, [] denies everything, [\"*\"] allows every chat. A phone number is refused in every configuration, wildcard included: messaging a raw number starts a conversation with someone who never interacted with the account. Without this list an injected turn can message strangers from the owner's personal account or carry a work chat's content into a DM one send at a time."
+                  "description": "Chat ids the account may SEND to (2.18.0): send, upload-file, react, edit and core's delivery path. Same shape as readChats — absent means no restriction, [] denies everything, [\"*\"] allows every chat. A phone number is refused in every configuration, wildcard included: messaging a raw number starts a conversation with someone who never interacted with the account. Without this list an injected turn can message strangers from the owner's personal account or carry a work chat's content into a DM one send at a time."
                 },
                 "manageChats": {
                   "type": "array",

package/package.json

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