clawgram 2.28.0 → 2.28.1

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/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.",
             ],

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/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.28.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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