clawgram 2.26.0 → 2.27.0

package/dist/account-scopes.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAccountReadChats = readAccountReadChats;
+exports.resolveAccountReadChats = resolveAccountReadChats;
+exports.resolveAccountSendChats = resolveAccountSendChats;
+exports.refuseOutboundOutsideScope = refuseOutboundOutsideScope;
+exports.resolveAccountOperatorIds = resolveAccountOperatorIds;
+exports.resolveAccountDiscoverChats = resolveAccountDiscoverChats;
+exports.resolveAccountManageChats = resolveAccountManageChats;
+exports.readAccountManageChats = readAccountManageChats;
+const core_1 = require("openclaw/plugin-sdk/core");
+const history_1 = require("./history");
+const send_scope_1 = require("./send-scope");
+/**
+ * Per-account scope as configured — the readers every action module shares.
+ *
+ * Lived at the top of `channel.ts` next to the dispatcher that used them;
+ * moved out with the dispatcher's branches (audit B5-13, part 3). Pure
+ * config readers: no runtime, no state.
+ */
+const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
+/**
+ * Read scope as configured for the account. Left `undefined` when the key is
+ * absent so `isChatReadable` can tell "not configured" from "configured empty" —
+ * the first means no restriction, the second denies everything.
+ */
+function readAccountReadChats(account) {
+    return (0, history_1.normalizeScopeList)(account?.readChats);
+}
+function resolveAccountReadChats(cfg, accountId) {
+    return readAccountReadChats(cfg?.channels?.["clawgram"]?.accounts?.[accountId]);
+}
+/**
+ * Outbound scope as configured. Handed to `isChatSendable` raw: an absent
+ * value means "unrestricted" and an empty list means "deny", and only the
+ * raw value tells those apart — same shape as `readChats`.
+ */
+function resolveAccountSendChats(cfg, accountId) {
+    return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.sendChats;
+}
+/** One refusal for every outbound action, so the three read the same. */
+function refuseOutboundOutsideScope(action, accountId, target) {
+    const refusal = (0, send_scope_1.describeSendRefusal)(target);
+    actionLog.warn(`clawgram ${action} refused: ${refusal.reason}`, { accountId, ...refusal.logFields });
+    throw refusal.error;
+}
+/**
+ * Who receives core's operational telemetry in a DM.
+ */
+function resolveAccountOperatorIds(cfg, accountId) {
+    const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
+    // Только явный список. Умолчание «operatorIds = allowFrom» делало
+    // оператором каждого допущенного собеседника — и телеметрию с путями
+    // secret-store получал любой из них (D2-03, A5-11). Не назван — не
+    // назван: уведомления подавляются везде.
+    const raw = account?.operatorIds;
+    if (raw === undefined || raw === null)
+        return [];
+    const entries = Array.isArray(raw) ? raw : [raw];
+    return entries.map((entry) => String(entry).trim()).filter(Boolean);
+}
+function resolveAccountDiscoverChats(cfg, accountId) {
+    return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.discoverChats;
+}
+/**
+ * Management scope as configured. Handed to `isChatManageable` raw: unlike
+ * `readChats`, an absent value already means "deny", so there is nothing to
+ * tell apart — but the raw value keeps the two gates symmetrical.
+ */
+function resolveAccountManageChats(cfg, accountId) {
+    return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.manageChats;
+}
+/** Same normalization `readChats` gets, for the resolved-account copy. */
+function readAccountManageChats(account) {
+    return (0, history_1.normalizeScopeList)(account?.manageChats);
+}

