@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/core/auto-reply.js

@@ -0,0 +1,27 @@
+/**
+ * Auto-reply rules, as `auto-reply` (src/commands/auto-reply.js) and the MCP tool `zalo_auto_reply` send them.
+ */
+
+/** One year in milliseconds — the default window for an open-ended rule. */
+const DEFAULT_WINDOW_MS = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the {startTime, endTime} window for an auto-reply rule.
+ *
+ * These used to default to 0/0, which Zalo rejects outright with
+ * "Tham số không hợp lệ" — so `auto-reply create` could never succeed on
+ * its defaults. Zalo treats the pair as a real active window, so an unset
+ * start means "from now" and an unset end means "no foreseeable end",
+ * expressed as a far-future timestamp rather than 0.
+ *
+ * @param {{start?: number, end?: number}} opts
+ * @returns {{startTime: number, endTime: number}}
+ */
+export function activeWindow(opts) {
+    const startTime = Number.isFinite(opts.start) && opts.start > 0 ? opts.start : Date.now();
+    const endTime = Number.isFinite(opts.end) && opts.end > 0 ? opts.end : startTime + DEFAULT_WINDOW_MS;
+    return { startTime, endTime };
+}
+
+/** Who a rule answers, by name: Zalo's `scope` codes. */
+export const AUTO_REPLY_SCOPES = Object.freeze({ all: 0, friends: 1, strangers: 2 });

package/src/core/bank-accounts.js

@@ -14,7 +14,7 @@ const SCAN_BATCH = 50;
  * an account starts by finding it. Scans page by page while Zalo says there are
  * more, with a cap so a server that never stops saying so cannot loop us.
  *
- * @param {object} api - logged-in zca-js api
+ * @param {object} api - logged-in session
  * @param {number} accountId
  * @returns {Promise<object|null>} the saved account, or null when no page has it
  */

package/src/core/block-sharing.js

@@ -0,0 +1,43 @@
+/**
+ * Block sharing for one conversation (`conv block-sharing`, zalo_conversation `block_sharing`): one function, one
+ * reply. It is Zalo's `/api/conv/blocksharing/updateConvers`, the `blocksharing-update` write
+ * (src/zalo/writes.js), which needs a zBusiness Max account and has never been seen to succeed: unverified.
+ */
+import { callWrite } from "../zalo/writes.js";
+import { errorCodeOf } from "../zalo/errors.js";
+
+/** The refusals Zalo names for this call, by error code. */
+export const BLOCK_SHARING_REFUSALS = Object.freeze({
+    829: "this feature is for zBusiness accounts only (zBusiness Max)",
+    273: "Zalo could not save the setting",
+    275: "only the group's admins may change it",
+    277: "this account's limit of such settings is reached",
+    278: "the other side's limit of such settings is reached",
+    280: "this account blocks the other side",
+});
+
+/**
+ * Turn block sharing on or off for one conversation.
+ *
+ * @param {object} api - logged-in session
+ * @param {{threadId: string, type: 0|1, enabled: boolean}} opts
+ * @returns {Promise<{success: true, threadId: string, threadType: "dm"|"group", blockSharing: boolean,
+ *   verified: false}>}
+ * @throws {Error} Zalo's refusal, named when its code is known
+ */
+export async function setBlockSharing(api, { threadId, type, enabled }) {
+    const isGroup = Number(type) === 1;
+    try {
+        await callWrite(api, "blocksharing-update", { threadId: String(threadId), isGroup, enabled: Boolean(enabled) });
+    } catch (e) {
+        const why = BLOCK_SHARING_REFUSALS[errorCodeOf(e)];
+        throw new Error(why ? `${e.message} (${why})` : e.message, { cause: e });
+    }
+    return {
+        success: true,
+        threadId: String(threadId),
+        threadType: isGroup ? "group" : "dm",
+        blockSharing: Boolean(enabled),
+        verified: false,
+    };
+}

package/src/core/board-pass.js

