@ardennguyen/zalo-agent-cli 2.5.1 → 2.5.3

package/src/core/sync.js

@@ -1,11 +1,7 @@
-import fs from "fs";
 import { resolve } from "path";
-import crypto from "crypto";
 import { getAccountDir } from "./credentials.js";
 import {
     initDb,
-    insertMessage,
-    upsertThread,
     getSyncState,
     setSyncState,
     recordSyncGap,
@@ -42,95 +38,14 @@ export const MAX_GAP_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
  */
 export const SYNC_FRESHNESS_MS = 60 * 60 * 1000; // 1 hour
 
-/**
- * Best-effort field aliases for a single synced message, mirroring the shape
- * `src/commands/listen.js` already normalizes live WS messages into before
- * calling insertMessage()/upsertThread(). The exact shape of a `get_crossdb`
- * message record hasn't been confirmed against real data yet (see
- * agent/docs/mobile-sync-live-test-results.md) — this stays defensive and
- * falls back to the raw dump file whenever a record doesn't look recognizable,
- * rather than silently dropping or mis-storing it.
- */
-function normalizeSyncedMessage(raw) {
-    if (!raw || typeof raw !== "object") return null;
-
-    const msgId = raw.msgId ?? raw.msg_id ?? raw.cliMsgId ?? raw.cli_msg_id;
-    const threadId = raw.threadId ?? raw.toId ?? raw.to_uid ?? raw.groupId ?? raw.uidTo;
-    if (!msgId || !threadId) return null;
-
-    const senderId = raw.uidFrom ?? raw.fromUid ?? raw.senderId ?? raw.from_uid ?? "";
-    const senderName = raw.dName ?? raw.displayName ?? raw.senderName ?? "";
-    const rawContent = raw.content ?? raw.text ?? raw.msg ?? null;
-    const isText = typeof rawContent === "string";
-    const msgType = raw.msgType ?? raw.msg_type ?? null;
-    const timestamp = raw.ts ? Number(raw.ts) : raw.timestamp ? Number(raw.timestamp) : Date.now();
-    const isGroup = raw.type === 1 || raw.isGroup === true || !!raw.groupId;
-
-    return {
-        msgId: String(msgId),
-        threadId: String(threadId),
-        senderId: String(senderId),
-        senderName: String(senderName),
-        text: isText ? rawContent : rawContent ? JSON.stringify(rawContent) : "",
-        timestamp,
-        type: isText ? "text" : msgType || "attachment",
-        raw_data: rawContent,
-        threadType: isGroup ? "group" : "dm",
-    };
-}
-
-/** Pull out a plausible array of message-like records from whatever shape
- * getCrossDB's decrypted payload turns out to have (object/array/JSON string). */
-function extractMessageRecords(payload) {
-    let parsed = payload;
-    if (typeof parsed === "string") {
-        try {
-            parsed = JSON.parse(parsed);
-        } catch {
-            return []; // not JSON — nothing we can map into rows
-        }
-    }
-    if (Array.isArray(parsed)) return parsed;
-    if (parsed && typeof parsed === "object") {
-        for (const key of ["msgs", "messages", "data", "list", "items"]) {
-            if (Array.isArray(parsed[key])) return parsed[key];
-        }
-    }
-    return [];
-}
-
 export class SyncManager {
     constructor(api, accountName) {
         this.api = api;
         this.accountName = accountName;
         this.accountDir = resolveAccountDir(accountName);
-        this.syncSessionDir = resolve(this.accountDir, "sync");
-        if (!fs.existsSync(this.syncSessionDir)) {
-            fs.mkdirSync(this.syncSessionDir, { recursive: true });
-        }
-        this.keys = this._loadOrGenerateKeys();
         this.dbInitialized = false;
     }
 
-    _loadOrGenerateKeys() {
-        const keyFile = resolve(this.syncSessionDir, "rsa_keys.json");
-        if (fs.existsSync(keyFile)) {
-            return JSON.parse(fs.readFileSync(keyFile, "utf8"));
-        }
-        const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
-            modulusLength: 2048,
-            publicKeyEncoding: { type: "spki", format: "pem" },
-            privateKeyEncoding: { type: "pkcs8", format: "pem" },
-        });
-        const pubKeyRaw = publicKey
-            .replace(/-----BEGIN PUBLIC KEY-----/g, "")
-            .replace(/-----END PUBLIC KEY-----/g, "")
-            .replace(/\n/g, "");
-        const keys = { publicKey: pubKeyRaw, privateKey };
-        fs.writeFileSync(keyFile, JSON.stringify(keys), "utf8");
-        return keys;
-    }
-
     /** Lazily open the same zalo.db the `listen` daemon uses, so synced
      * messages land in the exact same queryable cache as live-listened ones,
      * and so gap/state bookkeeping is shared between `listen` and `sync-mobile`
@@ -163,8 +78,8 @@ export class SyncManager {
     }
 
     /** Called whenever we're confidently caught up (e.g. right after the WS
-     * reports "connected", or right after startup with no prior gap) so the
-     * debounce check in pollSync() has an accurate picture. */
+     * reports "connected", or right after startup with no prior gap) so
+     * sync freshness checks have an accurate picture. */
     markConnected() {
         this._ensureDb();
         setSyncState("lastConnectedAt", Date.now());
@@ -197,7 +112,7 @@ export class SyncManager {
      * This single marker is what {@link checkSyncFreshness} reads, so every
      * sync path that reaches the server should call it on success.
      *
-     * @param {string} [kind] - which path completed ("backfill" | "legacy" | "transfer").
+     * @param {string} [kind] - which path completed ("backfill" | "transfer").
      * @param {{coveredFrom?: number}} [opts] - ms epoch this run reached back to,
      *   for the paths that know their window (transfer-sync does; the socket
      *   backfill does not). Recorded so a later, WIDER sync is not suppressed
@@ -213,7 +128,7 @@ export class SyncManager {
 
     /**
      * ms epoch the last successful sync reached back to, or null when that
-     * path never recorded a window (socket backfill, legacy, or a db written
+     * path never recorded a window (socket backfill, or a db written
      * before this marker existed).
      *
      * @returns {number|null}
@@ -279,90 +194,6 @@ export class SyncManager {
         return out(false, "stale");
     }
 
-    /**
-     * One full sync cycle:
-     *  1. pullMobileMsg() — nudges the phone and gets back a short opaque
-     *     token (confirmed live: 64 raw bytes, NOT message content — see
-     *     agent/docs/mobile-sync-live-test-results.md). Earlier code treated
-     *     this token itself as "the sync data" and stopped here, which meant
-     *     it never actually retrieved anything.
-     *  2. getCrossDB(token) — the actual retrieval call. Only call this once
-     *     we have a token from step 1.
-     *  3. Parse + store whatever comes back into zalo.db via the same
-     *     insertMessage()/upsertThread() helpers the `listen` daemon uses.
-     *  4. deleteSnapshotMobileMsg() to ack completion, regardless of whether
-     *     step 3 found anything, so the pending server-side request is
-     *     cleaned up either way.
-     *
-     * By default this is gap-aware and debounced (task #3): if we have no
-     * recorded pending gap and our last known connection state was healthy,
-     * it returns `{status: "already-synced", cached: true}` immediately
-     * instead of calling the mobile API — mirroring what Zalo Web itself does
-     * (confirmed live: its own IndexedDB `missing_message_range` table is
-     * what gates whether clicking "Sync" re-pings the phone or just reports
-     * success instantly). Pass `{force: true}` to bypass this and always hit
-     * the API, e.g. for the explicit `sync-mobile` CLI command.
-     */
-    async pollSync(fromSeqId = 0, isRetry = 0, opts = {}) {
-        const force = opts === true || opts?.force === true; // tolerate old boolean-ish callers
-        this._ensureDb();
-
-        if (!force) {
-            const pending = getPendingSyncGaps();
-            const connectionOk = getSyncState("lastConnectionOk");
-            if (pending.length === 0 && connectionOk === "true") {
-                console.log(`[Sync] No known coverage gap and connection state is healthy — skipping API call.`);
-                return { status: "already-synced", cached: true };
-            }
-        }
-
-        console.log(`[Sync] Requesting mobile push (pullMobileMsg)...`);
-        const pullRes = await this.api.pullMobileMsg(this.keys.publicKey, fromSeqId, isRetry, "");
-        const token = this._unwrap(pullRes);
-        if (!token) {
-            // MEASURED 2026-09-20 against the live Zalo Web client: this is
-            // not "the phone hasn't answered yet", it is the endpoint being
-            // retired. `/api/message/pull_mobile_msg` and `get_crossdb` still
-            // exist in Zalo Web's bundle but NOTHING calls them — 0 call sites
-            // across all 4,642 loaded modules. Current Zalo syncs over the
-            // WebSocket instead (cmd 590/591, "transfer-sync-v2"). See
-            // agent/work/transfer-sync-v2/NOTES.md § Mobile sync.
-            //
-            // Retrying therefore cannot help, and every retry used to push a
-            // notification to a real person's phone. One attempt, then stop.
-            console.log(`[Sync] pullMobileMsg returned no session token — the legacy mobile-sync endpoint is retired.`);
-            return { status: "legacy-retired", raw: pullRes };
-        }
-
-        console.log(`[Sync] Got sync session token, calling getCrossDB...`);
-        let crossDbRes;
-        try {
-            crossDbRes = await this.api.getCrossDB(token);
-        } catch (e) {
-            console.error(`[Sync] getCrossDB failed:`, e.message);
-            return { status: "crossdb-error", error: e.message, token };
-        }
-
-        const payload = this._unwrap(crossDbRes);
-        const result = await this.processSyncData(payload, token);
-
-        try {
-            await this.api.deleteSnapshotMobileMsg(this.keys.publicKey);
-        } catch (e) {
-            console.error(`[Sync] deleteSnapshotMobileMsg failed (non-fatal):`, e.message);
-        }
-
-        // A completed round-trip (even one that found nothing new) means
-        // we've genuinely asked the server "what did I miss?" and gotten an
-        // answer, so whatever gaps we knew about are covered now.
-        resolveAllPendingSyncGaps();
-        setSyncState("lastFullSyncAt", Date.now());
-        setSyncState("lastConnectionOk", "true");
-        this.markSyncSuccess("legacy");
-
-        return result;
-    }
-
     /**
      * Backfill recent history straight from Zalo's servers over an already-open
      * WebSocket, writing it into the same zalo.db the `listen` daemon uses.
@@ -475,66 +306,4 @@ export class SyncManager {
             return false;
         }
     }
-
-    /** zca-js's apiFactory convention isn't 100% consistent about whether a
-     * raw method return is the payload itself or `{data: payload, ...}` —
-     * handle both without guessing wrong silently. */
-    _unwrap(res) {
-        if (res && typeof res === "object" && "data" in res && Object.keys(res).length <= 2) {
-            return res.data;
-        }
-        return res;
-    }
-
-    async processSyncData(payload, token) {
-        // Always keep the raw dump — cheap forensic safety net regardless of
-        // whether structured parsing below succeeds.
-        const dumpFile = resolve(this.syncSessionDir, `sync_dump_${Date.now()}.json`);
-        fs.writeFileSync(dumpFile, JSON.stringify({ token, payload }), "utf8");
-
-        const records = extractMessageRecords(payload);
-        if (records.length === 0) {
-            console.log(
-                `[Sync] getCrossDB returned no recognizable message records (dumped raw to ${dumpFile}). ` +
-                    `This is expected if there's no real offline gap right now, or means the payload shape ` +
-                    `needs re-checking against agent/docs/mobile-sync-live-test-results.md.`,
-            );
-            return { status: "empty-or-unrecognized", dumpFile };
-        }
-
-        const threadsTouched = new Map();
-        let saved = 0;
-        for (const raw of records) {
-            const msg = normalizeSyncedMessage(raw);
-            if (!msg) continue;
-            try {
-                insertMessage({
-                    msgId: msg.msgId,
-                    threadId: msg.threadId,
-                    senderId: msg.senderId,
-                    senderName: msg.senderName,
-                    text: msg.text,
-                    timestamp: msg.timestamp,
-                    type: msg.type,
-                    raw_data: msg.raw_data,
-                });
-                if (!threadsTouched.has(msg.threadId) || threadsTouched.get(msg.threadId) < msg.timestamp) {
-                    threadsTouched.set(msg.threadId, msg.timestamp);
-                    upsertThread({
-                        threadId: msg.threadId,
-                        type: msg.threadType,
-                        name: msg.senderName,
-                        lastUpdate: msg.timestamp,
-                        sync_timestamp: Date.now(),
-                    });
-                }
-                saved++;
-            } catch (e) {
-                console.error(`[Sync] Failed to save message ${msg.msgId}:`, e.message);
-            }
-        }
-
-        console.log(`[Sync] Saved ${saved}/${records.length} synced messages to zalo.db (dump: ${dumpFile}).`);
-        return { status: "saved", saved, total: records.length, dumpFile };
-    }
 }

package/src/index.js

@@ -25,6 +25,7 @@ import { registerAutoReplyCommands } from "./commands/auto-reply.js";
 import { registerQuickMsgCommands } from "./commands/quick-msg.js";
 import { registerLabelCommands } from "./commands/label.js";
 import { registerCatalogCommands } from "./commands/catalog.js";
+import { registerBankCommands } from "./commands/bank.js";
 import { registerListenCommand } from "./commands/listen.js";
 import { registerOACommands } from "./commands/oa.js";
 import { registerMCPCommands } from "./commands/mcp.js";
@@ -147,6 +148,7 @@ registerAutoReplyCommands(program);
 registerQuickMsgCommands(program);
 registerLabelCommands(program);
 registerCatalogCommands(program);
+registerBankCommands(program);
 registerListenCommand(program);
 registerOACommands(program);
 registerMCPCommands(program);

package/src/mcp/mcp-config.js

@@ -44,6 +44,7 @@ export function getDefaultConfig() {
             clients: [],
         },
         webhookSecret: null,
+        groupConfirm: true, // zalo_group asks for confirm: true before leave / remove_member
         httpPort: null,
         host: null,
     };

package/src/mcp/mcp-tools.js

@@ -1,10 +1,10 @@
 /**
  * MCP tool registrations for Zalo message access, sending, user lookup, and group productivity.
- * Registers 23 tools: zalo_get_messages, zalo_get_history, zalo_send_message, zalo_list_threads,
+ * Registers 25 tools: zalo_get_messages, zalo_get_history, zalo_send_message, zalo_list_threads,
  * zalo_search_threads, zalo_mark_read, zalo_view_media, zalo_react, zalo_undo, zalo_get_group_members,
  * zalo_list_conversations, zalo_coverage, zalo_sync, zalo_sync_status, zalo_search_messages,
  * zalo_lookup_user, zalo_forward_message, zalo_delete_message, zalo_reminder, zalo_note, zalo_poll,
- * zalo_wait_for_message, zalo_label.
+ * zalo_wait_for_message, zalo_label, zalo_friend, zalo_group.
  *
  * A tool that mirrors a CLI command calls the same code the command does (src/core/cached-message.js,
  * forward.js, pin.js, group-members.js, recent-conversations.js, src/utils/my-documents.js, urgency.js),
@@ -47,6 +47,23 @@ import { expandMentions, ALL_MENTION_UID } from "../utils/mentions.js";
 import { resolveSelfThread } from "../utils/my-documents.js";
 import { buildQuote, resolveQuoteSender } from "../utils/quote.js";
 import { urgencyLevel } from "../utils/urgency.js";
+import {
+    describeFriendAddError,
+    extractErrorCode,
+    friendStatusFrom,
+    friendsFrom,
+    receivedRequestsFrom,
+    sentRequestsFrom,
+} from "../core/friend-requests.js";
+import {
+    CONFIRMED_ACTIONS,
+    NOT_A_MEMBER_CODES,
+    REMOVE_NOT_IN_GROUP,
+    createdGroupFrom,
+    groupConfirmRequired,
+    groupInfoFrom,
+    memberChangeFrom,
+} from "../core/group-admin.js";
 import { resolveCurrentUserNames, withCurrentSenderNames } from "../core/current-user-names.js";
 
 /** Repeat mode codes matching zca-js ReminderRepeatMode enum and src/commands/reminder.js. */
@@ -2549,4 +2566,287 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
             }
         },
     );
