clawgram 2.24.0 → 2.26.0

package/README.md

@@ -256,10 +256,11 @@ loud where it does occur.
 | `apiHash` | string | required | Telegram API hash |
 | `sessionString` | string | `""` | Authenticated StringSession |
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames for direct messages only. Three states: absent means everyone, `[]` denies everyone (a warning is logged at account start), a list allows those senders |
-| `operatorIds` | string[] | — | Who receives core's operational telemetry in a DM (tool-failure warnings, fallback notices). They quote shell commands and secret-store paths, so they go only to these ids. Absent falls back to `allowFrom` when it is a concrete list; a wildcard or an empty list means no operator is identified and the notices are dropped everywhere — they stay in the run diagnostics and the gateway log |
+| `operatorIds` | string[] | — | Who receives core's operational telemetry in a DM (tool-failure warnings, fallback notices). They quote shell commands and secret-store paths, so they go **only** to these ids. Absent, empty or containing `*` means no operator is identified and the notices are dropped everywhere — they stay in the run diagnostics, the job's `lastError` and the gateway log. `allowFrom` is **not** a fallback (2.25.0; it was until then, which made every allowed sender an operator) |
 | `groups` | object | `{}` | Allowed groups map keyed by explicit group id or `*` |
 | `proxy` | object | unset | Optional SOCKS4/SOCKS5 proxy for this account — see [Proxy (SOCKS4/SOCKS5)](#proxy-socks4socks5) |
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
+| `sendChats` | string[] | unset | Chats the assistant may **send to** — `send`, `upload-file`, `react` and core's own delivery path (`--deliver`, sub-agent announcements). Absent = every chat; `[]` = none. Phone-number targets are refused regardless (2.18.0; core delivery covered since 2.25.0) |
 | `replyParseMode` | `"html"` \| `"markdown"` \| `"none"` | unset | Outbound format for replies, core-delivered text, captions and `send` calls that omit `parseMode` — see [Message formatting](#message-formatting) |
 | `twoFaPassword` | string \| SecretRef | unset | The account's Telegram 2FA password; read only by `transferOwnership` |
 | `reactionModel` | string | unset | Model ref or alias for the emoji pick on a silent mention. Unset = the agent's own model. Needs `plugins.entries.clawgram.llm.allowModelOverride: true` in the gateway config; without it the override is refused and the pick quietly falls back to the default model |
@@ -713,6 +714,35 @@ Bindings
 ```
 
 
+## Actions and the names that reach them
+
+Two grammars name the same actions. The **native** names (`read`, `participants`, `topics`,
+`dialogs`, `chatInfo`, `fetch-media`, `createGroup`, …) are what the gateway RPC, the tests and
+this README use. The agent's `message` tool, however, only dispatches names from **core's own
+vocabulary** (`CHANNEL_MESSAGE_ACTION_NAMES`), so every action worth reaching from a prompt also
+answers to core's nearest name. `src/actions.ts` is the single source of both lists
+(`ACTION_ALIASES`, `CORE_VOCABULARY_SPELLINGS`); that core really knows each name is asserted
+against the installed core in `test/core-action-synonyms.test.ts`, so a core release that drops
+one fails the suite rather than the chat.
+
+| Does | Native name | Callable from the `message` tool as | Gate |
+|---|---|---|---|
+| send text | `send` | `send` | `sendChats` |
+| send a file | `upload-file` | `upload-file`, `sendAttachment` | `sendChats`, media roots |
+| react to a message | `react` | `react` | `sendChats` |
+| read history | `read` (also `list`) | `read` | `readChats` |
+| fetch an attachment | `fetch-media` | `download-file` | `readChats` |
+| list members | `participants` | `member-info` | `readChats` |
+| list forum topics | `topics` | `thread-list` | `readChats` |
+| list chats | `dialogs` | `channel-list` | `discoverChats` |
+| describe a chat | `chatInfo` | `channel-info` (the chat arrives in `channelId`) | `readChats` |
+| where the account was added | `joins` | — (gateway RPC only) | — |
+| chat management | see the table below | see the table below | `manageChats` |
+
+Names outside core's vocabulary (`joins`, `transferOwnership`, `inviteLink`) are reachable through
+the gateway RPC only. A name core does not know fails as "requires a target" and "does not accept a
+target" at once — there is no call that satisfies both, which is why this table exists.
+
 ## Chat management
 
 Since 2.12.0 the assistant can assemble a chat, not only speak in it: create a supergroup, add and
@@ -727,15 +757,15 @@ management to those chats, `["*"]` allows every chat. A non-empty list also unlo
 (the chat being created is not in any list yet). All actions honour `dryRun`, and the gate is
 checked before the dry-run answer, so a dry run exercises the same refusals a real call would hit.
 
-| Action | Parameters | Notes |
-|---|---|---|
-| `createGroup` | `title`, `about?`, `users?` | Creates a **supergroup** (megagroup) — granular admin rights, bans and ownership transfer only exist there. Initial members are invited right after creation; who could not be added is returned in `missing` |
-| `addMembers` | `chatId`, `users` | Adds to supergroups in one call, to basic groups one by one. Ids Telegram refused (privacy settings) come back in `missing` instead of failing the call |
-| `removeMember` | `chatId`, `user`, `ban?` | Soft kick by default — the person may be re-invited later. `ban: true` keeps them out until unbanned |
-| `promoteAdmin` | `chatId`, `user`, `rank?`, `rights?` | Grants a deliberate default set (change info, delete messages, ban, invite, pin, calls, topics). `addAdmins` and `anonymous` stay **off** unless explicitly set in `rights` |
-| `demoteAdmin` | `chatId`, `user` | Strips every admin right |
-| `transferOwnership` | `chatId`, `user` | Supergroups only. Requires `twoFaPassword` (below); Telegram's own rules surface as errors — see the fine print |
-| `inviteLink` | `chatId`, `expireDate?`, `usageLimit?`, `title?`, `requestNeeded?` | The path for people whose privacy settings refuse a direct add. `expireDate` takes unix seconds or an ISO date |
+| Action | Callable from the `message` tool as | Parameters | Notes |
+|---|---|---|---|
+| `createGroup` | `channel-create` | `title`, `about?`, `users?` | Creates a **supergroup** (megagroup) — granular admin rights, bans and ownership transfer only exist there. Initial members are invited right after creation; who could not be added is returned in `missing` |
+| `addMembers` | `addParticipant` | `chatId`, `users` | Adds to supergroups in one call, to basic groups one by one. Ids Telegram refused (privacy settings) come back in `missing` instead of failing the call |
+| `removeMember` | `kick` | `chatId`, `user`, `ban?` | Soft kick by default — the person may be re-invited later. `ban: true` keeps them out until unbanned |
+| `promoteAdmin` | `role-add` | `chatId`, `user`, `rank?`, `rights?` | Grants a deliberate default set (change info, delete messages, ban, invite, pin, calls, topics). `addAdmins` and `anonymous` stay **off** unless explicitly set in `rights` |
+| `demoteAdmin` | `role-remove` | `chatId`, `user` | Strips every admin right |
+| `transferOwnership` | — (gateway RPC only) | `chatId`, `user` | Supergroups only. Requires `twoFaPassword` (below); Telegram's own rules surface as errors — see the fine print |
+| `inviteLink` | — (gateway RPC only) | `chatId`, `expireDate?`, `usageLimit?`, `title?`, `requestNeeded?` | The path for people whose privacy settings refuse a direct add. `expireDate` takes unix seconds or an ISO date |
 
 User references in `users`/`user` are `@username` or a numeric Telegram id. A `@username` always
 resolves; a bare numeric id only when the account has already seen the user (shared chat, dialog,

package/dist/account-registry.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rememberAccount = rememberAccount;
+exports.forgetAccount = forgetAccount;
+exports.sendScopeFor = sendScopeFor;
+exports.operatorIdsFor = operatorIdsFor;
+exports.requireRuntime = requireRuntime;
+const records = new Map();
+function rememberAccount(accountId, record) {
+    records.set(accountId, { sendChats: record.sendChats, operatorIds: [...record.operatorIds] });
+}
+function forgetAccount(accountId) {
+    records.delete(accountId);
+}
+function sendScopeFor(accountId) {
+    return records.get(accountId)?.sendChats;
+}
+function operatorIdsFor(accountId) {
+    return records.get(accountId)?.operatorIds ?? [];
+}
+/**
+ * The connected runtime for an account, or a refusal naming it.
+ *
+ * One helper instead of the copies of this three-liner that used to sit in
+ * each dispatch branch (A6-11 removed six; D2-11 the remaining seven).
+ */
+function requireRuntime(runtimes, accountId) {
+    const gram = runtimes.get(accountId);
+    if (!gram) {
+        throw new Error(`clawgram: runtime not found for account ${accountId}`);
+    }
+    return gram;
+}

package/dist/channel.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createChannelPlugin = exports.canonicalAction = exports.CORE_ACTION_SYNONYMS = void 0;
+exports.resolveAccountOperatorIds = resolveAccountOperatorIds;
 const core_1 = require("openclaw/plugin-sdk/core");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -54,15 +55,14 @@ const fetch_media_1 = require("./fetch-media");
 const channel_runtime_1 = require("openclaw/plugin-sdk/channel-runtime");
 const param_readers_1 = require("openclaw/plugin-sdk/param-readers");
 const tool_send_1 = require("openclaw/plugin-sdk/tool-send");
-const channel_pairing_1 = require("openclaw/plugin-sdk/channel-pairing");
 const events_1 = require("telegram/events");
 const gramjs_client_1 = require("./gramjs-client");
 const history_1 = require("./history");
 const send_scope_1 = require("./send-scope");
+const account_registry_1 = require("./account-registry");
 const joins_1 = require("./joins");
 const reactions_1 = require("./reactions");
 const manage_1 = require("./manage");
-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");
@@ -75,6 +75,12 @@ const group_visible_reply_guard_1 = require("./group-visible-reply-guard");
 const helpers_1 = require("./helpers");
 const proxy_config_1 = require("./proxy-config");
 const constants_1 = require("./constants");
+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");
+const inbound_pipeline_1 = require("./inbound-pipeline");
+const attachments_1 = require("./attachments");
 const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
 /**
  * Read scope as configured for the account. Left `undefined` when the key is
@@ -82,20 +88,11 @@ const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
  * the first means no restriction, the second denies everything.
  */
 function readAccountReadChats(account) {
-    const raw = account?.readChats;
-    if (raw === undefined || raw === null)
-        return undefined;
-    const entries = Array.isArray(raw) ? raw : [raw];
-    return entries.map((entry) => String(entry).trim()).filter(Boolean);
+    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`.
- */
 /**
  * Хэндл в `allowFrom` — обещание, которое Telegram не держит.
  *
@@ -122,14 +119,19 @@ function warnAboutHandleAllowlistEntries(cfg, accountId) {
         why: "a released handle can be taken by someone else; numeric ids do not change hands",
     });
 }
+/**
+ * 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 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}`);
+    const refusal = (0, send_scope_1.describeSendRefusal)(target);
+    actionLog.warn(`clawgram ${action} refused: ${refusal.reason}`, { accountId, ...refusal.logFields });
+    throw refusal.error;
 }
 /**
  * Management scope as configured. Handed to `isChatManageable` raw: unlike
@@ -149,8 +151,11 @@ function refuseOutboundOutsideScope(action, accountId, target) {
  */
 function resolveAccountOperatorIds(cfg, accountId) {
     const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
-    const explicit = account?.operatorIds;
-    const raw = explicit !== undefined && explicit !== null ? explicit : account?.allowFrom;
+    // Только явный список. Умолчание «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];
@@ -164,31 +169,8 @@ function resolveAccountManageChats(cfg, accountId) {
 }
 /** Same normalization `readChats` gets, for the resolved-account copy. */
 function readAccountManageChats(account) {
-    const raw = account?.manageChats;
-    if (raw === undefined || raw === null)
-        return undefined;
-    const entries = Array.isArray(raw) ? raw : [raw];
-    return entries.map((entry) => String(entry).trim()).filter(Boolean);
+    return (0, history_1.normalizeScopeList)(account?.manageChats);
 }
-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");
-const inbound_pipeline_1 = require("./inbound-pipeline");
-/**
- * Turns an inbound attachment into text the agent can read.
- *
- * The work is deliberately delegated: `runtime.mediaUnderstanding` already
- * knows which backend this installation uses for speech and for images, so
- * the channel stays out of that choice — a local model today, something else
- * tomorrow, without touching this file.
- *
- * Failure is not an error worth dropping the message over. An attachment that
- * could not be read still happened, and the assistant is better off saying
- * "you sent something I could not read" than staying silent, which is
- * indistinguishable from being offline.
- */
-const attachments_1 = require("./attachments");
 const createChannelPlugin = (runtimes, pluginRuntime) => {
     const resolveRuntimeAccountId = (cfg, preferred) => {
         const configured = (0, helpers_1.resolveConfiguredAccountId)(cfg, preferred);
@@ -200,20 +182,8 @@ 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;
-    };
+    /** The connected runtime for an account, or a refusal naming it (A6-11, D2-11). */
+    const requireRuntimeFor = (id) => (0, account_registry_1.requireRuntime)(runtimes, id);
     return {
         id: "clawgram",
         meta: {
@@ -253,7 +223,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
             messageToolHints: () => [
                 "Use clawgram to send Telegram replies from the connected personal account.",
                 "When replying in the current Telegram chat, omit `to`/`target` and clawgram will send to the current conversation automatically.",
-                "Explicit targets may be @username, numeric Telegram user id, phone/contact resolvable by Telegram, group chat ids, or clawgram:<target>.",
+                "Explicit targets may be @username, numeric Telegram user id, group chat ids, or clawgram:<target>.",
                 "For Telegram forum topics, send to the group chat id and pass the topic id separately as `threadId`.",
                 "Use the `react` action to acknowledge a message with an emoji instead of sending a reply; pass an empty `emoji` (or `remove: true`) to take the reaction back.",
                 "Use the `channel-info` action to learn what a chat is — title, type, member count, description, pinned message — instead of guessing from its id. Name the chat with `chatId` and do not pass `target`: core refuses it for this action, and the descriptive spelling `chatInfo` is not callable from this tool at all.",
@@ -358,18 +328,14 @@ 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.
-                    core: { channel: channelRuntime },
-                    channel: "clawgram",
-                    accountId,
+                // Что `outbound.*` должен знать об аккаунте без конфига: область
+                // отправки (A5-12) и операторы (A5-11). Одна запись, снимается при
+                // остановке аккаунта (D2-11).
+                (0, account_registry_1.rememberAccount)(accountId, {
+                    sendChats: resolveAccountSendChats(cfg, accountId),
+                    operatorIds: resolveAccountOperatorIds(cfg, accountId),
                 });
+                warnAboutHandleAllowlistEntries(cfg, accountId);
                 const me = await gram.getMe();
                 const selfId = me?.id ? String(me.id) : undefined;
                 const selfUsername = (0, helpers_1.resolveActiveUsername)(me);
@@ -388,7 +354,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 const client = gram.getClient();
                 const eventBuilder = new events_1.NewMessage({});
                 const eventHandler = async (event) => (0, inbound_pipeline_1.handleInboundEvent)(event, {
-                    accountId, cfg, channelRuntime, client, gram, log, pairing,
+                    accountId, cfg, channelRuntime, client, gram, log,
                     pluginRuntime, runtimes, selfId, selfLabel, selfUsername,
                 });
                 client.addEventHandler(eventHandler, eventBuilder);
@@ -425,6 +391,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 await (0, channel_runtime_1.waitUntilAbort)(ctx.abortSignal, async () => {
                     client.removeEventHandler(eventHandler, eventBuilder);
                     client.removeEventHandler(joinEventHandler, joinEventBuilder);
+                    (0, account_registry_1.forgetAccount)(accountId);
                     const runtime = runtimes.get(accountId);
                     if (!runtime) {
                         return;
@@ -612,8 +579,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
             // bundled channels enforce them. This one used to take `filePath`
             // verbatim, so a path naming the secret store or the config holding
             // `sessionString` was uploaded like any attachment.
-            mediaLocalRoots, mediaAccess, }) => {
+            mediaLocalRoots, mediaReadFile, mediaAccess, }) => {
                 const allowedMediaRoots = mediaLocalRoots ?? mediaAccess?.localRoots;
+                const readMedia = mediaReadFile ?? mediaAccess?.readFile;
                 // Core passes the flag beside `params`; callers write it inside.
                 // Both count, because a rehearsal flag that is silently ignored puts
                 // a real message in a real chat — twice, so far (2.13.1).
@@ -640,10 +608,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         });
                         throw new Error(`clawgram: not-allowed-chat ${listParams.target}`);
                     }
-                    const listGram = runtimes.get(listAccountId);
-                    if (!listGram) {
-                        throw new Error(`clawgram: runtime not found for account ${listAccountId}`);
-                    }
+                    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.
@@ -687,10 +652,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         });
                         throw new Error(`clawgram: not-allowed-chat ${fetchParams.target}`);
                     }
-                    const fetchGram = runtimes.get(fetchAccountId);
-                    if (!fetchGram) {
-                        throw new Error(`clawgram: runtime not found for account ${fetchAccountId}`);
-                    }
+                    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
@@ -1018,10 +980,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             removed: reactionParams.remove,
                         });
                     }
