clawgram 2.9.0 → 2.10.1

package/dist/channel.js

@@ -58,6 +58,7 @@ const normalize_1 = require("./normalize");
 const history_1 = require("./history");
 const joins_1 = require("./joins");
 const reactions_1 = require("./reactions");
+const silent_reaction_1 = require("./silent-reaction");
 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");
@@ -75,6 +76,41 @@ function readAccountReactionLevel(cfg, accountId) {
     }
     return cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]?.reactionLevel;
 }
+/**
+ * Wires `reactToSilentMention` to this account's runtime, config and log.
+ *
+ * The decision itself lives in `silent-reaction.ts`, testable without a
+ * Telegram connection; everything here is lookup. Missing pieces — no
+ * connected client, no model access — resolve to no reaction rather than to
+ * an error, because by this point the agent has already declined to reply.
+ */
+async function reactToSilentMentionForAccount(params) {
+    const gram = params.gram;
+    const llm = params.pluginRuntime?.llm;
+    if (!gram || typeof llm?.complete !== "function") {
+        return;
+    }
+    await (0, silent_reaction_1.reactToSilentMention)({
+        appetite: (0, reactions_1.resolveAgentReactionGuidance)(readAccountReactionLevel(params.cfg, params.accountId)),
+        wasMentioned: params.wasMentioned,
+        chatId: params.chatId,
+        messageId: params.messageId,
+        messageText: params.messageText,
+        deps: {
+            // Bound rather than destructured: the SDK may implement this as a
+            // method that needs its receiver.
+            complete: (args) => llm.complete(args),
+            sendReaction: (args) => gram.sendReaction(args),
+            allowedReactions: gram.getAllowedReactions
+                ? () => gram.getAllowedReactions(params.chatId)
+                : undefined,
+            onDecision: (info) => actionLog.info("clawgram silent-mention reaction", {
+                accountId: params.accountId,
+                ...info,
+            }),
+        },
+    });
+}
 /**
  * Read scope as configured for the account. Left `undefined` when the key is
  * absent so `isChatReadable` can tell "not configured" from "configured empty" —
@@ -241,50 +277,24 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
         },
         capabilities: CHANNEL_CAPABILITIES,
         agentPrompt: {
-            // Core injects its `## Reactions` section only when this returns a
-            // level. Without it the prompt never mentions reactions, and the agent
-            // treats the `react` action as one more entry in a 106-property schema:
-            // she used it when asked outright in a DM and never once on her own.
-            reactionGuidance: ({ cfg, accountId }) => {
-                const resolvedAccountId = (0, helpers_1.resolveConfiguredAccountId)(cfg, accountId);
-                const account = resolvedAccountId
-                    ? cfg?.channels?.[constants_1.CHANNEL_ID]?.accounts?.[resolvedAccountId]
-                    : undefined;
-                const level = (0, reactions_1.resolveAgentReactionGuidance)(account?.reactionLevel);
-                // Logged because "the hook returns the right thing" and "the prompt
-                // gained a Reactions section" turned out to be different questions:
-                // on 2.8.0 the first was verifiable by hand on the server while the
-                // prompt stayed byte-identical. Without this line there is no way to
-                // tell a hook core never calls from a hook that answers undefined.
-                actionLog.info("clawgram reactionGuidance", {
-                    accountId: resolvedAccountId ?? null,
-                    requestedAccountId: accountId ?? null,
-                    configuredLevel: typeof account?.reactionLevel === "string" ? account.reactionLevel : null,
-                    level: level ?? null,
-                });
-                // "clawgram" is our plugin id; the section reads "Reactions are
-                // enabled for <label>", and the label is the platform people see.
-                return level ? { level, channelLabel: "Telegram" } : undefined;
-            },
-            messageToolHints: ({ cfg, accountId } = {}) => {
-                const level = (0, reactions_1.resolveAgentReactionGuidance)(readAccountReactionLevel(cfg, accountId));
-                // Logged for the same reason reactionGuidance is: this path is the
-                // workaround for core skipping that hook, so "did our text reach the
-                // prompt" has to be answerable from the log rather than by inference.
-                actionLog.info("clawgram messageToolHints", {
-                    accountId: accountId ?? null,
-                    reactionLevel: level ?? null,
-                });
-                return [
-                    "Use clawgram to send Telegram replies from the connected personal account.",
-                    "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.",
-                    ...(0, reactions_1.buildReactionHintLines)(level),
-                ];
-            },
+            // Nothing here steers reactions, and that is deliberate. 2.8.0 added a
+            // `reactionGuidance` hook and 2.9.0 moved the same text onto these
+            // hints; instrumentation then showed both hooks logging zero
+            // invocations across live turns while the assembled prompt stayed
+            // byte-identical at 44 266 chars. Core resolves the channel for prompt
+            // assembly from `params.messageChannel ?? params.messageProvider`,
+            // which is empty on this path, so nothing this channel contributes to
+            // the prompt reaches the agent at all. Reactions are decided in code
+            // instead — see `reactToSilentMention`. Do not re-add prompt text here
+            // expecting it to arrive.
+            messageToolHints: () => [
+                "Use clawgram to send Telegram replies from the connected personal account.",
+                "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.",
@@ -835,15 +845,53 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     const visibleFallbackText = fallbackText
                                         ? (0, helpers_1.stripTtsDirectives)((0, helpers_1.stripSilentReplyToken)(fallbackText))
                                         : "";
-                                    if (fallbackText && !visibleFallbackText) {
-                                        log?.info?.("clawgram skipping silent transcript fallback", {
+                                    if (!visibleFallbackText) {
+                                        if (fallbackText) {
+                                            log?.info?.("clawgram skipping silent transcript fallback", {
+                                                accountId,
+                                                chatId: normalized.chatId,
+                                                messageId: normalized.messageId,
+                                                routeSessionKey: route.sessionKey,
+                                            });
+                                        }
+                                        else {
+                                            log?.warn?.("clawgram transcript fallback unavailable", {
+                                                accountId,
+                                                chatId: normalized.chatId,
+                                                messageId: normalized.messageId,
+                                                routeSessionKey: route.sessionKey,
+                                            });
+                                        }
+                                        // Named, and nothing came back: leave a reaction so the
+                                        // decision is visible instead of reading as her ignoring
+                                        // people. The condition is her silence, not the shape of
+                                        // the transcript — a turn that wrote no entry at all is
+                                        // just as silent as one that wrote the NO_REPLY token.
+                                        //
+                                        // Never allowed to disturb the turn: the reply is already
+                                        // settled by this point, so a failure here stays silent.
+                                        await reactToSilentMentionForAccount({
+                                            cfg,
                                             accountId,
+                                            gram: runtimes.get(accountId),
+                                            pluginRuntime,
                                             chatId: normalized.chatId,
                                             messageId: normalized.messageId,
-                                            routeSessionKey: route.sessionKey,
+                                            messageText: normalized.text,
+                                            // Same sense of "addressed" the agent was given for this
+                                            // turn on line 817: a reply to her own message counts as
+                                            // being spoken to, mention or not.
+                                            wasMentioned: mentionDecision.effectiveWasMentioned || wasReplyToSelf,
+                                        }).catch((err) => {
+                                            log?.info?.("clawgram silent-mention reaction failed", {
+                                                accountId,
+                                                chatId: normalized.chatId,
+                                                messageId: normalized.messageId,
+                                                error: String(err),
+                                            });
                                         });
                                     }
-                                    else if (visibleFallbackText) {
+                                    else {
                                         log?.warn?.("clawgram using transcript fallback reply", {
                                             accountId,
                                             chatId: normalized.chatId,
@@ -857,14 +905,6 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                             messageThreadId,
                                         });
                                     }
-                                    else {
-                                        log?.warn?.("clawgram transcript fallback unavailable", {
-                                            accountId,
-                                            chatId: normalized.chatId,
-                                            messageId: normalized.messageId,
-                                            routeSessionKey: route.sessionKey,
-                                        });
-                                    }
                                 }
                             }, {
                                 readMessageId: Number(normalized.messageId),

package/dist/gramjs-client.js

@@ -360,6 +360,46 @@ class GramJsClientManager {
         })().catch(() => undefined);
         return { entity, full };
     }
+    /**
+     * Which reactions a chat permits, or `undefined` when it permits all.
+     *
+     * Telegram models this three ways on the full chat: absent or
+     * `ChatReactionsAll` means everything, `ChatReactionsSome` carries the
+     * allowed list, and `ChatReactionsNone` means reactions are switched off —
+     * reported here as an empty list, which callers must read as "react with
+     * nothing", not as "no restriction".
+     *
+     * Custom emoji entries are dropped: they need a Premium account to send.
+     */
+    async getAllowedReactions(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;
+                default:
+                    return undefined;
+            }
+        })();
+        const available = full?.availableReactions;
+        switch (available?.className) {
+            case "ChatReactionsNone":
+                return [];
+            case "ChatReactionsSome":
+                return (available.reactions ?? [])
+                    .map((reaction) => reaction?.emoticon)
+                    .filter((emoticon) => typeof emoticon === "string");
+            default:
+                return undefined;
+        }
+    }
     /**
      * Adds or clears this account's reaction on a message.
      *

package/dist/reactions.js

@@ -11,20 +11,16 @@
  * tested without a Telegram connection.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildReactionHintLines = buildReactionHintLines;
 exports.resolveAgentReactionGuidance = resolveAgentReactionGuidance;
 exports.parseReactionParams = parseReactionParams;
 /**
- * How chatty the agent may be with reactions, as core understands it.
+ * How freely the agent may react, from the account's `reactionLevel`.
  *
- * Core injects a `## Reactions` section into the system prompt only when a
- * channel returns a level from `agentPrompt.reactionGuidance`. Return nothing
- * and the prompt never mentions reactions at all — which is what happened
- * here until 2.8.0: the `react` action existed, the agent had it, and no line
- * of the prompt suggested using it.
- *
- * Levels and fallbacks mirror the bundled Telegram channel so the two behave
- * the same for the same config:
+ * This started as an answer for core's `agentPrompt.reactionGuidance` hook,
+ * which core turned out never to call for this channel. The config key stays
+ * and keeps its meaning; it now steers `reactToSilentMention` instead of a
+ * paragraph of prompt text. Levels mirror the bundled Telegram channel so the
+ * same config reads the same way in both:
  *
  * - `off`, `ack` — no agent reactions (`ack` is the "seen it" emoji core sends
  *   by itself, which is a different feature);
@@ -34,41 +30,6 @@ exports.parseReactionParams = parseReactionParams;
  * An invalid value yields no guidance rather than a guess: a typo turning a
  * work chat chatty is worse than a typo turning it quiet.
  */