+
+    // --- zalo_friend ---
+    server.registerTool(
+        "zalo_friend",
+        {
+            title: "Manage Zalo Friends and Friend Requests",
+            description:
+                "Check, list and answer friend requests, and list friends. Actions: " +
+                "'status' (the relationship with userId: is_friend, and is_requested / is_requesting, Zalo's two flags " +
+                "for a request pending between you and them; to tell which direction a request goes, use the two lists), " +
+                "'sent_requests' (requests you sent that are still pending), " +
+                "'received_requests' (requests others sent you, newest first, with their message), " +
+                "'send' (friend request to userId, with an optional message), " +
+                "'accept' / 'reject' (the request from userId), " +
+                "'undo' (cancel the request you sent to userId), " +
+                "'list' (your friends, most recently active first, capped by limit). " +
+                "userId is the numeric Zalo id (zalo_lookup_user finds one from a phone number). " +
+                "Zalo restricts accounts that send many friend requests, so send sparingly.",
+            inputSchema: z.object({
+                action: z
+                    .enum(["status", "sent_requests", "received_requests", "send", "accept", "reject", "undo", "list"])
+                    .describe("Friend operation to perform"),
+                userId: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("Numeric Zalo user id (required for status, send, accept, reject and undo)"),
+                message: z
+                    .string()
+                    .optional()
+                    .describe("Message sent with the friend request (only for 'send'; default: none)"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(1000)
+                    .optional()
+                    .describe(
+                        "Most friends to return for 'list' (default 200; the reply says how many there are in all)",
+                    ),
+            }),
+        },
+        async ({ action, userId, message, limit }) => {
+            const needsUser = ["status", "send", "accept", "reject", "undo"].includes(action);
+            const target = userId === undefined ? "" : String(userId).trim();
+            if (needsUser) {
+                if (!target) return err(`userId is required for action='${action}'.`);
+                if (!/^\d{1,30}$/.test(target)) {
+                    return err(
+                        `userId must be a numeric Zalo id (got "${target}"). zalo_lookup_user finds one from a phone number.`,
+                    );
+                }
+            }
+            try {
+                switch (action) {
+                    case "status":
+                        return ok({ action, ...friendStatusFrom(await api.getFriendRequestStatus(target), target) });
+                    case "sent_requests": {
+                        let res = null;
+                        try {
+                            res = await api.getSentFriendRequest();
+                        } catch (e) {
+                            // Zalo answers code 112 when there are none, which is an empty list, not a failure.
+                            if (!/\b112\b/.test(String(e?.message))) throw e;
+                        }
+                        const requests = sentRequestsFrom(res);
+                        return ok({ action, count: requests.length, requests });
+                    }
+                    case "received_requests": {
+                        const requests = receivedRequestsFrom(await api.getFriendRecommendations());
+                        return ok({ action, count: requests.length, requests });
+                    }
+                    case "send":
+                        await api.sendFriendRequest(message ?? "", target);
+                        return ok({ action, success: true, userId: target });
+                    case "accept":
+                        await api.acceptFriendRequest(target);
+                        return ok({ action, success: true, userId: target });
+                    case "reject":
+                        await api.rejectFriendRequest(target);
+                        return ok({ action, success: true, userId: target });
+                    case "undo":
+                        await api.undoFriendRequest(target);
+                        return ok({ action, success: true, userId: target });
+                    case "list": {
+                        const { total, friends } = friendsFrom(await api.getAllFriends(), limit ?? 200);
+                        return ok({ action, total, count: friends.length, truncated: friends.length < total, friends });
+                    }
+                    default:
+                        return err(`Unsupported friend action: ${action}`);
+                }
+            } catch (e) {
+                console.error("[mcp-tools] zalo_friend error:", e.message);
+                // 'send' keeps the CLI's wording for Zalo's refusal codes (already friends, blocked, ...).
+                const known =
+                    action === "send" ? describeFriendAddError(e.code ?? extractErrorCode(e.message), target) : null;
+                return err(known || e.message);
+            }
+        },
+    );
+
+    // --- zalo_group ---
+    server.registerTool(
+        "zalo_group",
+        {
+            title: "Manage Zalo Groups",
+            description:
+                "Leave, inspect, create and change the membership of a group (zalo_get_group_members lists who is " +
+                "in one). Actions: " +
+                "'info' (the group's name, description, creator, admins, member count and limit, creation time and " +
+                "settings), " +
+                "'create' (a new group named `name` with the members in userIds), " +
+                "'add_members' (add userIds to the group), " +
+                "'remove_member' (remove the one member userId from the group), " +
+                "'leave' (leave the group; `silent` hides the usual notice from ordinary members; the owner still sees it). " +
+                "groupId is the group's thread id (zalo_search_threads or zalo_list_conversations finds it); " +
+                "user ids are numeric Zalo ids (zalo_lookup_user finds one from a phone number). " +
+                "'leave' and 'remove_member' cannot be undone from here, so they need confirm: true (a plain " +
+                "parameter, no prompt; a deployment can turn the check off with groupConfirm: false in " +
+                "mcp-config.json or ZALO_MCP_GROUP_CONFIRM=0). Zalo can refuse some members " +
+                "of a create or add_members: the reply lists the members it did and did not take.",
+            inputSchema: z.object({
+                action: z
+                    .enum(["leave", "info", "create", "add_members", "remove_member"])
+                    .describe("Group operation to perform"),
+                groupId: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("The group's id (required for leave, info, add_members and remove_member)"),
+                name: z.string().optional().describe("The new group's name (required for 'create')"),
+                userIds: z
+                    .array(z.string().min(1))
+                    .min(1)
+                    .max(100)
+                    .optional()
+                    .describe("Numeric Zalo user ids (required for 'create' and 'add_members')"),
+                userId: z.string().min(1).optional().describe("Numeric Zalo user id (required for 'remove_member')"),
+                silent: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        "Only for 'leave': hide the usual notice from ordinary members; the owner still sees it (default false)",
+                    ),
+                confirm: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        "Must be true for 'leave' and 'remove_member', which cannot be undone from here " +
+                            "(ignored when the deployment has switched the check off)",
+                    ),
+            }),
+        },
+        async ({ action, groupId, name, userIds, userId, silent, confirm }) => {
+            const gid = groupId === undefined ? "" : String(groupId).trim();
+            if (["leave", "info", "add_members", "remove_member"].includes(action)) {
+                if (!gid) return err(`groupId is required for action='${action}'.`);
+                if (!/^\d{1,30}$/.test(gid)) {
+                    return err(
+                        `groupId must be a numeric Zalo group id (got "${gid}"). zalo_search_threads finds one by name.`,
+                    );
+                }
+            }
+            const badId = (id) => !/^\d{1,30}$/.test(id);
+            let members = [];
+            if (action === "create" || action === "add_members") {
+                members = [...new Set((userIds ?? []).map((u) => String(u).trim()))];
+                if (members.length === 0) return err(`userIds is required for action='${action}'.`);
+                const bad = members.find(badId);
+                if (bad !== undefined) {
+                    return err(
+                        `userIds must be numeric Zalo ids (got "${bad}"). zalo_lookup_user finds one from a phone number.`,
+                    );
+                }
+            }
+            const target = userId === undefined ? "" : String(userId).trim();
+            if (action === "remove_member") {
+                if (!target) return err("userId is required for action='remove_member'.");
+                if (badId(target)) {
+                    return err(
+                        `userId must be a numeric Zalo id (got "${target}"). zalo_get_group_members lists a group's members.`,
+                    );
+                }
+            }
+            const groupName = name === undefined ? "" : String(name).trim();
+            if (action === "create" && !groupName) return err("name is required for action='create'.");
+
+            // After validation, before Zalo: a refused call changes nothing and says exactly how to retry.
+            if (CONFIRMED_ACTIONS.includes(action) && confirm !== true && groupConfirmRequired({ config })) {
+                const what = action === "leave" ? `leave group ${gid}` : `remove ${target} from group ${gid}`;
+                return err(
+                    `Not done: this would ${what}, which cannot be undone from here. Repeat the call with ` +
+                        "confirm: true to proceed. (An automatic or headless deployment can turn this check off " +
+                        "with groupConfirm: false in mcp-config.json, or ZALO_MCP_GROUP_CONFIRM=0 in the environment.)",
+                );
+            }
+
+            try {
+                switch (action) {
+                    case "info": {
+                        const info = groupInfoFrom(await api.getGroupInfo([gid]), gid);
+                        if (!info) {
+                            return err(
+                                `Zalo's answer does not include group ${gid}: this account is not in it, or it is not ` +
+                                    "a group id (a 1-1 conversation's id is the other person's uid).",
+                            );
+                        }
+                        return ok({ action, ...info });
+                    }
+                    case "create": {
+                        const made = createdGroupFrom(await api.createGroup({ name: groupName, members }), members);
+                        if (!made.groupId)
+                            return err("Zalo did not return a group id; the group may not have been created.");
+                        return ok({
+                            action,
+                            groupId: made.groupId,
+                            name: groupName,
+                            added: made.added,
+                            failed: made.failed,
+                        });
+                    }
+                    case "add_members": {
+                        const change = memberChangeFrom(await api.addUserToGroup(members, gid), members);
+                        if (change.done.length === 0) {
+                            const why = change.errorData
+                                ? ` (Zalo's error codes: ${JSON.stringify(change.errorData)})`
+                                : "";
+                            return err(
+                                `Zalo did not add any of the ${members.length} member(s) to group ${gid}${why}.`,
+                            );
+                        }
+                        return ok({
+                            action,
+                            groupId: gid,
+                            added: change.done,
+                            failed: change.failed,
+                            ...(change.errorData && { errorData: change.errorData }),
+                        });
+                    }
+                    case "remove_member": {
+                        const change = memberChangeFrom(await api.removeUserFromGroup([target], gid), [target]);
+                        if (change.failed.length > 0) {
+                            return err(
+                                `Zalo did not remove ${target} from group ${gid}: not a member, or this account is not ` +
+                                    "allowed to remove members (a group's owner or an admin can).",
+                            );
+                        }
+                        return ok({ action, success: true, groupId: gid, userId: target });
+                    }
+                    case "leave": {
+                        const quiet = silent === true;
+                        const res = await api.leaveGroup(gid, quiet);
+                        const memberError = Array.isArray(res?.memberError) ? res.memberError : [];
+                        return ok({
+                            action,
+                            success: true,
+                            groupId: gid,
+                            silent: quiet,
+                            ...(memberError.length > 0 && { memberError }),
+                        });
+                    }
+                    default:
+                        return err(`Unsupported group action: ${action}`);
+                }
+            } catch (e) {
+                console.error("[mcp-tools] zalo_group error:", e.message);
+                if (action === "leave" && NOT_A_MEMBER_CODES.includes(Number(e.code ?? extractErrorCode(e.message)))) {
+                    return err(
+                        `This account is not in group ${gid} (already left, or never joined), so there is nothing to leave.`,
+                    );
+                }
+                if (
+                    action === "remove_member" &&
+                    Number(e.code ?? extractErrorCode(e.message)) === REMOVE_NOT_IN_GROUP
+                ) {
+                    return err(
+                        `Zalo says ${target} is not in group ${gid} ("${e.message}", code ${REMOVE_NOT_IN_GROUP}).`,
+                    );
+                }
+                return err(e.message);
+            }
+        },
+    );
 }