-                    const reactionGram = runtimes.get(reactionAccountId);
-                    if (!reactionGram) {
-                        throw new Error(`clawgram: runtime not found for account ${reactionAccountId}`);
-                    }
+                    const reactionGram = requireRuntimeFor(reactionAccountId);
                     await reactionGram.sendReaction(reactionParams);
                     return (0, core_1.jsonResult)({
                         ok: true,
@@ -1233,13 +1192,12 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     if (!(0, send_scope_1.isChatSendable)(uploadTo, resolveAccountSendChats(cfg, uploadAccountId))) {
                         refuseOutboundOutsideScope("upload-file", uploadAccountId, uploadTo);
                     }
-                    const file = attachedFile;
-                    if (!file) {
+                    if (!attachedFile) {
                         throw new Error("clawgram: upload-file requires filePath, path, media, or mediaUrl");
                     }
                     // Before anything else about the message is considered: an
                     // out-of-scope path is refused, not sent and then regretted.
-                    (0, media_1.assertLocalMediaWithinRoots)(file, allowedMediaRoots);
+                    (0, media_1.assertLocalMediaWithinRoots)(attachedFile, allowedMediaRoots);
                     const captionText = (0, helpers_1.readMessageText)(params) || ((0, param_readers_1.readStringParam)(params, "caption") ?? "");
                     // A caption is optional, but the silent-reply sentinel must never
                     // reach Telegram as one — same reasoning as the `send` path below.
@@ -1266,10 +1224,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                             accountId: uploadAccountId,
                         });
                     }
