clawgram 2.17.1 → 2.18.0

package/README.md

@@ -236,19 +236,42 @@ reconnect), not the whole Gateway.
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
 | `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 |
 
 Group config fields:
 
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | boolean | `true` | Enables or disables replies in the group |
-| `groupPolicy` | `"open"` \| `"mention"` | `"mention"` | `open` replies to any group message, `mention` only on @mention or reply-to-self |
+| `groupPolicy` | `"open"` \| `"mention"` \| `"tag"` | `"mention"` | What wakes the agent here — see [What wakes the agent in a group](#what-wakes-the-agent-in-a-group) |
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames inside that group |
 | `tools` | object | unset | `{ allow?, alsoAllow?, deny? }` — tool policy for this group; see [Per-group tools, skills and system prompt](#per-group-tools-skills-and-system-prompt) |
 | `toolsBySender` | object | unset | Per-sender tool policy inside this group, keys `id:<id>`, `username:<handle>`, `name:<display>` or `*` |
 | `skills` | string[] | unset | Skill allowlist for this group; `[]` = no skills here, unset = the agent's skills |
 | `systemPrompt` | string | unset | Trusted prompt block appended for messages from this group |
 
+### What wakes the agent in a group
+
+`groupPolicy` decides which messages start a turn at all. It is a ladder, widest
+first, and the rung is chosen per group:
+
+| Rung | Wakes on | Use it when |
+|---|---|---|
+| `open` | every message in the chat | the agent works as a member of the team and an address may carry no name at all |
+| `mention` | the name it answers to, an `@username`, or a reply to it | the default: the agent is a participant, not a fixture |
+| `tag` | an `@username` or a reply to it — **never the name** | the name occurs in conversation constantly, as it does in a large community |
+
+Two things are worth knowing before reaching for `open`:
+
+- it spends a **full turn on every message**, chatter included. Whether words
+  are owed is then the agent's decision, and most of the time the answer is no;
+- the typing indicator is shown only for messages that actually addressed the
+  agent. Under `open` the room would otherwise watch it "type" through
+  conversations it is merely reading, with nothing following.
+
+Emoji reactions are unaffected by the rung: the channel leaves one only where
+the agent was genuinely addressed, so background reading stays unmarked.
+
 ### Per-group tools, skills and system prompt
 
 Since 2.17.0 a group entry can narrow what the assistant does *in that chat*

package/dist/channel.js

@@ -80,6 +80,22 @@ function readAccountReactionLevel(cfg, accountId) {
     }
     return cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionLevel;
 }
+/**
+ * Model ref for the emoji pick, when the account names one.
+ *
+ * Picking one emoji out of a fixed list of 68 is the cheapest judgement this
+ * channel makes and the only model call it makes on its own; running it on the
+ * agent's own head spends the expensive quota on a decision a small model
+ * makes just as well.
+ */
+function readAccountReactionModel(cfg, accountId) {
+    const resolvedAccountId = (0, helpers_1.resolveConfiguredAccountId)(cfg, accountId);
+    if (!resolvedAccountId) {
+        return undefined;
+    }
+    const raw = cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionModel;
+    return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
 /**
  * Wires `reactToSilentMention` to this account's runtime, config and log.
  *
@@ -96,6 +112,7 @@ async function reactToSilentMentionForAccount(params) {
     }
     await (0, silent_reaction_1.reactToSilentMention)({
         appetite: (0, reactions_1.resolveAgentReactionGuidance)(readAccountReactionLevel(params.cfg, params.accountId)),
+        model: readAccountReactionModel(params.cfg, params.accountId),
         wasMentioned: params.wasMentioned,
         chatId: params.chatId,
         messageId: params.messageId,
@@ -696,13 +713,19 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             // channelRuntime comes from the untyped ctx, so the generic route type falls
                             // back to the minimal RouteLike. The runtime value is a ResolvedAgentRoute.
                             const route = inboundRoute;
-                            const wasMentioned = (0, helpers_1.hasTelegramMention)({
-                                cfg,
-                                agentId: route.agentId,
-                                selfUsername,
-                                text,
-                                message: rawMessage,
-                            });
+                            // Under `tag` the name is not an address: in a chat of a thousand
+                            // people it occurs in conversation constantly and is aimed at her
+                            // almost never. Only the `@` counts, and it is the same fact the
+                            // stricter rung of the ladder is named after.
+                            const wasMentioned = groupConfig.groupPolicy === "tag"
+                                ? (0, helpers_1.hasExplicitTelegramMention)({ selfUsername, text, message: rawMessage })
+                                : (0, helpers_1.hasTelegramMention)({
+                                    cfg,
+                                    agentId: route.agentId,
+                                    selfUsername,
+                                    text,
+                                    message: rawMessage,
+                                });
                             const wasReplyToSelf = await (0, helpers_1.isReplyToSelfMessage)(rawMessage, selfId);
                             const mentionDecision = (0, channel_inbound_1.resolveInboundMentionDecision)({
                                 facts: {
@@ -712,7 +735,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 },
                                 policy: {
                                     isGroup: true,
-                                    requireMention: groupConfig.groupPolicy === "mention",
+                                    requireMention: groupConfig.groupPolicy !== "open",
                                     allowTextCommands: false,
                                     hasControlCommand: false,
                                     commandAuthorized: true,
@@ -723,6 +746,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 chatId: normalized.chatId,
                                 messageId: normalized.messageId,
                                 selfUsername,
+                                groupPolicy: groupConfig.groupPolicy,
                                 mentionedFlag: rawMessage?.mentioned === true,
                                 hasEntities: Array.isArray(rawMessage?.entities) ? rawMessage.entities.length : 0,
                                 wasMentioned,
@@ -730,7 +754,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 shouldSkip: mentionDecision.shouldSkip,
                                 text,
                             });
-                            if (groupConfig.groupPolicy === "mention" && mentionDecision.shouldSkip && !wasReplyToSelf) {
+                            if (groupConfig.groupPolicy !== "open" && mentionDecision.shouldSkip && !wasReplyToSelf) {
                                 log?.info?.("clawgram skipping group message without mention", {
                                     accountId,
                                     chatId: normalized.chatId,
@@ -993,6 +1017,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             }, {
                                 readMessageId: Number(normalized.messageId),
                                 messageThreadId,
+                                // The indicator is a promise of an answer, and it is owed only
+                                // to someone who addressed her. Under `open` the turn runs on
+                                // every message in the chat, so without this the whole room
+                                // watches her "type" through conversations she is only reading.
+                                typing: mentionDecision.effectiveWasMentioned || wasReplyToSelf,
                             });
                             log?.info?.("clawgram group inbound handled", {
                                 accountId,

package/dist/gramjs-client.js

@@ -565,7 +565,29 @@ class GramJsClientManager {
         }
         await this.client.markAsRead(resolved.peer, messageId).catch(() => undefined);
     }
+    /**
+     * Runs `fn` while the chat shows "typing", and marks the message read.
+     *
+     * `typing: false` keeps the read receipt and drops the indicator. The two
+     * are separable because they promise different things: reading is what the
+     * agent did, typing is a promise that words are coming. Under
+     * `groupPolicy: "open"` every message starts a turn, and most of those turns
+     * end in silence — on 2026-08-17 the management chat watched «Тина
+     * печатает…» for 20–26 seconds on each of four messages that were never
+     * addressed to her, and nothing followed. An indicator that is not owed to
+     * anyone is worse than no indicator.
+     */
     async withTyping(target, fn, options) {
+        if (options?.typing === false) {
+            // Still a read receipt: she did read it, and the chat may show that.
+            const resolvedPeer = await this.resolvePeer(target).then((r) => r.peer).catch(() => undefined);
+            if (resolvedPeer) {
+                await this.markRead(resolvedPeer, options?.readMessageId, {
+                    messageThreadId: options?.messageThreadId,
+                }).catch(() => undefined);
+            }
+            return await fn();
+        }
         let peer;
         let readMarked = false;
         let stopped = false;

package/dist/helpers.js

@@ -27,6 +27,7 @@ exports.resolveActiveUsername = resolveActiveUsername;
 exports.normalizeAllowEntry = normalizeAllowEntry;
 exports.isSenderAllowed = isSenderAllowed;
 exports.hasTelegramMention = hasTelegramMention;
+exports.hasExplicitTelegramMention = hasExplicitTelegramMention;
 exports.toDisplayName = toDisplayName;
 exports.withTimeout = withTimeout;
 exports.stripSilentReplyToken = stripSilentReplyToken;
@@ -271,8 +272,17 @@ function resolveAllowFrom(value) {
     const entries = value.map((entry) => String(entry).trim()).filter(Boolean);
     return entries.length > 0 ? entries : ["*"];
 }
+/**
+ * Three rungs, widest first: `open` wakes on every message, `mention` on the
+ * name or an `@`, `tag` on the `@` alone. Anything unrecognised lands on
+ * `mention`, the rung this channel has always defaulted to.
+ */
 function resolveGroupPolicy(value) {
-    return value === "open" ? "open" : "mention";
+    if (value === "open")
+        return "open";
+    if (value === "tag")
+        return "tag";
+    return "mention";
 }
 /**
  * Per-group `skills` → core `replyOptions.skillFilter`, `systemPrompt` →
@@ -342,19 +352,27 @@ function isSenderAllowed(input) {
     ].filter((value) => Boolean(value)).map(normalizeAllowEntry);
     return input.allowFrom.map(normalizeAllowEntry).some((entry) => senderIds.includes(entry));
 }
-function hasTelegramMention(input) {
+/**
+ * Whether the message tags this account with `@username` — nothing else.
+ *
+ * The name the agent answers to (`Тина`, and whatever else core's mention
+ * regexes carry) is deliberately NOT consulted. In a thousand-person chat the
+ * name occurs in conversation constantly and almost never as an address; the
+ * `@` is the one form that is unambiguously aimed at her. This is the whole of
+ * `groupPolicy: "tag"`.
+ *
+ * `message.mentioned` is Telegram's own flag and stays in: the client sets it
+ * for an @-mention and for a reply to her, and both are addresses.
+ */
+function hasExplicitTelegramMention(input) {
     const normalizedText = input.text.trim();
     const message = input.message;
-    const mentionRegexes = (0, channel_inbound_1.buildMentionRegexes)(input.cfg, input.agentId);
     const selfUsername = input.selfUsername?.replace(/^@/, "").trim();
+    if (!selfUsername) {
+        return false;
+    }
     const entities = Array.isArray(message?.entities) ? message.entities : [];
-    const hasAnyMention = Boolean(message?.mentioned) ||
-        entities.some((entity) => {
-            const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
-            return kind === "MessageEntityMention" || kind === "mention" || kind === "MessageEntityMentionName" || kind === "InputMessageEntityMentionName";
-        }) ||
-        /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(normalizedText);
-    const entityExplicitMention = Boolean(selfUsername) && entities.some((entity) => {
+    const entityExplicitMention = entities.some((entity) => {
         const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
         if (kind !== "MessageEntityMention" && kind !== "mention") {
             return false;
@@ -366,10 +384,27 @@ function hasTelegramMention(input) {
         }
         return normalizedText.slice(offset, offset + length).replace(/^@/, "").trim().toLowerCase() === selfUsername.toLowerCase();
     });
-    const explicitlyMentioned = Boolean(selfUsername) &&
-        (message?.mentioned === true ||
-            entityExplicitMention ||
-            new RegExp(`(^|\\s)@${selfUsername?.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(normalizedText));
+    return message?.mentioned === true ||
+        entityExplicitMention ||
+        new RegExp(`(^|\\s)@${selfUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(normalizedText);
+}
+function hasTelegramMention(input) {
+    const normalizedText = input.text.trim();
+    const message = input.message;
+    const mentionRegexes = (0, channel_inbound_1.buildMentionRegexes)(input.cfg, input.agentId);
+    const selfUsername = input.selfUsername?.replace(/^@/, "").trim();
+    const entities = Array.isArray(message?.entities) ? message.entities : [];
+    const hasAnyMention = Boolean(message?.mentioned) ||
+        entities.some((entity) => {
+            const kind = typeof entity?.className === "string" ? entity.className : entity?.type;
+            return kind === "MessageEntityMention" || kind === "mention" || kind === "MessageEntityMentionName" || kind === "InputMessageEntityMentionName";
+        }) ||
+        /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(normalizedText);
+    const explicitlyMentioned = hasExplicitTelegramMention({
+        selfUsername: input.selfUsername,
+        text: input.text,
+        message,
+    });
     return (0, channel_inbound_1.matchesMentionWithExplicit)({
         text: normalizedText,
         mentionRegexes,

package/dist/silent-reaction.js

@@ -151,6 +151,33 @@ function shouldReactToSilentTurn(params) {
 }
 /** The message text is truncated before it reaches the model; a mood needs no more. */
 const MAX_JUDGED_CHARS = 2000;
+/**
+ * Asks for the emoji on the configured model, falling back to the default one.
+ *
+ * The fallback is not defensive habit. Core refuses a plugin's model override
+ * unless `plugins.entries.clawgram.llm.allowModelOverride` is set, and the
+ * refusal is a throw — which this feature swallows by design. Without the
+ * retry, pointing `reactionModel` at a cheap model in a config that never
+ * granted the permission would not make reactions cheaper, it would make them
+ * disappear, and the log would say nothing about why.
+ */
+async function completeEmoji(params) {
+    const request = {
+        messages: [{ role: "user", content: params.content }],
+        systemPrompt: params.systemPrompt,
+        maxTokens: 8,
+        purpose: "clawgram: emoji reaction for a silent mention",
+    };
+    if (!params.model) {
+        return { answer: await params.deps.complete(request), fellBack: false };
+    }
+    try {
+        return { answer: await params.deps.complete({ ...request, model: params.model }), fellBack: false };
+    }
+    catch {
+        return { answer: await params.deps.complete(request), fellBack: true };
+    }
+}
 /**
  * Leaves an emoji on a message the agent was named in but chose not to answer.
  *
@@ -187,11 +214,11 @@ async function reactToSilentMention(params) {
         params.deps.onDecision?.({ messageId, appetite, chose: "none", allowedCount: 0 });
         return undefined;
     }
-    const answer = await params.deps.complete({
-        messages: [{ role: "user", content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS) }],
+    const { answer, fellBack } = await completeEmoji({
+        deps: params.deps,
+        model: params.model,
         systemPrompt: buildEmojiSystemPrompt(appetite, allowed),
-        maxTokens: 8,
-        purpose: "clawgram: emoji reaction for a silent mention",
+        content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS),
     });
     const emoji = parseEmojiChoice(answer?.text, allowed);
     params.deps.onDecision?.({
@@ -200,6 +227,8 @@ async function reactToSilentMention(params) {
         chose: emoji ? "emoji" : "none",
         emoji,
         allowedCount: allowed?.length,
+        ...params.model ? { model: params.model } : {},
+        ...fellBack ? { modelFellBack: true } : {},
     });
     if (!emoji) {
         return undefined;

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.17.1",
+  "version": "2.18.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -53,9 +53,11 @@
                   "type": "string",
                   "enum": [
                     "open",
-                    "mention"
+                    "mention",
+                    "tag"
                   ],
-                  "default": "mention"
+                  "default": "mention",
+                  "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message, the agent decides for itself whether words are owed; `tag` \u2014 only an explicit @username or a reply, for chats where the name occurs in conversation constantly."
                 },
                 "allowFrom": {
                   "type": "array",
@@ -358,9 +360,11 @@
                         "type": "string",
                         "enum": [
                           "open",
-                          "mention"
+                          "mention",
+                          "tag"
                         ],
-                        "default": "mention"
+                        "default": "mention",
+                        "description": "What wakes the agent in this chat (2.18.0). `mention` \u2014 the name, an @mention or a reply to it; `open` \u2014 every message; `tag` \u2014 only an explicit @username or a reply."
                       },
                       "allowFrom": {
                         "type": "array",
@@ -507,6 +511,10 @@
                   ],
                   "description": "How freely the agent may leave emoji reactions (2.8.0). Core injects its `## Reactions` prompt section only for `minimal` and `extensive`; `off` and `ack` leave the prompt silent about reactions, and the agent then effectively never reacts on its own. Absent means `minimal`. Mirrors the bundled Telegram channel's reactionLevel."
                 },
+                "reactionModel": {
+                  "type": "string",
+                  "description": "Model ref or alias for the emoji pick on a silent mention (2.18.0). Absent = the agent's own model, which is what every version before this used. Requires `plugins.entries.clawgram.llm.allowModelOverride: true` in the gateway config; without it core refuses the override and the pick falls back to the default model rather than losing the reaction."
+                },
                 "replyParseMode": {
                   "type": "string",
                   "enum": [

package/package.json

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