clawgram 2.29.0 → 2.29.1

package/README.md

@@ -261,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`, `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) |
+| `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.22.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

@@ -133,116 +133,133 @@ async function handleReadAction(ctx) {
             : node_path_1.default.join(node_os_1.default.tmpdir(), `clawgram-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
         await (0, media_1.ensurePrivateDir)(mediaRoot);
         const sharedFetchDir = node_path_1.default.join(mediaRoot, "clawgram-fetched");
+        const described = (0, media_1.describeMedia)(found.message?.media);
+        // A PDF is not read here: the agent is handed the path for its PDF tool,
+        // so even in `read` mode the file has to outlive the answer. It goes to
+        // the shared directory, which is pruned by age — a private temp directory
+        // is removed only by the `read` branch below, and a PDF skips that branch,
+        // so every PDF read used to stay on disk for good (audit r3 C2-02).
+        const keepsFile = fetchParams.mode !== "read" || (0, media_1.fetchMediaUnderstanding)(described) === "pdf";
         let fetchDir = sharedFetchDir;
-        if (fetchParams.mode === "read") {
-            const { mkdtemp } = await import("node:fs/promises");
-            fetchDir = await mkdtemp(node_path_1.default.join(mediaRoot, "clawgram-media-"));
+        if (keepsFile) {
+            await (0, media_1.pruneFetchedMedia)(sharedFetchDir, FETCHED_MEDIA_TTL_MS, Date.now());
         }
         else {
-            await (0, media_1.pruneFetchedMedia)(sharedFetchDir, FETCHED_MEDIA_TTL_MS, Date.now());
+            const { mkdtemp } = await import("node:fs/promises");
+            fetchDir = await mkdtemp(node_path_1.default.join(mediaRoot, "clawgram-media-"));
         }
-        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,
-                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 tooLarge = typeof described?.size === "number" && described.size > attachments_1.INBOUND_MEDIA_MAX_BYTES;
-            const error = !described
-                ? "no-media"
-                : tooLarge
-                    ? "media-too-large"
-                    : "unsupported-media";
-            actionLog.info("clawgram fetch-media returned nothing", {
+        // Every way out of here removes the private temp directory — the early
+        // "nothing to fetch" answer and a download that throws included. Only the
+        // success branch used to, so a message without media, a video, or a
+        // failed download each left a directory behind for good (audit r3 V1-10).
+        try {
+            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,
+                    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 tooLarge = typeof described?.size === "number" && described.size > attachments_1.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 (0, attachments_1.understandAttachmentFile)({
+                        runtime: pluginRuntime,
+                        cfg,
+                        filePath: downloaded.path,
+                        mimeType: downloaded.mimeType,
+                        understanding: downloaded.understanding,
+                        fileName: downloaded.media.fileName,
+                    });
+                    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.
+            const pdfNeedsFile = downloaded.understanding === "pdf";
+            const finalReadError = pdfNeedsFile ? "use the PDF tool on filePath to read this PDF" : readError;
+            actionLog.info("clawgram fetch-media completed", {
                 accountId: fetchAccountId,
                 chatId: fetchChatId,
                 messageId: fetchParams.messageId,
-                kind: described?.kind ?? null,
-                error,
+                mode: fetchParams.mode,
+                kind: downloaded.media.kind,
+                understanding: downloaded.understanding,
+                characters: read?.length ?? 0,
+                readError: finalReadError ?? null,
             });
             return (0, core_1.jsonResult)({
-                ok: false,
+                ok: true,
                 accountId: fetchAccountId,
                 chatId: fetchChatId,
                 messageId: String(fetchParams.messageId),
-                media: described ?? null,
-                error,
+                mode: fetchParams.mode,
+                media: downloaded.media,
+                understanding: downloaded.understanding,
+                filePath: fetchParams.mode === "read" && !pdfNeedsFile ? undefined : downloaded.path,
+                text: read,
+                readError: finalReadError,
             });
         }
-        let read;
-        let readError;
-        if (fetchParams.mode !== "file") {
-            try {
-                read = await (0, attachments_1.understandAttachmentFile)({
-                    runtime: pluginRuntime,
-                    cfg,
-                    filePath: downloaded.path,
-                    mimeType: downloaded.mimeType,
-                    understanding: downloaded.understanding,
-                    fileName: downloaded.media.fileName,
-                });
-                if (!read) {
-                    readError = "read-empty";
+        finally {
+            // Only the private temp directory is ever removed here — never the
+            // shared one, which other fetches still point at.
+            if (!keepsFile) {
+                try {
+                    const { rm } = await import("node:fs/promises");
+                    await rm(fetchDir, { recursive: true, force: true });
+                }
+                catch {
+                    // A private temp directory left behind is litter, not a leak of
+                    // anything the agent was not already shown; failing the call over it
+                    // would throw away a reading that already succeeded.
                 }
-            }
-            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.
-        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 });
-            }
-            catch {
-                // A file left behind is pruned within a day; failing the call
-                // 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,
-            messageId: fetchParams.messageId,
-            mode: fetchParams.mode,
-            kind: downloaded.media.kind,
-            understanding: downloaded.understanding,
-            characters: read?.length ?? 0,
-            readError: finalReadError ?? 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" && !pdfNeedsFile ? undefined : downloaded.path,
-            text: read,
-            readError: finalReadError,
-        });
     }
     /**
      * The scaffold every chat-shaped read shares.

package/dist/actions-send.js

@@ -31,7 +31,7 @@ async function handleSendAction(ctx) {
         if (!reactionAccountId) {
             throw new Error("clawgram: no configured account found");
         }
-        // Реакция — видимое действие от имени владельца в чужом чате, и
+        // Реакция — видимое действие от имени этой учётки в чужом чате, и
         // адресуется она так же, как сообщение: та же область (A5-12).
         if (!(0, send_scope_1.isChatSendable)(reactionParams.target, (0, account_scopes_1.resolveAccountSendChats)(cfg, reactionAccountId))) {
             (0, account_scopes_1.refuseOutboundOutsideScope)("react", reactionAccountId, String(reactionParams.target));

package/dist/group-reply-address.js

@@ -82,7 +82,7 @@ function buildGroupReplyAddress(input) {
     // No handle and no name means no greeting, not a numeric one. The id
     // used to be the fallback, and in a basic group — where GramJS attaches
     // no sender profile to the message — every reply of a day opened with
-    // «890975818, …» (07.09.2026). A person does not know their own
+    // «<numeric id>, …» (07.09.2026). A person does not know their own
     // telegram id and reads it as a malfunction.
     return undefined;
 }

package/dist/inbound-pipeline.js

@@ -499,7 +499,7 @@ async function handleInboundEvent(event, ctx) {
             // and in a basic group (or after a restart) that cache is empty: the
             // turn then had nothing but the numeric id, the reply greeting fell
             // back to it, and a management chat spent 07.09.2026 being addressed
-            // as «890975818, …». One source of truth for the name: the address
+            // as «<numeric id>, …». One source of truth for the name: the address
             // the channel would prepend is also what the agent reads, so the
             // model cannot greet «Вася Ш.» while the channel greets «@vasya».
             await resolveNamelessSender(normalized, rawMessage, client);

package/dist/media.js

@@ -28,6 +28,7 @@ exports.assertLocalMediaWithinRoots = assertLocalMediaWithinRoots;
 exports.loadOutboundMedia = loadOutboundMedia;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
+const docx_text_1 = require("./docx-text");
 const util_1 = require("./util");
 /**
  * GramJS carries numbers as `big-integer` objects as often as native numbers —
@@ -131,19 +132,17 @@ 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"))) {
+    if (media?.kind !== "document")
+        return undefined;
+    // One definition of "a document we can read": the same predicates decide
+    // how it is read in `understandAttachmentFile`, so a format added there
+    // cannot be downloaded here and then decoded as the wrong thing (r3 C2-03).
+    if ((0, docx_text_1.isDocxDocument)(media.mimeType, media.fileName))
         return "document";
-    }
-    if (media?.kind === "document" && (media.mimeType === "application/pdf" || fileName.endsWith(".pdf"))) {
+    if (media.mimeType === "application/pdf" || media.fileName?.toLowerCase().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}`)))) {
+    if ((0, docx_text_1.isTextDocument)(media.mimeType, media.fileName))
         return "document";
-    }
     return undefined;
 }
 /**

package/dist/outbound.js

@@ -212,7 +212,7 @@ function createOutbound(runtimes) {
             }
             // Молчаливый ответ: подпись с токеном молчания означает «ничего не
             // говорить», и отправлять файл с ним в подписи — тем более.
-            const mediaCaption = ctx.caption ?? ctx.text;
+            let mediaCaption = ctx.caption ?? ctx.text;
             if (mediaCaption?.trim() && (0, helpers_1.isSilentReplyText)(mediaCaption)) {
                 actionLog.info("clawgram suppressing silent outbound media", {
                     accountId: ctx.accountId,
@@ -227,12 +227,30 @@ function createOutbound(runtimes) {
                 chatId: ctx.to,
                 replyToId: ctx.replyToId,
             });
-            // Чего здесь НЕТ намеренно:
-            // — подавление эха хода (`hadTurnSendJustNow`): у текста дубль стоит
-            //   лишнего сообщения, а у медиа отказ стоит потерянного файла —
-            //   картинку агент готовил, и второй раз она не появится;
-            // — подавление служебных сообщений ядра в группах: они текстовые,
-            //   медиа-доставка ими не бывает.
+            // Служебное уведомление ядра, склеенное с payload, уходило подписью:
+            // фильтр телеметрии стоял на трёх текстовых дверях и не стоял здесь
+            // (аудит r3 C0-11, «чинить каждый путь»). Файл при этом не теряется —
+            // уходит без подписи: картинку агент готовил, второй раз её не будет.
+            const captionNotice = mediaCaption?.trim()
+                ? (0, system_notice_1.shouldSuppressGroupSystemNotice)({
+                    targetKind: (0, helpers_1.inferOutboundTargetKind)(ctx.to),
+                    text: mediaCaption,
+                    to: ctx.to,
+                    operatorIds: (0, account_registry_1.operatorIdsFor)(ctx.accountId),
+                })
+                : undefined;
+            if (captionNotice) {
+                actionLog.warn("clawgram suppressing system notice in media caption", {
+                    accountId: ctx.accountId,
+                    rawTo: ctx.to,
+                    noticeKind: captionNotice,
+                    captionLength: mediaCaption.length,
+                });
+                mediaCaption = undefined;
+            }
+            // Чего здесь НЕТ намеренно: подавления эха хода (`hadTurnSendJustNow`):
+            // у текста дубль стоит лишнего сообщения, а у медиа отказ стоит
+            // потерянного файла.
             const messageThreadId = (0, helpers_2.parseOptionalThreadId)(ctx.threadId);
             // Same normalization `sendText` does two functions up. Without it the
             // channel prefix reaches peer resolution and the send throws — which is

package/dist/send-scope.js

@@ -11,8 +11,8 @@ const history_1 = require("./history");
  * Reading has had a declared scope since 2.x (`readChats`), management has
  * one (`manageChats`), and sending had none: `send`, `upload-file` and
  * `react` resolved whatever target the caller named and delivered it. The
- * account is a person's own Telegram account, so an injected turn could
- * message strangers under the owner's name, or carry a work chat's content
+ * account is a real Telegram account, so an injected turn could message
+ * strangers under this account's name, or carry a work chat's content
  * into an attacker's DM one `send` at a time (finding A5-12).
  *
  * Two decisions worth stating, because both could reasonably have gone the

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clawgram",
-  "version": "2.28.0",
+  "version": "2.29.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clawgram",
-      "version": "2.28.0",
+      "version": "2.29.1",
       "license": "MIT",
       "dependencies": {
         "json5": "2.2.3",

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.29.0",
+  "version": "2.29.1",
   "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, 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."
+                  "description": "Chat ids the account may SEND to (2.22.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 this 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.29.0",
+  "version": "2.29.1",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {
@@ -8,7 +8,8 @@
     "verify:actions": "node scripts/verify/action-probe.cjs",
     "build": "tsc -p tsconfig.json",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "npm run build:test && node test/ensure-compiled.mjs && node --test \"dist-test/test/*.test.js\"",
+    "test": "node scripts/check-pii.mjs && npm run build:test && node test/ensure-compiled.mjs && node --test \"dist-test/test/*.test.js\"",
+    "check:pii": "node scripts/check-pii.mjs",
     "prepublishOnly": "npm run build && npm test",
     "release:clawhub": "node scripts/publish-clawhub.mjs",
     "clawgram-cli": "node dist/clawgram-cli.js",