-                    const uploadGram = runtimes.get(uploadAccountId);
-                    if (!uploadGram) {
-                        throw new Error(`clawgram: runtime not found for account ${uploadAccountId}`);
-                    }
+                    const uploadGram = requireRuntimeFor(uploadAccountId);
+                    // Read last, through core's scoped reader when it gave one: a dry
+                    // run or a refusal above must not open the file.
+                    const file = await (0, media_1.loadOutboundMedia)(attachedFile, allowedMediaRoots, readMedia);
                     const uploaded = await uploadGram.sendMedia({
                         target: uploadTo,
                         file,
@@ -1407,10 +1365,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         accountId: resolvedAccountId,
                     });
                 }
-                const gram = runtimes.get(resolvedAccountId);
-                if (!gram) {
-                    throw new Error(`clawgram: runtime not found for account ${resolvedAccountId}`);
-                }
+                const gram = requireRuntimeFor(resolvedAccountId);
                 const sent = await gram.sendText({
                     target: to,
                     text,

package/dist/chunk.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_CAPTION_LIMIT = exports.TELEGRAM_TEXT_LIMIT = void 0;
+exports.chunkTelegramText = chunkTelegramText;
+/**
+ * Telegram limits: 4096 characters per message, 1024 per media caption.
+ *
+ * Core chunks only the replies it dispatches itself; a `send` issued through
+ * the message tool — the way the guard scripts deliver reports — reaches
+ * GramJS whole, and GramJS does not split either, so a long report failed
+ * with MESSAGE_TOO_LONG and the agent saw "✉️ Message failed" while the
+ * human saw nothing (audit B5-03).
+ *
+ * Splitting prefers paragraph breaks, then line breaks, then a hard cut at
+ * the limit. It runs on the text as the agent wrote it — before HTML
+ * rendering — so a chunk boundary can only fall between the agent's own
+ * lines, never inside an entity GramJS produced.
+ */
+exports.TELEGRAM_TEXT_LIMIT = 4096;
+exports.TELEGRAM_CAPTION_LIMIT = 1024;
+function chunkTelegramText(text, limit = exports.TELEGRAM_TEXT_LIMIT) {
+    const chars = Array.from(text);
+    if (chars.length <= limit)
+        return [text];
+    const chunks = [];
+    let rest = text;
+    while (Array.from(rest).length > limit) {
+        const window = Array.from(rest).slice(0, limit).join("");
+        let cut = window.lastIndexOf("\n\n");
+        if (cut < limit / 2)
+            cut = window.lastIndexOf("\n");
+        if (cut < limit / 2)
+            cut = window.lastIndexOf(" ");
+        if (cut < limit / 2)
+            cut = window.length;
+        const piece = rest.slice(0, cut).replace(/\s+$/u, "");
+        chunks.push(piece);
+        rest = rest.slice(cut).replace(/^\s+/u, "");
+    }
+    if (rest)
+        chunks.push(rest);
+    return chunks;
+}

package/dist/gramjs-client.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GramJsClientManager = void 0;
 exports.buildParticipantsQuery = buildParticipantsQuery;
 exports.buildVoiceNoteParams = buildVoiceNoteParams;
+const chunk_1 = require("./chunk");
 const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
+const uploads_1 = require("telegram/client/uploads");
 // Deep import, but the documented one: GramJS ships its SRP helper here and
 // the package has no `exports` field to forbid it.
 const Password_1 = require("telegram/Password");
@@ -62,29 +64,6 @@ function uniqueCandidates(values) {
     }
     return result;
 }
-function parseTargetWithThread(rawTarget) {
-    const raw = rawTarget.trim();
-    const topicMatch = /^(.+?):topic:(\d+)$/.exec(raw);
-    if (topicMatch) {
-        return {
-            raw,
-            chatId: topicMatch[1],
-            messageThreadId: Number.parseInt(topicMatch[2], 10),
-        };
-    }
-    const colonMatch = /^(.+):(\d+)$/.exec(raw);
-    if (colonMatch && /^-?\d+$/.test(colonMatch[1])) {
-        return {
-            raw,
-            chatId: colonMatch[1],
-            messageThreadId: Number.parseInt(colonMatch[2], 10),
-        };
-    }
-    return {
-        raw,
-        chatId: raw,
-    };
-}
 /**
  * Membership query for `getParticipants`.
  *
@@ -313,7 +292,8 @@ class GramJsClientManager {
         // но теперь виден в логе: если он в логе частый, значит кэш не спасает и
         // адресация идёт не тем ключом (A6-14).
         peerLog.info("clawgram peer resolve falling back to dialog scan", {
-            target: raw,
+            // Цель может быть телефоном или @handle человека — в журнал идёт только её форма (B5-09).
+            targetShape: String(raw).startsWith("+") ? "phone" : String(raw).startsWith("@") ? "handle" : /^-?\d+/.test(String(raw)) ? "id" : "other",
             kind: kind ?? null,
         });
         const dialogs = await this.client.getDialogs({ limit: 200 }).catch(() => []);
@@ -356,7 +336,7 @@ class GramJsClientManager {
                 peer: entity
             };
         }
-        const parsedTarget = parseTargetWithThread(rawTarget);
+        const parsedTarget = (0, history_1.parseTargetWithThread)(rawTarget);
         const raw = parsedTarget.raw;
         const chatLookupTarget = parsedTarget.chatId;
         const kind = options?.kind;
@@ -418,6 +398,17 @@ class GramJsClientManager {
         const resolved = await this.resolvePeer(args.target, { kind: args.targetKind });
         const messageThreadId = args.messageThreadId ?? resolved.messageThreadId;
         const replyParams = buildForumReplyParams(messageThreadId, args.replyToMessageId);
+        // Длиннее лимита Telegram — несколько сообщений подряд, а не
+        // MESSAGE_TOO_LONG (B5-03). Нарезка — по тексту агента, до рендера.
+        const chunks = (0, chunk_1.chunkTelegramText)(args.text, chunk_1.TELEGRAM_TEXT_LIMIT);
+        if (chunks.length > 1) {
+            let last;
+            for (const [index, chunk] of chunks.entries()) {
+                last = await this.sendText({ ...args, text: chunk,
+                    ...(index > 0 ? { replyToMessageId: undefined } : {}) });
+            }
+            return last;
+        }
         return this.client.sendMessage(resolved.peer, {
             // In html mode the text is rendered first: the agent writes markdown,
             // Telegram HTML, or both, and GramJS's HTML parser alone would ship
@@ -757,8 +748,22 @@ class GramJsClientManager {
         const resolved = await this.resolvePeer(args.target);
         const messageThreadId = args.messageThreadId ?? resolved.messageThreadId;
         const replyParams = buildForumReplyParams(messageThreadId, args.replyToMessageId);
+        // Подпись длиннее 1024 — файл с первой частью, остальное текстом следом
+        // (B5-03); раньше вся подпись уезжала целиком и падала на лимите.
+        const captionChunks = args.caption ? (0, chunk_1.chunkTelegramText)(args.caption, chunk_1.TELEGRAM_CAPTION_LIMIT) : [];
+        if (captionChunks.length > 1) {
+            const sent = await this.sendMedia({ ...args, caption: captionChunks[0] });
+            for (const chunk of captionChunks.slice(1)) {
+                await this.sendText({ target: args.target, text: chunk, parseMode: args.parseMode, messageThreadId });
+            }
+            return sent;
+        }
         return this.client.sendFile(resolved.peer, {
-            file: args.file,
+            // Bytes core read through its scoped reader keep the file's own name;
+            // a bare Buffer would reach Telegram as "unnamed" (B5-14).
+            file: typeof args.file === "string"
+                ? args.file
+                : new uploads_1.CustomFile(args.file.fileName, args.file.buffer.length, "", args.file.buffer),
             // Captions are agent prose too — the outbound path sends `caption ??
             // text` — so they render exactly like sendText does. Before 2.15.0
             // captions carried no mode at all, which meant GramJS's default

package/dist/helpers.js

@@ -834,8 +834,11 @@ function normalizeParseMode(raw) {
  * raw markup.
  */
 function resolveReplyParseMode(cfg, accountId) {
-    const channel = cfg?.channels?.["clawgram"];
-    const account = channel?.accounts?.[accountId] ?? channel;
+    // Account level only: the schema has never allowed `replyParseMode` on the
+    // channel itself, so the old fallback to `channels.clawgram.replyParseMode`
+    // read a key `openclaw config validate` rejects — a setting that could not
+    // exist was read, and a test pinned it (audit B5-10).
+    const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
     return normalizeParseMode(account?.replyParseMode);
 }
 /**

package/dist/history.js

@@ -20,6 +20,8 @@ exports.normalizeParticipants = normalizeParticipants;
 exports.parseListParticipantsParams = parseListParticipantsParams;
 exports.buildHistoryQuery = buildHistoryQuery;
 exports.normalizeChatKey = normalizeChatKey;
+exports.normalizeScopeList = normalizeScopeList;
+exports.parseTargetWithThread = parseTargetWithThread;
 exports.chatKeyCandidates = chatKeyCandidates;
 exports.isChatReadable = isChatReadable;
 exports.isWithinWindow = isWithinWindow;
@@ -234,6 +236,20 @@ function buildHistoryQuery(args) {
 function normalizeChatKey(value) {
     return String(value ?? "").trim().replace(/^@/, "").toLowerCase();
 }
+/**
+ * A configured chat scope (`readChats`, `sendChats`, `manageChats`) as a list
+ * of chat keys — or `undefined` when the key is absent, because every gate
+ * tells "not configured" from "configured empty" by that difference.
+ *
+ * Four copies of this normalizer used to live in three files, two of them
+ * trimming only and two lowercasing, so the same entry could pass one gate
+ * and fail another (audit B5-13). One now.
+ */
+function normalizeScopeList(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    return (Array.isArray(raw) ? raw : [raw]).map(normalizeChatKey).filter(Boolean);
+}
 /**
  * Все написания одной цели, по которым её ищут в списке доступа.
  *
@@ -247,11 +263,44 @@ function normalizeChatKey(value) {
  * `-1001234:topic:5` сегодня работает как область в одну тему, и сведение
  * всего к чату молча расширило бы её на весь чат.
  */
+/**
+ * One target address, split into the chat and the forum topic it may name.
+ *
+ * Two spellings carry a topic: `-1001234:topic:5` and the short `-1001234:5`
+ * (a numeric chat, a colon, a number). This is the parser the resolver in
+ * `gramjs-client` uses, and since B5-08 the only one: the gates used to strip
+ * `:topic:N` with a regex of their own and did not know the short form, so
+ * `-1001234:5` passed the resolver as a topic of a listed chat and failed the
+ * gate as an unknown one.
+ */
+function parseTargetWithThread(rawTarget) {
+    const raw = rawTarget.trim();
+    const topicMatch = /^(.+?):topic:(\d+)$/.exec(raw);
+    if (topicMatch) {
+        return {
+            raw,
+            chatId: topicMatch[1],
+            messageThreadId: Number.parseInt(topicMatch[2], 10),
+        };
+    }
+    const colonMatch = /^(.+):(\d+)$/.exec(raw);
+    if (colonMatch && /^-?\d+$/.test(colonMatch[1])) {
+        return {
+            raw,
+            chatId: colonMatch[1],
+            messageThreadId: Number.parseInt(colonMatch[2], 10),
+        };
+    }
+    return {
+        raw,
+        chatId: raw,
+    };
+}
 function chatKeyCandidates(target) {
     const raw = String(target ?? "").trim();
     const withoutChannel = raw.replace(/^(?:clawgram|tguserbot|telegram|tg):/i, "");
     const withoutKind = withoutChannel.replace(/^(?:user|channel|group|conversation|room|dm):/i, "");
-    const chatOnly = withoutKind.replace(/:topic:\d+$/i, "");
+    const chatOnly = parseTargetWithThread(withoutKind).chatId;
     const candidates = [raw, withoutKind, chatOnly]
         .map(normalizeChatKey)
         .filter(Boolean);
@@ -280,11 +329,9 @@ function isChatReadable(target, readChats) {
     const candidates = chatKeyCandidates(target);
     if (candidates.includes(constants_1.TELEGRAM_SERVICE_CHAT_ID))
         return false;
-    if (readChats === undefined || readChats === null)
+    const entries = normalizeScopeList(readChats);
+    if (entries === undefined)
         return true;
-    const entries = (Array.isArray(readChats) ? readChats : [readChats])
-        .map(normalizeChatKey)
-        .filter(Boolean);
     // An empty list is a configured empty list — deny, rather than silently
     // reading everything because someone left brackets behind.
     if (entries.length === 0)