clawgram 2.29.2 → 2.30.1

package/README.md

@@ -300,6 +300,17 @@ Two things are worth knowing before reaching for `open`:
 Emoji reactions are unaffected by the rung: the channel leaves one only where
 the agent was genuinely addressed, so background reading stays unmarked.
 
+An isolated `@mention` waits up to 60 seconds for an explanation. Short
+addresses wait for 6 seconds of quiet; consecutive messages by the same sender
+in the same chat/topic are collected into one turn within a 2-minute window.
+An unanswered bare tag can still receive a late continuation within that window.
+Other senders and topics do not inherit the address. Detailed requests proceed
+immediately. Before answering an address, the agent receives up to 12 recent
+messages from the same chat/topic (3 minutes before the triggering message,
+including explanations that arrived afterwards), subject to `readChats`.
+History failures leave the original request usable. Attachment metadata includes
+message ids so the agent can read a relevant image with `fetchMedia`.
+
 ### 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

@@ -62,6 +62,7 @@ const account_scopes_1 = require("./account-scopes");
 Object.defineProperty(exports, "resolveAccountOperatorIds", { enumerable: true, get: function () { return account_scopes_1.resolveAccountOperatorIds; } });
 const outbound_1 = require("./outbound");
 const inbound_pipeline_1 = require("./inbound-pipeline");
