clawgram 2.9.0 → 2.10.0

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,38 @@ 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),
+            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 +274,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 +842,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 +902,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/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,132 @@
+"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.buildEmojiSystemPrompt = buildEmojiSystemPrompt;
+exports.parseEmojiChoice = parseEmojiChoice;
+exports.shouldReactToSilentTurn = shouldReactToSilentTurn;
+exports.reactToSilentMention = reactToSilentMention;
+function buildEmojiSystemPrompt(appetite) {
+    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.",
+        "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");
+}
+/**
+ * Turns a model answer into an emoji, or nothing.
+ *
+ * Deliberately strict. A wrong emoji is a visible act on someone else's
+ * message, and Telegram rejects emoji outside the chat's allowed set anyway —
+ * so anything that does not look like a bare emoji is treated as "no
+ * reaction" rather than sent hopefully.
+ */
+function parseEmojiChoice(raw) {
+    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;
+    }
+    // Latin letters and digits mean words like "NONE", "ok" or "1" slipped
+    // through; an emoji has none of them.
+    if (/[A-Za-z0-9]/.test(cleaned)) {
+        return undefined;
+    }
+    return cleaned;
+}
+/**
+ * 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;
+    }
+    const answer = await params.deps.complete({
+        messages: [{ role: "user", content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS) }],
+        systemPrompt: buildEmojiSystemPrompt(appetite),
+        maxTokens: 8,
+        purpose: "clawgram: emoji reaction for a silent mention",
+    });
+    const emoji = parseEmojiChoice(answer?.text);
+    params.deps.onDecision?.({ messageId, appetite, chose: emoji ? "emoji" : "none" });
+    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.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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