clawgram 2.21.1 → 2.23.0

package/dist/channel.js

@@ -3,15 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createChannelPlugin = exports.CORE_ACTION_SYNONYMS = void 0;
+exports.createChannelPlugin = exports.canonicalAction = exports.CORE_ACTION_SYNONYMS = void 0;
 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 node_fs_1 = require("node:fs");
-/** Attachments above this are left unread: a long recording or a huge image is
- *  a different conversation from a spoken line or a screenshot, and the
- *  transfer is not free. */
-const INBOUND_MEDIA_MAX_BYTES = 25 * 1024 * 1024;
 /**
  * How long a file fetched by `fetch-media` stays on disk.
  *
@@ -20,7 +15,10 @@ const INBOUND_MEDIA_MAX_BYTES = 25 * 1024 * 1024;
  * that a chat full of images does not silently become a copy of itself in the
  * temp directory.
  */
-const FETCHED_MEDIA_TTL_MS = 24 * 60 * 60 * 1000;
+// Час, а не сутки: `fetch-media` существует ради «прочитать и переслать», и
+// файл нужен ровно на время хода. Сутки означали сутки чужой личной переписки
+// на диске (A5-13).
+const FETCHED_MEDIA_TTL_MS = 60 * 60 * 1000;
 /**
  * What this channel promises the Gateway.
  *
@@ -67,11 +65,13 @@ const constants_1 = require("./constants");
 const gramjs_client_1 = require("./gramjs-client");
 const normalize_1 = require("./normalize");
 const history_1 = require("./history");
+const send_scope_1 = require("./send-scope");
 const joins_1 = require("./joins");
 const reactions_1 = require("./reactions");
 const manage_1 = require("./manage");
 const silent_reaction_1 = require("./silent-reaction");
 const system_notice_1 = require("./system-notice");
+const state_dir_1 = require("./state-dir");
 const chat_info_1 = require("./chat-info");
 const topics_1 = require("./topics");
 const dialogs_1 = require("./dialogs");
@@ -159,12 +159,71 @@ function readAccountReadChats(account) {
 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`.
+ */
+/**
+ * Хэндл в `allowFrom` — обещание, которое Telegram не держит.
+ *
+ * Запись `@username` утверждает не про человека, а про хэндл: хэндл можно
+ * освободить, и тогда его берёт кто угодно — запись начинает пускать
+ * постороннего, ничего об этом не сказав. Числовой id так не переходит из рук
+ * в руки. Отказываться от хэндлов нельзя (люди пишут ими, и конфиг у многих
+ * уже такой), но молчать об этом тоже не годится — поэтому предупреждение
+ * один раз при старте аккаунта (находка A5-16).
+ */
+function warnAboutHandleAllowlistEntries(cfg, accountId) {
+    const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
+    const entries = Array.isArray(account?.allowFrom) ? account.allowFrom : [];
+    const handles = entries
+        .map((entry) => String(entry ?? "").trim())
+        .filter((entry) => entry.startsWith("@"));
+    if (handles.length === 0) {
+        return;
+    }
+    actionLog.warn("clawgram allowFrom names handles, not ids", {
+        accountId,
+        // Сами хэндлы — это про людей: в лог уходит только их число.
+        handleEntries: handles.length,
+        why: "a released handle can be taken by someone else; numeric ids do not change hands",
+    });
+}
+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 reason = (0, send_scope_1.isPhoneNumberTarget)(target) ? "phone-number target" : "chat outside send scope";
+    actionLog.warn(`clawgram ${action} refused: ${reason}`, { accountId, target });
+    throw new Error(`clawgram: not-allowed-chat ${target}`);
+}
 /**
  * Management scope as configured. Handed to `isChatManageable` raw: unlike
  * `readChats`, an absent value already means "deny", so there is nothing to
  * tell apart here.
  */
 /** Chat discovery as configured; absent means "deny", like management scope. */
+/**
+ * Кому уходит операционная телеметрия ядра в личке.
+ *
+ * `operatorIds` — если задан. Иначе `allowFrom`, но только когда это
+ * конкретный список: со звёздочкой он означает «пишет кто угодно», и слать
+ * туда пути secret-store нельзя (A5-11). Пустой результат означает «оператор
+ * не назван», и уведомление подавляется везде.
+ *
+ * Запоминается при старте аккаунта — см. реестр в system-notice.ts.
+ */
+function resolveAccountOperatorIds(cfg, accountId) {
+    const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
+    const explicit = account?.operatorIds;
+    const raw = explicit !== undefined && explicit !== null ? explicit : account?.allowFrom;
+    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;
 }
@@ -179,88 +238,10 @@ function readAccountManageChats(account) {
     const entries = Array.isArray(raw) ? raw : [raw];
     return entries.map((entry) => String(entry).trim()).filter(Boolean);
 }
