clawgram 2.11.0 → 2.12.1

package/README.md

@@ -32,6 +32,7 @@ Clawgram is a personal-Telegram channel plugin for [OpenClaw](https://github.com
 - **Read receipts** — mark messages as read
 - **Emoji reactions** — acknowledge a message with a reaction instead of a reply (`react` action)
 - **Chat metadata** — title, type, member count, description, forum flag and pinned message (`chatInfo` action)
+- **Chat management** — create supergroups, add/remove members, promote/demote admins, transfer ownership, export invite links (`createGroup`, `addMembers`, `removeMember`, `promoteAdmin`, `demoteAdmin`, `transferOwnership`, `inviteLink`) — off until `manageChats` allows it
 - **User allowlist** — control which user has access to send messages for direct
 - **Chat allowlist** — control which chats the assistant can access
 - **Multi-account** — run multiple Telegram accounts simultaneously
@@ -226,6 +227,8 @@ openclaw gateway restart
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames for direct messages only |
 | `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 |
+| `twoFaPassword` | string \| SecretRef | unset | The account's Telegram 2FA password; read only by `transferOwnership` |
 
 Group config fields:
 
@@ -579,6 +582,58 @@ Bindings
 ```
 
 
+## Chat management
+
+Since 2.12.0 the assistant can assemble a chat, not only speak in it: create a supergroup, add and
+remove members, promote and demote admins, hand the chat to a new owner, and issue invite links.
+This exists because the plugin drives a personal MTProto account — Telegram's Bot API forbids most
+of these to bots (a bot cannot create a group, cannot add an unwilling member, and cannot transfer
+ownership at all).
+
+**Off by default.** Every action below is gated by `accounts.*.manageChats`, and the default is the
+exact opposite of `readChats`: absent or empty means *manage nothing*, a list of chat ids confines
+management to those chats, `["*"]` allows every chat. A non-empty list also unlocks `createGroup`
+(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 |
+
+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,
+recent contact) — Telegram refuses to look up strangers by id.
+
+**Ownership transfer fine print.** Telegram guards `transferOwnership` with an SRP proof of the
+account's two-step-verification password, so the password has to be available to the runtime:
+`accounts.*.twoFaPassword`, either a literal or a [SecretRef](#keeping-credentials-out-of-the-config-file).
+It is read only by this action, exchanged for the SRP proof in-process, and never travels through
+action parameters or logs. Telegram additionally refuses the transfer when 2FA was enabled less
+than 7 days ago (`PASSWORD_TOO_FRESH_*`), when the session is younger than 24 hours
+(`SESSION_TOO_FRESH_*`), or when the new owner is not yet an admin of the chat — promote them
+first. These errors are surfaced as-is rather than retried.
+
+```json
+{
+  "channels": {
+    "clawgram": {
+      "accounts": {
+        "default": {
+          "manageChats": [ "-1001234567890" ],
+          "twoFaPassword": { "source": "file", "provider": "corp", "id": "/telegram/2fa-password" }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Security and privacy
 
 This plugin holds credentials for a real Telegram account and handles private correspondence. What
@@ -590,6 +645,8 @@ that means in practice, and what the code does about it:
 | Proxy password | `accounts.*.proxy.password`, or a secret store | Also accepts a SecretRef since 2.2.0. Marked `sensitive` in `uiHints`; diagnostics say `socks4`/`socks5` and nothing more. An invalid proxy fails the account rather than falling back to a direct connection, which would leak the host IP to Telegram |
 | Message bodies | channel logs | **Not logged.** Outbound sends record recipient, ids and `textLength`. Until 2.1.0 the full outbound text was written to the channel log — if you ran 2.0.x, treat those journal entries as containing private correspondence |
 | Read scope | `accounts.*.readChats` | History and membership reads are confined to the listed chats. Absent means no restriction; an empty array denies everything |
+| Manage scope | `accounts.*.manageChats` | Creating groups, changing membership, admin rights, ownership and invite links are confined to the listed chats — and **off entirely** when the key is absent or empty (opposite default to `readChats`, because these actions change chats rather than read them) |
+| 2FA password | `accounts.*.twoFaPassword`, or a secret store | Read only by `transferOwnership`, exchanged for an SRP proof in-process. Accepts a SecretRef since 2.12.0; `sensitive` in `uiHints`; on the forbidden-log-keys list the static tests enforce |
 | Who may talk to it | `allowFrom`, `groups.*.groupPolicy` | Direct-message senders and group behaviour are allowlisted; `mention` limits group replies to explicit mentions |
 
 Two static tests (`test/no-secret-logging.test.ts`) fail the build if a message body or a credential

package/dist/channel.js

@@ -58,6 +58,7 @@ const normalize_1 = require("./normalize");
 const history_1 = require("./history");
 const joins_1 = require("./joins");
 const reactions_1 = require("./reactions");
+const manage_1 = require("./manage");
 const silent_reaction_1 = require("./silent-reaction");
 const chat_info_1 = require("./chat-info");
 const secret_refs_1 = require("./secret-refs");
@@ -126,6 +127,48 @@ function readAccountReadChats(account) {
 function resolveAccountReadChats(cfg, accountId) {
     return readAccountReadChats(cfg?.channels?.["clawgram"]?.accounts?.[accountId]);
 }
+/**
+ * Management scope as configured. Handed to `isChatManageable` raw: unlike
+ * `readChats`, an absent value already means "deny", so there is nothing to
+ * tell apart here.
+ */
+function resolveAccountManageChats(cfg, accountId) {
+    return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.manageChats;
+}
+/** 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);
+}
+/** Canonical management action for every accepted spelling. */
+const MANAGE_ACTION_ALIASES = {
+    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;
@@ -294,6 +337,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "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 `chatInfo` action to learn what a chat is — title, type, member count, description, pinned message — instead of guessing from its id.",
+                "Use `createGroup` (title, optional about, optional users) to create a new Telegram supergroup; `addMembers`/`removeMember` change who is in a managed chat, `promoteAdmin`/`demoteAdmin` grant or revoke admin rights, `transferOwnership` hands the chat over, `inviteLink` issues an invite link for people Telegram refused to add directly.",
             ],
             messageToolCapabilities: () => [
                 "clawgram can reply in the current Telegram conversation when no explicit target is provided.",
@@ -301,6 +345,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "clawgram supports Telegram forum topics via the `threadId` parameter on group sends.",
                 "clawgram can add and clear emoji reactions on messages. A plain Telegram account holds one reaction per message, so a new emoji replaces the previous one.",
                 "clawgram can describe a chat via `chatInfo`: title, type (direct/group/supergroup/channel), member count, description, whether it is a forum, and the pinned message id.",
+                "clawgram can manage chats where the account's manageChats config allows it: create supergroups, add and remove members, promote and demote admins, transfer ownership, and export invite links.",
             ],
         },
         config: {
@@ -328,6 +373,11 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // client from a config object this function had already stripped it
                     // from, so the setting validated, deployed and did nothing.
                     replyParseMode: account?.replyParseMode,
+                    manageChats: readAccountManageChats(account),
+                    // Optional secret: absent must stay absent, not become "".
+                    twoFaPassword: account?.twoFaPassword === undefined || account?.twoFaPassword === null
+                        ? undefined
+                        : (0, secret_refs_1.readSecretInput)(account.twoFaPassword),
                 };
             },
         },
@@ -1241,7 +1291,13 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // Leaving it out does not degrade to a text send: the agent simply
                     // never sees a way to send the file, announces it in words, and the
                     // file stays on disk. That is exactly what happened on 2026-08-07.
-                    actions: ["send", "read", "participants", "joins", "react", "chatInfo", "upload-file"],
+                    actions: [
+                        "send", "read", "participants", "joins", "react", "chatInfo", "upload-file",
+                        // Chat management (2.12.0) — gated by the account's manageChats
+                        // scope; without it every one of these is refused.
+                        "createGroup", "addMembers", "removeMember",
+                        "promoteAdmin", "demoteAdmin", "transferOwnership", "inviteLink",
+                    ],
                     capabilities: [],
                     mediaSourceParams: {
                         "upload-file": ["filePath", "path", "media"],
@@ -1432,6 +1488,220 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         removed: reactionParams.remove,
                     });
                 }
+                // ---- 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 = MANAGE_ACTION_ALIASES[action];
+                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)) {
+                            actionLog.warn("clawgram management refused: chat outside manage scope", {
+                                accountId: manageAccountId,
+                                action: manageAction,
+                                target,
+                            });
+                            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", {
+                            accountId: manageAccountId,
+                            dryRun: dryRun === true,
+                            users: createParams.users.length,
+                            hasAbout: Boolean(createParams.about),
+                        });
+                        if (dryRun === true) {
+                            return (0, core_1.jsonResult)({ ok: true, dryRun: true, accountId: manageAccountId });
+                        }
+                        const created = await requireRuntime().createGroup(createParams);
+                        actionLog.info("clawgram handleAction createGroup completed", {
+                            accountId: manageAccountId,
+                            chatId: created.chatId ?? null,
+                            missing: created.missing.length,
+                        });
+                        return (0, core_1.jsonResult)({
+                            ok: true,
+                            accountId: manageAccountId,
+                            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,
+                        });
+                    }
+                    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,
+                        });
+                    }
+                    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 } : {}),
+                        });
+                    }
+                    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,
+                        });
+                    }
+                    // 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,
+                    });
+                }
                 // Core normalizes whichever of these it filled in to a local path (see
                 // `mediaSourceParams` above); `mediaUrl` stays a URL, which GramJS
                 // accepts as well.

package/dist/gramjs-client.js

@@ -4,10 +4,14 @@ exports.GramJsClientManager = void 0;
 exports.buildVoiceNoteParams = buildVoiceNoteParams;
 const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
+// 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");
 const helpers_1 = require("./helpers");
 const proxy_config_1 = require("./proxy-config");
 const secret_refs_1 = require("./secret-refs");
 const history_1 = require("./history");
+const manage_1 = require("./manage");
 function toStringId(value) {
     if (value === null || value === undefined)
         return undefined;
@@ -562,5 +566,189 @@ class GramJsClientManager {
             ...buildVoiceNoteParams(args.asVoice),
         });
     }
+    // ---- Chat management (2.12.0) ----
+    //
+    // Transport only: parameter parsing, the manageChats gate and the readers
+    // for what these calls return live in `manage.ts`, where they are tested.
+    // GramJS resolves EntityLike fields itself (every request below carries a
+    // `resolve()` step), so user references travel as the strings the caller
+    // supplied — `@username` always works; a bare numeric id only when this
+    // account has already seen the user.
+    /** The account's 2FA password, if configured — needed only to transfer ownership. */
+    get twoFaPassword() {
+        const value = this.config.twoFaPassword;
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    /** True when the resolved chat is a supergroup/channel rather than a basic group. */
+    isChannelLike(resolved, fallback) {
+        const chatType = resolved.chatType ?? inferChatTypeFromRaw(String(resolved.chatId ?? fallback));
+        return chatType === "channel";
+    }
+    /**
+     * The id a basic-group request wants: positive, without the `-` the rest of
+     * this plugin prefixes. Taken from the resolved peer when possible — that is
+     * the exact value Telegram handed us.
+     */
+    basicChatId(resolved, fallback) {
+        const fromPeer = resolved.peer?.chatId;
+        if (fromPeer !== undefined && fromPeer !== null) {
+            return fromPeer;
+        }
+        return String(resolved.chatId ?? fallback).replace(/^-/, "");
+    }
+    /**
+     * Creates a supergroup (megagroup) and invites the initial members.
+     *
+     * A supergroup rather than a basic group on purpose: granular admin rights,
+     * bans and ownership transfer only exist there, and those are the point of
+     * managing a chat. Members are added in a second call because
+     * `CreateChannel` does not take them; who could not be added (privacy
+     * settings) is reported, not thrown — that is an expected outcome and the
+     * caller's cue to send an invite link.
+     */
+    async createGroup(args) {
+        const updates = await this.client.invoke(new telegram_1.Api.channels.CreateChannel({
+            title: args.title,
+            about: args.about ?? "",
+            megagroup: true,
+        }));
+        const chatId = (0, manage_1.resolveCreatedChannelId)(updates);
+        if (args.users.length === 0) {
+            return { chatId, missing: [] };
+        }
+        // The Channel object out of the same Updates is the most reliable handle:
+        // it carries the access hash, and needs no entity-cache round trip.
+        const createdEntity = (updates?.chats ?? []).find((chat) => chat?.className === "Channel");
+        if (!createdEntity) {
+            throw new Error("clawgram: group created, but Telegram's answer carried no channel to invite into");
+        }
+        const invited = await this.client.invoke(new telegram_1.Api.channels.InviteToChannel({
+            channel: createdEntity,
+            users: args.users,
+        }));
+        return { chatId, missing: (0, manage_1.summarizeMissingInvitees)(invited) };
+    }
+    /**
+     * Adds members to an existing chat. Supergroups take the whole list in one
+     * call and report who was refused; basic groups only add one user per call,
+     * so refusals are collected per user instead of failing the batch.
+     */
+    async addChatMembers(args) {
+        const resolved = await this.resolvePeer(args.target, { kind: "group" });
+        if (this.isChannelLike(resolved, args.target)) {
+            const invited = await this.client.invoke(new telegram_1.Api.channels.InviteToChannel({
+                channel: resolved.peer,
+                users: args.users,
+            }));
+            return { chatId: resolved.chatId, missing: (0, manage_1.summarizeMissingInvitees)(invited) };
+        }
+        const chatId = this.basicChatId(resolved, args.target);
+        const missing = [];
+        for (const user of args.users) {
+            try {
+                // fwdLimit is how much recent history the newcomer sees; 50 is
+                // Telegram's own default in official clients.
+                await this.client.invoke(new telegram_1.Api.messages.AddChatUser({
+                    chatId: chatId,
+                    userId: user,
+                    fwdLimit: 50,
+                }));
+            }
+            catch {
+                missing.push(user);
+            }
+        }
+        return { chatId: resolved.chatId, missing };
+    }
+    /**
+     * Removes a member. In a supergroup removal is a ban that may then be
+     * lifted: lifting it (the default) leaves the person able to come back by
+     * invite, keeping the ban makes the removal stick. Basic groups have no ban
+     * concept, so there the two collapse into plain removal.
+     */
+    async removeChatMember(args) {
+        const resolved = await this.resolvePeer(args.target, { kind: "group" });
+        if (this.isChannelLike(resolved, args.target)) {
+            await this.client.invoke(new telegram_1.Api.channels.EditBanned({
+                channel: resolved.peer,
+                participant: args.user,
+                bannedRights: new telegram_1.Api.ChatBannedRights({ untilDate: 0, viewMessages: true }),
+            }));
+            if (!args.ban) {
+                await this.client.invoke(new telegram_1.Api.channels.EditBanned({
+                    channel: resolved.peer,
+                    participant: args.user,
+                    bannedRights: new telegram_1.Api.ChatBannedRights({ untilDate: 0 }),
+                }));
+            }
+            return;
+        }
+        await this.client.invoke(new telegram_1.Api.messages.DeleteChatUser({
+            chatId: this.basicChatId(resolved, args.target),
+            userId: args.user,
+            revokeHistory: false,
+        }));
+    }
+    /**
+     * Grants or revokes admin rights. Supergroups take the granular set; basic
+     * groups only know a boolean, so the rights collapse to `isAdmin` there.
+     */
+    async setChatAdmin(args) {
+        const resolved = await this.resolvePeer(args.target, { kind: "group" });
+        if (this.isChannelLike(resolved, args.target)) {
+            await this.client.invoke(new telegram_1.Api.channels.EditAdmin({
+                channel: resolved.peer,
+                userId: args.user,
+                adminRights: new telegram_1.Api.ChatAdminRights({ ...args.rights }),
+                rank: args.rank ?? "",
+            }));
+            return;
+        }
+        await this.client.invoke(new telegram_1.Api.messages.EditChatAdmin({
+            chatId: this.basicChatId(resolved, args.target),
+            userId: args.user,
+            isAdmin: args.isAdmin,
+        }));
+    }
+    /**
+     * Hands the chat to a new owner. Telegram demands an SRP proof of the
+     * account's 2FA password for this — the one action here that cannot be
+     * softened or undone by the old owner, so the proof is the ceremony.
+     *
+     * The password never leaves this object: it is read from the resolved
+     * account config, exchanged for the SRP check, and the check is what goes
+     * to Telegram. Callers pass who and where, never the secret.
+     */
+    async transferChatOwnership(args) {
+        const password = this.twoFaPassword;
+        if (!password) {
+            throw new Error("clawgram: ownership transfer requires twoFaPassword in the account config");
+        }
+        const resolved = await this.resolvePeer(args.target, { kind: "group" });
+        if (!this.isChannelLike(resolved, args.target)) {
+            throw new Error("clawgram: ownership of a basic group cannot be transferred — Telegram only supports this for supergroups");
+        }
+        const srp = await this.client.invoke(new telegram_1.Api.account.GetPassword());
+        const check = await (0, Password_1.computeCheck)(srp, password);
+        await this.client.invoke(new telegram_1.Api.channels.EditCreator({
+            channel: resolved.peer,
+            userId: args.user,
+            password: check,
+        }));
+    }
+    /** Issues an invite link — the path for people whose privacy settings refuse a direct add. */
+    async exportChatInviteLink(args) {
+        const resolved = await this.resolvePeer(args.target, { kind: "group" });
+        const exported = await this.client.invoke(new telegram_1.Api.messages.ExportChatInvite({
+            peer: resolved.peer,
+            ...(args.expireDate !== undefined ? { expireDate: args.expireDate } : {}),
+            ...(args.usageLimit !== undefined ? { usageLimit: args.usageLimit } : {}),
+            ...(args.title ? { title: args.title } : {}),
+            // Presence flips the flag, so the key only exists when asked for —
+            // the same lesson the proxy config paid for (see MTProxy note there).
+            ...(args.requestNeeded ? { requestNeeded: true } : {}),
+        }));
+        return { link: (0, manage_1.readInviteLink)(exported) };
+    }
 }
 exports.GramJsClientManager = GramJsClientManager;

package/dist/history.js

@@ -18,6 +18,7 @@ exports.parseMessageId = parseMessageId;
 exports.parseListMessagesParams = parseListMessagesParams;
 exports.parseListParticipantsParams = parseListParticipantsParams;
 exports.buildHistoryQuery = buildHistoryQuery;
+exports.normalizeChatKey = normalizeChatKey;
 exports.isChatReadable = isChatReadable;
 exports.isWithinWindow = isWithinWindow;
 exports.normalizeHistoryMessage = normalizeHistoryMessage;

package/dist/manage.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * Chat management — assembling a team chat, as opposed to speaking in it.
+ *
+ * Creating a group, adding and removing people, appointing admins and handing
+ * the chat over are what a manager does with their own account, and the
+ * account this plugin drives is exactly that. Telegram's Bot API forbids most
+ * of this; MTProto does not, which is why these actions exist here and not in
+ * a bot.
+ *
+ * Everything in this file is pure — parameter parsing, the management scope
+ * gate, and readers for the TL shapes the calls return — so it can be tested
+ * without a Telegram client. The transport lives in `GramJsClientManager`.
+ *
+ * The scope gate is deliberately opposite to reading: an absent `readChats`
+ * means "read anywhere", an absent `manageChats` means "manage nothing".
+ * Reading is what the plugin is for; rearranging chats and kicking people is
+ * not something a fresh install may do because nobody said no.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_ADMIN_RIGHTS = exports.DEFAULT_ADMIN_RIGHTS = void 0;
+exports.parseCreateGroupParams = parseCreateGroupParams;
+exports.parseAddMembersParams = parseAddMembersParams;
+exports.parseRemoveMemberParams = parseRemoveMemberParams;
+exports.parsePromoteAdminParams = parsePromoteAdminParams;
+exports.parseDemoteAdminParams = parseDemoteAdminParams;
+exports.parseTransferOwnershipParams = parseTransferOwnershipParams;
+exports.parseInviteLinkParams = parseInviteLinkParams;
+exports.isManagementEnabled = isManagementEnabled;
+exports.isChatManageable = isChatManageable;
+exports.resolveCreatedChannelId = resolveCreatedChannelId;
+exports.summarizeMissingInvitees = summarizeMissingInvitees;
+exports.readInviteLink = readInviteLink;
+const history_1 = require("./history");
+function readString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** A user reference: `@username` or a numeric id, as a trimmed string. */
+function readUserRef(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(Math.trunc(value));
+    }
+    return readString(value);
+}
+function readTarget(params, toolContext, action) {
+    const raw = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
+    const target = readString(raw);
+    if (!target) {
+        throw new Error(`clawgram: ${action} requires a chatId`);
+    }
+    return target;
+}
+function readUserList(params) {
+    const raw = params.users ?? params.members ?? params.user ?? params.userId;
+    const entries = Array.isArray(raw) ? raw : raw === undefined || raw === null ? [] : [raw];
+    return entries
+        .map(readUserRef)
+        .filter((entry) => Boolean(entry));
+}
+function readSingleUser(params, action) {
+    const user = readUserRef(params.user ?? params.userId ?? params.member);
+    if (!user) {
+        throw new Error(`clawgram: ${action} requires a user`);
+    }
+    return user;
+}
+/** Only a literal `true` (or its string form) turns a dangerous flag on. */
+function readFlag(value) {
+    return value === true || value === "true";
+}
+function parseCreateGroupParams(params) {
+    const title = readString(params.title ?? params.name);
+    if (!title) {
+        throw new Error("clawgram: createGroup requires a title");
+    }
+    return {
+        title,
+        about: readString(params.about ?? params.description),
+        users: readUserList(params),
+    };
+}
+function parseAddMembersParams(params, toolContext) {
+    const target = readTarget(params, toolContext, "addMembers");
+    const users = readUserList(params);
+    if (users.length === 0) {
+        throw new Error("clawgram: addMembers requires users to add");
+    }
+    return { target, users };
+}
+function parseRemoveMemberParams(params, toolContext) {
+    return {
+        target: readTarget(params, toolContext, "removeMember"),
+        user: readSingleUser(params, "removeMember"),
+        ban: readFlag(params.ban),
+    };
+}
+/**
+ * What a team admin gets: run the room, not the hierarchy. `addAdmins` and
+ * `anonymous` are escalation and impersonation respectively, and each must be
+ * an explicit choice, never a default.
+ */
+exports.DEFAULT_ADMIN_RIGHTS = Object.freeze({
+    changeInfo: true,
+    postMessages: false,
+    editMessages: false,
+    deleteMessages: true,
+    banUsers: true,
+    inviteUsers: true,
+    pinMessages: true,
+    addAdmins: false,
+    anonymous: false,
+    manageCall: true,
+    manageTopics: true,
+});
+exports.NO_ADMIN_RIGHTS = Object.freeze({
+    changeInfo: false,
+    postMessages: false,
+    editMessages: false,
+    deleteMessages: false,
+    banUsers: false,
+    inviteUsers: false,
+    pinMessages: false,
+    addAdmins: false,
+    anonymous: false,
+    manageCall: false,
+    manageTopics: false,
+});
+function parsePromoteAdminParams(params, toolContext) {
+    const target = readTarget(params, toolContext, "promoteAdmin");
+    const user = readSingleUser(params, "promoteAdmin");
+    const rights = { ...exports.DEFAULT_ADMIN_RIGHTS };
+    const overrides = params.rights;
+    if (overrides && typeof overrides === "object") {
+        for (const key of Object.keys(rights)) {
+            const value = overrides[key];
+            // Only a real boolean overrides: a string "true" here would be a typo'd
+            // config, and rights are not the place to guess.
+            if (typeof value === "boolean") {
+                rights[key] = value;
+            }
+        }
+    }
+    return {
+        target,
+        user,
+        isAdmin: true,
+        rights,
+        rank: readString(params.rank ?? params.title),
+    };
+}
+function parseDemoteAdminParams(params, toolContext) {
+    return {
+        target: readTarget(params, toolContext, "demoteAdmin"),
+        user: readSingleUser(params, "demoteAdmin"),
+        isAdmin: false,
+        rights: { ...exports.NO_ADMIN_RIGHTS },
+    };
+}
+function parseTransferOwnershipParams(params, toolContext) {
+    return {
+        target: readTarget(params, toolContext, "transferOwnership"),
+        user: readSingleUser(params, "transferOwnership"),
+    };
+}
+function parseExpireDate(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (/^\d+$/.test(trimmed)) {
+            return Number.parseInt(trimmed, 10);
+        }
+        const parsed = Date.parse(trimmed);
+        if (Number.isFinite(parsed)) {
+            return Math.floor(parsed / 1000);
+        }
+    }
+    // A link that was meant to expire and silently does not is a standing hole
+    // in the chat's boundary — refuse rather than degrade.
+    throw new Error("clawgram: inviteLink expireDate must be unix seconds or an ISO date");
+}
+function parseUsageLimit(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    const parsed = typeof value === "number" ? value : Number(String(value).trim());
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("clawgram: inviteLink usageLimit must be a positive number");
+    }
+    return Math.trunc(parsed);
+}
+function parseInviteLinkParams(params, toolContext) {
+    return {
+        target: readTarget(params, toolContext, "inviteLink"),
+        expireDate: parseExpireDate(params.expireDate ?? params.expiresAt),
+        usageLimit: parseUsageLimit(params.usageLimit ?? params.memberLimit),
+        title: readString(params.title ?? params.label),
+        requestNeeded: readFlag(params.requestNeeded ?? params.requireApproval),
+    };
+}
+function normalizeScope(manageChats) {
+    if (manageChats === undefined || manageChats === null) {
+        return [];
+    }
+    return (Array.isArray(manageChats) ? manageChats : [manageChats])
+        .map(history_1.normalizeChatKey)
+        .filter(Boolean);
+}
+/** True while the account is allowed to manage anything at all. */
+function isManagementEnabled(manageChats) {
+    return normalizeScope(manageChats).length > 0;
+}
+/**
+ * The management gate. Absent, null and empty all deny: management is opt-in,
+ * and the wildcard has to be written down to mean "everywhere".
+ */
+function isChatManageable(target, manageChats) {
+    const entries = normalizeScope(manageChats);
+    if (entries.length === 0) {
+        return false;
+    }
+    if (entries.includes("*")) {
+        return true;
+    }
+    return entries.includes((0, history_1.normalizeChatKey)(target));
+}
+/**
+ * The id of the supergroup a `channels.CreateChannel` call just created, read
+ * from the `Updates` it returns, in the `-100…` form the rest of this plugin
+ * speaks. GramJS carries ids as `big-integer` objects as often as native
+ * numbers, so the id goes through `String` rather than arithmetic.
+ */
+function resolveCreatedChannelId(updates) {
+    const chats = updates?.chats;
+    if (!Array.isArray(chats)) {
+        return undefined;
+    }
+    for (const chat of chats) {
+        if (chat?.className !== "Channel") {
+            continue;
+        }
+        const id = chat?.id;
+        if (id === undefined || id === null) {
+            continue;
+        }
+        const asString = String(id).trim();
+        if (asString && asString !== "[object Object]") {
+            return `-100${asString.replace(/^-100|-/, "")}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Who Telegram refused to add, as user ids. Privacy settings make this an
+ * expected outcome, not an error: the caller is told exactly who still needs
+ * an invite link instead of the whole call failing.
+ */
+function summarizeMissingInvitees(result) {
+    const missing = result?.missingInvitees;
+    if (!Array.isArray(missing)) {
+        return [];
+    }
+    const ids = [];
+    for (const entry of missing) {
+        const id = entry?.userId;
+        if (id === undefined || id === null) {
+            continue;
+        }
+        const asString = String(id).trim();
+        if (asString && asString !== "[object Object]") {
+            ids.push(asString);
+        }
+    }
+    return ids;
+}
+/** The link out of a `TypeExportedChatInvite`, or nothing when there is none. */
+function readInviteLink(result) {
+    return readString(result?.link);
+}

package/dist/secret-refs.js

@@ -24,7 +24,7 @@ exports.applyAccountSecrets = applyAccountSecrets;
 exports.hasUnresolvedSecretRef = hasUnresolvedSecretRef;
 exports.readSecretInput = readSecretInput;
 /** Credential fields that accept a reference, in the order they are reported. */
-const ACCOUNT_SECRET_FIELDS = ["apiHash", "sessionString"];
+const ACCOUNT_SECRET_FIELDS = ["apiHash", "sessionString", "twoFaPassword"];
 const PROXY_SECRET_FIELDS = ["username", "password"];
 /**
  * Must match OpenClaw's own keying, or every lookup misses and a correctly

package/dist/silent-reaction.js

@@ -46,8 +46,19 @@ function buildEmojiSystemPrompt(appetite, allowed) {
         `- the message is about producing something written — a text, a reply, a document, a draft → ✍`,
         "Otherwise match the mood: a joke gets something amused, bad news something",
         "sympathetic, an achievement something celebratory.",
-        "Answer NONE when the message is conflictual, heavy, or discusses a person's",
-        "performance — a reaction there reads as a verdict on someone.",
+        "Answer NONE when the message is conflictual or heavy, or when it judges",
+        "SOMEONE ELSE's work or behaviour — a reaction there reads as a verdict on",
+        "that person.",
+        // Without this the NONE rule swallowed the praise rule: "молодец тина" is
+        // literally a statement about someone's performance, the model applied the
+        // rule as written, and answered NONE to being praised. The carve-out
+        // exists in the assistant's own rules — the ban on judging people protects
+        // others, not itself — and had to be repeated here.
+        "That restraint protects other people and does NOT apply to the assistant",
+        "itself. Praise, teasing, thanks or criticism aimed at the assistant is",
+        "exactly what the fixed answers above are for: being called clever, useful",
+        "or 'молодец' is praise → ❤, not a verdict on a third party.",
+        "When a fixed answer applies, it wins over the mood rule.",
     ];
     return appetite === "minimal"
         ? [

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -322,6 +322,47 @@
                   },
                   "description": "Chat ids the account may read history and membership for. Absent means no restriction; an empty array denies everything."
                 },
+                "manageChats": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Chat ids the account may MANAGE (2.12.0): add/remove members, promote/demote admins, transfer ownership, export invite links; a non-empty list also unlocks createGroup. Opposite default to readChats: absent or empty means chat management is off, [\"*\"] allows every chat."
+                },
+                "twoFaPassword": {
+                  "description": "The account's Telegram 2FA (cloud) password — needed only by transferOwnership, which Telegram guards with an SRP proof. Literal value, or a SecretRef resolved at account start-up.",
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "source",
+                        "provider",
+                        "id"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "source": {
+                          "enum": [
+                            "env",
+                            "file",
+                            "exec"
+                          ]
+                        },
+                        "provider": {
+                          "type": "string",
+                          "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+                        },
+                        "id": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      }
+                    }
+                  ]
+                },
                 "joinsJournalPath": {
                   "type": "string",
                   "description": "Where joins observed for this account are journalled. Defaults to a per-account file under the OpenClaw state directory."
@@ -356,6 +397,17 @@
         }
       },
       "uiHints": {
+        "accounts.*.manageChats": {
+          "label": "Managed Chats",
+          "help": "Chat ids the assistant may manage (create groups, add/remove members, admins, ownership, invite links). Leave empty to keep chat management off; use * to allow every chat.",
+          "advanced": true
+        },
+        "accounts.*.twoFaPassword": {
+          "label": "2FA Password",
+          "help": "The account's Telegram two-step verification password. Only needed for ownership transfer.",
+          "sensitive": true,
+          "advanced": true
+        },
         "accounts.*.proxy": {
           "label": "SOCKS Proxy",
           "help": "Optional native SOCKS4/SOCKS5 proxy for this account's MTProto connection. GramJS uses raw TCP sockets, so OpenClaw's proxy.proxyUrl does not cover it. This is a SOCKS proxy, not a Telegram MTProxy.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {