clawgram 2.1.0 → 2.2.1

package/README.md

@@ -30,6 +30,8 @@ Clawgram is a personal-Telegram channel plugin for [OpenClaw](https://github.com
 - **Forum topic routing** — correctly routes replies to the right forum topic thread
 - **@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)
+- **Chat metadata** — title, type, member count, description, forum flag and pinned message (`chatInfo` action)
 - **User allowlist** — control which user has access to send messages for direct
 - **Chat allowlist** — control which chats the assistant can access
 - **Multi-account** — run multiple Telegram accounts simultaneously
@@ -584,8 +586,8 @@ that means in practice, and what the code does about it:
 
 | Concern | Where it lives | What the plugin does |
 | --- | --- | --- |
-| `apiHash`, `sessionString` | `openclaw.json` | 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 |
-| Proxy password | `accounts.*.proxy.password` | 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 |
+| `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 |
 | Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions |
@@ -593,6 +595,31 @@ that means in practice, and what the code does about it:
 Two static tests (`test/no-secret-logging.test.ts`) fail the build if a message body or a credential
 is ever added back to a log call, or if the auth flow prints the session string unprompted.
 
+### Keeping credentials out of the config file
+
+`apiHash`, `sessionString`, `proxy.username` and `proxy.password` accept a
+[SecretRef](https://docs.openclaw.ai/gateway/secrets) in place of a literal value:
+
+```json
+{
+  "channels": {
+    "clawgram": {
+      "accounts": {
+        "default": {
+          "apiId": 12345678,
+          "apiHash": { "source": "file", "provider": "corp", "id": "/telegram/api-hash" },
+          "sessionString": { "source": "file", "provider": "corp", "id": "/telegram/session" }
+        }
+      }
+    }
+  }
+}
+```
+
+References are resolved once per account at start-up. If one cannot be resolved the account fails to
+start, naming the field but never the value — and the client refuses to be constructed while any
+reference remains, so an unresolved secret can never travel to Telegram as a credential.
+
 Found a security issue? Open an issue at
 [github.com/d3pre5s/clawgram/issues](https://github.com/d3pre5s/clawgram/issues) — or, if it is
 sensitive, contact the maintainer directly instead of filing publicly.
@@ -617,6 +644,16 @@ or
 npm run clawgram-cli:auth
 ```
 