-/**
- * The reaction guidance as prompt lines, carried by `messageToolHints`.
- *
- * Core has its own `## Reactions` section, but it only builds it when
- * `params.config` is truthy in the prompt assembler — a condition our channel
- * never satisfied: the hook logged zero invocations across live turns while
- * the neighbouring `messageToolHints`, guarded only by the channel being
- * resolved, is called every time.
- *
- * That condition lives in the minified `openclaw` dependency, so it is not
- * ours to fix; patching `node_modules` would evaporate on the next update.
- * The hints path is ours, reaches the same prompt, and does not depend on
- * that diagnosis being right — if the hints arrive, so does the text.
- *
- * Wording follows core's own so behaviour stays the same if it ever starts
- * calling the hook and both appear.
- */
-function buildReactionHintLines(level) {
-    if (!level) {
-        return [];
-    }
-    const shared = [
-        "Use the `react` action for this: it leaves an emoji on a message without sending one.",
-        "A reaction is not a reply — you can react and still return NO_REPLY, and that is the point when someone names you but needs no answer.",
-    ];
-    return level === "minimal"
-        ? [
-            "Reactions are enabled for Telegram in MINIMAL mode. React ONLY when truly relevant: acknowledge an important request or confirmation, or show genuine sentiment sparingly. Do not react to routine messages or to your own replies. Guideline: at most 1 reaction per 5-10 exchanges.",
-            ...shared,
-        ]
-        : [
-            "Reactions are enabled for Telegram in EXTENSIVE mode. React liberally: acknowledge messages with a fitting emoji, show sentiment and personality, react to humour, notable events or good news, and use a reaction to confirm agreement. Guideline: react whenever it feels natural.",
-            ...shared,
-        ];
-}
 function resolveAgentReactionGuidance(value) {
     if (value === undefined || value === null) {
         return "minimal";

package/dist/silent-reaction.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Reacting when the agent decides to stay silent.
+ *
+ * The agent is told, in her own workspace rules, to leave a reaction when she
+ * is named but has nothing to say. She never did — not once across every turn
+ * in the logs — and the reason turned out not to be the wording: core builds
+ * her system prompt without knowing which channel it is for, so nothing this
+ * channel contributes to the prompt reaches her at all. `messageToolHints`
+ * and `reactionGuidance` both logged zero invocations while the assembled
+ * prompt stayed byte-identical.
+ *
+ * So the decision moves out of the prompt and into code, at the one moment
+ * that is unambiguous: she returned NO_REPLY on a message that named her.
+ * The emoji is still chosen by a model — the point was a reaction that fits
+ * the message, not a fixed acknowledgement stamp — but choosing it is now a
+ * separate, cheap call that cannot be forgotten mid-prompt.
+ *
+ * Parsing lives here, away from the network, so the awkward cases can be
+ * tested without Telegram or a model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_REACTIONS = void 0;
+exports.buildEmojiSystemPrompt = buildEmojiSystemPrompt;
+exports.canonicalizeReactionEmoji = canonicalizeReactionEmoji;
+exports.parseEmojiChoice = parseEmojiChoice;
+exports.shouldReactToSilentTurn = shouldReactToSilentTurn;
+exports.reactToSilentMention = reactToSilentMention;
+function buildEmojiSystemPrompt(appetite, allowed) {
+    const choices = allowed === undefined || allowed.length === 0 ? exports.TELEGRAM_REACTIONS : allowed;
+    const shared = [
+        "You pick a single emoji reaction for a chat message.",
+        "The assistant was mentioned in this message but decided it needs no written reply.",
+        "Answer with exactly one emoji and nothing else, or the word NONE if no reaction fits.",
+        // The set is not decoration: Telegram refuses anything outside it, and an
+        // answer outside it is discarded, so offering the choices up front is the
+        // difference between a reaction and silence.
+        `Choose ONLY from this set, copied exactly: ${choices.join(" ")}`,
+        "Match the mood of the message: a joke gets something amused, praise something warm,",
+        "bad news something sympathetic, an achievement something celebratory.",
+        "Answer NONE when the message is conflictual, heavy, or discusses a person's",
+        "performance — a reaction there reads as a verdict on someone.",
+    ];
+    return appetite === "minimal"
+        ? [
+            ...shared,
+            "Be sparing: answer NONE unless the message clearly invites a reaction.",
+        ].join("\n")
+        : [
+            ...shared,
+            "Be generous: react whenever a reaction would feel natural to a colleague.",
+        ].join("\n");
+}
+/**
+ * The emoji Telegram accepts as reactions, in the exact form it expects.
+ *
+ * Reactions are not "any emoji". Telegram keeps a fixed set, and several of
+ * its members carry **no** variation selector — `❤` is U+2764 alone, and so
+ * are `⚡`, `✍`, `🕊`, `☃`. Sending the U+FE0F-decorated form of any of them
+ * fails, which is exactly what happened on the first live attempt:
+ *
+ *   RPCError: 400: REACTION_INVALID (caused by messages.SendReaction)
+ *
+ * The list is written with explicit escapes for those five, because the
+ * difference is invisible in an editor and a stray U+FE0F would break them
+ * again silently.
+ */
+exports.TELEGRAM_REACTIONS = [
+    "👍", "👎", "❤", "🔥", "🥰", "👏", "😁", "🤔", "🤯", "😱",
+    "🤬", "😢", "🎉", "🤩", "🤮", "💩", "🙏", "👌", "\u{1F54A}", "🤡",
+    "🥱", "🥴", "😍", "🐳", "🌚", "🌭", "💯", "🤣", "⚡", "🍌",
+    "🏆", "💔", "🤨", "😐", "🍓", "🍾", "💋", "😈", "😴", "😭",
+    "🤓", "👻", "👀", "🎃", "🙈", "😇", "😨", "🤝", "✍", "🤗",
+    "🫡", "🎅", "🎄", "☃", "💅", "🤪", "🗿", "🆒", "💘", "🙉",
+    "🦄", "😘", "💊", "🙊", "😎", "👾", "🤷", "😡",
+];
+/**
+ * Strips the decorations a model adds that Telegram will not accept.
+ *
+ * U+FE0F is the big one — models emit `❤️` and `⚡️` by habit, and the reaction
+ * set wants them bare. Skin-tone modifiers are dropped for the same reason:
+ * `👍🏽` is not a member of the set, `👍` is.
+ */
+function canonicalizeReactionEmoji(value) {
+    return value.replace(/️/g, "").replace(/[\u{1F3FB}-\u{1F3FF}]/gu, "");
+}
+/**
+ * Turns a model answer into an emoji Telegram will actually take, or nothing.
+ *
+ * Deliberately strict, and strict in the one way that matters: the result is
+ * matched against the reaction set rather than merely "looks like an emoji".
+ * The first live attempt proved the difference — the model picked a perfectly
+ * sensible emoji, the parser passed it, and Telegram refused it.
+ *
+ * `allowed` narrows the set further for chats that restrict which reactions
+ * they permit; omit it when the chat allows all of them.
+ */
+function parseEmojiChoice(raw, allowed) {
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    // Models like to wrap answers in quotes, backticks or a trailing period.
+    const cleaned = raw.trim().replace(/^["'`]+|["'`.]+$/g, "").trim();
+    if (!cleaned || /^none$/i.test(cleaned)) {
+        return undefined;
+    }
+    // A sentence is a refusal or an explanation, not a reaction.
+    if (/\s/.test(cleaned) || cleaned.length > 8) {
+        return undefined;
+    }
+    const candidate = canonicalizeReactionEmoji(cleaned);
+    // `undefined` is "the chat does not restrict reactions"; an empty list is
+    // `ChatReactionsNone` — reactions switched off — and must permit nothing.
+    // Collapsing the two would react in a chat that forbids reacting.
+    const permitted = allowed === undefined
+        ? exports.TELEGRAM_REACTIONS
+        : allowed.map(canonicalizeReactionEmoji);
+    return permitted.includes(candidate) ? candidate : undefined;
+}
+/**
+ * Whether a silent turn deserves a reaction attempt at all.
+ *
+ * Only mentions: the rule the owner asked for is about being named and having
+ * nothing to add. A silent turn on a message that never mentioned her is
+ * ordinary background reading, and reacting to it would be noise.
+ */
+function shouldReactToSilentTurn(params) {
+    if (!params.appetite || !params.wasMentioned) {
+        return false;
+    }
+    return Boolean(params.messageText?.trim());
+}
+/** The message text is truncated before it reaches the model; a mood needs no more. */
+const MAX_JUDGED_CHARS = 2000;
+/**
+ * Leaves an emoji on a message the agent was named in but chose not to answer.
+ *
+ * Best-effort by construction: the reply is already settled when this runs, so
+ * a missing model, a refusal, or an emoji Telegram will not take all end as
+ * silence — the same outcome as before the feature existed. Callers still wrap
+ * it, because a throw here would surface as a failed turn on a message the
+ * agent had already decided needed nothing.
+ *
+ * Returns the emoji it sent, for tests and for nothing else.
+ */
+async function reactToSilentMention(params) {
+    const { appetite } = params;
+    if (!appetite || !shouldReactToSilentTurn({
+        wasMentioned: params.wasMentioned,
+        appetite,
+        messageText: params.messageText,
+    })) {
+        return undefined;
+    }
+    const messageId = Number(params.messageId);
+    if (!Number.isInteger(messageId) || messageId <= 0) {
+        return undefined;
+    }
+    // A chat that restricts reactions would reject anything outside its own set,
+    // so the restriction has to reach the model rather than be discovered by a
+    // rejected send. Not knowing is not the same as being forbidden: a failure
+    // here falls back to the full Telegram set.
+    const allowed = await (params.deps.allowedReactions?.() ?? Promise.resolve(undefined))
+        .catch(() => undefined);
+    // Reactions switched off for the whole chat: nothing to pick from, and no
+    // reason to spend a model call finding that out.
+    if (allowed !== undefined && allowed.length === 0) {
+        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) }],
+        systemPrompt: buildEmojiSystemPrompt(appetite, allowed),
+        maxTokens: 8,
+        purpose: "clawgram: emoji reaction for a silent mention",
+    });
+    const emoji = parseEmojiChoice(answer?.text, allowed);
+    params.deps.onDecision?.({
+        messageId,
+        appetite,
+        chose: emoji ? "emoji" : "none",
+        emoji,
+        allowedCount: allowed?.length,
+    });
+    if (!emoji) {
+        return undefined;
+    }
+    await params.deps.sendReaction({
+        target: params.chatId,
+        messageId,
+        emoji,
+        remove: false,
+    });
+    return emoji;
+}

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.9.0",
+  "version": "2.10.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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