clawgram 2.29.1 → 2.30.0

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/actions-read.js

@@ -132,6 +132,7 @@ async function handleReadAction(ctx) {
             ? node_path_1.default.join((0, state_dir_1.resolveStateDir)(), "tmp")
             : node_path_1.default.join(node_os_1.default.tmpdir(), `clawgram-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
         await (0, media_1.ensurePrivateDir)(mediaRoot);
+        await (0, media_1.sweepOrphanMediaDirs)(mediaRoot, Date.now());
         const sharedFetchDir = node_path_1.default.join(mediaRoot, "clawgram-fetched");
         const described = (0, media_1.describeMedia)(found.message?.media);
         // A PDF is not read here: the agent is handed the path for its PDF tool,

package/dist/attachments.js

@@ -81,6 +81,7 @@ async function readInboundAttachment(params) {
     if (!media || !message) {
         return undefined;
     }
+    await (0, media_1.sweepOrphanMediaDirs)(node_os_1.default.tmpdir(), Date.now());
     let downloaded;
     try {
         downloaded = await (0, media_1.downloadInboundMediaToTempFile)({

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/media.js

@@ -15,6 +15,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORPHAN_MEDIA_DIR_TTL_MS = void 0;
 exports.describeMedia = describeMedia;
 exports.inboundMediaUnderstanding = inboundMediaUnderstanding;
 exports.fetchMediaUnderstanding = fetchMediaUnderstanding;
@@ -23,6 +24,8 @@ exports.describePrivateDirProblem = describePrivateDirProblem;
 exports.ensurePrivateDir = ensurePrivateDir;
 exports.downloadMessageMediaToFile = downloadMessageMediaToFile;
 exports.pruneFetchedMedia = pruneFetchedMedia;
+exports.pruneOrphanMediaDirs = pruneOrphanMediaDirs;
+exports.sweepOrphanMediaDirs = sweepOrphanMediaDirs;
 exports.isLocalMediaPath = isLocalMediaPath;
 exports.assertLocalMediaWithinRoots = assertLocalMediaWithinRoots;
 exports.loadOutboundMedia = loadOutboundMedia;
@@ -167,17 +170,32 @@ async function downloadInboundMediaToTempFile(params) {
         return undefined;
     }
     const dir = await mkdtemp(join(params.tmpDir, "clawgram-media-"));
-    const downloaded = await downloadMessageMediaToFile({
-        client: params.client,
-        message: params.message,
-        maxBytes: params.maxBytes,
-        dir,
-        fileNameFor: ({ extension }) => `attachment.${extension}`,
-    });
+    // The caller removes only a path it was handed. Every other way out — an
+    // empty download, a document, a throw — removes the directory here, or it
+    // stays in the temp directory for good (audit r3 V1-10, the inbound path).
+    const discard = async () => {
+        const { rm } = await import("node:fs/promises");
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    };
+    let downloaded;
+    try {
+        downloaded = await downloadMessageMediaToFile({
+            client: params.client,
+            message: params.message,
+            maxBytes: params.maxBytes,
+            dir,
+            fileNameFor: ({ extension }) => `attachment.${extension}`,
+        });
+    }
+    catch (err) {
+        await discard();
+        throw err;
+    }
     // This path asks only for `inboundMediaUnderstanding`, so a document cannot
     // get here. Keep the runtime guard as the public downloader also serves the
     // explicit `fetch-media` action, which is allowed to request DOCX files.
     if (!downloaded || downloaded.understanding === "document" || downloaded.understanding === "pdf") {
+        await discard();
         return undefined;
     }
     return {
@@ -335,6 +353,57 @@ async function pruneFetchedMedia(dir, maxAgeMs, now) {
     }
     return removed;
 }
+/**
+ * A private `clawgram-media-*` directory lives for one call: the inbound
+ * reader and `fetch-media mode=read` remove it when they are done. One that is
+ * an hour old was left by a crash, or by a version before 2.29.1, which kept a
+ * directory on every error branch and every PDF read (audit r3 C2-02, V1-10).
+ */
+exports.ORPHAN_MEDIA_DIR_TTL_MS = 60 * 60 * 1000;
+const ORPHAN_SWEEP_EVERY_MS = 10 * 60 * 1000;
+const lastOrphanSweep = new Map();
+/** Removes `clawgram-media-*` directories in `root` older than `maxAgeMs`. */
+async function pruneOrphanMediaDirs(root, maxAgeMs, now) {
+    const { readdir, stat, rm } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.startsWith("clawgram-media-"))
+            continue;
+        const path = join(root, entry);
+        try {
+            const info = await stat(path);
+            // In a shared /tmp another account's directory fails `rm` on the
+            // sticky bit and is skipped; only our own leftovers go.
+            if (info.isDirectory() && now - info.mtimeMs > maxAgeMs) {
+                await rm(path, { recursive: true, force: true });
+                removed += 1;
+            }
+        }
+        catch {
+            // Gone already, or not ours.
+        }
+    }
+    return removed;
+}
+/**
+ * `pruneOrphanMediaDirs` at most once per ten minutes per root: it reads the
+ * whole temp directory, and it runs on the path of every inbound attachment.
+ */
+async function sweepOrphanMediaDirs(root, now) {
+    const last = lastOrphanSweep.get(root);
+    if (last !== undefined && now - last < ORPHAN_SWEEP_EVERY_MS)
+        return 0;
+    lastOrphanSweep.set(root, now);
+    return pruneOrphanMediaDirs(root, exports.ORPHAN_MEDIA_DIR_TTL_MS, now).catch(() => 0);
+}
 function extensionFor(media, understanding) {
     if (understanding === "description") {
         if (media.mimeType === "image/png")

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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clawgram",
-  "version": "2.29.1",
+  "version": "2.30.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clawgram",
-      "version": "2.29.1",
+      "version": "2.30.0",
       "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.1",
+  "version": "2.30.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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