+## Releases
+
+Every push and pull request is built and tested on Node 22 and 24. Releases are cut by pushing a
+`v<version>` tag: CI then builds from a clean checkout and publishes to npm with
+[provenance](https://docs.npmjs.com/generating-provenance-statements), so each published tarball is
+verifiably tied to the commit it was built from. The tag and `package.json` must agree or the job
+refuses to publish.
+
+Changes per version: [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT

package/dist/channel.js

@@ -16,6 +16,10 @@ const gramjs_client_1 = require("./gramjs-client");
 const normalize_1 = require("./normalize");
 const history_1 = require("./history");
 const joins_1 = require("./joins");
+const reactions_1 = require("./reactions");
+const chat_info_1 = require("./chat-info");
+const secret_refs_1 = require("./secret-refs");
+const secret_ref_runtime_1 = require("openclaw/plugin-sdk/secret-ref-runtime");
 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");
@@ -86,11 +90,15 @@ const createChannelPlugin = (runtimes) => {
                 "When replying in the current Telegram chat, omit `to`/`target` and clawgram will send to the current conversation automatically.",
                 "Explicit targets may be @username, numeric Telegram user id, phone/contact resolvable by Telegram, group chat ids, or clawgram:<target>.",
                 "For Telegram forum topics, send to the group chat id and pass the topic id separately as `threadId`.",
+                "Use the `react` action to acknowledge a message with an emoji instead of sending a reply; pass an empty `emoji` (or `remove: true`) to take the reaction back.",
+                "Use the `chatInfo` action to learn what a chat is — title, type, member count, description, pinned message — instead of guessing from its id.",
             ],
             messageToolCapabilities: () => [
                 "clawgram can reply in the current Telegram conversation when no explicit target is provided.",
                 "clawgram can send text messages to direct chats and groups from the connected personal account.",
                 "clawgram supports Telegram forum topics via the `threadId` parameter on group sends.",
+                "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.",
             ],
         },
         config: {
@@ -105,8 +113,8 @@ const createChannelPlugin = (runtimes) => {
                 const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
                 return {
                     apiId: Number(account?.apiId),
-                    apiHash: String(account?.apiHash ?? ""),
-                    sessionString: String(account?.sessionString ?? ""),
+                    apiHash: (0, secret_refs_1.readSecretInput)(account?.apiHash),
+                    sessionString: (0, secret_refs_1.readSecretInput)(account?.sessionString),
                     allowFrom: (0, helpers_1.resolveAllowFrom)(account?.allowFrom),
                     groups: (0, helpers_1.resolveGroups)(account?.groups),
                     readChats: readAccountReadChats(account),
@@ -127,7 +135,32 @@ const createChannelPlugin = (runtimes) => {
                     await runtimes.get(accountId)?.stop().catch(() => undefined);
                     runtimes.delete(accountId);
                 }
-                const gram = new gramjs_client_1.GramJsClientManager(account);
+                // Credentials may be SecretRefs rather than literals. Resolve them here,
+                // once per account start, and hand the client only resolved values.
+                // Failing loudly beats starting with a blank credential and getting an
+                // authentication error that says nothing about the real cause.
+                const secretRefs = (0, secret_refs_1.collectAccountSecretRefs)(account);
+                let resolvedAccount = account;
+                if (secretRefs.length > 0) {
+                    // `source` is whatever the config says; OpenClaw validates it and
+                    // reports an unknown source better than a local check would.
+                    const values = await (0, secret_ref_runtime_1.resolveSecretRefValues)(secretRefs, {
+                        config: cfg,
+                        env: process.env,
+                    });
+                    const applied = (0, secret_refs_1.applyAccountSecrets)(account, values);
+                    if (applied.missing.length > 0) {
+                        // Field names only. The value is what we are protecting, and the
+                        // reference itself names a location in the secret store.
+                        throw new Error(`clawgram: could not resolve secret references for ${applied.missing.join(", ")}`);
+                    }
+                    log?.info?.("clawgram resolved secret references", {
+                        accountId,
+                        fields: secretRefs.length,
+                    });
+                    resolvedAccount = applied.account;
+                }
+                const gram = new gramjs_client_1.GramJsClientManager(resolvedAccount);
                 await gram.start();
                 runtimes.set(accountId, gram);
                 const pairing = (0, channel_pairing_1.createChannelPairingController)({
@@ -918,7 +951,7 @@ const createChannelPlugin = (runtimes) => {
                     return null;
                 }
                 return {
-                    actions: ["send", "read", "participants", "joins"],
+                    actions: ["send", "read", "participants", "joins", "react", "chatInfo"],
                     capabilities: [],
                 };
             },
@@ -1030,6 +1063,82 @@ const createChannelPlugin = (runtimes) => {
                         joins: selected,
                     });
                 }
+                // Describing a chat is a read, so the same `readChats` scope that gates
+                // history gates it too — this must not become a way to learn the title
+                // and size of a chat the account was never allowed to read.
+                if (action === "chatInfo" || action === "getChatInfo"
+                    || action === "chatMetadata" || action === "getChatMetadata") {
+                    const chatInfoParams = (0, chat_info_1.parseChatInfoParams)(params, toolContext);
+                    const chatInfoAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!chatInfoAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    if (!(0, history_1.isChatReadable)(chatInfoParams.target, resolveAccountReadChats(cfg, chatInfoAccountId))) {
+                        actionLog.warn("clawgram chatInfo refused: chat outside read scope", {
+                            accountId: chatInfoAccountId,
+                            target: chatInfoParams.target,
+                        });
+                        throw new Error(`clawgram: not-allowed-chat ${chatInfoParams.target}`);
+                    }
+                    const chatInfoGram = runtimes.get(chatInfoAccountId);
+                    if (!chatInfoGram) {
+                        throw new Error(`clawgram: runtime not found for account ${chatInfoAccountId}`);
+                    }
+                    const { entity, full } = await chatInfoGram.getChatInfo(chatInfoParams.target);
+                    const info = (0, chat_info_1.describeChat)(entity, full);
+                    // Type and size only. The title of a private chat is as personal as
+                    // its contents and has no business in a debugging log.
+                    actionLog.info("clawgram handleAction chatInfo completed", {
+                        accountId: chatInfoAccountId,
+                        type: info.type,
+                        memberCount: info.memberCount ?? null,
+                        isForum: info.isForum ?? null,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: chatInfoAccountId,
+                        chat: { ...info, chatId: info.chatId ?? chatInfoParams.target },
+                    });
+                }
+                // A reaction is an outbound act on someone else's message, so it is
+                // gated like sending rather than like reading — and it respects
+                // `dryRun`, which reading does not need to.
+                if (action === "react") {
+                    const reactionParams = (0, reactions_1.parseReactionParams)(params, toolContext);
+                    const reactionAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!reactionAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    actionLog.info("clawgram handleAction react", {
+                        accountId: reactionAccountId,
+                        dryRun: dryRun === true,
+                        target: reactionParams.target,
+                        messageId: reactionParams.messageId,
+                        remove: reactionParams.remove,
+                    });
+                    if (dryRun === true) {
+                        return (0, core_1.jsonResult)({
+                            ok: true,
+                            dryRun: true,
+                            accountId: reactionAccountId,
+                            chatId: reactionParams.target,
+                            messageId: reactionParams.messageId,
+                            removed: reactionParams.remove,
+                        });
+                    }
+                    const reactionGram = runtimes.get(reactionAccountId);
+                    if (!reactionGram) {
+                        throw new Error(`clawgram: runtime not found for account ${reactionAccountId}`);
+                    }
+                    await reactionGram.sendReaction(reactionParams);
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: reactionAccountId,
+                        chatId: reactionParams.target,
+                        messageId: reactionParams.messageId,
+                        removed: reactionParams.remove,
+                    });
+                }
                 if (action !== "send") {
                     throw new Error(`clawgram: unsupported message action ${action}`);
                 }
@@ -1086,7 +1195,30 @@ const createChannelPlugin = (runtimes) => {
                     chatId: to,
                     replyToId,
                 });