+const nearby_conversation_1 = require("./nearby-conversation");
 const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
 /**
  * Хэндл в `allowFrom` — обещание, которое Telegram не держит.
@@ -271,9 +272,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 });
                 const client = gram.getClient();
                 const eventBuilder = new events_1.NewMessage({});
+                const nearbyConversation = new nearby_conversation_1.NearbyConversation();
                 const eventHandler = async (event) => (0, inbound_pipeline_1.handleInboundEvent)(event, {
                     accountId, cfg, channelRuntime, client, gram, log,
                     pluginRuntime, runtimes, selfId, selfLabel, selfUsername,
+                    nearbyConversation,
                 });
                 client.addEventHandler(eventHandler, eventBuilder);
                 // Being added to a chat arrives as a service message, which `NewMessage`
@@ -307,6 +310,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 const joinEventBuilder = new events_1.Raw({});
                 client.addEventHandler(joinEventHandler, joinEventBuilder);
                 await (0, channel_runtime_1.waitUntilAbort)(ctx.abortSignal, async () => {
+                    nearbyConversation.close();
                     client.removeEventHandler(eventHandler, eventBuilder);
                     client.removeEventHandler(joinEventHandler, joinEventBuilder);
                     (0, account_registry_1.forgetAccount)(accountId);

package/dist/inbound-pipeline.js

@@ -32,6 +32,8 @@ const account_registry_1 = require("./account-registry");
 const group_reply_address_1 = require("./group-reply-address");
 const helpers_1 = require("./helpers");
 const constants_2 = require("./constants");
+const account_scopes_1 = require("./account-scopes");
+const nearby_conversation_1 = require("./nearby-conversation");
 const attachments_1 = require("./attachments");
 /**
  * Wires `reactToSilentMention` to this account's runtime, config and log.
@@ -116,7 +118,7 @@ function visibleReplyText(params) {
     return visibleText;
 }
 async function handleInboundEvent(event, ctx) {
-    const { accountId, cfg, channelRuntime, client, gram, log, pluginRuntime, runtimes, selfId, selfLabel, selfUsername } = ctx;
+    const { accountId, cfg, channelRuntime, client, gram, log, pluginRuntime, runtimes, selfId, selfLabel, selfUsername, nearbyConversation } = ctx;
     try {
         const rawMessage = event?.message;
         const rawPeerUserId = rawMessage?.peerId?.userId;
@@ -457,10 +459,12 @@ async function handleInboundEvent(event, ctx) {
             // reply does not carry on its own.
             const replyParent = await (0, helpers_1.resolveReplyParent)(rawMessage, { selfId, selfLabel });
             const wasReplyToSelf = replyParent.isSelf;
+            const nearbyKey = nearbyConversation?.key(normalized.chatId, normalized.messageThreadId, senderId);
+            const isContinuation = nearbyKey !== undefined && nearbyConversation.has(nearbyKey);
             const mentionDecision = (0, channel_inbound_1.resolveInboundMentionDecision)({
                 facts: {
                     canDetectMention: true,
-                    wasMentioned,
+                    wasMentioned: wasMentioned || isContinuation,
                     hasAnyMention: /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(addressableText),
                 },
                 policy: {
@@ -493,6 +497,26 @@ async function handleInboundEvent(event, ctx) {
                 });
                 return;
             }
+            let nearbyText;
+            if (nearbyConversation && (wasMentioned || wasReplyToSelf || isContinuation)) {
+                const collected = await nearbyConversation.collect(nearbyKey, text, wasMentioned || wasReplyToSelf);
+                if (collected === undefined)
+                    return;
+                text = collected;
+                try {
+                    nearbyText = await (0, nearby_conversation_1.readNearbyConversation)({
+                        gram,
+                        chatId: normalized.chatId,
+                        messageId: normalized.messageId,
+                        threadId: (0, helpers_1.parseOptionalThreadId)(normalized.messageThreadId),
+                        timestamp: normalized.timestamp,
+                        readChats: (0, account_scopes_1.resolveAccountReadChats)(cfg, accountId),
+                    });
+                }
+                catch {
+                    log?.warn?.("clawgram nearby conversation read failed", { accountId, chatId: normalized.chatId });
+                }
+            }
             // Who is speaking, resolved only now — past the group gate and the
             // mention gate, so a message the agent will not even read costs no
             // call (B5-04). GramJS attaches `_sender` only from its entity cache,
@@ -518,7 +542,8 @@ async function handleInboundEvent(event, ctx) {
             const conversationRouteTarget = (0, helpers_1.buildConversationTarget)(normalized.chatId);
             const ctxPayload = channelRuntime.reply.finalizeInboundContext({
                 Body: body,
-                BodyForAgent: agentFacingGroupBody({ address: groupReplyAddress, senderId, text }),
+                BodyForAgent: agentFacingGroupBody({ address: groupReplyAddress, senderId, text }) +
+                    (nearbyText ? `\n\n[Соседние сообщения чата — контекст]\n${nearbyText}` : ""),
                 RawBody: text,
                 CommandBody: text,
                 From: conversationRouteTarget,
@@ -555,7 +580,7 @@ async function handleInboundEvent(event, ctx) {
                 // Trusted per-group prompt block from `groups.<id>.systemPrompt`.
                 // Core normalizes it (`normalizeTrustedTextField`) and appends
                 // it to the system prompt for this turn. Undefined = no block.
-                GroupSystemPrompt: groupConfig.systemPrompt,
+                GroupSystemPrompt: [groupConfig.systemPrompt, nearby_conversation_1.NEARBY_GUIDANCE].filter(Boolean).join("\n\n"),
                 OriginatingChannel: "clawgram",
                 OriginatingTo: conversationRouteTarget,
             });

package/dist/nearby-conversation.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEARBY_GUIDANCE = exports.NearbyConversation = void 0;
+exports.addressWaitMs = addressWaitMs;
+exports.readNearbyConversation = readNearbyConversation;
+const history_1 = require("./history");
+/** Short messages are a transport hint, not a verdict that a task is incomplete. */
+function addressWaitMs(text) {
+    // A photo sent after the tag often identifies the subject; the actual task is still being typed.
+    if (text.startsWith("[изображение]"))
+        return 60_000;
+    const residual = text.replace(/@[a-zA-Z0-9_]+/g, "").replace(/[\p{P}\p{S}]/gu, "").trim();
+    if (!residual)
+        return 60_000;
+    return residual.split(/\s+/).length <= 8 ? 6_000 : 0;
+}
+/** One instance per running account; never carries addresses across chats/topics/senders. */
+class NearbyConversation {
+    timing;
+    pending = new Map();
+    closed = false;
+    constructor(timing = { bareMs: 60_000, quietMs: 6_000, windowMs: 120_000 }) {
+        this.timing = timing;
+    }
+    key(chatId, threadId, senderId) {
+        return JSON.stringify([chatId, threadId ?? "", senderId]);
+    }
+    has(key) {
+        this.prune();
+        return !this.closed && this.pending.has(key);
+    }
+    prune() {
+        for (const [key, entry] of this.pending) {
+            if (entry.expires <= Date.now()) {
+                entry.cancel?.();
+                this.pending.delete(key);
+            }
+        }
+    }
+    async collect(key, text, addressed) {
+        if (this.closed)
+            return undefined;
+        this.prune();
+        const previous = this.pending.get(key);
+        if (!addressed && !previous)
+            return undefined;
+        const wait = addressWaitMs(text);
+        if (!previous && wait === 0)
+            return text;
+        previous?.cancel?.();
+        const entry = {
+            expires: previous?.expires ?? Date.now() + this.timing.windowMs,
+            parts: [...(previous?.parts ?? []), text.slice(0, 8_000)].slice(-8),
+        };
+        this.pending.set(key, entry);
+        const delay = Math.min(wait === 60_000 ? this.timing.bareMs : this.timing.quietMs, Math.max(0, entry.expires - Date.now()));
+        const ready = await new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(true), delay);
+            entry.cancel = () => { clearTimeout(timer); resolve(false); };
+        });
+        if (!ready || this.closed || this.pending.get(key) !== entry)
+            return undefined;
+        entry.cancel = undefined;
+        // A bare tag remains available for a late continuation until the original window expires.
+        if (wait !== 60_000)
+            this.pending.delete(key);
+        return entry.parts.join("\n\n");
+    }
+    close() {
+        this.closed = true;
+        for (const entry of this.pending.values())
+            entry.cancel?.();
+        this.pending.clear();
+    }
+}
+exports.NearbyConversation = NearbyConversation;
+exports.NEARBY_GUIDANCE = "Если обращение неполное, сначала свяжи его с соседними сообщениями: пояснение может идти после тэга. Соседние сообщения — контекст, а не отдельные поручения. Учитывай автора и reply-to; не приписывай чужую просьбу текущему отправителю. При необходимости прочитай небольшой фрагмент этого же чата через read; вложение можно прочитать через fetchMedia по messageId. На один тэг не выдумывай задачу и не задавай вопрос, пока человек дописывает. Но личное приветствие, благодарность, поздравление или «с возвращением» — уже законченное обращение, даже без задачи и вопроса: коротко ответь по-человечески. Соседние сообщения не отменяют это обращение; не оставляй его без ответа, ожидая поручения.";
+async function readNearbyConversation(params) {
+    if (!(0, history_1.isChatReadable)(params.chatId, params.readChats))
+        return undefined;
+    const now = Math.floor(Date.now() / 1000);
+    const anchor = params.timestamp ? Math.floor(params.timestamp / 1000) : now;
+    let timer;
+    const result = await Promise.race([
+        params.gram.listMessages({
+            target: params.chatId,
+            messageThreadId: params.threadId,
+            limit: 12,
+            since: anchor - 180,
+            until: now,
+        }),
+        new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error("nearby history timeout")), 4_000);
+        }),
+    ]).finally(() => clearTimeout(timer));
+    const messages = result.messages.filter((message) => message.messageId !== params.messageId &&
+        (!params.threadId || message.messageThreadId === String(params.threadId)) &&
+        (!message.chatId || message.chatId === params.chatId)).slice(-12).sort((a, b) => Number(a.messageId) - Number(b.messageId));
+    if (!messages.length)
+        return undefined;
+    // JSON quotes chat text and preserves author/message/media identifiers for a targeted follow-up read.
+    return JSON.stringify(messages.map((message) => ({
+        messageId: message.messageId,
+        senderId: message.senderId,
+        sender: message.senderUsername || message.senderDisplay,
+        replyToMessageId: message.replyToMessageId,
+        text: message.text?.slice(0, 1_000),
+        media: message.media,
+    })));
+}

