clawgram 2.25.0 → 2.26.1

package/dist/actions-read.js

@@ -0,0 +1,394 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleReadAction = handleReadAction;
+const core_1 = require("openclaw/plugin-sdk/core");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const account_scopes_1 = require("./account-scopes");
+const attachments_1 = require("./attachments");
+const chat_info_1 = require("./chat-info");
+const dialogs_1 = require("./dialogs");
+const fetch_media_1 = require("./fetch-media");
+const history_1 = require("./history");
+const joins_1 = require("./joins");
+const media_1 = require("./media");
+const state_dir_1 = require("./state-dir");
+const topics_1 = require("./topics");
+/**
+ * The read-shaped actions: `read`, `fetch-media`, `participants`, `topics`,
+ * `dialogs`, `joins`, `chatInfo`.
+ *
+ * Cut out of `handleAction` in `channel.ts` unchanged — same gates, same log
+ * lines, same answers; the probe in `scripts/verify/action-probe.cjs` is the
+ * proof (audit B5-13, part 3). Answers `undefined` for any other action.
+ */
+const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
+// Час, а не сутки: `fetch-media` существует ради «прочитать и переслать», и
+// файл нужен ровно на время хода. Сутки означали сутки чужой личной переписки
+// на диске (A5-13).
+const FETCHED_MEDIA_TTL_MS = 60 * 60 * 1000;
+async function handleReadAction(ctx) {
+    const { canonical, params, cfg, accountId, toolContext, pluginRuntime, resolveRuntimeAccountId, requireRuntimeFor } = ctx;
+    // `read` is what OpenClaw core dispatches (`openclaw message read`,
+    // MCP `messages_read`); `list` resolves to it too.
+    if (canonical === "read") {
+        const listParams = (0, history_1.parseListMessagesParams)(params);
+        const listAccountId = resolveRuntimeAccountId(cfg, accountId);
+        if (!listAccountId) {
+            throw new Error("clawgram: no configured account found");
+        }
+        // Reading is not a side effect, so a dry run still answers — reporting
+        // an empty window would look like a quiet chat rather than a no-op.
+        if (!(0, history_1.isChatReadable)(listParams.target, (0, account_scopes_1.resolveAccountReadChats)(cfg, listAccountId))) {
+            actionLog.warn("clawgram list refused: chat outside read scope", {
+                accountId: listAccountId,
+                target: listParams.target,
+            });
+            throw new Error(`clawgram: not-allowed-chat ${listParams.target}`);
+        }
+        const listGram = requireRuntimeFor(listAccountId);
+        const history = await listGram.listMessages(listParams);
+        // Metadata only. Message text is the user's correspondence and has no
+        // business in a log that is read while debugging something else.
+        actionLog.info("clawgram handleAction list completed", {
+            accountId: listAccountId,
+            target: listParams.target,
+            limit: listParams.limit,
+            since: listParams.since ?? null,
+            until: listParams.until ?? null,
+            returned: history.messages.length,
+            truncated: history.truncated,
+        });
+        return (0, core_1.jsonResult)({
+            ok: true,
+            accountId: listAccountId,
+            chatId: history.chatId ?? listParams.target,
+            count: history.messages.length,
+            truncated: history.truncated,
+            messages: history.messages,
+        });
+    }
+    // The attachment on a message that is already in a chat.
+    //
+    // `read` says a photo exists; it does not fetch it, and the inbound
+    // path only ever reads what arrives while the agent is being addressed.
+    // Everything else — a screenshot posted an hour ago, a diagram in a
+    // chat the agent reads but was not tagged in — was visible to the
+    // channel and unreachable to the agent. Same `readChats` scope as
+    // history: this must not become a way to pull bytes out of a chat the
+    // account was never allowed to read.
+    if (canonical === "fetch-media") {
+        const fetchParams = (0, fetch_media_1.parseFetchMediaParams)(params);
+        const fetchAccountId = resolveRuntimeAccountId(cfg, accountId);
+        if (!fetchAccountId) {
+            throw new Error("clawgram: no configured account found");
+        }
+        if (!(0, history_1.isChatReadable)(fetchParams.target, (0, account_scopes_1.resolveAccountReadChats)(cfg, fetchAccountId))) {
+            actionLog.warn("clawgram fetch-media refused: chat outside read scope", {
+                accountId: fetchAccountId,
+                target: fetchParams.target,
+            });
+            throw new Error(`clawgram: not-allowed-chat ${fetchParams.target}`);
+        }
+        const fetchGram = requireRuntimeFor(fetchAccountId);
+        // Fetching is a read: a dry run answers for real, the same way `read`
+        // does. Nothing leaves the machine — the file lands in a temp
+        // directory this channel prunes — so a rehearsal that reported
+        // "would fetch" would only teach the agent to ask twice.
+        const found = await fetchGram.getMessageById(fetchParams.target, fetchParams.messageId);
+        const fetchChatId = found.chatId ?? fetchParams.target;
+        if (!found.message) {
+            actionLog.info("clawgram fetch-media found no message", {
+                accountId: fetchAccountId,
+                chatId: fetchChatId,
+                messageId: fetchParams.messageId,
+            });
+            return (0, core_1.jsonResult)({
+                ok: false,
+                accountId: fetchAccountId,
+                chatId: fetchChatId,
+                messageId: String(fetchParams.messageId),
+                error: "message-not-found",
+            });
+        }
+        // `read` throws the file away, so it gets a directory of its own —
+        // the shared directory is keyed by chat and message, and deleting
+        // that path would pull the file out from under an earlier `both`
+        // fetch of the same message that handed the caller a path.
+        // Не общий /tmp: там файлы видит каждый локальный пользователь, а на
+        // этом хосте живёт ещё и раннер деплоя. Каталог состояния OpenClaw
+        // принадлежит агенту; если он не задан, остаётся /tmp — но права
+        // 0700/0600 ставятся в любом случае (A5-13).
+        // Каталог состояния принадлежит агенту; при явно заданном
+        // OPENCLAW_STATE_DIR вложения не покидают его.
+        const mediaRoot = process.env.OPENCLAW_STATE_DIR?.trim()
+            ? node_path_1.default.join((0, state_dir_1.resolveStateDir)(), "tmp")
+            : node_os_1.default.tmpdir();
+        const sharedFetchDir = node_path_1.default.join(mediaRoot, "clawgram-fetched");
+        let fetchDir = sharedFetchDir;
+        if (fetchParams.mode === "read") {
+            const { mkdtemp, mkdir } = await import("node:fs/promises");
+            await mkdir(mediaRoot, { recursive: true, mode: 0o700 });
+            fetchDir = await mkdtemp(node_path_1.default.join(mediaRoot, "clawgram-media-"));
+        }
+        else {
+            await (0, media_1.pruneFetchedMedia)(sharedFetchDir, FETCHED_MEDIA_TTL_MS, Date.now());
+        }
+        const downloaded = await (0, media_1.downloadMessageMediaToFile)({
+            client: fetchGram.getClient(),
+            message: found.message,
+            maxBytes: attachments_1.INBOUND_MEDIA_MAX_BYTES,
+            dir: fetchDir,
+            fileNameFor: ({ media, extension }) => (0, fetch_media_1.fetchedMediaFileName)({
+                chatId: fetchChatId,
+                messageId: fetchParams.messageId,
+                extension,
+                fileName: media.fileName,
+            }),
+        });
+        if (!downloaded) {
+            // Three different nothings, and the agent has to be able to tell
+            // them apart: a message with no attachment, an attachment this
+            // channel does not read (a video, a spreadsheet), and one too
+            // large to be worth the transfer. Saying "could not fetch" to all
+            // three is how "she ignored the picture" starts.
+            const described = (0, media_1.describeMedia)(found.message?.media);
+            const tooLarge = typeof described?.size === "number" && described.size > attachments_1.INBOUND_MEDIA_MAX_BYTES;
+            const error = !described
+                ? "no-media"
+                : tooLarge
+                    ? "media-too-large"
+                    : "unsupported-media";
+            actionLog.info("clawgram fetch-media returned nothing", {
+                accountId: fetchAccountId,
+                chatId: fetchChatId,
+                messageId: fetchParams.messageId,
+                kind: described?.kind ?? null,
+                error,
+            });
+            return (0, core_1.jsonResult)({
+                ok: false,
+                accountId: fetchAccountId,
+                chatId: fetchChatId,
+                messageId: String(fetchParams.messageId),
+                media: described ?? null,
+                error,
+            });
+        }
+        let read;
+        let readError;
+        if (fetchParams.mode !== "file") {
+            try {
+                read = await (0, attachments_1.understandAttachmentFile)({
+                    runtime: pluginRuntime,
+                    cfg,
+                    filePath: downloaded.path,
+                    mimeType: downloaded.mimeType,
+                    understanding: downloaded.understanding,
+                });
+                if (!read) {
+                    readError = "read-empty";
+                }
+            }
+            catch (err) {
+                // The bytes are already here. A failed reading is worth
+                // reporting, but it does not undo a successful fetch: the file
+                // still exists and can still be forwarded.
+                readError = String(err);
+            }
+        }
+        // `read` mode is the inbound contract — the words, not the file — so
+        // the bytes go away with the answer. Any other mode keeps them:
+        // that is the whole point of asking for a path.
+        if (fetchParams.mode === "read") {
+            try {
+                const { rm } = await import("node:fs/promises");
+                await rm(fetchDir, { recursive: true, force: true });
+            }
+            catch {
+                // A file left behind is pruned within a day; failing the call
+                // over it would throw away a reading that already succeeded.
+            }
+        }
+        actionLog.info("clawgram fetch-media completed", {
+            accountId: fetchAccountId,
+            chatId: fetchChatId,
+            messageId: fetchParams.messageId,
+            mode: fetchParams.mode,
+            kind: downloaded.media.kind,
+            understanding: downloaded.understanding,
+            characters: read?.length ?? 0,
+            readError: readError ?? null,
+        });
+        return (0, core_1.jsonResult)({
+            ok: true,
+            accountId: fetchAccountId,
+            chatId: fetchChatId,
+            messageId: String(fetchParams.messageId),
+            mode: fetchParams.mode,
+            media: downloaded.media,
+            understanding: downloaded.understanding,
+            filePath: fetchParams.mode === "read" ? undefined : downloaded.path,
+            text: read,
+            readError,
+        });
+    }
+    /**
+     * The scaffold every chat-shaped read shares.
+     *
+     * `participants`, `topics`, `dialogs`, `joins` and `chatInfo` each
+     * spelled out the same sequence: parse, resolve the account, check a
+     * scope, fetch the runtime, call it, log counts, answer. Roughly
+     * forty lines apiece, differing in four places — which is how a new
+     * action came to cost sixty lines of scaffold and how the two gates
+     * drifted apart (finding A6-11).
+     *
+     * The gate follows from the shape rather than being restated: an
+     * action that names a chat is gated by `readChats`, `dialogs` has its
+     * own discovery gate precisely because its point is to find chats
+     * that are not in scope yet, and `joins` has none — the journal only
+     * ever holds chats this account was put into.
+     *
+     * The runtime is a getter, not a value: `joins` reads a file and must
+     * not fail merely because no runtime is connected.
+     */
+    const runRead = async (spec) => {
+        const parsed = spec.parse();
+        const readAccountId = resolveRuntimeAccountId(cfg, accountId);
+        if (!readAccountId) {
+            throw new Error("clawgram: no configured account found");
+        }
+        const target = spec.target?.(parsed);
+        if (target !== undefined) {
+            if (!(0, history_1.isChatReadable)(target, (0, account_scopes_1.resolveAccountReadChats)(cfg, readAccountId))) {
+                actionLog.warn(`clawgram ${spec.name} refused: chat outside read scope`, {
+                    accountId: readAccountId,
+                    target,
+                });
+                throw new Error(`clawgram: not-allowed-chat ${target}`);
+            }
+        }
+        else if (spec.discovery) {
+            if (!(0, dialogs_1.isChatDiscoveryEnabled)((0, account_scopes_1.resolveAccountDiscoverChats)(cfg, readAccountId))) {
+                actionLog.warn(`clawgram ${spec.name} refused: chat-discovery is not enabled`, {
+                    accountId: readAccountId,
+                });
+                throw new Error("clawgram: chat-discovery is not enabled");
+            }
+        }
+        const gram = () => requireRuntimeFor(readAccountId);
+        const result = await spec.run({ parsed, accountId: readAccountId, gram });
+        actionLog.info(`clawgram handleAction ${spec.name} completed`, {
+            accountId: readAccountId,
+            ...spec.after(parsed, result),
+        });
+        return (0, core_1.jsonResult)({ ok: true, accountId: readAccountId, ...spec.result(parsed, result) });
+    };
+    // Membership is a read, so the same `readChats` scope that gates history
+    // gates it too: this cannot become a way to enumerate chats the account
+    // was never allowed to read.
+    if (canonical === "participants") {
+        return await runRead({
+            name: "participants",
+            parse: () => (0, history_1.parseListParticipantsParams)(params),
+            target: (p) => p.target,
+            run: ({ parsed, gram }) => gram().listParticipants(parsed),
+            // Counts only. Member ids are personal data and have no business in
+            // a log that is read while debugging something else.
+            after: (p, m) => ({
+                target: p.target,
+                limit: p.limit,
+                returned: m.participants.length,
+                truncated: m.truncated,
+            }),
+            result: (p, m) => ({
+                chatId: m.chatId ?? p.target,
+                count: m.participants.length,
+                truncated: m.truncated,
+                participants: m.participants,
+            }),
+        });
+    }
+    // Topic names. A forum chat is addressed by topic id, and until now an
+    // id could only be lifted off an inbound message — so a topic nobody had
+    // written in yet was unreachable, and one named in words was unfindable.
+    // Titles say what a chat is working on, so the read scope gates them.
+    if (canonical === "topics") {
+        return await runRead({
+            name: "topics",
+            parse: () => (0, topics_1.parseTopicsParams)(params),
+            target: (p) => p.target,
+            run: ({ parsed, gram }) => gram().listTopics(parsed),
+            after: (p, f) => ({
+                target: p.target,
+                limit: p.limit,
+                returned: f.topics.length,
+                truncated: f.truncated,
+            }),
+            result: (p, f) => ({
+                chatId: f.chatId ?? p.target,
+                count: f.topics.length,
+                truncated: f.truncated,
+                topics: f.topics,
+            }),
+        });
+    }
+    // Which chats this account is in. Not gated by `readChats` — the whole
+    // point is to find chats that are not in it yet — so it has a gate of
+    // its own, is metadata only, and never reports direct chats.
+    if (canonical === "dialogs") {
+        return await runRead({
+            name: "dialogs",
+            parse: () => (0, dialogs_1.parseDialogsParams)(params),
+            discovery: true,
+            run: ({ parsed, gram }) => gram().listDialogs(parsed),
+            // Counts only: which chats a person's account sits in is exactly
+            // the kind of thing that should not be sitting in a log.
+            after: (p, f) => ({ limit: p.limit, returned: f.dialogs.length, truncated: f.truncated }),
+            result: (_p, f) => ({ count: f.dialogs.length, truncated: f.truncated, dialogs: f.dialogs }),
+        });
+    }
+    // Where this account was recently added, and by whom. Reading the journal
+    // has no scope check of its own: it only ever contains chats this account
+    // was put into, which is exactly what the caller is allowed to learn.
+    if (canonical === "joins") {
+        return await runRead({
+            name: "joins",
+            parse: () => (0, joins_1.parseJoinsParams)(params),
+            // No runtime: this reads a file, and must answer with none connected.
+            run: async ({ parsed, accountId: joinsAccountId }) => (0, joins_1.selectJoinRecords)((0, joins_1.readJoinRecords)((0, joins_1.resolveJoinsJournalPath)(cfg?.channels?.["clawgram"]?.accounts?.[joinsAccountId], joinsAccountId)), parsed),
+            after: (p, selected) => ({
+                since: p.since ?? null,
+                limit: p.limit,
+                returned: selected.length,
+            }),
+            result: (_p, selected) => ({ count: selected.length, joins: selected }),
+        });
+    }
+    // Describing a chat is a read, so the same `readChats` scope that gates
+    // history gates it too — this must not become a way to learn the title
+    // and size of a chat the account was never allowed to read.
+    if (canonical === "chatInfo") {
+        return await runRead({
+            name: "chatInfo",
+            parse: () => (0, chat_info_1.parseChatInfoParams)(params, toolContext),
+            target: (p) => p.target,
+            run: async ({ parsed, gram }) => {
+                const { entity, full } = await gram().getChatInfo(parsed.target);
+                return (0, chat_info_1.describeChat)(entity, full);
+            },
+            // Type and size only. The title of a private chat is as personal as
+            // its contents and has no business in a debugging log.
+            after: (_p, info) => ({
+                type: info.type,
+                memberCount: info.memberCount ?? null,
+                isForum: info.isForum ?? null,
+            }),
+            result: (p, info) => ({ chat: { ...info, chatId: info.chatId ?? p.target } }),
+        });
+    }
+    return undefined;
+}