-/**
- * Core's own name for a clawgram action, and the only thing that makes the
- * action reachable from the agent's `message` tool.
- *
- * Core keys its target policy by `CHANNEL_MESSAGE_ACTION_NAMES`, and an action
- * outside that vocabulary is simultaneously "requires a target" and "does not
- * accept a target" — there is no call that satisfies both. Declaring `chatId`
- * through `messageActionTargetAliases` looks like the fix and is not: core
- * resolves the channel with `getBootstrapChannelPlugin`, which only knows
- * bundled channels, so a plugin channel's declaration is never read. Measured
- * on 2026-08-30 — `thread-list` reached `handleAction` and `topics` did not,
- * from the same caller, on the same chat.
- *
- * Every name on the right maps to core target mode `"none"` except
- * `channel-info`, which is `"channelId"`: the chat arrives in
- * `params.channelId`, a spelling no parser here read until 2.21.0 — so the
- * call fell through to the current chat and answered about the wrong one.
- * `readChatTargetParam` is the single list of accepted spellings now.
- */
-exports.CORE_ACTION_SYNONYMS = {
-    "thread-list": "topics",
-    "channel-list": "dialogs",
-    "channel-info": "chatInfo",
-    "member-info": "participants",
-    "download-file": "fetch-media",
-    // Chat management. `kick` was already accepted; the rest were advertised
-    // under names core does not know and were therefore never callable from the
-    // tool at all — 2.19.4 gives them core's nearest name. `transferOwnership`
-    // and `inviteLink` have no counterpart in that vocabulary and stay
-    // gateway-only, as does `joins`.
-    "channel-create": "createGroup",
-    addParticipant: "addMembers",
-    kick: "removeMember",
-    "role-add": "promoteAdmin",
-    "role-remove": "demoteAdmin",
-};
-/** Canonical management action for every accepted spelling. */
-const MANAGE_ACTION_ALIASES = {
-    // Core's spellings first — these are the only ones the agent's tool can
-    // reach; see CORE_ACTION_SYNONYMS.
-    "channel-create": "createGroup",
-    addParticipant: "addMembers",
-    "role-add": "promoteAdmin",
-    "role-remove": "demoteAdmin",
-    createGroup: "createGroup",
-    createChat: "createGroup",
-    "create-group": "createGroup",
-    addMembers: "addMembers",
-    addMember: "addMembers",
-    "add-members": "addMembers",
-    removeMember: "removeMember",
-    removeMembers: "removeMember",
-    "remove-member": "removeMember",
-    kick: "removeMember",
-    promoteAdmin: "promoteAdmin",
-    promote: "promoteAdmin",
-    "promote-admin": "promoteAdmin",
-    setAdmin: "promoteAdmin",
-    demoteAdmin: "demoteAdmin",
-    demote: "demoteAdmin",
-    "demote-admin": "demoteAdmin",
-    transferOwnership: "transferOwnership",
-    transferOwner: "transferOwnership",
-    "transfer-ownership": "transferOwnership",
-    inviteLink: "inviteLink",
-    exportInviteLink: "inviteLink",
-    "invite-link": "inviteLink",
-};
-function parseOptionalThreadId(value) {
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? Math.trunc(value) : undefined;
-    }
-    if (typeof value !== "string") {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (!trimmed || !/^\d+$/.test(trimmed)) {
-        return undefined;
-    }
-    const parsed = Number.parseInt(trimmed, 10);
-    return Number.isFinite(parsed) ? parsed : undefined;
-}
+const actions_1 = require("./actions");
+Object.defineProperty(exports, "CORE_ACTION_SYNONYMS", { enumerable: true, get: function () { return actions_1.CORE_ACTION_SYNONYMS; } });
+Object.defineProperty(exports, "canonicalAction", { enumerable: true, get: function () { return actions_1.canonicalAction; } });
+const outbound_1 = require("./outbound");
 /**
  * Turns an inbound attachment into text the agent can read.
  *
@@ -274,128 +255,7 @@ function parseOptionalThreadId(value) {
  * "you sent something I could not read" than staying silent, which is
  * indistinguishable from being offline.
  */
-/**
- * Locates the agent directory that image understanding needs.
- *
- * Image models are called with the agent's own credentials, so the pipeline
- * refuses to run without this path — audio does not need it, which is why
- * voice notes worked before images did. The platform exposes no resolver to
- * plugins, so the documented layout is reconstructed here and checked before
- * use: a wrong guess would fail the read anyway, and returning undefined lets
- * the caller degrade instead of throwing.
- */
-function resolveAgentDirForMedia(cfg) {
-    const stateDir = typeof process.env.OPENCLAW_STATE_DIR === "string" && process.env.OPENCLAW_STATE_DIR.trim()
-        ? process.env.OPENCLAW_STATE_DIR.trim()
-        : node_path_1.default.join(node_os_1.default.homedir(), ".openclaw");
-    const configuredId = cfg?.agents?.defaults?.id;
-    const agentId = typeof configuredId === "string" && configuredId.trim() ? configuredId.trim() : "main";
-    const dir = node_path_1.default.join(stateDir, "agents", agentId, "agent");
-    return (0, node_fs_1.existsSync)(dir) ? dir : undefined;
-}
-/**
- * Turns a downloaded attachment into text.
- *
- * Shared by the inbound path and by `fetch-media`: the backend choice lives in
- * `runtime.mediaUnderstanding`, and both callers have to make exactly the same
- * call — an image read on arrival and the same image read on request must not
- * become two different readings because two call sites drifted.
- */
-async function understandAttachmentFile(params) {
-    const media = params.runtime?.mediaUnderstanding;
-    if (!media)
-        return undefined;
-    const result = params.understanding === "transcript"
-        ? await media.transcribeAudioFile({
-            filePath: params.filePath,
-            cfg: params.cfg,
-            mime: params.mimeType,
-        })
-        : await media.describeImageFile({
-            filePath: params.filePath,
-            cfg: params.cfg,
-            mime: params.mimeType,
-            agentDir: resolveAgentDirForMedia(params.cfg),
-        });
-    const text = typeof result?.text === "string" ? result.text.trim() : "";
-    return text || undefined;
-}
-async function readInboundAttachment(params) {
-    const media = params.runtime?.mediaUnderstanding;
-    const message = params.event?.message;
-    if (!media || !message) {
-        return undefined;
-    }
-    let downloaded;
-    try {
-        downloaded = await (0, media_1.downloadInboundMediaToTempFile)({
-            client: params.gram.getClient(),
-            message,
-            maxBytes: INBOUND_MEDIA_MAX_BYTES,
-            tmpDir: node_os_1.default.tmpdir(),
-        });
-    }
-    catch (err) {
-        params.log?.info?.("clawgram attachment download failed", {
-            accountId: params.accountId,
-            chatId: params.chatId,
-            messageId: params.messageId,
-            error: String(err),
-        });
-        return undefined;
-    }
-    if (!downloaded) {
-        return undefined;
-    }
-    try {
-        const read = await understandAttachmentFile({
-            runtime: params.runtime,
-            cfg: params.cfg,
-            filePath: downloaded.path,
-            mimeType: downloaded.mimeType,
-            understanding: downloaded.understanding,
-        });
-        if (!read) {
-            params.log?.info?.("clawgram attachment read empty", {
-                accountId: params.accountId,
-                chatId: params.chatId,
-                messageId: params.messageId,
-                understanding: downloaded.understanding,
-            });
-            return undefined;
-        }
-        params.log?.info?.("clawgram attachment read", {
-            accountId: params.accountId,
-            chatId: params.chatId,
-            messageId: params.messageId,
-            understanding: downloaded.understanding,
-            characters: read.length,
-        });
-        return { text: read, understanding: downloaded.understanding };
-    }
-    catch (err) {
-        params.log?.info?.("clawgram attachment read failed", {
-            accountId: params.accountId,
-            chatId: params.chatId,
-            messageId: params.messageId,
-            understanding: downloaded.understanding,
-            error: String(err),
-        });
-        return undefined;
-    }
-    finally {
-        void (async () => {
-            try {
-                const { rm } = await import("node:fs/promises");
-                const { dirname } = await import("node:path");
-                await rm(dirname(downloaded.path), { recursive: true, force: true });
-            }
-            catch {
-                // Leaving a temp file behind is not worth failing a delivered message.
-            }
-        })();
-    }
-}
+const attachments_1 = require("./attachments");
 const createChannelPlugin = (runtimes, pluginRuntime) => {
     const resolveRuntimeAccountId = (cfg, preferred) => {
         const configured = (0, helpers_1.resolveConfiguredAccountId)(cfg, preferred);
@@ -407,6 +267,20 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
         }
         return configured ?? runtimes.keys().next().value;
     };