-                const text = (0, helpers_1.prefixReplyTextToAddress)((0, helpers_1.readMessageText)(params).replaceAll("\\n", "\n"), groupReplyAddress);
+                const requestedText = (0, helpers_1.readMessageText)(params).replaceAll("\\n", "\n");
+                // `NO_REPLY` is OpenClaw's "say nothing" sentinel. The inbound pipeline
+                // and core both strip it, but an explicit `message.action` call is
+                // neither path — and the SDK itself prompts agents to send a message
+                // and *then* answer NO_REPLY, so the two are one slip apart. Posting
+                // the token into a work chat looks like the assistant malfunctioning.
+                //
+                // Checked before the reply-address prefix on purpose: prefixing first
+                // leaves "Name: " behind, which is not empty, and the token goes out.
+                // That is precisely how it once reached the inbound path.
+                if (requestedText.trim() && (0, helpers_1.isSilentReplyText)(requestedText)) {
+                    actionLog.info("clawgram suppressing silent send", {
+                        accountId: resolvedAccountId,
+                        to,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        skipped: "silent",
+                        sent: false,
+                        to,
+                        accountId: resolvedAccountId,
+                    });
+                }
+                const text = (0, helpers_1.prefixReplyTextToAddress)(requestedText, groupReplyAddress);
                 if (!text) {
                     throw new Error("clawgram: message text is required");
                 }
@@ -1161,6 +1293,17 @@ const createChannelPlugin = (runtimes) => {
                     threadId: ctx.threadId ?? null,
                     textLength: ctx.text.length,
                 });
+                // Core normalizes reply payloads and drops the silent token before a
+                // channel is called, so this should never see one. "Should never" is
+                // what the inbound path was assumed to be too, right until it posted a
+                // token — and the check costs a string comparison.
+                if (ctx.text.trim() && (0, helpers_1.isSilentReplyText)(ctx.text)) {
+                    actionLog.info("clawgram suppressing silent outbound send", {
+                        accountId: ctx.accountId,
+                        rawTo: ctx.to,
+                    });
+                    return { skipped: "silent" };
+                }
                 const gram = runtimes.get(ctx.accountId);
                 if (!gram) {
                     throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);