@@ -0,0 +1,94 @@
+/**
+ * One board pass over the cached threads: notes, pinned messages, polls and reminders, which live behind per-thread
+ * board endpoints rather than in the message stream. What `sync-boards` and `sync`'s boards stage run, and what the
+ * MCP server's `boards` sync stage calls too; it reports through `onProgress` instead of printing.
+ */
+
+import { clearSyncState, getRecentThreads, getSyncState, getThreadType, setSyncState } from "./db.js";
+import { syncBoards } from "./sync-v2/board.js";
+
+/** Where a pass stopped by Zalo's 221 left off; the next full pass starts there. */
+export const BOARD_RESUME_KEY = "boardPass:resumeFrom";
+
+/**
+ * The threads one pass visits: exactly `thread` when one is named (whatever its age), else every cached thread, most
+ * recent first, or the first `limit` of them when the caller asked for a bound.
+ *
+ * @param {{thread?: string, limit?: number}} opts
+ * @returns {Array<{threadId: string, type: string, name?: string}>}
+ */
+function threadsFor(opts) {
+    if (opts.thread) {
+        const id = String(opts.thread);
+        const type = getThreadType(id);
+        if (!type) return [];
+        const row = getRecentThreads(-1).find((t) => String(t.threadId) === id);
+        return [{ threadId: id, type, name: row?.name }];
+    }
+    const limit = Number(opts.limit) > 0 ? Number(opts.limit) : -1;
+    return getRecentThreads(limit).map((t) => ({ threadId: String(t.threadId), type: t.type, name: t.name }));
+}
+
+/**
+ * Visit every cached thread (or one, or the first `limit`), the ones a live board event flagged first, and store
+ * what their boards hold. A thread's "board changed" flag is cleared only once its own fetch worked. When Zalo answers
+ * 221 the pass stops, remembers the thread it stopped at, and the next full pass starts from there.
+ *
+ * @param {object} api - logged-in session
+ * @param {{limit?: number, thread?: string, boards?: boolean, reminders?: boolean, concurrency?: number,
+ *   onProgress?: (p: object) => void, onNote?: (message: string) => void}} opts
+ * @returns {Promise<{status: "ok"|"skipped", reason?: string, stats?: object, resumed?: boolean, note?: string}>}
+ */
+export async function runBoardPass(api, opts = {}) {
+    const onProgress = opts.onProgress ?? (() => {});
+    const onNote = opts.onNote ?? (() => {});
+    const threads = threadsFor(opts);
+    if (!threads.length) {
+        return {
+            status: "skipped",
+            reason: opts.thread ? `thread ${opts.thread} is not in the local cache` : "no threads in the local cache",
+        };
+    }
+    const whole = !opts.thread && !(Number(opts.limit) > 0);
+    // A pass a 221 stopped resumes where it stopped; the threads before it come last.
+    let resumed = false;
+    if (whole) {
+        const from = getSyncState(BOARD_RESUME_KEY);
+        const at = from ? threads.findIndex((t) => t.threadId === from) : -1;
+        if (at > 0) {
+            threads.push(...threads.splice(0, at));
+            resumed = true;
+            onNote(`resuming the board pass a rate limit stopped, at thread ${from}`);
+        }
+    }
+    // A live board event flags its thread; those go first, so a pass right after one refreshes what moved.
+    if (!opts.thread) {
+        const stale = threads.filter((t) => getSyncState(`boardStale:${t.threadId}`));
+        if (stale.length) {
+            onNote(`${stale.length} thread(s) had a board change since the last pass — doing those first`);
+            const rest = threads.filter((t) => !getSyncState(`boardStale:${t.threadId}`));
+            threads.splice(0, threads.length, ...stale, ...rest);
+        }
+    }
+    const stats = await syncBoards({
+        api,
+        threads,
+        boards: opts.boards !== false,
+        reminders: opts.reminders !== false,
+        concurrency: opts.concurrency,
+        onProgress: (p) => {
+            if (p.phase === "thread" && p.ok) clearSyncState(`boardStale:${p.threadId}`);
+            onProgress(p);
+        },
+    });
+    const out = { status: "ok", stats, ...(resumed && { resumed }) };
+    if (stats.stoppedBy === "rate-limit") {
+        if (whole && stats.nextThreadId) setSyncState(BOARD_RESUME_KEY, stats.nextThreadId);
+        out.note =
+            `Zalo answered 221 (too many requests): the pass stopped with ${stats.left} thread(s) left.` +
+            (whole ? " Run it again later; it resumes where it stopped." : " Run it again later.");
+    } else if (whole) {
+        clearSyncState(BOARD_RESUME_KEY);
+    }
+    return out;
+}

