@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/mcp/actions-media.js

@@ -0,0 +1,268 @@
+/**
+ * Smaller MCP action tools: stickers (`zalo_sticker`, `msg sticker-list` / `sticker-detail`), links (`zalo_link`,
+ * `msg link-preview` / `scan-url`) and the local zCloud index (`zalo_cloud`, `cloud ls` / `cloud plan`). Each action
+ * makes its command's call; the cloud actions read only the local cache, as their commands do.
+ */
+
+import { z } from "zod";
+import { findMessageByClientId, getCloudItems, getThreadNames } from "../core/db.js";
+import { CLEANUP_WARNING, applyCloudCleanup, planCloudCleanup } from "../core/cloud-plan.js";
+import { confirmInput, dryRunInput, ticketInput } from "./action-tool.js";
+
+const MB = 1024 * 1024;
+
+// --- zalo_sticker ---
+
+/** The action table; see src/mcp/action-tool.js for what a row holds. */
+export const STICKER_ACTIONS = {
+    search: {
+        needs: ["keyword"],
+        async run(a, { api }) {
+            const ids = (await api.getStickers(a.keyword)) ?? [];
+            const stickerIds = (Array.isArray(ids) ? ids : []).map(String);
+            return { keyword: a.keyword, count: stickerIds.length, stickerIds };
+        },
+    },
+    detail: {
+        needs: ["stickerIds"],
+        async run(a, { api }) {
+            return { data: (await api.getStickersDetail(a.stickerIds.map(Number))) ?? null };
+        },
+    },
+};
+
+/** zalo_sticker's metadata. */
+export const STICKER_META = {
+    title: "Find Zalo Stickers",
+    description:
+        "Find Zalo stickers. Actions: 'search' (the sticker ids matching `keyword`) and 'detail' (the details of " +
+        "`stickerIds`). To send a sticker, give zalo_send_message a `sticker` keyword; zalo_read 'sticker-category' " +
+        "reads a sticker category. Read-only: nothing is sent.",
+    inputSchema: z
+        .object({
+            action: z.enum(Object.keys(STICKER_ACTIONS)).describe("Sticker operation to perform"),
+            keyword: z.string().min(1).max(100).optional().describe("Only for 'search': a word to find stickers by"),
+            stickerIds: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Only for 'detail': sticker ids, from 'search'"),
+        })
+        .strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+
+// --- zalo_link ---
+
+/** The action table; see src/mcp/action-tool.js for what a row holds. */
+export const LINK_ACTIONS = {
+    preview: {
+        needs: ["url"],
+        async run(a, { api }) {
+            const d = (await api.parseLink(a.url))?.data ?? {};
+            return {
+                url: a.url,
+                title: d.title ?? null,
+                description: d.desc ?? null,
+                source: d.src || d.href || null,
+                thumbnail: d.thumb ?? null,
+            };
+        },
+    },
+    scan: {
+        needs: ["url"],
+        async run(a, { api }) {
+            const res = await api.scanURL(a.url);
+            return { url: a.url, isSafe: res?.isSafe === undefined ? null : Boolean(res.isSafe), data: res ?? null };
+        },
+    },
+};
+
+/** zalo_link's metadata. */
+export const LINK_META = {
+    title: "Check a Link with Zalo",
+    description:
+        "Ask Zalo about a link without sending it anywhere. Actions: 'preview' (the title, description and " +
+        "thumbnail Zalo would show for `url`) and 'scan' (whether Zalo considers `url` safe to open). To send " +
+        "a link card to a conversation, use zalo_send_message `link`.",
+    inputSchema: z
+        .object({
+            action: z.enum(Object.keys(LINK_ACTIONS)).describe("Link operation to perform"),
+            url: z.string().url().optional().describe("The link to ask about (required)"),
+        })
+        .strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+
+// --- zalo_cloud ---
+
+/** "12.3 MB": the size the guard's sentence quotes, as `cloud apply` words it. */
+function bytesText(n) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let v = Number(n) || 0;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+/** A cleanup plan from the local index, with the filters 'plan' and 'apply' share (as `cloud plan` / `apply`). */
+function planOf(a, ctx) {
+    const index = openIndex();
+    return planCloudCleanup({
+        rows: index.rows,
+        ownId: ctx.ownId(),
+        filters: {
+            threads: a.threadIds ?? [],
+            kinds: a.kinds ?? [],
+            olderThanDays: a.olderThanDays ?? null,
+            largerThanBytes: a.largerThanMb === undefined ? null : a.largerThanMb * MB,
+            onlySavedLocally: Boolean(a.onlySavedLocally),
+            includeGroups: Boolean(a.includeGroups),
+            includeMyCloud: Boolean(a.includeMyCloud),
+            limit: a.limit,
+        },
+        savedLocally: index.savedLocally,
+        nameOf: index.nameOf,
+    });
+}
+
+/** What `cloud apply` would act on, as the guard's target: the listed items, their size, their conversations. */
+function applyTarget(r) {
+    return {
+        items: r.listed,
+        size: bytesText(r.items.reduce((sum, it) => sum + it.bytes, 0)),
+        conversations: new Set(r.items.map((it) => it.threadId)).size,
+    };
+}
+
+/** The local zCloud index and the helpers a plan needs, as `cloud` reads them. */
+function openIndex() {
+    const rows = getCloudItems(null, 10_000_000);
+    const names = getThreadNames();
+    const savedLocally = (item) => {
+        if (!item.cliMsgId) return false;
+        try {
+            return Boolean(findMessageByClientId(item.cliMsgId, item.threadId)?.localPath);
+        } catch {
+            return false;
+        }
+    };
+    return { rows, nameOf: (id) => names.get(String(id))?.name ?? null, savedLocally };
+}
+
+/** The action table; see src/mcp/action-tool.js for what a row holds. */
+export const CLOUD_ACTIONS = {
+    summary: {
+        async run(a, ctx) {
+            const index = openIndex();
+            const r = planCloudCleanup({
+                rows: index.rows,
+                ownId: ctx.ownId(),
+                filters: { includeGroups: true, includeMyCloud: true, limit: 1 },
+                nameOf: index.nameOf,
+            });
+            return {
+                items: r.matched + r.excluded.e2ee,
+                bytes: r.bytes,
+                byKind: r.byKind,
+                byConversation: a.top ? r.byConversation.slice(0, a.top) : r.byConversation,
+                e2eeItems: r.excluded.e2ee,
+                ...(r.matched + r.excluded.e2ee === 0 && {
+                    note: "The local zCloud index is empty: zalo_sync stage 'cloud' fills it.",
+                }),
+            };
+        },
+    },
+    plan: {
+        async run(a, ctx) {
+            return { warning: CLEANUP_WARNING, generatedAt: new Date().toISOString(), ...planOf(a, ctx) };
+        },
+    },
+    apply: {
+        // The plan is read from the local index first, so the guard, the preview and the call see the same items.
+        prepare: (a, ctx) => {
+            const plan = planOf(a, ctx);
+            return { plan, applyTarget: applyTarget(plan) };
+        },
+        guard: (a) => ({ key: "cloud.delete", target: a.applyTarget }),
+        // Like `cloud apply --dry-run`: the plan itself.
+        preview: (a) => ({ warning: CLEANUP_WARNING, verified: false, plan: a.plan }),
+        async run(a, ctx) {
+            if (!a.plan.listed) return { deleted: 0, failed: [], skipped: [], bytes: 0, matched: 0, verified: false };
+            // As `cloud apply`: delete the chat message behind each item, for this account on every device.
+            const result = await applyCloudCleanup({
+                items: a.plan.items,
+                ownId: ctx.ownId(),
+                deleteForMe: (t) => ctx.api.deleteMessage(t, true),
+            });
+            return { ...result, matched: a.plan.matched, verified: false, warning: CLEANUP_WARNING };
+        },
+    },
+};
+
+/** zalo_cloud's metadata. */
+export const CLOUD_META = {
+    title: "Zalo zCloud Index",
+    description:
+        "What the account's zCloud index holds, what a cleanup would cover, and the cleanup itself (the `cloud` " +
+        "commands), from the local index (zalo_sync stage 'cloud' fills it). Actions: 'summary' (items and bytes by " +
+        "kind and by conversation) and 'plan' (the items a cleanup of this shape would cover, and the space it would " +
+        "free; groups and My Cloud are left out unless asked for) only read; 'apply' deletes the chat message behind " +
+        "each planned item, for this account on every device, as Zalo's cloud view does: it cannot be undone, " +
+        "has not been validated live yet, and is asked about first (`confirm`, `dryRun` shows the plan).",
+    inputSchema: z
+        .object({
+            action: z.enum(Object.keys(CLOUD_ACTIONS)).describe("zCloud report to make"),
+            top: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Only for 'summary': conversations to list (omit for all)"),
+            threadIds: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("For 'plan' and 'apply': only these conversations"),
+            kinds: z
+                .array(z.enum(["photo", "video", "file", "voice", "gif", "other"]))
+                .min(1)
+                .optional()
+                .describe("For 'plan' and 'apply': only these kinds"),
+            olderThanDays: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("For 'plan' and 'apply': only items older than this many days"),
+            largerThanMb: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("For 'plan' and 'apply': only items of at least this many MB"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("For 'plan' and 'apply': items to list and act on (default: every match)"),
+            onlySavedLocally: z
+                .boolean()
+                .optional()
+                .describe("For 'plan' and 'apply': only items whose file this machine already holds"),
+            includeGroups: z.boolean().optional().describe("For 'plan' and 'apply': include group conversations"),
+            includeMyCloud: z
+                .boolean()
+                .optional()
+                .describe("For 'plan' and 'apply': include My Cloud, the chat with yourself"),
+            confirm: confirmInput("'apply'"),
+            ticket: ticketInput(),
+            dryRun: dryRunInput("'apply'"),
+        })
+        .strict(),
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+};

package/src/mcp/actions-profile.js

@@ -0,0 +1,281 @@
+/**
+ * `zalo_profile`: the `profile` commands and `account devices` as MCP actions, each making its command's call.
+ * This account's own profile is read with zalo_lookup_user (`self: true`), as `profile me` and `whoami` print it.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { UPDATE_LANG } from "../zalo/enums.js";
+import { createTrustStore } from "../zalo/trust-store.js";
+import { getAccountDir } from "../core/credentials.js";
+import { summarizeCompanion } from "../core/account-devices.js";
+import { dbUsedBytes } from "../core/db.js";
+import { describeStorage } from "../core/storage-quota.js";
+import {
+    SETTING_MAP,
+    describeSettings,
+    profileUpdatePayload,
+    settingValueError,
+    updateSetting,
+} from "../core/profile-settings.js";
+import { confirmInput, dryRunInput, ticketInput } from "./action-tool.js";
+import { allAvatars } from "../core/list-all.js";
+
+/** 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}` };
+}
+
+/** The action table; see src/mcp/action-tool.js for what a row holds. */
+export const PROFILE_ACTIONS = {
+    avatar: {
+        needs: ["filePath"],
+        check: (a) => localFile(a.filePath).error,
+        async run(a, { api }) {
+            await api.changeAccountAvatar(localFile(a.filePath).abs);
+            return { success: true };
+        },
+    },
+    bio: {
+        async run(a, { api }) {
+            if (a.bio === undefined) {
+                const info = await api.fetchAccountInfo();
+                return { bio: info?.profile?.status || "" };
+            }
+            await api.updateProfileBio(a.bio);
+            // Read back, as `profile bio` does: Zalo may take a moment, or not support a bio on this account.
+            const now = (await api.fetchAccountInfo())?.profile?.status || "";
+            return { success: true, bio: now, ...(now !== a.bio && { requested: a.bio, applied: false }) };
+        },
+    },
+    update: {
+        check: (a) =>
+            a.name === undefined && a.dob === undefined && a.gender === undefined
+                ? "Give at least one of name, dob or gender for action='update'."
+                : undefined,
+        async run(a, ctx) {
+            // Zalo takes the three together, so the ones not given come from the current profile.
+            const current = (await ctx.api.fetchAccountInfo())?.profile || {};
+            const payload = profileUpdatePayload(current, {
+                name: a.name,
+                dob: a.dob,
+                gender: a.gender === undefined ? undefined : a.gender === "female" ? 1 : 0,
+            });
+            await ctx.api.updateProfile(payload);
+            if (payload.profile.name) ctx.onSelfName?.(payload.profile.name);
+            const p = payload.profile;
+            return { success: true, name: p.name, dob: p.dob, gender: p.gender === 1 ? "female" : "male" };
+        },
+    },
+    settings: {
+        async run(_a, { api }) {
+            // The same reply as `profile settings --json` (src/core/profile-settings.js).
+            return describeSettings(await api.getSettings());
+        },
+    },
+    set: {
+        needs: ["setting", "value"],
+        check: (a) => settingValueError(a.setting, a.value),
+        async run(a, { api }) {
+            return updateSetting(api, a.setting, a.value);
+        },
+    },
+    avatars: {
+        async run(a, { api }) {
+            if (a.limit !== undefined || a.page !== undefined) {
+                return { data: (await api.getAvatarList(a.limit ?? 50, a.page ?? 1)) ?? null };
+            }
+            // No page asked: the whole gallery, page by page (src/core/list-all.js).
+            const { paging, ...data } = await allAvatars(api);
+            return { data: Object.keys(data).length ? data : null, ...(paging.note && { note: paging.note }) };
+        },
+    },
+    full_avatar: {
+        needs: ["userId"],
+        async run(a, { api }) {
+            const res = await api.getFullAvatar(a.userId);
+            return { userId: a.userId, avatar: res?.avatar ?? null };
+        },
+    },
+    avatar_url: {
+        needs: ["userIds"],
+        async run(a, { api }) {
+            return { data: (await api.getAvatarUrlProfile(a.userIds)) ?? null };
+        },
+    },
+    delete_avatar: {
+        needs: ["photoIds"],
+        guard: (a) => ({ key: "profile.deleteAvatar", target: { photoIds: a.photoIds } }),
+        async run(a, { api }) {
+            await api.deleteAvatar(a.photoIds);
+            return { success: true, photoIds: a.photoIds };
+        },
+    },
+    reuse_avatar: {
+        needs: ["photoId"],
+        async run(a, { api }) {
+            await api.reuseAvatar(a.photoId);
+            return { success: true, photoId: a.photoId };
+        },
+    },
+    active: {
+        needs: ["enabled"],
+        async run(a, { api }) {
+            await api.updateActiveStatus(a.enabled);
+            return { success: true, enabled: a.enabled };
+        },
+    },
+    lang: {
+        needs: ["language"],
+        async run(a, { api }) {
+            await api.updateLang(UPDATE_LANG[a.language.toUpperCase()]);
+            return { success: true, language: a.language };
+        },
+    },
+    devices: {
+        async run(_a, { api }) {
+            const devices = (await api.getListDevice())?.devices ?? null;
+            // Which entry is this server: the companion identity the official QR login saved, if any. The signed
+            // identity material of each entry is never returned.
+            const saved = createTrustStore(getAccountDir).load(String(api.getOwnId()));
+            const mine = { companionId: saved?.companionId ?? null };
+            const companions = (devices?.companions || []).map((c) => {
+                const { id, ...rest } = summarizeCompanion(c, mine);
+                return { companionId: id === null ? null : String(id), ...rest };
+            });
+            return {
+                primaryDevice: devices?.masterId ?? null,
+                lastUpdate: devices?.lastUpdateTs ?? null,
+                count: companions.length,
+                companions,
+            };
+        },
+    },
+    usage: {
+        // `db usage`: this account's storage on the server (database, media, outbox), its quota and retention rules,
+        // and the quota state. Read-only and local: Zalo is not asked.
+        async run(_a, ctx) {
+            const ownId = String(ctx.ownId?.() ?? ctx.api.getOwnId());
+            let dbBytes = null;
+            try {
+                dbBytes = dbUsedBytes();
+            } catch {
+                /* no open cache: the file sizes */
+            }
+            return { accountId: ownId, ...describeStorage(ownId, { mediaRoot: ctx.mediaRoot ?? null, dbBytes }) };
+        },
+    },
+    presence_resume: {
+        // `presence resume`: take the account back after a yield (another session of this login took the socket; the
+        // daemon refuses every request until the user closes that session and confirms). The one call let through
+        // while yielded (src/mcp/tool-presence.js).
+        guard: () => ({ key: "presence.resume", target: {} }),
+        async run(_a, ctx) {
+            if (!ctx.presence) throw new Error("this server runs no on-demand presence: there is nothing to resume");
+            return await ctx.presence.serve({ action: "resume" });
+        },
+    },
+};
+
+/** zalo_profile's metadata. */
+export const PROFILE_META = {
+    title: "Manage This Zalo Account's Profile",
+    description:
+        "Change this account's own profile and settings, as the `profile` commands do (read the profile itself " +
+        "with zalo_lookup_user `self: true`). Actions: 'avatar' (set the avatar from a local image, `filePath`), " +
+        "'bio' (read it, or set it to `bio`), 'update' (`name`, `dob`, `gender`), 'settings' (the privacy " +
+        "settings, the read-only ones, and every other key Zalo sent under `other`) and 'set' (one of them: " +
+        "`setting`, `value`), 'avatars' (the avatar gallery), 'full_avatar' " +
+        "(a user's full-size avatar), 'avatar_url' (several users' avatar URLs), 'delete_avatar' (photos from " +
+        "the gallery; asked about first: `confirm`, `dryRun`), 'reuse_avatar' (an earlier photo as the avatar), " +
+        "'active' (this session's presence, active or away, as Zalo sends when its window gains or " +
+        "loses focus; it does not hide the online status, which is 'set' with setting 'online-status'), " +
+        "'lang' (the account language), 'devices' (the phone and " +
+        "the devices linked to this account) and 'usage' (read-only: this account's storage on the server, its " +
+        "database, media and webhook outbox in bytes, its quota and retention rules, and the quota level ok, warn or " +
+        "over with the purge date, as `db usage` prints it; the server also sends `storage_quota` system events " +
+        "through zalo_get_messages and zalo_wait_for_message), and 'presence_resume' (after an `account_state` " +
+        '"yielded" event, when every call is refused with YIELDED: the user closed the other session of this ' +
+        "login, take the account back; asked about first: `confirm`, `dryRun`). Everyone who sees this account " +
+        "sees what changes here.",
+    inputSchema: z
+        .object({
+            action: z
+                .enum(Object.keys(PROFILE_ACTIONS))
+                .describe("Profile operation to perform (the `profile` subcommand, with _ for -)"),
+            filePath: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Only for 'avatar': a local image path on the machine this server runs on"),
+            bio: z
+                .string()
+                .max(500)
+                .optional()
+                .describe("Only for 'bio': the new bio; leave it out to read the current one"),
+            name: z.string().min(1).max(100).optional().describe("Only for 'update': the new display name"),
+            dob: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("Only for 'update': the date of birth, YYYY-MM-DD"),
+            gender: z.enum(["male", "female"]).optional().describe("Only for 'update': male or female"),
+            setting: z
+                .enum(Object.keys(SETTING_MAP))
+                .optional()
+                .describe("Only for 'set': which privacy setting ('settings' shows each with its values)"),
+            value: z
+                .number()
+                .int()
+                .min(0)
+                .max(9)
+                .optional()
+                .describe("Only for 'set': the setting's new value, a number 'settings' lists for it"),
+            userId: z.string().min(1).optional().describe("Only for 'full_avatar': the user whose avatar to fetch"),
+            userIds: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Only for 'avatar_url': the users whose avatar URLs to fetch"),
+            photoIds: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Only for 'delete_avatar': gallery photo ids, from 'avatars'"),
+            photoId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Only for 'reuse_avatar': a gallery photo id, from 'avatars'"),
+            enabled: z
+                .boolean()
+                .optional()
+                .describe(
+                    "Only for 'active': true marks this session active, false away (session presence, not the " +
+                        "online-status privacy setting)",
+                ),
+            language: z.enum(["vi", "en"]).optional().describe("Only for 'lang': vi or en"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Only for 'avatars': page size (one page is read when limit or page is given; 50 a page)"),
+            page: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Only for 'avatars': read only this page (omit limit and page for the whole gallery)"),
+            confirm: confirmInput("'delete_avatar'"),
+            ticket: ticketInput(),
+            dryRun: dryRunInput("'delete_avatar'"),
+        })
+        .strict(),
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+};