package/dist/chat-info.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Chat metadata — what a chat *is*, as opposed to what was said in it.
+ *
+ * Without this the assistant can read a chat and list its members but cannot
+ * say which chat it is standing in: the title, whether it is a work supergroup
+ * or a one-to-one conversation, whether replies must be addressed to a forum
+ * topic. That had to come from a hand-maintained allowlist, which goes stale
+ * the moment a chat is renamed.
+ *
+ * Telegram splits this across two objects — the entity carries the title and
+ * the type flags, the full object carries the description, the member count
+ * and the pinned message — so both are taken and merged here. Parsing is pure
+ * so it can be tested without a Telegram client; the transport lives in
+ * `GramJsClientManager.getChatInfo`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseChatInfoParams = parseChatInfoParams;
+exports.describeChat = describeChat;
+function parseChatInfoParams(params, toolContext) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: chatInfo requires a chatId");
+    }
+    return { target };
+}
+/**
+ * GramJS carries ids and counts as `big-integer` objects as often as native
+ * numbers — the shape that once made `senderId` come back silently undefined.
+ */
+function readNumber(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const parsed = Number(String(value));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function readString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+function readId(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const asString = String(value).trim();
+    return asString === "" || asString === "[object Object]" ? undefined : asString;
+}
+function resolveType(entity) {
+    switch (entity?.className) {
+        case "User":
+            return "direct";
+        case "Chat":
+            return "group";
+        case "Channel":
+            return entity.broadcast === true ? "channel" : "supergroup";
+        default:
+            return "unknown";
+    }
+}
+/** A user has no title, so the displayed name is assembled from what exists. */
+function resolveUserTitle(entity) {
+    const parts = [readString(entity?.firstName), readString(entity?.lastName)].filter(Boolean);
+    return parts.length > 0 ? parts.join(" ") : undefined;
+}
+function describeChat(entity, full) {
+    const raw = entity;
+    const fullChat = full;
+    const type = resolveType(raw);
+    const info = {
+        chatId: readId(raw?.id),
+        type,
+        title: type === "direct" ? resolveUserTitle(raw) : readString(raw?.title),
+        username: readString(raw?.username),
+        about: readString(fullChat?.about),
+        pinnedMessageId: readId(fullChat?.pinnedMsgId),
+    };
+    if (type === "direct") {
+        // Member count is meaningless for a two-person conversation, and reporting
+        // "1" or "2" would invite a reader to treat it as a group of that size.
+        return { ...info, isBot: raw?.bot === true };
+    }
+    if (type === "supergroup" || type === "channel") {
+        info.isForum = raw?.forum === true;
+    }
+    // The full object is fetched now; the entity may come from a cache that
+    // predates the last few joins, so prefer the fresher number.
+    info.memberCount = readNumber(fullChat?.participantsCount) ?? readNumber(raw?.participantsCount);
+    return info;
+}

package/dist/gramjs-client.js

@@ -4,6 +4,7 @@ exports.GramJsClientManager = void 0;
 const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
 const proxy_config_1 = require("./proxy-config");
+const secret_refs_1 = require("./secret-refs");
 const history_1 = require("./history");
 function toStringId(value) {
     if (value === null || value === undefined)
@@ -168,6 +169,15 @@ class GramJsClientManager {
     started = false;
     constructor(config) {
         this.config = config;
+        // Credentials may be written as SecretRefs; account start-up resolves them
+        // before constructing this. Refusing here rather than trusting the caller
+        // keeps an unresolved reference from being sent to Telegram as the literal
+        // string "[object Object]" — which comes back as a complaint about the
+        // credential, not about the secret that failed to resolve.
+        if ((0, secret_refs_1.hasUnresolvedSecretRef)(config)) {
+            throw new Error("clawgram: account credentials still contain unresolved secret references; "
+                + "they must be resolved before the client is created");
+        }
         const clientOptions = (0, proxy_config_1.buildTelegramClientOptions)(config.proxy);
         this.proxy = clientOptions.proxy;
         this.client = new telegram_1.TelegramClient(new sessions_1.StringSession(config.sessionString), config.apiId, config.apiHash, clientOptions);
@@ -288,6 +298,56 @@ class GramJsClientManager {
             ...replyParams,
         });
     }
+    /**
+     * Reads what a chat is: title, type, member count, description, pinned
+     * message.
+     *
+     * Telegram has no single "describe this chat" call — the full object comes
+     * from a different method per chat type, and none of them accepts the other's
+     * peer. The entity is resolved first precisely to find out which one to ask.
+     * A failing full request is not fatal: the entity alone already carries the
+     * title and the type, and a partial answer beats an error when the caller
+     * only wanted to know where it is.
+     */
+    async getChatInfo(target) {
+        const resolved = await this.resolvePeer(target);
+        const entity = await this.client.getEntity(resolved.peer);
+        const full = await (async () => {
+            switch (entity?.className) {
+                case "Channel":
+                    return (await this.client.invoke(new telegram_1.Api.channels.GetFullChannel({
+                        channel: entity,
+                    }))).fullChat;
+                case "Chat":
+                    return (await this.client.invoke(new telegram_1.Api.messages.GetFullChat({
+                        chatId: entity.id,
+                    }))).fullChat;
+                case "User":
+                    return (await this.client.invoke(new telegram_1.Api.users.GetFullUser({
+                        id: entity,
+                    }))).fullUser;
+                default:
+                    return undefined;
+            }
+        })().catch(() => undefined);
+        return { entity, full };
+    }
+    /**
+     * Adds or clears this account's reaction on a message.
+     *
+     * Telegram models "no reaction" as an empty reaction list rather than a
+     * separate call, so removal is the same request with nothing in it. A plain
+     * account may hold only one reaction per message, which is why removing a
+     * specific emoji and clearing collapse to the same thing here.
+     */
+    async sendReaction(args) {
+        const resolved = await this.resolvePeer(args.target);
+        await this.client.invoke(new telegram_1.Api.messages.SendReaction({
+            peer: resolved.peer,
+            msgId: args.messageId,
+            reaction: args.remove ? [] : [new telegram_1.Api.ReactionEmoji({ emoticon: args.emoji })],
+        }));
+    }
     /**
      * Reads a window of chat history.
      *

package/dist/history.js

@@ -24,6 +24,7 @@ exports.normalizeHistoryMessage = normalizeHistoryMessage;
 exports.collectHistoryWindow = collectHistoryWindow;
 exports.HISTORY_DEFAULT_LIMIT = 100;
 exports.HISTORY_MAX_LIMIT = 500;
+const media_1 = require("./media");
 /**
  * Matches `normalize.ts` and `gramjs-client.ts` deliberately.
  *
@@ -258,6 +259,7 @@ function normalizeHistoryMessage(msg, fallbackChatId) {
         sentAt: timestamp === undefined ? undefined : new Date(timestamp * 1000).toISOString(),
         replyToMessageId: toStringId(msg?.replyTo?.replyToMsgId) ?? toStringId(msg?.replyToMsgId),
         messageThreadId: toStringId(msg?.replyTo?.replyToTopId) ?? toStringId(msg?.replyToTopId),
+        media: (0, media_1.describeMedia)(msg?.media),
         isOutgoing: msg?.out === true,
     };
 }

package/dist/media.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Attachment metadata for history reads.
+ *
+ * A message whose whole content is a screenshot used to arrive as an empty
+ * `text` — indistinguishable from a message that said nothing. That is a real
+ * loss for a reader summarizing a work chat, where the screenshot of the error
+ * *is* the report.
+ *
+ * Only metadata is produced. Nothing is downloaded: knowing that "spec.pdf,
+ * 240 KB" was posted is what a summary needs, and fetching the bytes of every
+ * attachment in a window would be a different feature with different costs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeMedia = describeMedia;
+/**
+ * GramJS carries numbers as `big-integer` objects as often as native numbers —
+ * the same shape that once made `senderId` silently undefined. Anything that
+ * stringifies to digits is accepted.
+ */
+function readNumber(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const parsed = Number(String(value));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function readAttributes(document) {
+    const attributes = document?.attributes;
+    return Array.isArray(attributes) ? attributes : [];
+}
+function findAttribute(document, className) {
+    return readAttributes(document).find((attribute) => attribute?.className === className);
+}
+const SIMPLE_KINDS = {
+    MessageMediaPhoto: "photo",
+    MessageMediaPoll: "poll",
+    MessageMediaGeo: "geo",
+    MessageMediaGeoLive: "geo",
+    MessageMediaContact: "contact",
+    MessageMediaWebPage: "webpage",
+};
+/**
+ * Documents are the ambiguous case: a voice note, a video, a sticker and a
+ * spreadsheet are all `MessageMediaDocument`, separated only by attributes.
+ */
+function describeDocument(document) {
+    const mimeType = typeof document?.mimeType === "string" ? document.mimeType : undefined;
+    const size = readNumber(document?.size);
+    const fileName = findAttribute(document, "DocumentAttributeFilename")?.fileName;
+    const base = {
+        kind: "document",
+        fileName: typeof fileName === "string" ? fileName : undefined,
+        mimeType,
+        size,
+    };
+    const sticker = findAttribute(document, "DocumentAttributeSticker");
+    if (sticker) {
+        return { ...base, kind: "sticker", emoji: typeof sticker.alt === "string" ? sticker.alt : undefined };
+    }
+    const audio = findAttribute(document, "DocumentAttributeAudio");
+    if (audio) {
+        const duration = readNumber(audio.duration);
+        return {
+            ...base,
+            kind: audio.voice === true ? "voice" : "audio",
+            durationSeconds: duration === undefined ? undefined : Math.round(duration),
+        };
+    }
+    const video = findAttribute(document, "DocumentAttributeVideo");
+    if (video) {
+        const duration = readNumber(video.duration);
+        return {
+            ...base,
+            kind: "video",
+            durationSeconds: duration === undefined ? undefined : Math.round(duration),
+        };
+    }
+    return base;
+}
+function describeMedia(media) {
+    const raw = media;
+    const className = raw?.className;
+    if (!className || typeof className !== "string" || className === "MessageMediaEmpty") {
+        return undefined;
+    }
+    const simple = SIMPLE_KINDS[className];
+    if (simple) {
+        return { kind: simple };
+    }
+    if (className === "MessageMediaDocument") {
+        return describeDocument(raw.document);
+    }
+    // Telegram keeps adding media types. An unmodelled one still has to show up
+    // as "something was attached" — a blank message is the failure being fixed.
+    return { kind: "other", telegramType: className };
+}

package/dist/proxy-config.js

@@ -37,12 +37,29 @@ function resolveSocksType(value) {
     }
     return socksType;
 }
+/** Shape check only; the real resolution happens in `secret-refs`. */
+function asProxySecretRef(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value;
+    return typeof candidate.source === "string"
+        && typeof candidate.provider === "string"
+        && typeof candidate.id === "string"
+        ? { source: candidate.source, provider: candidate.provider, id: candidate.id }
+        : undefined;
+}
 function resolveProxyCredential(value, field) {
     if (value === undefined || value === null) {
         return undefined;
     }
+    // A SecretRef is resolved later, at account start-up. Rejecting it here
+    // would make the config unloadable before the resolver ever runs.
+    const ref = asProxySecretRef(value);
+    if (ref) {
+        return ref;
+    }
     if (typeof value !== "string") {
-        throw new Error(`clawgram: proxy.${field} must be a string.`);
+        throw new Error(`clawgram: proxy.${field} must be a string or a secret reference.`);
     }
     return value.trim() ? value : undefined;
 }
@@ -95,11 +112,29 @@ function buildTelegramClientOptions(proxy) {
             connectionRetries: CONNECTION_RETRIES,
         };
     }
+    // Secret references are substituted before the client is built, and the
+    // account start-up refuses to continue while any remain — so by here the
+    // credentials are strings. The cast states that, and `assertProxyResolved`
+    // enforces it rather than trusting it.
+    assertProxyResolved(resolved);
     return {
         connectionRetries: CONNECTION_RETRIES,
         proxy: resolved,
     };
 }