package/src/core/cached-message.js

@@ -12,7 +12,8 @@
  * the active account's first, and `mcp start` opened it at start-up.
  */
 
-import { getMessageById } from "./db.js";
+import { findMessageByClientId, getMessageForAction } from "./db.js";
+import { senderNameFields } from "./contact-names.js";
 
 /**
  * `raw_data` as an object, whatever shape its writer used.
@@ -48,7 +49,7 @@ export function cachedCliMsgId(row) {
  * The message's text as it was sent.
  *
  * The listener trims the `text` column; the payload keeps the original string,
- * which is what Zalo Web forwards and pins.
+ * which is what a forward or a pin carries.
  *
  * @param {object} row - a `messages` row
  * @returns {string}
@@ -58,6 +59,73 @@ export function cachedText(row) {
     return typeof content === "string" && content.length > 0 ? content : row?.text || "";
 }
 
+/** A Zalo user id is all digits; a synced row's author can be an opaque noised id, which no tool takes. */
+const USER_ID = /^\d+$/;
+
+/**
+ * What a reply quotes, in the reply shape every MCP message carries as `replyTo`, from the quote Zalo puts on
+ * the message (the `quote` of a live event; the same object a restore keeps). Null when there is no quote or
+ * it names no message.
+ *
+ * @param {object|null|undefined} quote
+ * @returns {{msgId: string|null, cliMsgId: string|null, senderId: string|null, senderName: string|null,
+ *   senderAlias: string|null, senderZaloName: string|null, text: string, timestamp: number|null, hasAttachment: boolean}|null}
+ */
+export function quotedReply(quote) {
+    if (!quote || typeof quote !== "object") return null;
+    const id = (v) => (v === undefined || v === null || v === "" || Number(v) === 0 ? null : String(v));
+    const msgId = id(quote.globalMsgId);
+    const cliMsgId = id(quote.cliMsgId);
+    if (!msgId && !cliMsgId) return null;
+    const owner = id(quote.ownerId);
+    const senderId = owner && USER_ID.test(owner) ? owner : null;
+    const attach = typeof quote.attach === "string" ? quote.attach.trim() : quote.attach;
+    return {
+        msgId,
+        cliMsgId,
+        senderId,
+        // The quoted author as Zalo shows them: it renames the quote's `fromD` at render with the owner's alias
+        // (src/core/contact-names.js). `senderZaloName` keeps the name the quote carried.
+        ...senderNameFields(senderId, typeof quote.fromD === "string" && quote.fromD ? quote.fromD : null),
+        text: typeof quote.msg === "string" ? quote.msg : "",
+        timestamp: Number(quote.ts) || null,
+        hasAttachment: Boolean(attach) && attach !== "{}",
+    };
+}
+
+/**
+ * What a cached row replies to (see `quotedReply`), read from the payload the listener or a restore stored.
+ *
+ * @param {object} row - a `messages` row
+ * @returns {ReturnType<typeof quotedReply>}
+ */
+export function cachedReplyTo(row) {
+    return resolveReplyTo(quotedReply(parseRawData(row?.raw_data).quote), row?.threadId);
+}
+
+/**
+ * Fill in `replyTo.msgId` from the cache when the quote named the message only by its client id.
+ *
+ * A reply sent from the phone quotes with `globalMsgId: "0"` and the quoted message's `cliMsgId` (seen live
+ * 2026-11-06), so without this `replyTo.msgId` was null and nothing tied the reply to the message it answers. Left
+ * as it is when the message is not cached, or no database is open in this process.
+ *
+ * @param {ReturnType<typeof quotedReply>} replyTo
+ * @param {string|number|null} [threadId] - the reply's thread, where the quoted message is
+ * @param {{find?: Function}} [o] - the client-id lookup, `findMessageByClientId` by default
+ * @returns {ReturnType<typeof quotedReply>}
+ */
+export function resolveReplyTo(replyTo, threadId = null, { find = findMessageByClientId } = {}) {
+    if (!replyTo || replyTo.msgId || !replyTo.cliMsgId) return replyTo;
+    try {
+        const row = find(replyTo.cliMsgId, threadId);
+        if (row?.msgId) return { ...replyTo, msgId: String(row.msgId) };
+    } catch {
+        /* no database open here */
+    }
+    return replyTo;
+}
+
 /**
  * Look one message up in the local SQLite cache by its global msgId.
  *
@@ -73,7 +141,8 @@ export function cachedText(row) {
  * A direct lookup by msgId, checked against the thread. This used to scan the
  * thread's newest 200 rows, so anything older was reported as uncached.
  *
- * Never throws.
+ * Throws only when the cached row fails its integrity check (`RowIntegrityError`, code ROW_MAC; src/core/row-mac.js):
+ * an action must not take its ids from a row someone changed. Otherwise never throws.
  *
  * @param {string} threadId
  * @param {string} msgId
@@ -81,7 +150,7 @@ export function cachedText(row) {
  */
 export function cachedMessageById(threadId, msgId) {
     try {
-        const row = getMessageById(msgId);
+        const row = getMessageForAction(msgId);
         // msgIds are account-wide: a row from another conversation must not
         // lend its ids to an action aimed at this one.
         if (!row || (row.threadId && String(row.threadId) !== String(threadId))) return null;
@@ -90,7 +159,8 @@ export function cachedMessageById(threadId, msgId) {
         const cliMsgId = cachedCliMsgId(row);
         const uidFrom = row.senderId ?? data.uidFrom;
         return cliMsgId ? { cliMsgId, uidFrom: uidFrom ? String(uidFrom) : null } : null;
-    } catch {
+    } catch (e) {
+        if (e?.code === "ROW_MAC") throw e;
         return null; // no db open in this process
     }
 }
@@ -168,13 +238,13 @@ export function isNumericUid(id) {
 /**
  * The sender's real numeric uid.
  *
- * A listener row already holds it (zca-js rewrites the own "0" to the uid). A
+ * A listener row already holds it (the listener rewrites the own "0" to the uid). A
  * row the mobile sync restored holds a noised id instead, which Zalo will not
  * accept in a pin or a forward reference; it decodes through the same
  * /api/gid/decrypt the sync path uses for conversation ids. gid.js is imported
  * lazily so the common path pays nothing for it.
  *
- * @param {object} api - a logged-in zca-js API (only used for a noised id)
+ * @param {object} api - a logged-in session (only used for a noised id)
  * @param {string|null} senderId - the row's senderId
  * @param {string|null} ownId - this account's uid
  * @returns {Promise<{uid: string}|{error: string}>}
@@ -186,7 +256,7 @@ export async function resolveSenderUid(api, senderId, ownId) {
     if (!id) return { error: "its sender is not in the cache" };
 
     try {
-        const { resolveNonFriendDms } = await import("./sync-v2/gid.js");
+        const { resolveNonFriendDms } = await import("../zalo/custom/gid.js");
         const hit = (await resolveNonFriendDms(api, [id])).get(id);
         if (hit?.id && isNumericUid(hit.id)) return { uid: String(hit.id) };
     } catch {

package/src/core/cloud-plan.js

@@ -0,0 +1,285 @@
+/**
+ * What is in the zCloud index, what a cleanup would touch (decision D27, 2026-10-28), and what deleting it sends.
+ *
+ * Zalo has no endpoint that deletes a zCloud item. Zalo's own "Delete" in its cloud view deletes the chat MESSAGE
+ * each item belongs to, for this account only (`onlyMe`, the delete-for-me sync), one message at a time, conversation
+ * by conversation, and waits for the cloud queue to drop the items. That has no undo. The planning half reads the local
+ * index (`cloud_items`, filled by `sync-cloud`) and the local message cache and sends nothing; {@link
+ * cloudDeleteTarget} builds the message reference Zalo's cloud delete sends for one item, which `cloud apply` hands to
+ * the session's `deleteMessage`.
+ */
+
+/** The message types of a queue item, as Zalo names them, reduced to the kinds a person thinks in. */
+const KIND_OF = {
+    "chat.photo": "photo",
+    "chat.video.msg": "video",
+    "chat.voice": "voice",
+    "share.file": "file",
+    "chat.gif": "gif",
+    "chat.doodle": "photo",
+};
+
+/**
+ * Items per page of Zalo's cloud manager: fixed at 60. Its "select all" selects the loaded page, and a delete works
+ * through that page; `cloud apply` works through every match the same way, a page of 60 after another.
+ */
+export const CLOUD_PAGE_SIZE = 60;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * An item reduced to what a plan needs.
+ *
+ * @param {object} row - a `cloud_items` row
+ * @param {string|null} ownId
+ * @returns {{noiseId: string, threadId: string|null, bytes: number, ts: number, kind: string, group: boolean,
+ *   incoming: boolean, selfChat: boolean, e2ee: boolean, cliMsgId: string|null, zKey: string|null}}
+ */
+export function describeItem(row, ownId = null) {
+    let raw = {};
+    try {
+        raw = JSON.parse(row.raw_data || "{}");
+    } catch {
+        raw = {};
+    }
+    const info = raw.msgInfo || {};
+    const type = String(info.msgType ?? "");
+    const src = info.srcId === undefined || info.srcId === null ? null : String(info.srcId);
+    return {
+        noiseId: String(row.noiseId),
+        threadId: row.threadId === null || row.threadId === undefined ? null : String(row.threadId),
+        bytes: Number(row.mediaSize) || 0,
+        ts: Number(row.timestamp) || Number(info.ts) || 0,
+        kind: KIND_OF[type] ?? (type ? "other" : "unknown"),
+        group: Number(info.destType) === 6,
+        incoming: Boolean(ownId && src && src !== String(ownId)),
+        // The self chat ("My Cloud"): sent to oneself.
+        selfChat: Boolean(ownId && String(row.threadId) === String(ownId)),
+        e2ee: Number(info.isE2EE) === 1,
+        cliMsgId: info.cliMsgId === undefined || info.cliMsgId === null ? null : String(info.cliMsgId),
+        msgId: info.glbMsgId === undefined || info.glbMsgId === null ? null : String(info.glbMsgId),
+        srcId: src,
+        zKey: row.zKey ?? null,
+    };
+}
+
+/**
+ * The message reference Zalo's cloud delete sends for one item: the message's global id,
+ * or `<cliMsgId>_001` when the queue names none; this account written as `"0"` when it sent the message; the
+ * conversation the item belongs to. In the shape the session's `deleteMessage(target, true)` takes.
+ *
+ * @param {ReturnType<typeof describeItem>} item
+ * @param {string|null} ownId
+ * @returns {{data: {cliMsgId: string, msgId: string, uidFrom: string}, threadId: string, type: 0|1}|null} null for an
+ *   item without a client message id, a sender or a conversation (it cannot be named), or an encrypted one
+ */
+export function cloudDeleteTarget(item, ownId) {
+    if (!item || item.e2ee || !item.cliMsgId || !item.srcId || !item.threadId) return null;
+    const msgId = item.msgId || `${item.cliMsgId}_001`;
+    const uidFrom = ownId && item.srcId === String(ownId) ? "0" : item.srcId;
+    return { data: { cliMsgId: item.cliMsgId, msgId, uidFrom }, threadId: item.threadId, type: item.group ? 1 : 0 };
+}
+
+/**
+ * Delete the messages behind planned items for this account, as Zalo's cloud manager does: a page of
+ * {@link CLOUD_PAGE_SIZE} items at a time, and within a page conversation by conversation, one delete-for-me per
+ * message, sequentially, with no pause. A conversation stops at its first failure: the rest of
+ * its items, in this page and every later one, are not tried, and the other conversations go on. The local index is
+ * left alone: the server's cloud queue reports the removals, and the next `sync-cloud` applies them.
+ *
+ * @param {object} args
+ * @param {Array<ReturnType<typeof describeItem>>} args.items - the planned items (every match unless a limit was asked)
+ * @param {string|null} args.ownId
+ * @param {(target: object) => Promise<unknown>} args.deleteForMe - `(t) => api.deleteMessage(t, true)`
+ * @param {(p: {done: number, total: number, item: object, ok: boolean, error?: string, page: number}) => void}
+ *   [args.onProgress]
+ * @param {number} [args.pageSize] - items per page (tests)
+ * @returns {Promise<{deleted: number, failed: Array<{noiseId: string, threadId: string|null, error: string}>,
+ *   skipped: Array<{noiseId: string, reason: string}>, bytes: number, pages: number,
+ *   stoppedConversations: Array<{threadId: string, error: string}>}>} `bytes`: the media of the deleted items
+ */
+export async function applyCloudCleanup({
+    items,
+    ownId,
+    deleteForMe,
+    onProgress = () => {},
+    pageSize = CLOUD_PAGE_SIZE,
+}) {
+    const skipped = [];
+    const named = [];
+    for (const it of items) {
+        const target = cloudDeleteTarget(it, ownId);
+        if (!target) {
+            skipped.push({
+                noiseId: it.noiseId,
+                reason: it.e2ee ? "end-to-end encrypted" : "the message is not named",
+            });
+            continue;
+        }
+        named.push({ it, target });
+    }
+    const total = named.length;
+    const failed = [];
+    const stopped = new Map(); // threadId -> the error that stopped it
+    let deleted = 0;
+    let bytes = 0;
+    let done = 0;
+    let pages = 0;
+    for (let start = 0; start < named.length; start += pageSize) {
+        pages++;
+        const byConv = new Map();
+        for (const entry of named.slice(start, start + pageSize)) {
+            const list = byConv.get(entry.target.threadId) ?? [];
+            list.push(entry);
+            byConv.set(entry.target.threadId, list);
+        }
+        for (const [threadId, list] of byConv) {
+            for (const { it, target } of list) {
+                if (stopped.has(threadId)) {
+                    failed.push({ noiseId: it.noiseId, threadId, error: "not tried: an earlier delete failed" });
+                    continue;
+                }
+                try {
+                    await deleteForMe(target);
+                    deleted++;
+                    bytes += it.bytes;
+                    onProgress({ done: ++done, total, item: it, ok: true, page: pages });
+                } catch (e) {
+                    const error = e?.message || String(e);
+                    stopped.set(threadId, error);
+                    failed.push({ noiseId: it.noiseId, threadId, error });
+                    onProgress({ done: ++done, total, item: it, ok: false, error, page: pages });
+                }
+            }
+        }
+    }
+    const stoppedConversations = [...stopped].map(([threadId, error]) => ({ threadId, error }));
+    return { deleted, failed, skipped, bytes, pages, stoppedConversations };
+}
+
+/**
+ * Plan a cleanup: which items, how many bytes, and what is risky. A dry run on the local index.
+ *
+ * Excluded always: end-to-end encrypted items (their removal needs a key and a Signal identity this tool does not
+ * have). Excluded unless asked: groups, My Cloud (the self chat).
+ *
+ * @param {object} args
+ * @param {object[]} args.rows - `cloud_items` rows
+ * @param {string|null} [args.ownId]
+ * @param {object} [args.filters]
+ * @param {string[]} [args.filters.threads] - only these conversations
+ * @param {string[]} [args.filters.kinds] - only these kinds (photo, video, file, voice, gif, other)
+ * @param {number} [args.filters.olderThanDays]
+ * @param {number} [args.filters.largerThanBytes]
+ * @param {boolean} [args.filters.onlySavedLocally] - only items whose file this machine already has
+ * @param {boolean} [args.filters.includeGroups=false]
+ * @param {boolean} [args.filters.includeMyCloud=false]
+ * @param {number} [args.filters.limit] - items listed; every match unless given (the totals always cover every match)
+ * @param {(item: ReturnType<typeof describeItem>) => boolean} [args.savedLocally] - whether this machine holds the
+ *   item's file
+ * @param {(threadId: string) => string|null} [args.nameOf]
+ * @param {number} [args.now]
+ * @returns {{
+ *   items: Array<object>, matched: number, listed: number, bytes: number,
+ *   byKind: Record<string, {items: number, bytes: number}>,
+ *   byConversation: Array<{threadId: string, name: string|null, items: number, bytes: number}>,
+ *   excluded: {e2ee: number, groups: number, myCloud: number, notSavedLocally: number},
+ *   risks: {notSavedLocally: number, incoming: number, groups: number}
+ * }}
+ */
+export function planCloudCleanup({
+    rows,
+    ownId = null,
+    filters = {},
+    savedLocally = () => false,
+    nameOf = () => null,
+    now = Date.now(),
+}) {
+    const {
+        threads = [],
+        kinds = [],
+        olderThanDays = null,
+        largerThanBytes = null,
+        onlySavedLocally = false,
+        includeGroups = false,
+        includeMyCloud = false,
+    } = filters;
+    // No limit by default: the plan lists every match, and `apply` acts on every one. A limit is the caller's choice.
+    const asked = Math.floor(Number(filters.limit));
+    const limit = Number.isFinite(asked) && asked >= 1 ? asked : Infinity;
+    const wantThreads = new Set(threads.map(String));
+    const wantKinds = new Set(kinds.map((k) => String(k).toLowerCase()));
+    const cutoff = olderThanDays === null || olderThanDays === undefined ? null : now - Number(olderThanDays) * DAY_MS;
+
+    const excluded = { e2ee: 0, groups: 0, myCloud: 0, notSavedLocally: 0 };
+    const chosen = [];
+    for (const row of rows) {
+        const it = describeItem(row, ownId);
+        if (wantThreads.size && !wantThreads.has(String(it.threadId))) continue;
+        if (wantKinds.size && !wantKinds.has(it.kind)) continue;
+        if (cutoff !== null && !(it.ts > 0 && it.ts < cutoff)) continue;
+        if (largerThanBytes !== null && !(it.bytes >= Number(largerThanBytes))) continue;
+        if (it.e2ee) {
+            excluded.e2ee++;
+            continue;
+        }
+        if (it.selfChat && !includeMyCloud) {
+            excluded.myCloud++;
+            continue;
+        }
+        if (it.group && !includeGroups) {
+            excluded.groups++;
+            continue;
+        }
+        const saved = Boolean(savedLocally(it));
+        if (onlySavedLocally && !saved) {
+            excluded.notSavedLocally++;
+            continue;
+        }
+        chosen.push({ ...it, saved });
+    }
+    chosen.sort((a, b) => b.bytes - a.bytes || b.ts - a.ts);
+
+    const byKind = {};
+    const convs = new Map();
+    const risks = { notSavedLocally: 0, incoming: 0, groups: 0 };
+    let bytes = 0;
+    for (const it of chosen) {
+        bytes += it.bytes;
+        const k = (byKind[it.kind] ??= { items: 0, bytes: 0 });
+        k.items++;
+        k.bytes += it.bytes;
+        const key = it.threadId ?? "?";
+        const c = convs.get(key) ?? { threadId: key, name: nameOf(key), items: 0, bytes: 0 };
+        c.items++;
+        c.bytes += it.bytes;
+        convs.set(key, c);
+        if (!it.saved) risks.notSavedLocally++;
+        if (it.incoming) risks.incoming++;
+        if (it.group) risks.groups++;
+    }
+    const listed = chosen.slice(0, limit).map((it) => ({
+        ...it,
+        risk: [!it.saved && "not-saved-locally", it.incoming && "incoming-message", it.group && "group"].filter(
+            Boolean,
+        ),
+    }));
+    return {
+        items: listed,
+        matched: chosen.length,
+        listed: listed.length,
+        bytes,
+        byKind,
+        byConversation: [...convs.values()].sort((a, b) => b.bytes - a.bytes),
+        excluded,
+        risks,
+    };
+}
+
+/**
+ * The words that go with every plan: what applying one would mean at Zalo. Printed, and stored in the plan file.
+ */
+export const CLEANUP_WARNING =
+    "Zalo has no endpoint that deletes a zCloud item. The only removal, the one Zalo's own cloud view uses, is " +
+    "deleting the chat message the item belongs to, for this account on every device, and that cannot be undone. This is a " +
+    "report: nothing was sent to Zalo and nothing was deleted (`cloud apply --yes` with the same filters does it).";