@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/mcp/actions-social.js

@@ -0,0 +1,518 @@
+/**
+ * The `friend` and `group` commands zalo_friend and zalo_group did not cover, as action-table rows (see
+ * src/mcp/action-tool.js). The two tools keep their own handlers for their first actions and hand these to the
+ * action runner; each row makes the call its CLI command makes.
+ */
+
+import { nameFor, personNameFields } from "../core/contact-names.js";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { getInviteBoxInfo } from "../zalo/custom/group-invite.js";
+import { allGroupBlocked, groupLinkInfoAll, inviteInfoAll } from "../core/list-all.js";
+import { applyGroupSettingChanges } from "../zalo/custom/group-settings.js";
+import { SETTING_FLAGS } from "../core/group-settings.js";
+import { lastOnlineStatus } from "../core/last-online.js";
+import { recordOwnExit } from "../core/group-exit.js";
+import { planDisperse, runDisperse } from "../core/group-departure.js";
+import { groupNames } from "../core/mutual-groups.js";
+
+/** The session's own uid, or "". */
+function ownOf(api) {
+    try {
+        return String(api.getOwnId?.() ?? "");
+    } catch {
+        return "";
+    }
+}
+
+/** What Zalo answers for an endpoint it has retired, and what to use instead (as `friend online` / `close` say). */
+const RETIRED_404 = {
+    online:
+        "Zalo answers 404 for the online-friends list, and Zalo's own apps discard this answer too; 'last_online' " +
+        "works for one user, and the listener caches Zalo's presence pushes ('last_online' with `cached`).",
+    close: "Zalo has retired close friends: Zalo's own apps no longer use it, and the request answers 404.",
+};
+
+/** A 404 from a retired endpoint, said plainly. */
+const retired = (which) => (e) => (/404/.test(e.message) ? `${e.message}. ${RETIRED_404[which]}` : undefined);
+
+// --- zalo_friend ---
+
+/** zalo_friend's further actions. */
+export const FRIEND_EXTRA_ACTIONS = {
+    online: {
+        async run(_a, { api }) {
+            return { data: (await api.getFriendOnlines()) ?? null };
+        },
+        fail: retired("online"),
+    },
+    remove: {
+        needs: ["userId"],
+        guard: (a) => ({ key: "friend.remove", target: { userId: a.userId } }),
+        async run(a, { api }) {
+            await api.removeFriend(a.userId);
+            return { success: true, userId: a.userId };
+        },
+    },
+    block: {
+        needs: ["userId"],
+        guard: (a) => ({ key: "friend.block", target: { userId: a.userId } }),
+        async run(a, { api }) {
+            await api.blockUser(a.userId);
+            return { success: true, userId: a.userId };
+        },
+    },
+    unblock: {
+        needs: ["userId"],
+        async run(a, { api }) {
+            await api.unblockUser(a.userId);
+            return { success: true, userId: a.userId };
+        },
+    },
+    last_online: {
+        needs: ["userId"],
+        async run(a, { api }) {
+            // The same reply as `friend last-online` (src/core/last-online.js).
+            return lastOnlineStatus(api, a.userId, {
+                askAnyway: a.askAnyway === true,
+                cached: a.cached === true,
+                ...(a.isOA === true ? { isOA: true } : {}),
+            });
+        },
+    },
+    close: {
+        async run(_a, { api }) {
+            const res = await api.getCloseFriends();
+            const friends = (Array.isArray(res) ? res : []).map((f) => ({
+                userId: String(f.userId || f.uid || ""),
+                ...personNameFields(f.userId || f.uid, f),
+            }));
+            return { count: friends.length, friends };
+        },
+        fail: retired("close"),
+    },
+    find_phones: {
+        needs: ["phones"],
+        async run(a, { api }) {
+            const res = (await api.getMultiUsersByPhones(a.phones)) || {};
+            const users = Object.entries(res).map(([phone, u]) => ({
+                phone,
+                userId: u?.uid ? String(u.uid) : null,
+                ...personNameFields(u?.uid, u),
+            }));
+            return { count: users.length, users };
+        },
+    },
+    qr: {
+        needs: ["userIds"],
+        async run(a, { api }) {
+            const res = (await api.getQR(a.userIds)) ?? {};
+            return { codes: Object.entries(res).map(([userId, url]) => ({ userId, url })) };
+        },
+    },
+    common_groups: {
+        needs: ["userIds"],
+        async run(a, { api, hidden, hiddenMode }) {
+            const res = await api.getRelatedFriendGroup(a.userIds);
+            // Groups in hidden chats are left out unless the deployment includes them, as Zalo leaves them out.
+            const set = hiddenMode?.() === "include" ? null : (hidden?.() ?? null);
+            const lists = Object.entries(res?.groupRelateds ?? {}).map(([userId, groups]) => [
+                userId,
+                (Array.isArray(groups) ? groups : []).map(String).filter((id) => !set?.isHidden(id)),
+            ]);
+            const names = await groupNames(
+                api,
+                lists.flatMap(([, ids]) => ids),
+                { ownId: ownOf(api) || null },
+            );
+            const shared = lists.map(([userId, groupIds]) => ({
+                userId,
+                count: groupIds.length,
+                groupIds,
+                groups: groupIds.map((groupId) => ({ groupId, name: names.get(groupId) ?? null })),
+            }));
+            return { shared };
+        },
+    },
+    biz: {
+        needs: ["userId"],
+        async run(a, { api }) {
+            return { userId: a.userId, data: (await api.getBizAccount(a.userId)) ?? null };
+        },
+    },
+    block_feed: {
+        needs: ["userId"],
+        async run(a, { api }) {
+            const hide = a.unblock !== true;
+            await api.blockViewFeed(hide, a.userId);
+            return { success: true, userId: a.userId, feedHidden: hide };
+        },
+    },
+};
+
+/** zalo_friend's inputs for the actions above. */
+export const FRIEND_EXTRA_INPUTS = {
+    userIds: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Several Zalo user ids (required for 'qr' and 'common_groups')"),
+    phones: z
+        .array(z.string().min(3))
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Phone numbers to look up (required for 'find_phones'), e.g. '0901234567'"),
+    unblock: z
+        .boolean()
+        .optional()
+        .describe("Only for 'block_feed': true shows the user's posts in the feed again instead of hiding them"),
+    askAnyway: z
+        .boolean()
+        .optional()
+        .describe(
+            "Only for 'last_online': ask Zalo even when this account's own online status is hidden (by default " +
+                'nothing is asked then and the reply says hiddenBy "you", as Zalo does)',
+        ),
+    cached: z
+        .boolean()
+        .optional()
+        .describe("Only for 'last_online': answer from the listener's cache of Zalo's presence pushes; send nothing"),
+    isOA: z
+        .boolean()
+        .optional()
+        .describe("Only for 'last_online': the user is an Official Account (skips the profile lookup that tells)"),
+};
+
+// --- zalo_group ---
+
+/** A local file the server can read, or the refusal that names it. */
+function localFile(path) {
+    const abs = resolve(String(path).trim());
+    return existsSync(abs) ? { abs } : { error: `File not found on the machine this server runs on: ${abs}` };
+}
+
+/** `settings` as the GroupSetting changes Zalo takes (1 on, 0 off), only for the settings given. */
+function settingChanges(settings) {
+    const changes = {};
+    for (const key of Object.values(SETTING_FLAGS)) {
+        if (settings?.[key] !== undefined) changes[key] = settings[key] ? 1 : 0;
+    }
+    return changes;
+}
+
+/** zalo_group's further actions. */
+export const GROUP_EXTRA_ACTIONS = {
+    avatar: {
+        needs: ["groupId", "filePath"],
+        check: (a) => localFile(a.filePath).error,
+        async run(a, { api }) {
+            await api.changeGroupAvatar(localFile(a.filePath).abs, a.groupId);
+            return { success: true, groupId: a.groupId };
+        },
+    },
+    add_admin: {
+        needs: ["groupId", "userIds"],
+        async run(a, { api }) {
+            await api.addGroupDeputy(a.userIds, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    remove_admin: {
+        needs: ["groupId", "userIds"],
+        guard: (a) => ({ key: "group.removeAdmin", target: { groupId: a.groupId, userIds: a.userIds } }),
+        async run(a, { api }) {
+            await api.removeGroupDeputy(a.userIds, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    transfer_owner: {
+        needs: ["groupId", "userId"],
+        guard: (a) => ({ key: "group.transferOwner", target: { groupId: a.groupId, userId: a.userId } }),
+        async run(a, { api }) {
+            await api.changeGroupOwner(a.userId, a.groupId);
+            return { success: true, groupId: a.groupId, userId: a.userId };
+        },
+    },
+    block_member: {
+        needs: ["groupId", "userIds"],
+        guard: (a) => ({ key: "group.blockMember", target: { groupId: a.groupId, userIds: a.userIds } }),
+        async run(a, { api }) {
+            await api.addGroupBlockedMember(a.userIds, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    unblock_member: {
+        needs: ["groupId", "userIds"],
+        async run(a, { api }) {
+            await api.removeGroupBlockedMember(a.userIds, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    blocked: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            // No page asked: every page (src/core/list-all.js); a page or a limit is that one page.
+            const res =
+                a.page === undefined && a.limit === undefined
+                    ? await allGroupBlocked(api, a.groupId)
+                    : await api.getGroupBlockedMember({ page: a.page ?? 1, count: a.limit ?? 50 }, a.groupId);
+            const members = (res?.blocked_members ?? []).map((m) => ({
+                userId: String(m.id),
+                ...personNameFields(m.id, m),
+            }));
+            return {
+                groupId: a.groupId,
+                count: members.length,
+                members,
+                hasMore: Boolean(res?.has_more),
+                ...(res?.paging?.note && { note: res.paging.note }),
+            };
+        },
+    },
+    upgrade_community: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            await api.upgradeGroupToCommunity(a.groupId);
+            return { success: true, groupId: a.groupId };
+        },
+    },
+    settings: {
+        needs: ["groupId", "settings"],
+        check: (a) =>
+            Object.keys(settingChanges(a.settings)).length === 0
+                ? "settings names nothing to change: give at least one setting, true or false."
+                : undefined,
+        // Only turning membership approval off is asked about, as `group settings --no-join-appr`.
+        guard: (a) => ({
+            key: "group.settings",
+            target: { groupId: a.groupId, approvalOff: a.settings.joinAppr === false },
+            applies: a.settings.joinAppr === false,
+        }),
+        async run(a, { api }) {
+            // Zalo stores the whole setting object on every update: this reads it and sends back everything not
+            // named, unchanged (src/zalo/custom/group-settings.js), as `group settings` does.
+            const outcome = await applyGroupSettingChanges(api, a.groupId, settingChanges(a.settings));
+            const notApplied = Object.keys(outcome.notApplied ?? {}).length > 0;
+            return { success: !notApplied, groupId: a.groupId, ...outcome };
+        },
+    },
+    disperse: {
+        needs: ["groupId"],
+        // Only the owner can disband a group for everyone: anyone else is refused before the guard and the call
+        // (src/core/group-departure.js).
+        prepare: async (a, { api }) => ({ plan: await planDisperse(api, { groupId: a.groupId, ownId: ownOf(api) }) }),
+        guard: (a) => ({ key: "group.disperse", target: { groupId: a.groupId, others: a.plan?.others } }),
+        async run(a, { api }) {
+            await runDisperse(api, a.plan);
+            // The disperser deletes locally on the API's success, as Zalo does (src/core/group-exit.js).
+            return {
+                success: true,
+                groupId: a.groupId,
+                ...(await recordOwnExit({ ownId: ownOf(api), groupId: a.groupId, reason: "disbanded" })),
+            };
+        },
+    },
+    pending: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            const res = await api.getPendingGroupMembers(a.groupId);
+            const users = (res?.users ?? []).map((u) => ({ userId: String(u.uid), ...personNameFields(u.uid, u) }));
+            return { groupId: a.groupId, count: users.length, users };
+        },
+    },
+    approve: {
+        needs: ["groupId", "userIds"],
+        async run(a, { api }) {
+            await api.reviewPendingMemberRequest({ members: a.userIds, isApprove: true }, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    reject_member: {
+        needs: ["groupId", "userIds"],
+        async run(a, { api }) {
+            await api.reviewPendingMemberRequest({ members: a.userIds, isApprove: false }, a.groupId);
+            return { success: true, groupId: a.groupId, userIds: a.userIds };
+        },
+    },
+    enable_link: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            const res = await api.enableGroupLink(a.groupId);
+            return { success: true, groupId: a.groupId, link: res?.link ?? null };
+        },
+    },
+    disable_link: {
+        needs: ["groupId"],
+        guard: (a) => ({ key: "group.disableLink", target: { groupId: a.groupId } }),
+        async run(a, { api }) {
+            await api.disableGroupLink(a.groupId);
+            return { success: true, groupId: a.groupId };
+        },
+    },
+    link_info: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            const res = await api.getGroupLinkDetail(a.groupId);
+            return {
+                groupId: a.groupId,
+                enabled: res?.enabled === 1,
+                link: res?.link ?? null,
+                expiresAt: res?.expiration_date ?? null,
+            };
+        },
+    },
+    link_preview: {
+        needs: ["link"],
+        async run(a, { api }) {
+            if (a.page !== undefined) {
+                return {
+                    link: a.link,
+                    data: (await api.getGroupLinkInfo({ link: a.link, memberPage: a.page })) ?? null,
+                };
+            }
+            // No member page asked: every member page, as Zalo reads a link preview (src/core/list-all.js).
+            const { paging, ...data } = await groupLinkInfoAll(api, a.link);
+            return {
+                link: a.link,
+                data: Object.keys(data).length ? data : null,
+                ...(paging.note && { note: paging.note }),
+            };
+        },
+    },
+    join: {
+        needs: ["link"],
+        async run(a, { api }) {
+            return { success: true, link: a.link, data: (await api.joinGroupLink(a.link)) ?? null };
+        },
+    },
+    invite_boxes: {
+        async run(_a, { api }) {
+            const res = await api.getGroupInviteBoxList();
+            const invitations = (res?.invitations ?? []).map((inv) => ({
+                groupId: inv.groupInfo?.groupId ? String(inv.groupInfo.groupId) : null,
+                name: inv.groupInfo?.name ?? null,
+                // Alias first, as Zalo shows the inviter (src/core/contact-names.js).
+                inviterName: nameFor(inv.inviterInfo?.id ?? inv.inviterInfo?.uid, inv.inviterInfo?.dName),
+            }));
+            return { count: invitations.length, total: res?.total ?? invitations.length, invitations };
+        },
+    },
+    invite_info: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            const mcount = a.limit ?? 10;
+            if (a.page !== undefined) {
+                const res = await getInviteBoxInfo(api, { groupId: a.groupId, mpage: a.page, mcount });
+                return { groupId: a.groupId, data: res ?? null };
+            }
+            // No member page asked: every member page (src/core/list-all.js).
+            const { paging, ...data } = await inviteInfoAll(
+                (mpage) => getInviteBoxInfo(api, { groupId: a.groupId, mpage, mcount }),
+                mcount,
+            );
+            return {
+                groupId: a.groupId,
+                data: Object.keys(data).length ? data : null,
+                ...(paging.note && { note: paging.note }),
+            };
+        },
+    },
+    join_invite: {
+        needs: ["groupId"],
+        async run(a, { api }) {
+            await api.joinGroupInviteBox(a.groupId);
+            return { success: true, groupId: a.groupId };
+        },
+    },
+    delete_invite: {
+        needs: ["groupIds"],
+        async run(a, { api }) {
+            const block = a.blockFutureInvites === true;
+            await api.deleteGroupInviteBox(a.groupIds, block);
+            return { success: true, groupIds: a.groupIds, blockFutureInvites: block };
+        },
+    },
+    invite_to: {
+        needs: ["userId", "groupIds"],
+        async run(a, { api }) {
+            const res = await api.inviteUserToGroups(a.userId, a.groupIds);
+            return { success: true, userId: a.userId, groupIds: a.groupIds, data: res ?? null };
+        },
+    },
+    members_info: {
+        needs: ["userIds"],
+        async run(a, { api }) {
+            const res = await api.getGroupMembersInfo(a.userIds);
+            const members = Object.entries(res?.profiles ?? {}).map(([userId, p]) => ({
+                userId,
+                ...personNameFields(userId, p),
+                avatar: p?.avatar ?? null,
+            }));
+            return { count: members.length, members };
+        },
+    },
+};
+
+/** zalo_group's inputs for the actions above. */
+export const GROUP_EXTRA_INPUTS = {
+    groupIds: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Several group ids (required for 'delete_invite' and 'invite_to')"),
+    filePath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Only for 'avatar': a local image path on the machine this server runs on"),
+    link: z
+        .string()
+        .url()
+        .optional()
+        .describe("A group invite link, https://zalo.me/g/... (required for 'join' and 'link_preview')"),
+    settings: z
+        .object(
+            Object.fromEntries(
+                Object.entries(SETTING_FLAGS).map(([flag, key]) => [
+                    key,
+                    z.boolean().optional().describe(`true or false, as \`group settings --${flag}\` / --no-${flag}`),
+                ]),
+            ),
+        )
+        .strict()
+        .optional()
+        .describe(
+            "Only for 'settings': the settings to change, each true or false; the rest keep their values. blockName " +
+                "(members cannot rename or change the avatar), signAdminMsg (highlight admins' messages), " +
+                "enableMsgHistory (new members read recent messages), joinAppr (joining needs approval; turning it " +
+                "off is asked about first), lockCreatePost (members cannot create notes or reminders), " +
+                "lockCreatePoll, lockSendMsg (members cannot send messages), lockViewMember (hide the member list, " +
+                "communities only), setTopicOnly (only admins pin to the top of the chat)",
+        ),
+    page: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(
+            "Only this page for 'blocked', or this member page for 'link_preview' and 'invite_info' (omit for every page)",
+        ),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe(
+            "Page size for 'blocked' (one page is read when page or limit is given; 50 a page), and members per " +
+                "request for 'invite_info' (10)",
+        ),
+    blockFutureInvites: z
+        .boolean()
+        .optional()
+        .describe("Only for 'delete_invite': also refuse future invitations from these groups"),
+};

package/src/mcp/instructions.js

@@ -9,24 +9,38 @@ export const SERVER_INSTRUCTIONS = [
     "",
     "IDS",
     "- threadId is the conversation: the other person's user id for a DM, the group id for a group. Find one by name with zalo_search_threads, among recent ones with zalo_list_conversations, or from a phone number or username with zalo_lookup_user. `me` is the owner's My Documents.",
-    "- msgId is one message, and it is called `msgId` in every input and reply. Live messages also carry it as `id`, and a send reply as `messageId`: the same value, kept for older clients.",
+    "- msgId is one message, and it is called `msgId` in every input and reply.",
     "- userId is a Zalo user. A message's author is its `senderId` (a userId); group members have a `userId`. `@[userId]` mentions someone.",
     "- cliMsgId is the sender's own id for a message. zalo_send_message returns it, and zalo_react and zalo_undo need it (they read it from the cache when you leave it out).",
-    '- threadType, as an input, is the number 0 (DM) or 1 (group); leave it out and the type stored for the thread is used. Messages show `threadType` as the text "dm" or "group": never pass that text back.',
+    "- threadType is `dm` or `group`, in inputs and in replies. Leave it out: the type stored for the thread is used.",
     "",
     "READING",
     "- To receive messages, wait with zalo_wait_for_message or poll with zalo_get_messages, then call zalo_mark_read with the returned `cursor`. If several bots share the server, each passes its own `consumer` name.",
-    "- For older messages use zalo_get_history (one conversation) or zalo_search_messages (text, across all conversations).",
+    '- A recall arrives as an entry with `type` "undo" whose `msgId` is the recalled message.',
+    "- Older messages: zalo_get_history (one conversation) or zalo_search_messages (text, all conversations).",
     "",
     "SENDING TEXT",
-    "- Put real line breaks in `text`. Never type the two characters backslash and n: Zalo shows them as typed.",
+    "- Put real line breaks in `text`, never the two characters backslash and n.",
     '- Markdown is converted to Zalo formatting by default; `format: "plain"` sends the text as written.',
     "- Mention someone in a group with `@[uid]` (`@[-1]` is everyone). Reply to a message with `quoteMsgId`.",
     "- A text over 3000 bytes goes out as several messages; the reply lists each part.",
     "- A sent message cannot be edited. To correct one, recall it with zalo_undo (msgId and cliMsgId from the send reply) and send it again.",
     "",
+    "THE REST OF THE ACCOUNT",
+    "- zalo_conversation (pin, mute, archive, hide, mark read, delete), zalo_group, zalo_friend, zalo_profile, zalo_catalog, zalo_bank, zalo_auto_reply, zalo_quick_message, zalo_cloud, zalo_sticker and zalo_link each take an `action`: the CLI subcommand's name with _ for -.",
+    "- zalo_official runs the `oa`, `zbs` and `social` CLI commands (official APIs, own logins).",
+    "",
     "RULES",
     "- Call zalo_sync only when the owner asked: it makes the owner's phone ask for a confirmation.",
-    "- zalo_group `leave` and `remove_member` need `confirm: true`.",
     "- A refused call says why in its error text. Fix the argument it names; do not repeat the same call.",
+    "",
+    "GUARDED ACTIONS",
+    "- Actions Zalo asks about first are guarded: zalo_undo, zalo_delete_message, every zalo_write, and the removing or blocking actions of the tools above (each description names its own, e.g. zalo_group `leave`, `disperse`, zalo_friend `remove`, `block`). `dryRun: true` says what one would do and sends nothing; `confirm: true` goes ahead.",
+    "- The FIRST time you reach a guarded action, stop and ask the user how they want these handled: always ask them first, let you confirm on your own for some kinds of action, or never do them. Remember the answer in the way you and the user agree on (your memory, the project's rules, its CLAUDE.md or AGENTS.md) so you do not ask again, and follow it: send `confirm: true` only where the user allowed it.",
+    '- A refusal with `confirmationRequired` means nothing was sent; repeat the call with `confirm: true` only when allowed. If the server says its confirm mode is "human", it asks the user itself and your `confirm` does not answer for them; a decline means do not retry. When it cannot ask in the call (HTTP), the reply carries a one-time `secureUrl`: give it to the user, and once they approved there repeat the call with its `ticket`.',
+    "- `approvalPending`: the owner got the page elsewhere; repeat with `ticket` once they are done.",
+    "- Try zalo_write with `dryRun: true` first.",
+    "",
+    "HIDDEN CHATS",
+    "- The account's hidden conversations are left out of every list, search, history and event unless the deployment includes them. Never ask the user for their hidden-chat PIN in chat: a reply with `pinRequired` carries a one-time `secureUrl` where they type it; then repeat the call with its `ticket`.",
 ].join("\n");