+    /**
+     * The connected runtime for an account, or a refusal naming it.
+     *
+     * One helper instead of the eleven copies of this three-liner that used to
+     * sit inside each dispatch branch — the same repetition that made every new
+     * action cost a scaffold (finding A6-11).
+     */
+    const requireRuntimeFor = (id) => {
+        const gram = runtimes.get(id);
+        if (!gram) {
+            throw new Error(`clawgram: runtime not found for account ${id}`);
+        }
+        return gram;
+    };
     return {
         id: "clawgram",
         meta: {
@@ -551,6 +425,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 const gram = new gramjs_client_1.GramJsClientManager(resolvedAccount);
                 await gram.start();
                 runtimes.set(accountId, gram);
+                (0, system_notice_1.rememberOperatorIds)(accountId, resolveAccountOperatorIds(cfg, accountId));
+                // Область отправки — туда же и по той же причине: в `outbound.*`
+                // конфига нет, а барьер нужен и на пути доставки ядра (A5-12).
+                (0, send_scope_1.rememberSendScope)(accountId, resolveAccountSendChats(cfg, accountId));
+                warnAboutHandleAllowlistEntries(cfg, accountId);
                 const pairing = (0, channel_pairing_1.createChannelPairingController)({
                     // The controller only reads core.channel.pairing, but its parameter is typed
                     // as the full PluginRuntime, and ctx (hence channelRuntime) is untyped.
@@ -687,7 +566,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         // voice note and a screenshot alike, the attachment *is* the
                         // message. A caption is kept and the reading appended, because
                         // "look at this" plus the picture is one thought, not two.
-                        const attachment = senderMayReachAgent ? await readInboundAttachment({
+                        const attachment = senderMayReachAgent ? await (0, attachments_1.readInboundAttachment)({
                             gram,
                             event,
                             cfg,
@@ -956,7 +835,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 replyToId: normalized.messageId,
                                 address: groupReplyAddress,
                             });
-                            const messageThreadId = parseOptionalThreadId(normalized.messageThreadId);
+                            const messageThreadId = (0, helpers_1.parseOptionalThreadId)(normalized.messageThreadId);
                             const groupTypingTarget = normalized.chatId;
                             await gram.withTyping(groupTypingTarget, async () => {
                                 log?.info?.("clawgram dispatching group reply", {
@@ -1033,6 +912,25 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                                 });
                                                 return;
                                             }
+                                            // Ядро подклеивает свою телеметрию к полезной нагрузке
+                                            // хода, и сюда она приходит тем же путём, что ответ.
+                                            // Проверка стояла только в `outbound.sendText`, то есть
+                                            // класс инцидента 30.08–01.09 был закрыт для рассылок и
+                                            // открыт для обычного ответа на упоминание (A5-10).
+                                            const groupNotice = (0, system_notice_1.shouldSuppressGroupSystemNotice)({
+                                                targetKind: "group",
+                                                text: visibleText,
+                                            });
+                                            if (groupNotice) {
+                                                log?.warn?.("clawgram suppressing system notice in group reply", {
+                                                    accountId,
+                                                    chatId: normalized.chatId,
+                                                    messageId: normalized.messageId,
+                                                    noticeKind: groupNotice,
+                                                    textLength: visibleText.length,
+                                                });
+                                                return;
+                                            }
                                             const replyToMessageId = payload.replyToId ? Number(payload.replyToId) : Number(normalized.messageId);
                                             const rememberedAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
                                                 accountId: route.accountId ?? accountId,
@@ -1086,9 +984,24 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     // `[[tts:text]]Привет, Вася!…[[/tts:text]]` verbatim. The
                                     // spoken words are kept — a synthesis that did not happen
                                     // should degrade to readable text, not to markup.
-                                    const visibleFallbackText = fallbackText
+                                    const rawFallback = fallbackText
                                         ? (0, helpers_1.stripTtsDirectives)((0, helpers_1.stripSilentReplyToken)(fallbackText))
                                         : "";
+                                    // Тот же фильтр и здесь: последняя реплика в стенограмме
+                                    // вполне может оказаться именно уведомлением об ошибке.
+                                    const fallbackNotice = rawFallback
+                                        ? (0, system_notice_1.shouldSuppressGroupSystemNotice)({ targetKind: "group", text: rawFallback })
+                                        : undefined;
+                                    if (fallbackNotice) {
+                                        log?.warn?.("clawgram suppressing system notice in transcript fallback", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                            noticeKind: fallbackNotice,
+                                            textLength: rawFallback.length,
+                                        });
+                                    }
+                                    const visibleFallbackText = fallbackNotice ? "" : rawFallback;
                                     if (!visibleFallbackText) {
                                         if (fallbackText) {
                                             log?.info?.("clawgram skipping silent transcript fallback", {
@@ -1570,10 +1483,14 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // Both count, because a rehearsal flag that is silently ignored puts
                 // a real message in a real chat — twice, so far (2.13.1).
                 const dryRun = (0, helpers_1.resolveDryRun)(dryRunFlag, params);
+                // Every branch below compares the canonical name, so a spelling is
+                // resolved once, here, and `ACTION_ALIASES` is the only place that
+                // decides what a name means. An unknown name stays itself and falls
+                // through to the unsupported-action error, as before.
+                const canonical = (0, actions_1.canonicalAction)(action);
                 // `read` is what OpenClaw core dispatches (`openclaw message read`,
-                // MCP `messages_read`). `list` is accepted as a synonym so a caller that
-                // guessed the other obvious name is not silently refused.
-                if (action === "read" || action === "list") {
+                // 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) {
@@ -1622,9 +1539,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // 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 (action === "fetch-media" || action === "fetchMedia" ||
-                    action === "download-media" || action === "downloadMedia" ||
-                    action === "getMedia" || action === "download-file") {
+                if (canonical === "fetch-media") {
                     const fetchParams = (0, fetch_media_1.parseFetchMediaParams)(params);
                     const fetchAccountId = resolveRuntimeAccountId(cfg, accountId);
                     if (!fetchAccountId) {
@@ -1665,11 +1580,21 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // 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.
-                    const sharedFetchDir = node_path_1.default.join(node_os_1.default.tmpdir(), "clawgram-fetched");
+                    // Не общий /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 } = await import("node:fs/promises");
-                        fetchDir = await mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "clawgram-media-"));
+                        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());
@@ -1677,7 +1602,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     const downloaded = await (0, media_1.downloadMessageMediaToFile)({
                         client: fetchGram.getClient(),
                         message: found.message,
-                        maxBytes: INBOUND_MEDIA_MAX_BYTES,
+                        maxBytes: attachments_1.INBOUND_MEDIA_MAX_BYTES,
                         dir: fetchDir,
                         fileNameFor: ({ media, extension }) => (0, fetch_media_1.fetchedMediaFileName)({
                             chatId: fetchChatId,
@@ -1693,7 +1618,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         // 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 > INBOUND_MEDIA_MAX_BYTES;
+                        const tooLarge = typeof described?.size === "number" && described.size > attachments_1.INBOUND_MEDIA_MAX_BYTES;
                         const error = !described
                             ? "no-media"
                             : tooLarge
@@ -1719,7 +1644,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     let readError;
                     if (fetchParams.mode !== "file") {
                         try {
-                            read = await understandAttachmentFile({
+                            read = await (0, attachments_1.understandAttachmentFile)({
                                 runtime: pluginRuntime,
                                 cfg,
                                 filePath: downloaded.path,
@@ -1773,189 +1698,174 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         readError,
                     });
                 }
-                // 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 (action === "participants" || action === "members" || action === "member-info") {
-                    const participantsParams = (0, history_1.parseListParticipantsParams)(params);
-                    const participantsAccountId = resolveRuntimeAccountId(cfg, accountId);
-                    if (!participantsAccountId) {
+                /**
+                 * 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");
                     }
-                    if (!(0, history_1.isChatReadable)(participantsParams.target, resolveAccountReadChats(cfg, participantsAccountId))) {
-                        actionLog.warn("clawgram participants refused: chat outside read scope", {
-                            accountId: participantsAccountId,
-                            target: participantsParams.target,
-                        });
-                        throw new Error(`clawgram: not-allowed-chat ${participantsParams.target}`);
+                    const target = spec.target?.(parsed);
+                    if (target !== undefined) {
+                        if (!(0, history_1.isChatReadable)(target, resolveAccountReadChats(cfg, readAccountId))) {
+                            actionLog.warn(`clawgram ${spec.name} refused: chat outside read scope`, {
+                                accountId: readAccountId,
+                                target,
+                            });
+                            throw new Error(`clawgram: not-allowed-chat ${target}`);
+                        }
                     }
-                    const participantsGram = runtimes.get(participantsAccountId);
-                    if (!participantsGram) {
-                        throw new Error(`clawgram: runtime not found for account ${participantsAccountId}`);
+                    else if (spec.discovery) {
+                        if (!(0, dialogs_1.isChatDiscoveryEnabled)(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 membership = await participantsGram.listParticipants(participantsParams);
-                    // Counts only. Member ids are personal data and have no business in a
-                    // log that is read while debugging something else.
-                    actionLog.info("clawgram handleAction participants completed", {
-                        accountId: participantsAccountId,
-                        target: participantsParams.target,
-                        limit: participantsParams.limit,
-                        returned: membership.participants.length,
-                        truncated: membership.truncated,
+                    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: participantsAccountId,
-                        chatId: membership.chatId ?? participantsParams.target,
-                        count: membership.participants.length,
-                        truncated: membership.truncated,
-                        participants: membership.participants,
+                    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 (action === "topics" || action === "forumTopics" || action === "thread-list") {
-                    const topicsParams = (0, topics_1.parseTopicsParams)(params);
-                    const topicsAccountId = resolveRuntimeAccountId(cfg, accountId);
-                    if (!topicsAccountId) {
-                        throw new Error("clawgram: no configured account found");
-                    }
-                    if (!(0, history_1.isChatReadable)(topicsParams.target, resolveAccountReadChats(cfg, topicsAccountId))) {
-                        actionLog.warn("clawgram topics refused: chat outside read scope", {
-                            accountId: topicsAccountId,
-                            target: topicsParams.target,
-                        });
-                        throw new Error(`clawgram: not-allowed-chat ${topicsParams.target}`);
-                    }
-                    const topicsGram = runtimes.get(topicsAccountId);
-                    if (!topicsGram) {
-                        throw new Error(`clawgram: runtime not found for account ${topicsAccountId}`);
-                    }
-                    const forum = await topicsGram.listTopics(topicsParams);
-                    actionLog.info("clawgram handleAction topics completed", {
-                        accountId: topicsAccountId,
-                        target: topicsParams.target,
-                        limit: topicsParams.limit,
-                        returned: forum.topics.length,
-                        truncated: forum.truncated,
-                    });
-                    return (0, core_1.jsonResult)({
-                        ok: true,
-                        accountId: topicsAccountId,
-                        chatId: forum.chatId ?? topicsParams.target,
-                        count: forum.topics.length,
-                        truncated: forum.truncated,
-                        topics: forum.topics,
+                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 (action === "dialogs" || action === "chats" || action === "channel-list") {
-                    const dialogsParams = (0, dialogs_1.parseDialogsParams)(params);
-                    const dialogsAccountId = resolveRuntimeAccountId(cfg, accountId);
-                    if (!dialogsAccountId) {
-                        throw new Error("clawgram: no configured account found");
-                    }
-                    if (!(0, dialogs_1.isChatDiscoveryEnabled)(resolveAccountDiscoverChats(cfg, dialogsAccountId))) {
-                        actionLog.warn("clawgram dialogs refused: chat-discovery is not enabled", {
-                            accountId: dialogsAccountId,
-                        });
-                        throw new Error("clawgram: chat-discovery is not enabled");
-                    }
-                    const dialogsGram = runtimes.get(dialogsAccountId);
-                    if (!dialogsGram) {
-                        throw new Error(`clawgram: runtime not found for account ${dialogsAccountId}`);
-                    }
-                    const found = await dialogsGram.listDialogs(dialogsParams);
-                    // Counts only: which chats a person's account sits in is exactly the
-                    // kind of thing that should not be sitting in a log.
-                    actionLog.info("clawgram handleAction dialogs completed", {
-                        accountId: dialogsAccountId,
-                        limit: dialogsParams.limit,
-                        returned: found.dialogs.length,
-                        truncated: found.truncated,
-                    });
-                    return (0, core_1.jsonResult)({
-                        ok: true,
-                        accountId: dialogsAccountId,
-                        count: found.dialogs.length,
-                        truncated: found.truncated,
-                        dialogs: found.dialogs,
+                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 (action === "joins") {
-                    const joinsParams = (0, joins_1.parseJoinsParams)(params);
-                    const joinsAccountId = resolveRuntimeAccountId(cfg, accountId);
-                    if (!joinsAccountId) {
-                        throw new Error("clawgram: no configured account found");
-                    }
-                    const journalPath = (0, joins_1.resolveJoinsJournalPath)(cfg?.channels?.["clawgram"]?.accounts?.[joinsAccountId], joinsAccountId);
-                    const selected = (0, joins_1.selectJoinRecords)((0, joins_1.readJoinRecords)(journalPath), joinsParams);
-                    actionLog.info("clawgram handleAction joins completed", {
-                        accountId: joinsAccountId,
-                        since: joinsParams.since ?? null,
-                        limit: joinsParams.limit,
-                        returned: selected.length,
-                    });
-                    return (0, core_1.jsonResult)({
-                        ok: true,
-                        accountId: joinsAccountId,
-                        count: selected.length,
-                        joins: selected,
+                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 (action === "chatInfo" || action === "getChatInfo" || action === "channel-info"
-                    || action === "chatMetadata" || action === "getChatMetadata") {
-                    const chatInfoParams = (0, chat_info_1.parseChatInfoParams)(params, toolContext);
-                    const chatInfoAccountId = resolveRuntimeAccountId(cfg, accountId);
-                    if (!chatInfoAccountId) {
-                        throw new Error("clawgram: no configured account found");
-                    }
-                    if (!(0, history_1.isChatReadable)(chatInfoParams.target, resolveAccountReadChats(cfg, chatInfoAccountId))) {
-                        actionLog.warn("clawgram chatInfo refused: chat outside read scope", {
-                            accountId: chatInfoAccountId,
-                            target: chatInfoParams.target,
-                        });
-                        throw new Error(`clawgram: not-allowed-chat ${chatInfoParams.target}`);
-                    }
-                    const chatInfoGram = runtimes.get(chatInfoAccountId);
-                    if (!chatInfoGram) {
-                        throw new Error(`clawgram: runtime not found for account ${chatInfoAccountId}`);
-                    }
-                    const { entity, full } = await chatInfoGram.getChatInfo(chatInfoParams.target);
-                    const info = (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.
-                    actionLog.info("clawgram handleAction chatInfo completed", {
-                        accountId: chatInfoAccountId,
-                        type: info.type,
-                        memberCount: info.memberCount ?? null,
-                        isForum: info.isForum ?? null,
-                    });
-                    return (0, core_1.jsonResult)({
-                        ok: true,
-                        accountId: chatInfoAccountId,
-                        chat: { ...info, chatId: info.chatId ?? chatInfoParams.target },
+                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 } }),
                     });
                 }
                 // A reaction is an outbound act on someone else's message, so it is
                 // gated like sending rather than like reading — and it respects
                 // `dryRun`, which reading does not need to.
-                if (action === "react") {
+                if (canonical === "react") {
                     const reactionParams = (0, reactions_1.parseReactionParams)(params, toolContext);
                     const reactionAccountId = resolveRuntimeAccountId(cfg, accountId);
                     if (!reactionAccountId) {
                         throw new Error("clawgram: no configured account found");
                     }
+                    // Реакция — видимое действие от имени владельца в чужом чате, и
+                    // адресуется она так же, как сообщение: та же область (A5-12).
+                    if (!(0, send_scope_1.isChatSendable)(reactionParams.target, resolveAccountSendChats(cfg, reactionAccountId))) {
+                        refuseOutboundOutsideScope("react", reactionAccountId, String(reactionParams.target));
+                    }
                     actionLog.info("clawgram handleAction react", {
                         accountId: reactionAccountId,
                         dryRun: dryRun === true,
@@ -2000,15 +1910,43 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // 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 = MANAGE_ACTION_ALIASES[action];
+                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 = resolveAccountManageChats(cfg, manageAccountId);
-                    const requireManagedChat = (target) => {
-                        if (!(0, manage_1.isChatManageable)(target, manageScope)) {
+                    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,
@@ -2016,188 +1954,126 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             });
                             throw new Error(`clawgram: not-managed-chat ${target}`);
                         }
-                    };
-                    const requireRuntime = () => {
-                        const gram = runtimes.get(manageAccountId);
-                        if (!gram) {
-                            throw new Error(`clawgram: runtime not found for account ${manageAccountId}`);
-                        }
-                        return gram;
-                    };
-                    if (manageAction === "createGroup") {
-                        const createParams = (0, manage_1.parseCreateGroupParams)(params);
-                        // A group being created is not in any scope yet, so the gate is
-                        // coarser: management must be enabled at all for this account.
-                        if (!(0, manage_1.isManagementEnabled)(manageScope)) {
-                            actionLog.warn("clawgram createGroup 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`);
-                        }
-                        actionLog.info("clawgram handleAction createGroup", {
+                        actionLog.info(`clawgram handleAction ${spec.name}`, {
                             accountId: manageAccountId,
                             dryRun: dryRun === true,
-                            users: createParams.users.length,
-                            hasAbout: Boolean(createParams.about),
+                            ...spec.before(parsed),
                         });
                         if (dryRun === true) {
-                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId });
+                            return (0, core_1.jsonResult)({
+                                ok: true,
+                                dryRun: true,
+                                accountId: manageAccountId,
+                                ...(target === undefined ? {} : { chatId: target }),
+                            });
                         }
-                        const created = await requireRuntime().createGroup(createParams);
-                        actionLog.info("clawgram handleAction createGroup completed", {
+                        const gram = requireRuntime();
+                        spec.precondition?.(gram);
+                        const result = await spec.run(gram, parsed);
+                        actionLog.info(`clawgram handleAction ${spec.name} completed`, {
                             accountId: manageAccountId,
-                            chatId: created.chatId ?? null,
-                            missing: created.missing.length,
+                            ...spec.after(parsed, result),
                         });
-                        return (0, core_1.jsonResult)({
-                            ok: true,
-                            accountId: manageAccountId,
-                            chatId: created.chatId,
-                            missing: created.missing,
+                        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") {
-                        const addParams = (0, manage_1.parseAddMembersParams)(params, toolContext);
-                        requireManagedChat(addParams.target);
-                        actionLog.info("clawgram handleAction addMembers", {
-                            accountId: manageAccountId,
-                            dryRun: dryRun === true,
-                            target: addParams.target,
-                            users: addParams.users.length,
-                        });
-                        if (dryRun === true) {
-                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId, chatId: addParams.target });
-                        }
-                        const added = await requireRuntime().addChatMembers(addParams);
-                        actionLog.info("clawgram handleAction addMembers completed", {
-                            accountId: manageAccountId,
-                            target: addParams.target,
-                            requested: addParams.users.length,
-                            missing: added.missing.length,
-                        });
-                        return (0, core_1.jsonResult)({
-                            ok: true,
-                            accountId: manageAccountId,
-                            chatId: added.chatId ?? addParams.target,
-                            requested: addParams.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,
+                        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") {
-                        const removeParams = (0, manage_1.parseRemoveMemberParams)(params, toolContext);
-                        requireManagedChat(removeParams.target);
-                        actionLog.info("clawgram handleAction removeMember", {
-                            accountId: manageAccountId,
-                            dryRun: dryRun === true,
-                            target: removeParams.target,
-                            ban: removeParams.ban,
-                        });
-                        if (dryRun === true) {
-                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId, chatId: removeParams.target });
-                        }
-                        await requireRuntime().removeChatMember(removeParams);
-                        actionLog.info("clawgram handleAction removeMember completed", {
-                            accountId: manageAccountId,
-                            target: removeParams.target,
-                            ban: removeParams.ban,
-                        });
-                        return (0, core_1.jsonResult)({
-                            ok: true,
-                            accountId: manageAccountId,
-                            chatId: removeParams.target,
-                            user: removeParams.user,
-                            banned: removeParams.ban,
+                        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 adminParams = manageAction === "promoteAdmin"
-                            ? (0, manage_1.parsePromoteAdminParams)(params, toolContext)
-                            : (0, manage_1.parseDemoteAdminParams)(params, toolContext);
-                        requireManagedChat(adminParams.target);
-                        actionLog.info("clawgram handleAction setAdmin", {
-                            accountId: manageAccountId,
-                            dryRun: dryRun === true,
-                            target: adminParams.target,
-                            isAdmin: adminParams.isAdmin,
-                            hasRank: Boolean(adminParams.rank),
-                        });
-                        if (dryRun === true) {
-                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId, chatId: adminParams.target });
-                        }
-                        await requireRuntime().setChatAdmin(adminParams);
-                        actionLog.info("clawgram handleAction setAdmin completed", {
-                            accountId: manageAccountId,
-                            target: adminParams.target,
-                            isAdmin: adminParams.isAdmin,
-                        });
-                        return (0, core_1.jsonResult)({
-                            ok: true,
-                            accountId: manageAccountId,
-                            chatId: adminParams.target,
-                            user: adminParams.user,
-                            isAdmin: adminParams.isAdmin,
-                            ...(adminParams.rank ? { rank: adminParams.rank } : {}),
+                        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") {
-                        const transferParams = (0, manage_1.parseTransferOwnershipParams)(params, toolContext);
-                        requireManagedChat(transferParams.target);
-                        actionLog.info("clawgram handleAction transferOwnership", {
-                            accountId: manageAccountId,
-                            dryRun: dryRun === true,
-                            target: transferParams.target,
-                        });
-                        if (dryRun === true) {
-                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId, chatId: transferParams.target });
-                        }
-                        const transferGram = requireRuntime();
-                        // 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.
-                        if (!transferGram.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)");
-                        }
-                        await transferGram.transferChatOwnership(transferParams);
-                        actionLog.info("clawgram handleAction transferOwnership completed", {
-                            accountId: manageAccountId,
-                            target: transferParams.target,
-                        });
-                        return (0, core_1.jsonResult)({
-                            ok: true,
-                            accountId: manageAccountId,
-                            chatId: transferParams.target,
-                            newOwner: transferParams.user,
+                        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.
-                    const inviteParams = (0, manage_1.parseInviteLinkParams)(params, toolContext);
-                    requireManagedChat(inviteParams.target);
-                    actionLog.info("clawgram handleAction inviteLink", {
-                        accountId: manageAccountId,
-                        dryRun: dryRun === true,
-                        target: inviteParams.target,
-                        hasExpiry: inviteParams.expireDate !== undefined,
-                        usageLimit: inviteParams.usageLimit ?? null,
-                        requestNeeded: inviteParams.requestNeeded,
-                    });
-                    if (dryRun === true) {
-                        return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId, chatId: inviteParams.target });
-                    }
-                    const exported = await requireRuntime().exportChatInviteLink(inviteParams);
-                    actionLog.info("clawgram handleAction inviteLink completed", {
-                        accountId: manageAccountId,
-                        target: inviteParams.target,
-                        hasLink: Boolean(exported.link),
-                    });
-                    return (0, core_1.jsonResult)({
-                        ok: true,
-                        accountId: manageAccountId,
-                        chatId: inviteParams.target,
-                        link: exported.link,
+                    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 }),
                     });
                 }
                 // Core normalizes whichever of these it filled in to a local path (see
@@ -2211,13 +2087,17 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 // and arrives from older callers. A plain `send` carrying a file lands
                 // here too — `openclaw message send --media` does exactly that, and
                 // routing it to the text path dropped the file without a word.
-                if (action === "upload-file" || action === "sendAttachment" || (action === "send" && attachedFile)) {
+                if (canonical === "upload-file" || (canonical === "send" && attachedFile)) {
                     const rawUploadTo = (0, helpers_1.resolveActionTarget)(params, toolContext);
                     const uploadTo = (0, helpers_1.normalizeOutboundTarget)(rawUploadTo);
                     const uploadAccountId = resolveRuntimeAccountId(cfg, accountId);
                     if (!uploadAccountId) {
                         throw new Error("clawgram: no configured account found");
                     }
+                    // Та же граница, что у `send`: файл наружу — такое же исходящее.
+                    if (!(0, send_scope_1.isChatSendable)(uploadTo, resolveAccountSendChats(cfg, uploadAccountId))) {
+                        refuseOutboundOutsideScope("upload-file", uploadAccountId, uploadTo);
+                    }
                     const file = attachedFile;
                     if (!file) {
                         throw new Error("clawgram: upload-file requires filePath, path, media, or mediaUrl");
@@ -2264,7 +2144,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         // the same prose as a message and renders identically.
                         parseMode: (0, helpers_1.resolveOutboundParseMode)(params, cfg, uploadAccountId),
                         replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(rawUploadTo, uploadReplyToId),
-                        messageThreadId: parseOptionalThreadId(uploadThreadId),
+                        messageThreadId: (0, helpers_1.parseOptionalThreadId)(uploadThreadId),
                         asVoice,
                     });
                     actionLog.info("clawgram handleAction upload-file completed", {
@@ -2287,7 +2167,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 const to = (0, helpers_1.normalizeOutboundTarget)(rawTo);
                 const replyToId = (0, param_readers_1.readStringOrNumberParam)(params, "replyToId") ?? (0, param_readers_1.readStringOrNumberParam)(params, "replyTo");
                 const threadId = (0, param_readers_1.readStringOrNumberParam)(params, "threadId");
-                const messageThreadId = parseOptionalThreadId(threadId);
+                const messageThreadId = (0, helpers_1.parseOptionalThreadId)(threadId);
                 // Omitting parseMode inherits the account's configured mode rather
                 // than falling back to plain text (2.13.0): an account set to `html`
                 // used to render replies as HTML and these sends as raw markup.
@@ -2307,6 +2187,12 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 if (!resolvedAccountId) {
                     throw new Error("clawgram: no configured account found");
                 }
+                // Проверка ПОСЛЕ резолва аккаунта и ДО любой доставки: область задаётся
+                // на аккаунт, а отказ должен случиться раньше, чем цель разрешена в
+                // Telegram-сущность — resolve сам по себе виден собеседнику (A5-12).
+                if (!(0, send_scope_1.isChatSendable)(to, resolveAccountSendChats(cfg, resolvedAccountId))) {
+                    refuseOutboundOutsideScope("send", resolvedAccountId, to);
+                }
                 const currentChannelId = toolContext?.currentChannelId?.trim() ?? "";
                 const currentMessageId = toolContext?.currentMessageId;
                 const currentChannelTarget = currentChannelId ? (0, helpers_1.normalizeOutboundTarget)(currentChannelId) : "";
@@ -2433,187 +2319,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 });
             },
         },
-        outbound: {
-            // Core's agent-delivery path (`--deliver`, subagent announces) calls this
-            // hook under three constraints, all learned live on 2026-08-06:
-            //
-            // - `to` may be undefined (no explicit target, session route yielded
-            //   none), and a rejection is NOT caught: a throw here is an unhandled
-            //   rejection that takes down the entire gateway process.
-            // - `resolveAgentDeliveryPlanWithSessionRoute` calls it WITHOUT await.
-            //   An async hook hands core a Promise, `promise.ok` reads undefined and
-            //   the error branch dereferences `promise.error.message` — the crash
-            //   every subagent announce died on. The hook must return a plain value;
-            //   the call sites that do await are unaffected, await of a value works.
-            // - In a not-ok result core reads `error.message`, so the error must be
-            //   Error-like, not a bare string.
-            //
-            // Peer resolution deliberately does not happen here: `sendText` resolves
-            // the peer itself, and doing it here would force the hook async again.
-            resolveTarget(ctx) {
-                try {
-                    const raw = typeof ctx.to === "string" ? ctx.to.trim() : "";
-                    actionLog.info("clawgram outbound resolveTarget", {
-                        accountId: ctx.accountId,
-                        rawTo: raw || null,
-                    });
-                    if (!raw) {
-                        return { ok: false, error: new Error("clawgram: no delivery target — pass `to` or use a session with a bound chat") };
-                    }
-                    return { ok: true, to: (0, helpers_1.normalizeOutboundTarget)(raw) };
-                }
-                catch (err) {
-                    return { ok: false, error: err instanceof Error ? err : new Error(String(err)) };
-                }
-            },
-            async sendText(ctx) {
-                // Never log `text`: outbound bodies are private correspondence and the
-                // channel log is a plain journald sink. Length is enough to tell an
-                // empty or truncated send apart from a real one.
-                actionLog.info("clawgram outbound sendText", {
-                    accountId: ctx.accountId,
-                    rawTo: ctx.to,
-                    replyToId: ctx.replyToId ?? null,
-                    threadId: ctx.threadId ?? null,
-                    textLength: ctx.text.length,
-                });
-                // Core normalizes reply payloads and drops the silent token before a
-                // channel is called, so this should never see one. "Should never" is
-                // what the inbound path was assumed to be too, right until it posted a
-                // token — and the check costs a string comparison.
-                if (ctx.text.trim() && (0, helpers_1.isSilentReplyText)(ctx.text)) {
-                    actionLog.info("clawgram suppressing silent outbound send", {
-                        accountId: ctx.accountId,
-                        rawTo: ctx.to,
-                    });
-                    return { skipped: "silent" };
-                }
-                // Core's operational chatter (tool-error warnings, fallback notices)
-                // stays out of group chats: it is telemetry for the operator, not a
-                // reply to the room, and it has already been seen carrying shell
-                // commands with secret-store paths. DMs keep it. The text itself is
-                // never logged — see system-notice.ts for why.
-                const suppressedNotice = (0, system_notice_1.shouldSuppressGroupSystemNotice)({
-                    targetKind: (0, helpers_1.inferOutboundTargetKind)(ctx.to),
-                    text: ctx.text,
-                });
-                if (suppressedNotice) {
-                    actionLog.warn("clawgram suppressing system notice in group", {
-                        accountId: ctx.accountId,
-                        rawTo: ctx.to,
-                        noticeKind: suppressedNotice,
-                        textLength: ctx.text.length,
-                    });
-                    return { skipped: "system-notice" };
-                }
-                const gram = runtimes.get(ctx.accountId);
-                if (!gram) {
-                    throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
-                }
-                // The agent already answered this message with its own `send`, and this
-                // is core delivering the same turn's final text. Two messages for one
-                // answer is how 2026-08-10 read in a work chat: every request reported
-                // twice, in slightly different words, seconds apart.
-                //
-                // Core's own convention is that an agent which has sent a message
-                // returns NO_REPLY; this catches the turns that forget. The window is
-                // seconds wide, so a result the assistant comes back with later is
-                // still delivered.
-                if (ctx.replyToId !== null && ctx.replyToId !== undefined && (0, group_visible_reply_guard_1.hadTurnSendJustNow)({
-                    accountId: ctx.accountId,
-                    chatId: (0, helpers_1.normalizeOutboundTarget)(ctx.to),
-                    currentMessageId: ctx.replyToId,
-                })) {
-                    actionLog.warn("clawgram suppressing echo of a turn that already sent", {
-                        accountId: ctx.accountId,
-                        rawTo: ctx.to,
-                        replyToId: ctx.replyToId,
-                        textLength: ctx.text.length,
-                    });
-                    return { skipped: "duplicate" };
-                }
-                const groupReplyAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
-                    accountId: ctx.accountId,
-                    chatId: ctx.to,
-                    replyToId: ctx.replyToId,
-                });
-                const targetKind = (0, helpers_1.inferOutboundTargetKind)(ctx.to);
-                const target = (0, helpers_1.normalizeOutboundTarget)(ctx.to);
-                const messageThreadId = parseOptionalThreadId(ctx.threadId);
-                const sent = await gram.sendText({
-                    target,
-                    text: (0, helpers_1.prefixReplyTextToAddress)(ctx.text, groupReplyAddress),
-                    targetKind,
-                    replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
-                    messageThreadId,
-                    parseMode: gram.replyParseMode,
-                });
-                actionLog.info("clawgram outbound sendText completed", {
-                    accountId: ctx.accountId,
-                    to: target,
-                    targetKind,
-                    replyToId: ctx.replyToId ?? null,
-                    sentMessageId: String(sent?.id ?? ""),
-                });
-                return {
-                    ok: true,
-                    messageId: String(sent?.id ?? ""),
-                };
-            },
-            async sendMedia(ctx) {
-                const gram = runtimes.get(ctx.accountId);
-                if (!gram) {
-                    throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
-                }
-                // Same rule as the action path: a local file outside the declared
-                // roots is refused before anything is uploaded.
-                const outboundRoots = ctx.mediaLocalRoots ?? ctx.mediaAccess?.localRoots;
-                (0, media_1.assertLocalMediaWithinRoots)(ctx.filePath, outboundRoots);
-                (0, media_1.assertLocalMediaWithinRoots)(ctx.mediaUrl, outboundRoots);
-                actionLog.info("clawgram outbound sendMedia", {
-                    accountId: ctx.accountId,
-                    rawTo: ctx.to,
-                    replyToId: ctx.replyToId ?? null,
-                    threadId: ctx.threadId ?? null,
-                    filePath: ctx.filePath ?? null,
-                    mediaUrl: ctx.mediaUrl ?? null,
-                    hasText: Boolean(ctx.text),
-                    hasCaption: Boolean(ctx.caption),
-                    asVoice: ctx.audioAsVoice === true,
-                });
-                const file = ctx.filePath ?? ctx.mediaUrl;
-                if (!file) {
-                    throw new Error("clawgram: sendMedia requires filePath or mediaUrl");
-                }
-                const messageThreadId = parseOptionalThreadId(ctx.threadId);
-                // Same normalization `sendText` does two functions up. Without it the
-                // channel prefix reaches peer resolution and the send throws — which is
-                // exactly how a synthesized group reply died on 2026-08-08, silently
-                // enough that the transcript fallback posted it as raw text instead.
-                const target = (0, helpers_1.normalizeOutboundTarget)(ctx.to);
-                const sent = await gram.sendMedia({
-                    target,
-                    file,
-                    caption: ctx.caption ?? ctx.text,
-                    // Captions follow the account reply format like every other reply:
-                    // they are the same agent prose, just attached to a file (2.15.0).
-                    parseMode: gram.replyParseMode,
-                    replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
-                    messageThreadId,
-                    asVoice: ctx.audioAsVoice === true,
-                });
-                actionLog.info("clawgram outbound sendMedia completed", {
-                    accountId: ctx.accountId,
-                    to: ctx.to,
-                    replyToId: ctx.replyToId ?? null,
-                    sentMessageId: String(sent?.id ?? ""),
-                });
-                return {
-                    ok: true,
-                    messageId: String(sent?.id ?? ""),
-                };
-            },
-        },
+        outbound: (0, outbound_1.createOutbound)(runtimes),
     };
 };
 exports.createChannelPlugin = createChannelPlugin;