+/**
+ * Defence in depth. If an unresolved reference ever reached GramJS it would be
+ * sent as the literal string "[object Object]" — a credential-shaped value
+ * travelling to a proxy server.
+ */
+function assertProxyResolved(proxy) {
+    for (const field of ["username", "password"]) {
+        const value = proxy[field];
+        if (value !== undefined && typeof value !== "string") {
+            throw new Error(`clawgram: proxy.${field} is still an unresolved secret reference.`);
+        }
+    }
+}
 /** Credential-free proxy summary safe to log. */
 function describeProxy(proxy) {
     return proxy ? `socks${proxy.socksType}` : undefined;

package/dist/reactions.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Emoji reactions — the `react` action of OpenClaw's message tool.
+ *
+ * Semantics follow the tool contract, and deliberately match what OpenClaw's
+ * own Telegram channel does: an empty `emoji` clears this account's reactions,
+ * and `remove: true` also clears but still requires a non-empty `emoji` so the
+ * tool call stays self-describing.
+ *
+ * Parsing lives here, apart from the network, so the argument handling can be
+ * tested without a Telegram connection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseReactionParams = parseReactionParams;
+/** Accepts the boolean and the string a JSON-ish caller may send for it. */
+function readBooleanFlag(value) {
+    return value === true || value === "true";
+}
+/**
+ * Message ids are positive integers. A date arriving here would resolve to
+ * some unrelated message, so anything else is refused rather than coerced —
+ * the same reasoning as the history parser's id/date guard.
+ */
+function parseMessageId(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`clawgram: react messageId must be a positive integer, got ${JSON.stringify(value)}`);
+    }
+    return parsed;
+}
+function parseReactionParams(params, toolContext) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: react requires a chatId");
+    }
+    const messageId = parseMessageId(params.messageId ?? params.msgId ?? params.message_id)
+        ?? parseMessageId(toolContext?.currentMessageId);
+    if (messageId === undefined) {
+        throw new Error("clawgram: react requires a messageId");
+    }
+    const rawEmoji = params.emoji;
+    if (rawEmoji !== undefined && rawEmoji !== null && typeof rawEmoji !== "string") {
+        throw new Error("clawgram: react emoji must be a string");
+    }
+    const removeFlag = readBooleanFlag(params.remove);
+    const emoji = typeof rawEmoji === "string" ? rawEmoji.trim() : undefined;
+    // Only two shapes are meaningful: add this emoji, or clear. A call with
+    // neither is a caller mistake, not an empty-string removal.
+    if (emoji === undefined) {
+        throw new Error("clawgram: react requires an emoji");
+    }
+    if (removeFlag && emoji === "") {
+        throw new Error("clawgram: react with remove requires an emoji");
+    }
+    return {
+        target,
+        messageId,
+        emoji,
+        remove: removeFlag || emoji === "",
+    };
+}