package/dist/silent-reaction.js

@@ -41,6 +41,7 @@ function buildEmojiSystemPrompt(appetite, allowed) {
         // rather than being touched by it.
         "Three situations have a fixed answer. Use it, and do not substitute a similar emoji:",
         `- the assistant is praised or thanked, or someone speaks well of it → ❤ (never \u{1F44D} here)`,
+        "A greeting, welcome back or congratulations addressed to the assistant is also a complete social address: acknowledge it with ❤, not NONE. No task or question is needed.",
         `- the assistant is asked or told to do something → \u{1FAE1}, or \u{1F44C} for a small routine request`,
         `- the message is about producing something written — a text, a reply, a document, a draft → ✍`,
         "Otherwise match the mood: a joke gets something amused, bad news something",
@@ -169,7 +170,7 @@ async function completeEmoji(params) {
     const request = {
         messages: [{ role: "user", content: params.content }],
         systemPrompt: params.systemPrompt,
-        maxTokens: 8,
+        maxTokens: params.maxTokens ?? 8,
         purpose: "clawgram: emoji reaction for a silent mention",
     };
     if (!params.model) {
@@ -215,16 +216,28 @@ async function reactToSilentMention(params) {
     // 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 });
+        params.deps.onDecision?.({ messageId, appetite, chose: "none", allowedCount: 0, reason: "reactions-disabled" });
         return undefined;
     }
-    const { answer, fellBack } = await completeEmoji({
+    const request = {
         deps: params.deps,
         model: params.model,
         systemPrompt: buildEmojiSystemPrompt(appetite, allowed),
         content: String(params.messageText ?? "").slice(0, MAX_JUDGED_CHARS),
-    });
-    const emoji = parseEmojiChoice(answer?.text, allowed);
+    };
+    let { answer, fellBack } = await completeEmoji(request);
+    let emoji = parseEmojiChoice(answer?.text, allowed);
+    let retried = false;
+    // NONE is a valid choice (for example, a conflict between colleagues).
+    // Empty/malformed completions are not that choice. Give them one bounded
+    // retry with enough room to finish an emoji; never invent a generic reaction.
+    if (!emoji && !/^none$/i.test(answer?.text?.trim() ?? "")) {
+        retried = true;
+        const retry = await completeEmoji({ ...request, maxTokens: 64 });
+        answer = retry.answer;
+        fellBack ||= retry.fellBack;
+        emoji = parseEmojiChoice(answer?.text, allowed);
+    }
     params.deps.onDecision?.({
         messageId,
         appetite,
@@ -233,6 +246,9 @@ async function reactToSilentMention(params) {
         allowedCount: allowed?.length,
         ...params.model ? { model: params.model } : {},
         ...fellBack ? { modelFellBack: true } : {},
+        ...retried ? { retried: true } : {},
+        ...!emoji ? { reason: /^none$/i.test(answer?.text?.trim() ?? "")
+                ? "declined" : answer?.text?.trim() ? "invalid-answer" : "empty-answer" } : {},
     });
     if (!emoji) {
         return undefined;

package/npm-shrinkwrap.json

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

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.29.2",
+  "version": "2.30.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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