package/dist/action-context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions-manage.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleManageAction = handleManageAction;
+const core_1 = require("openclaw/plugin-sdk/core");
+const account_scopes_1 = require("./account-scopes");
+const actions_1 = require("./actions");
+const manage_1 = require("./manage");
+/**
+ * The chat-management actions, gated by `manageChats`.
+ *
+ * Cut out of `handleAction` in `channel.ts` unchanged (audit B5-13, part 3);
+ * the probe is the proof. Answers `undefined` for any other action.
+ */
+const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
+async function handleManageAction(ctx) {
+    const { canonical, params, cfg, accountId, dryRun, toolContext, resolveRuntimeAccountId, requireRuntimeFor } = ctx;
+    // ---- Chat management (2.12.0) ----
+    //
+    // Assembling a chat rather than speaking in it: create a supergroup,
+    // add and remove people, appoint admins, hand the chat over, issue an
+    // invite link. All of it is possible only because this is a personal
+    // MTProto account — a bot could do almost none of this.
+    //
+    // Every branch is gated by the account's `manageChats` scope, which is
+    // opt-in (absent = deny, see manage.ts) — these are the first actions
+    // that change a chat rather than write into it. Parsing runs before
+    // the gate so a malformed call fails on its own shape, and `dryRun`
+    // returns after the gate so a dry run exercises the same refusals a
+    // real call would hit. People's ids stay out of the logs throughout;
+    // the JSON result carries them to the caller, the journal does not.
+    const manageAction = actions_1.MANAGE_ACTIONS.has(canonical) ? canonical : undefined;
+    if (manageAction) {
+        const manageAccountId = resolveRuntimeAccountId(cfg, accountId);
+        if (!manageAccountId) {
+            throw new Error("clawgram: no configured account found");
+        }
+        const manageScope = (0, account_scopes_1.resolveAccountManageChats)(cfg, manageAccountId);
+        const requireRuntime = () => requireRuntimeFor(manageAccountId);
+        /**
+         * The scaffold every management action shares.
+         *
+         * Six actions used to spell it out one after another: resolve the
+         * account, check the scope, log, answer a dry run, call the
+         * runtime, log again, build the result. A change to any of those —
+         * the dry-run contract, say — was a six-place edit in the plugin's
+         * largest file, and the one deliberate exception (createGroup does
+         * not check a chat scope, because the chat does not exist yet) was
+         * invisible among the copies (finding A12-06).
+         *
+         * The differences stay written at each call site: what to parse,
+         * what to log, what to run, what to answer. Only the scaffold moved.
+         */
+        const runManage = async (spec) => {
+            const parsed = spec.parse();
+            const target = spec.target(parsed);
+            if (target === undefined) {
+                // Nothing to check a scope against yet, so the gate is coarser:
+                // management must be enabled at all for this account.
+                if (!(0, manage_1.isManagementEnabled)(manageScope)) {
+                    actionLog.warn(`clawgram ${spec.name} refused: management is not enabled`, {
+                        accountId: manageAccountId,
+                    });
+                    throw new Error("clawgram: chat management is not enabled for this account — "
+                        + `set channels.clawgram.accounts.${manageAccountId}.manageChats`);
+                }
+            }
+            else if (!(0, manage_1.isChatManageable)(target, manageScope)) {
+                actionLog.warn("clawgram management refused: chat outside manage scope", {
+                    accountId: manageAccountId,
+                    action: manageAction,
+                    target,
+                });
+                throw new Error(`clawgram: not-managed-chat ${target}`);
+            }
+            actionLog.info(`clawgram handleAction ${spec.name}`, {
+                accountId: manageAccountId,
+                dryRun: dryRun === true,
+                ...spec.before(parsed),
+            });
+            if (dryRun === true) {
+                return (0, core_1.jsonResult)({
+                    ok: true,
+                    dryRun: true,
+                    accountId: manageAccountId,
+                    ...(target === undefined ? {} : { chatId: target }),
+                });
+            }
+            const gram = requireRuntime();
+            spec.precondition?.(gram);
+            const result = await spec.run(gram, parsed);
+            actionLog.info(`clawgram handleAction ${spec.name} completed`, {
+                accountId: manageAccountId,
+                ...spec.after(parsed, result),
+            });
+            return (0, core_1.jsonResult)({ ok: true, accountId: manageAccountId, ...spec.result(parsed, result) });
+        };
+        if (manageAction === "createGroup") {
+            return await runManage({
+                name: "createGroup",
+                parse: () => (0, manage_1.parseCreateGroupParams)(params),
+                // A group being created is not in any scope yet.
+                target: () => undefined,
+                before: (p) => ({ users: p.users.length, hasAbout: Boolean(p.about) }),
+                run: (gram, p) => gram.createGroup(p),
+                after: (_p, created) => ({ chatId: created.chatId ?? null, missing: created.missing.length }),
+                result: (_p, created) => ({ chatId: created.chatId, missing: created.missing }),
+            });
+        }
+        if (manageAction === "addMembers") {
+            return await runManage({
+                name: "addMembers",
+                parse: () => (0, manage_1.parseAddMembersParams)(params, toolContext),
+                target: (p) => p.target,
+                before: (p) => ({ target: p.target, users: p.users.length }),
+                run: (gram, p) => gram.addChatMembers(p),
+                after: (p, added) => ({
+                    target: p.target,
+                    requested: p.users.length,
+                    missing: added.missing.length,
+                }),
+                result: (p, added) => ({
+                    chatId: added.chatId ?? p.target,
+                    requested: p.users.length,
+                    // Telegram refuses silently-restricted invites per user; the
+                    // caller gets the ids so it can hand them an invite link.
+                    missing: added.missing,
+                }),
+            });
+        }
+        if (manageAction === "removeMember") {
+            return await runManage({
+                name: "removeMember",
+                parse: () => (0, manage_1.parseRemoveMemberParams)(params, toolContext),
+                target: (p) => p.target,
+                before: (p) => ({ target: p.target, ban: p.ban }),
+                run: (gram, p) => gram.removeChatMember(p),
+                after: (p) => ({ target: p.target, ban: p.ban }),
+                result: (p) => ({ chatId: p.target, user: p.user, banned: p.ban }),
+            });
+        }
+        if (manageAction === "promoteAdmin" || manageAction === "demoteAdmin") {
+            const promote = manageAction === "promoteAdmin";
+            return await runManage({
+                // Both spellings log as `setAdmin`, as they always have.
+                name: "setAdmin",
+                parse: () => (promote
+                    ? (0, manage_1.parsePromoteAdminParams)(params, toolContext)
+                    : (0, manage_1.parseDemoteAdminParams)(params, toolContext)),
+                target: (p) => p.target,
+                before: (p) => ({ target: p.target, isAdmin: p.isAdmin, hasRank: Boolean(p.rank) }),
+                run: (gram, p) => gram.setChatAdmin(p),
+                after: (p) => ({ target: p.target, isAdmin: p.isAdmin }),
+                result: (p) => ({
+                    chatId: p.target,
+                    user: p.user,
+                    isAdmin: p.isAdmin,
+                    ...(p.rank ? { rank: p.rank } : {}),
+                }),
+            });
+        }
+        if (manageAction === "transferOwnership") {
+            return await runManage({
+                name: "transferOwnership",
+                parse: () => (0, manage_1.parseTransferOwnershipParams)(params, toolContext),
+                target: (p) => p.target,
+                before: (p) => ({ target: p.target }),
+                // The password stays inside the runtime: it is read from the
+                // account config at start-up and never travels through dispatch
+                // arguments, which are one log call away from the journal.
+                precondition: (gram) => {
+                    if (!gram.twoFaPassword) {
+                        throw new Error("clawgram: ownership transfer requires twoFaPassword in the account config "
+                            + "(the account's Telegram 2FA password, as a literal or a SecretRef)");
+                    }
+                },
+                run: (gram, p) => gram.transferChatOwnership(p),
+                after: (p) => ({ target: p.target }),
+                result: (p) => ({ chatId: p.target, newOwner: p.user }),
+            });
+        }
+        // inviteLink — the only management action left.
+        return await runManage({
+            name: "inviteLink",
+            parse: () => (0, manage_1.parseInviteLinkParams)(params, toolContext),
+            target: (p) => p.target,
+            before: (p) => ({
+                target: p.target,
+                hasExpiry: p.expireDate !== undefined,
+                usageLimit: p.usageLimit ?? null,
+                requestNeeded: p.requestNeeded,
+            }),
+            run: (gram, p) => gram.exportChatInviteLink(p),
+            after: (p, exported) => ({ target: p.target, hasLink: Boolean(exported.link) }),
+            result: (p, exported) => ({ chatId: p.target, link: exported.link }),
+        });
+    }
+    return undefined;
+}

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;
+}