package/dist/secret-refs.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * SecretRef support for the account's credentials.
+ *
+ * `apiHash` and `sessionString` are bearer credentials for the whole Telegram
+ * account, and until now they could only live as plaintext in `openclaw.json` —
+ * a file that gets backed up, copied between machines and pasted into issues.
+ * Every other secret in this deployment is a reference resolved at start-up;
+ * these were the exception. Proxy credentials are here for the same reason.
+ *
+ * A reference is `{ source, provider, id }`, and OpenClaw resolves a batch of
+ * them into a map keyed by `source:provider:id`. Collecting and substituting is
+ * kept pure so it can be tested without a secret store; the resolution call
+ * itself lives in the channel's account start-up.
+ *
+ * Nothing here logs a value, and an unresolved reference is reported by field
+ * name only. A missing secret is a configuration error, and the error message
+ * for it must not become the leak it was meant to prevent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secretRefKey = secretRefKey;
+exports.collectAccountSecretRefs = collectAccountSecretRefs;
+exports.applyAccountSecrets = applyAccountSecrets;
+exports.hasUnresolvedSecretRef = hasUnresolvedSecretRef;
+exports.readSecretInput = readSecretInput;
+/** Credential fields that accept a reference, in the order they are reported. */
+const ACCOUNT_SECRET_FIELDS = ["apiHash", "sessionString"];
+const PROXY_SECRET_FIELDS = ["username", "password"];
+/**
+ * Must match OpenClaw's own keying, or every lookup misses and a correctly
+ * configured secret looks unresolvable.
+ */
+function secretRefKey(ref) {
+    return `${ref.source}:${ref.provider}:${ref.id}`;
+}
+/**
+ * Shape check only. A partially written reference is treated as "not a
+ * reference" rather than as an error, so a typo cannot be mistaken for a
+ * resolvable secret and silently blank a credential.
+ */
+function asSecretRef(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const candidate = value;
+    const { source, provider, id } = candidate;
+    if (typeof source !== "string" || typeof provider !== "string" || typeof id !== "string") {
+        return undefined;
+    }
+    if (!source.trim() || !provider.trim() || !id.trim()) {
+        return undefined;
+    }
+    return { source, provider, id };
+}
+/** Every credential slot, as `[path, value]` pairs — account fields and proxy alike. */
+function* eachSecretSlot(account) {
+    for (const field of ACCOUNT_SECRET_FIELDS) {
+        yield [field, account?.[field]];
+    }
+    for (const field of PROXY_SECRET_FIELDS) {
+        yield [`proxy.${field}`, account?.proxy?.[field]];
+    }
+}
+/**
+ * References this account needs resolved, deduplicated: two fields pointing at
+ * the same secret must not become two lookups.
+ */
+function collectAccountSecretRefs(account) {
+    const byKey = new Map();
+    for (const [, value] of eachSecretSlot(account)) {
+        const ref = asSecretRef(value);
+        if (ref) {
+            byKey.set(secretRefKey(ref), ref);
+        }
+    }
+    return [...byKey.values()];
+}
+/**
+ * Substitutes resolved values into a copy of the account.
+ *
+ * A value that did not resolve is left as the reference object and its field
+ * named in `missing`. Writing the reference through as a string would produce
+ * "[object Object]", which Telegram rejects with a complaint about the
+ * credential itself — sending whoever reads it to check a secret that was
+ * never the problem.
+ */
+function applyAccountSecrets(account, values) {
+    const missing = [];
+    const resolved = { ...account };
+    if (account?.proxy && typeof account.proxy === "object") {
+        resolved.proxy = { ...account.proxy };
+    }
+    for (const field of ACCOUNT_SECRET_FIELDS) {
+        const ref = asSecretRef(account?.[field]);
+        if (!ref) {
+            continue;
+        }
+        const value = values.get(secretRefKey(ref));
+        if (typeof value === "string") {
+            resolved[field] = value;
+        }
+        else {
+            missing.push(field);
+        }
+    }
+    for (const field of PROXY_SECRET_FIELDS) {
+        const ref = asSecretRef(account?.proxy?.[field]);
+        if (!ref) {
+            continue;
+        }
+        const value = values.get(secretRefKey(ref));
+        if (typeof value === "string") {
+            resolved.proxy[field] = value;
+        }
+        else {
+            missing.push(`proxy.${field}`);
+        }
+    }
+    return { account: resolved, missing };
+}
+/**
+ * True while any credential is still a reference. Used as a last gate before
+ * handing the account to GramJS, where an unresolved value would travel into a
+ * login attempt.
+ */
+function hasUnresolvedSecretRef(account) {
+    for (const [, value] of eachSecretSlot(account)) {
+        if (asSecretRef(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Reads a credential straight out of the config.
+ *
+ * A reference is returned untouched, for resolution later; everything else is
+ * stringified exactly as the config reader always did. The point is the first
+ * half: `String(ref)` yields "[object Object]", which travels into a Telegram
+ * login and returns as a complaint about the credential rather than about the
+ * secret that failed to resolve.
+ */
+function readSecretInput(value) {
+    const ref = asSecretRef(value);
+    if (ref) {
+        return ref;
+    }
+    return String(value ?? "");
+}

package/openclaw.plugin.json

@@ -99,10 +99,72 @@
                   ]
                 },
                 "apiHash": {
-                  "type": "string"
+                  "description": "Literal value, or a SecretRef resolved at account start-up.",
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "source",
+                        "provider",
+                        "id"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "source": {
+                          "enum": [
+                            "env",
+                            "file",
+                            "exec"
+                          ]
+                        },
+                        "provider": {
+                          "type": "string",
+                          "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                        },
+                        "id": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      }
+                    }
+                  ]
                 },
                 "sessionString": {
-                  "type": "string"
+                  "description": "Literal value, or a SecretRef resolved at account start-up.",
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "source",
+                        "provider",
+                        "id"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "source": {
+                          "enum": [
+                            "env",
+                            "file",
+                            "exec"
+                          ]
+                        },
+                        "provider": {
+                          "type": "string",
+                          "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                        },
+                        "id": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      }
+                    }
+                  ]
                 },
                 "proxy": {
                   "type": "object",
@@ -126,10 +188,72 @@
                       ]
                     },
                     "username": {
-                      "type": "string"
+                      "description": "Literal value, or a SecretRef resolved at account start-up.",
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "required": [
+                            "source",
+                            "provider",
+                            "id"
+                          ],
+                          "additionalProperties": false,
+                          "properties": {
+                            "source": {
+                              "enum": [
+                                "env",
+                                "file",
+                                "exec"
+                              ]
+                            },
+                            "provider": {
+                              "type": "string",
+                              "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                            },
+                            "id": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
                     },
                     "password": {
-                      "type": "string"
+                      "description": "Literal value, or a SecretRef resolved at account start-up.",
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "object",
+                          "required": [
+                            "source",
+                            "provider",
+                            "id"
+                          ],
+                          "additionalProperties": false,
+                          "properties": {
+                            "source": {
+                              "enum": [
+                                "env",
+                                "file",
+                                "exec"
+                              ]
+                            },
+                            "provider": {
+                              "type": "string",
+                              "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                            },
+                            "id": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
                     },
                     "timeout": {
                       "type": "number",

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "clawgram",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {
     "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\"",
+    "prepublishOnly": "npm run build && npm test",
     "clawgram-cli": "node dist/clawgram-cli.js",
     "clawgram-cli:hello": "node dist/clawgram-cli.js --hello",
     "clawgram-cli:auth": "node dist/clawgram-cli.js --auth"