clawgram 2.25.0 → 2.26.1

package/README.md

@@ -714,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
@@ -728,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/account-scopes.js

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

package/dist/action-context.js

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

package/dist/actions-manage.js

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