@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/sync.js

@@ -5,12 +5,13 @@ import {
     getSyncState,
     setSyncState,
     recordSyncGap,
+    countSyncRanges,
     getPendingSyncGaps,
     resolveAllPendingSyncGaps,
 } from "./db.js";
 import { storeLiveMessage } from "./live-store.js";
 
-/** zca-js ThreadType values, mirrored so this module doesn't import the enum. */
+/** Thread type values, mirrored so this module doesn't import the enum. */
 const THREAD_TYPE_USER = 0;
 const THREAD_TYPE_GROUP = 1;
 
@@ -18,9 +19,8 @@ function resolveAccountDir(accountName) {
     return resolve(getAccountDir(accountName));
 }
 
-/** Zalo Web's own client only ever seems to backfill about this far on a
- * fresh login (confirmed by live observation — see agent/docs/mobile-sync-
- * live-test-results.md, task #4). Clamp any gap we ask the mobile app to
+/** Zalo only ever seems to backfill about this far on a fresh login
+ * (confirmed by live observation). Clamp any gap we ask the mobile app to
  * fill to this width so we never request something the platform wouldn't
  * honor anyway, and so a very old `lastConnectedAt` (e.g. the tool sat
  * uninstalled for months) doesn't produce a nonsensical multi-month ask. */
@@ -28,12 +28,9 @@ export const MAX_GAP_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
 
 /**
  * How recently a sync must have completed for a fresh one to be treated as
- * redundant and skipped. This is the CLI equivalent of Zalo Web's own
- * redundant-sync gate: after a successful sync, Zalo Web sets a
- * `0_sufficient_msg_ts` marker and records the run in `0_sync_download_stats_v1`,
- * and clicking "Đồng bộ tin nhắn" again while those are fresh is a silent no-op —
- * it never re-opens the transfer session, so it never re-pings the phone
- * (confirmed by a live capture, 2026-09-21). Bypass with `{force: true}`
+ * redundant and skipped: a redundant-sync gate, so that asking again while the
+ * last run is fresh is a silent no-op that never re-opens the transfer session
+ * and so never re-pings the phone. Bypass with `{force: true}`
  * (the `sync-mobile --force` flag).
  */
 export const SYNC_FRESHNESS_MS = 60 * 60 * 1000; // 1 hour
@@ -71,7 +68,9 @@ export class SyncManager {
         if (safeTo - safeFrom < 1000) return null; // not worth tracking (<1s)
         const id = recordSyncGap(safeFrom, safeTo, reason);
         setSyncState("lastConnectionOk", "false");
-        console.log(
+        // stderr: `listen --json` streams one event per stdout line, and a
+        // startup gap is recorded while that stream is open.
+        console.error(
             `[Sync] Recorded coverage gap #${id} (${reason}): ${new Date(safeFrom).toISOString()} → ${new Date(safeTo).toISOString()}`,
         );
         return id;
@@ -158,12 +157,13 @@ export class SyncManager {
 
     /**
      * Decide whether a sync can be skipped because we completed one recently
-     * and know of no coverage gap — the CLI equivalent of Zalo Web's
-     * redundant-sync debounce (see {@link SYNC_FRESHNESS_MS}), so repeated runs
+     * and know of no coverage gap — a redundant-sync
+     * debounce (see {@link SYNC_FRESHNESS_MS}), so repeated runs
      * don't spam the socket or, for the phone-waking transfer-sync path, the
      * owner's phone.
      *
-     * A pending coverage gap always forces a sync, and so does `force`.
+     * A pending coverage gap always forces a sync, and so does an unfinished conversation range (a restore that
+     * settled only part of its window), and so does `force`.
      * Otherwise we skip when the last success is younger than `freshnessMs` —
      * unless the caller is asking for a WIDER window than the last success
      * covered (`coversFrom` older than the recorded `lastSyncOkFrom`). A
@@ -186,6 +186,10 @@ export class SyncManager {
 
         if (force) return out(false, "forced");
         if (getPendingSyncGaps().length > 0) return out(false, "pending-gap");
+        // A restore that settled only part of its window left ranges behind: that is work to finish, however
+        // recently the last run ended (Y5b).
+        const ranges = countSyncRanges();
+        if (ranges.pending + ranges.failed > 0) return out(false, "unfinished-ranges");
         if (lastSyncAt === null) return out(false, "never-synced");
         if (ageMs < freshnessMs) {
             const widening = Number.isFinite(opts.coversFrom) && coveredFrom !== null && coveredFrom > opts.coversFrom;
@@ -199,22 +203,20 @@ export class SyncManager {
      * WebSocket, writing it into the same zalo.db the `listen` daemon uses.
      *
      * Uses socket cmd 510 (DMs) and 511 (groups), subCmd 1, payload
-     * `{first: true, lastId, preIds: []}` — which zca-js already speaks via
-     * `listener.requestOldMessages()` and the `old_messages` event, so no
-     * patch to the library is needed.
+     * `{first: true, lastId, preIds: []}` — which the listener already speaks via
+     * `listener.requestOldMessages()` and the `old_messages` event.
      *
      * MEASURED 2026-09-20, and worth knowing before trusting this: Zalo
      * returned an EMPTY set for both commands on the development account, both
-     * with `lastId: null` and with the exact anchor ids Zalo Web sends. Zalo
-     * Web gets the same empty answer and falls back to `transfer-sync-v2`
-     * (cmd 590/591, libsignal), which is not implemented here. Treat this as a
+     * with `lastId: null` and with exact anchor ids. The fallback is
+     * `transfer-sync-v2` (cmd 590/591, libsignal), which is not implemented here. Treat this as a
      * cheap probe, not a guaranteed restore. See agent/work/transfer-sync-v2/NOTES.md § Mobile sync.
      *
      * The caller owns the socket: it must hold `daemon.lock`, start the
      * listener, and stop it afterwards. This method only issues the two
      * requests and persists whatever comes back.
      *
-     * @param {import("zca-js").Listener} listener A started zca-js listener.
+     * @param {import("../zalo/listener/listener.js").Listener} listener A started listener.
      * @param {{timeoutMs?: number, onBatch?: (info: object) => void}} [opts]
      * @returns {Promise<{status: string, saved: number, total: number, reason: string}>}
      */

package/src/core/test-fake-session.js

@@ -0,0 +1,87 @@
+/**
+ * Test seam: run a CLI command against an injected fake session instead of logging in.
+ *
+ * `ZALO_TEST_FAKE_API=<path to a module>` makes `autoLogin()` (src/core/zalo-client.js) import that module and
+ * use the session its `createFakeSession(env)` returns, so an offline test can execute any command's action
+ * without a Zalo account (tests/cli/json-contract.test.js runs every personal command this way).
+ *
+ * It must be impossible to reach in normal use, so the variable is REFUSED -- the command fails before
+ * anything else happens, it never falls back to a real login -- unless every one of these holds:
+ *
+ *   1. `ZALO_SANDBOX_ACTIVE=1`, which only the offline test sandbox sets (tests/helpers/sandbox.js, cli.js);
+ *   2. the home directory is a sandbox home: a `zalo-agent-test-*` folder directly inside the OS temp folder;
+ *   3. the config directory in use (after `--config-dir` / `ZALO_CONFIG_DIR`) lies inside that home;
+ *   4. the module is a file under this package's own `tests/` folder, which the npm package does not ship
+ *      (package.json `files` lists `src/` only), so an installed CLI has no module it could load.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, isAbsolute } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const TEST_FAKE_API_ENV = "ZALO_TEST_FAKE_API";
+
+/** `.code` of the error a refused {@link TEST_FAKE_API_ENV} raises. */
+export const TEST_FAKE_API_REFUSED = "TEST_FAKE_API_REFUSED";
+
+const TESTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "tests");
+
+const real = (p) => {
+    try {
+        return realpathSync(p);
+    } catch {
+        return resolve(p);
+    }
+};
+
+/** Whether `child` is `parent` itself or lies inside it. */
+const inside = (child, parent) => {
+    const rel = relative(real(parent), real(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
+/**
+ * The fake-session module to load, or null when the variable is not set.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string} opts.configDir - the config directory in use
+ * @param {string} [opts.home]
+ * @param {string} [opts.temp]
+ * @returns {string|null} absolute module path
+ * @throws {Error} when the variable is set outside the offline test sandbox
+ */
+export function resolveTestFakeApi({ env = process.env, configDir, home = homedir(), temp = tmpdir() } = {}) {
+    const raw = env[TEST_FAKE_API_ENV];
+    if (!raw) return null;
+    const refuse = (why) => {
+        const e = new Error(`${TEST_FAKE_API_ENV} is a test-only setting and is refused here: ${why}. Unset it.`);
+        e.code = TEST_FAKE_API_REFUSED;
+        throw e;
+    };
+    if (env.ZALO_SANDBOX_ACTIVE !== "1") refuse("not running in the offline test sandbox");
+    if (!basename(home).startsWith("zalo-agent-test-") || real(dirname(home)) !== real(temp)) {
+        refuse("the home directory is not a test sandbox home");
+    }
+    if (!configDir || !inside(configDir, home)) refuse("the config directory is outside the test sandbox");
+    const modulePath = resolve(raw);
+    if (!existsSync(modulePath) || !existsSync(TESTS_DIR) || !inside(modulePath, TESTS_DIR)) {
+        refuse("the module is not part of this package's test suite");
+    }
+    return modulePath;
+}
+
+/**
+ * Load the fake session the module makes.
+ *
+ * @param {string} modulePath - from {@link resolveTestFakeApi}
+ * @returns {Promise<{api: object, ownId: string|null}>}
+ */
+export async function loadTestFakeSession(modulePath) {
+    const mod = await import(pathToFileURL(modulePath).href);
+    if (typeof mod.createFakeSession !== "function") {
+        throw new Error(`${TEST_FAKE_API_ENV}: ${modulePath} does not export createFakeSession()`);
+    }
+    return mod.createFakeSession(process.env);
+}

package/src/core/typing.js

@@ -0,0 +1,78 @@
+/**
+ * Sending the "typing…" indicator (`msg typing`, zalo_conversation `typing`): one function, one reply, and Zalo's
+ * privacy rule for strangers.
+ *
+ * Zalo does not send typing to a stranger in a 1-1 conversation when the `enable_new_privacy_stranger_chat`
+ * switch is on and the peer is a stranger. This client follows it, using the
+ * friend list this process already holds ({@link rememberFriends}: the MCP server loads it on start). A one-shot CLI
+ * holds none: the cache is cold, so the indicator is sent and the reply says the check could not be made. Groups are
+ * never checked.
+ */
+import { THREAD_TYPE } from "../zalo/enums.js";
+
+/** The friend ids this process knows, or null while it knows none (cold). */
+let friends = null;
+
+/**
+ * Remember this account's friends (from `getAllFriends`, or a list of ids), replacing what was known.
+ *
+ * @param {Array<string|{userId?: string, uid?: string}>|null} list - null forgets them (cold again)
+ */
+export function rememberFriends(list) {
+    if (!Array.isArray(list)) {
+        friends = null;
+        return;
+    }
+    friends = new Set(
+        list.map((f) => (f && typeof f === "object" ? String(f.userId ?? f.uid ?? "") : String(f))).filter(Boolean),
+    );
+}
+
+/**
+ * Whether a user is a friend: true, false, or null when this process knows no friend list.
+ *
+ * @param {string} userId
+ * @returns {boolean|null}
+ */
+export function isKnownFriend(userId) {
+    return friends === null ? null : friends.has(String(userId));
+}
+
+/**
+ * Show the typing indicator in a conversation, unless it is a 1-1 with a stranger.
+ *
+ * Reply: `{success, threadId, threadType, friendCheck, note?}`; `friendCheck` is "friend", "unknown" (no friend list
+ * in this process, sent anyway) or "group" (not checked).
+ *
+ * @param {object} api - logged-in session
+ * @param {{threadId: string, type: 0|1, ownId?: string, isFriend?: (userId: string) => boolean|null}} opts
+ * @returns {Promise<{success: true, threadId: string, threadType: "dm"|"group", friendCheck: string, note?: string}>}
+ * @throws {Error} for a stranger in a 1-1 conversation, before any request
+ */
+export async function sendTyping(api, { threadId, type, ownId, isFriend = isKnownFriend }) {
+    const id = String(threadId);
+    const group = Number(type) === THREAD_TYPE.GROUP;
+    let friendCheck = "group";
+    if (!group) {
+        const known = ownId && id === String(ownId) ? true : isFriend(id);
+        if (known === false) {
+            throw new Error(
+                "Not sent: this user is not a friend, and Zalo never shows a stranger that you are typing " +
+                    "(its privacy rule for strangers' chats).",
+            );
+        }
+        friendCheck = known ? "friend" : "unknown";
+    }
+    await api.sendTypingEvent(id, group ? THREAD_TYPE.GROUP : THREAD_TYPE.USER);
+    return {
+        success: true,
+        threadId: id,
+        threadType: group ? "group" : "dm",
+        friendCheck,
+        ...(friendCheck === "unknown" && {
+            note:
+                "Sent without checking whether this user is a friend: no friend list is loaded in this process. " +
+                "Zalo does not send typing to strangers.",
+        }),
+    };
+}

package/src/core/unknown-acts.js

@@ -0,0 +1,240 @@
+/**
+ * The control actions this client has no handler for, collected (plan item X10).
+ *
+ * The server pushes actions to a connected client as `602` frames (`data.actions[{act_type, act, data}]`) and as the
+ * `controls[]` of a `601` frame. The listener reads one kind of 602 (`typing`); Zalo sends dozens more, and a new one
+ * can appear with any server release. Nothing here changes how a frame is handled. It only notices a name this
+ * client does not know, once, and keeps a small local file so that a person (or the next release) can see which actions
+ * the server is sending that nobody handles.
+ *
+ * What is stored, per `act_type/act`: when it was first and last seen, how often, which command carried it, and the
+ * NAMES of the keys of its `data` (never the values: a control can carry a message, a name or an id). The file lives in
+ * the account folder at 0600 and holds no identity. Reading a frame is defensive on every line: a frame of an
+ * unexpected shape is skipped, and nothing here can throw into the socket.
+ */
+import { readFileSync } from "node:fs";
+import { writeFileAtomic } from "../zalo/kernel/atomic-file.js";
+import { readControls } from "../zalo/queues/control-queue.js";
+
+/** The chat push that carries `actions[]`. */
+export const CMD_PUSH_ACTIONS = 602;
+/** The control push whose `controls[]` this also reads. */
+export const CMD_PUSH_CONTROLS = 601;
+
+/** 602 actions a handler of this client or the listener already reads: by `act_type`, or by `act_type/act`. */
+const KNOWN_ACTIONS = new Set(["typing", "profile/online_status"]);
+
+/**
+ * 602 actions that are known and need nothing from this client, by `act_type` or `act_type/act`, each with why (what
+ * it is for).
+ */
+export const IGNORED_ACTIONS = new Map([
+    [
+        "recent_search",
+        "Zalo's list of recent searches, kept on each device for its search box; this client has no such list",
+    ],
+]);
+
+/**
+ * The socket commands this client handles or names on purpose (the offline queues, messages, receipts, reactions, the
+ * sync-v2 pair, the control pushes, the zCloud push and notice, the handshake and the keepalive, and those in
+ * {@link IGNORED_COMMANDS}). Any other command that arrives is noted once, by number: the server can start sending a
+ * new one with any release, and until now the ones that were not handled (533, 570 to 578, 592, 604, 614, 623, 800
+ * were seen in captures) left no trace.
+ */
+export const KNOWN_COMMANDS = new Set([
+    1, 2, 501, 502, 504, 510, 511, 521, 522, 524, 530, 532, 534, 590, 591, 601, 602, 603, 610, 611, 612, 613, 620, 621,
+]);
+
+/**
+ * Commands that are known and need nothing from this client, each with why (what it is for).
+ * Every one is also in {@link KNOWN_COMMANDS}.
+ */
+export const IGNORED_COMMANDS = new Map([
+    [
+        530,
+        "PUSH_LIST_INTERACTIVE_FILE: Zalo syncs a record of which shared files were downloaded or opened " +
+            "on each device; this client keeps no such record",
+    ],
+]);
+
+/** How many distinct names one file keeps: a flood of new names must not grow it without end. */
+export const MAX_NAMES = 200;
+/** How often the counts of names already known are written back. */
+export const SAVE_EVERY_MS = 60_000;
+/** How many key names of a `data` are kept per action. */
+const MAX_KEYS = 12;
+
+/**
+ * The actions of one 602 frame.
+ *
+ * @param {object|null|undefined} data - a decoded 602 frame's `data`
+ * @returns {Array<{actType: string, act: string, keys: string[]}>}
+ */
+export function readActions(data) {
+    const out = [];
+    for (const a of Array.isArray(data?.actions) ? data.actions : []) {
+        if (!a || typeof a !== "object") continue;
+        const inner = a.data;
+        let obj = inner;
+        if (typeof inner === "string") {
+            try {
+                obj = JSON.parse(inner);
+            } catch {
+                obj = null;
+            }
+        }
+        out.push({
+            actType: String(a.act_type ?? ""),
+            act: String(a.act ?? ""),
+            keys: obj && typeof obj === "object" && !Array.isArray(obj) ? Object.keys(obj).slice(0, MAX_KEYS) : [],
+        });
+    }
+    return out;
+}
+
+/** The names of the saved file, or an empty set when there is no usable one. */
+function loadNames(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        const names = parsed?.names;
+        return names && typeof names === "object" && !Array.isArray(names) ? { ...names } : {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * A collector for one account.
+ *
+ * @param {object} args
+ * @param {string} args.file - where the names are kept (created on the first unknown name)
+ * @param {() => number} [args.now]
+ * @param {(line: string) => void} [args.log] - told once per new name
+ * @returns {{
+ *   observeCommand: (view: object) => number,
+ *   observe: (cmd: number, data: object|null|undefined) => number,
+ *   names: () => Record<string, {firstSeen: number, lastSeen: number, count: number, cmd: number, keys: string[]}>,
+ * }} `observe` returns how many names in this frame were new to the file
+ */
+export function createUnknownActs({ file, now = Date.now, log = () => {} }) {
+    const names = loadNames(file);
+    let dirty = false;
+    let savedAt = 0;
+
+    function note(cmd, actType, act, keys) {
+        const key = `${actType || "?"}/${act || "?"}`;
+        const t = now();
+        const seen = names[key];
+        if (seen) {
+            seen.count += 1;
+            seen.lastSeen = t;
+            dirty = true;
+            return false;
+        }
+        if (Object.keys(names).length >= MAX_NAMES) return false;
+        names[key] = { firstSeen: t, lastSeen: t, count: 1, cmd, keys };
+        try {
+            log(`unknown action from the server: ${key} (cmd ${cmd}); noted in ${file}`);
+        } catch {
+            /* a broken logger must not break the socket */
+        }
+        return true;
+    }
+
+    function save() {
+        dirty = false;
+        savedAt = now();
+        try {
+            writeFileAtomic(file, JSON.stringify({ names }), { mode: 0o600 });
+        } catch {
+            /* the file is a convenience: failing to write it is not a reason to disturb anything */
+        }
+    }
+
+    return {
+        /**
+         * One frame's header: a command that is not in {@link KNOWN_COMMANDS} is noted as `cmd/<cmd>_<subCmd>`, with the
+         * key names of its body (never the values) from the first time it is seen.
+         *
+         * @param {{cmd: number, subCmd: number, size: number, frame: () => (object|null)}} view
+         * @returns {number} 1 when the name was new
+         */
+        observeCommand(view) {
+            try {
+                if (KNOWN_COMMANDS.has(view.cmd)) return 0;
+                const key = `cmd/${view.cmd}_${view.subCmd}`;
+                let fresh = 0;
+                if (names[key]) {
+                    note(view.cmd, "cmd", `${view.cmd}_${view.subCmd}`, []);
+                } else {
+                    let keys = [];
+                    try {
+                        const data = view.frame()?.data;
+                        if (data && typeof data === "object" && !Array.isArray(data)) {
+                            keys = Object.keys(data).slice(0, MAX_KEYS);
+                        }
+                    } catch {
+                        /* an undecodable body is still a command worth naming */
+                    }
+                    if (note(view.cmd, "cmd", `${view.cmd}_${view.subCmd}`, keys)) {
+                        names[key].size = view.size;
+                        fresh = 1;
+                    }
+                }
+                if (fresh > 0 || (dirty && now() - savedAt >= SAVE_EVERY_MS)) save();
+                return fresh;
+            } catch {
+                return 0;
+            }
+        },
+        observe(cmd, data) {
+            let fresh = 0;
+            try {
+                if (cmd === CMD_PUSH_ACTIONS) {
+                    for (const a of readActions(data)) {
+                        const both = `${a.actType}/${a.act}`;
+                        if (KNOWN_ACTIONS.has(a.actType) || KNOWN_ACTIONS.has(both)) continue;
+                        if (IGNORED_ACTIONS.has(a.actType) || IGNORED_ACTIONS.has(both)) continue;
+                        if (note(cmd, a.actType, a.act, a.keys)) fresh++;
+                    }
+                } else if (cmd === CMD_PUSH_CONTROLS) {
+                    for (const c of readControls(data)) {
+                        if (c.handled) continue;
+                        if (note(cmd, c.actType, c.act, c.data ? Object.keys(c.data).slice(0, MAX_KEYS) : [])) fresh++;
+                    }
+                }
+                // A new name is written at once; the counts of known names at most once a minute.
+                if (fresh > 0 || (dirty && now() - savedAt >= SAVE_EVERY_MS)) save();
+            } catch {
+                /* a frame of a shape nobody expected is skipped */
+            }
+            return fresh;
+        },
+        names: () => ({ ...names }),
+    };
+}
+
+/**
+ * Collect unknown actions from a socket tap, for one account. Built the same by `listen` and `mcp start`.
+ *
+ * @param {object} args
+ * @param {{on: (cmd: number, fn: (frame: object) => void) => () => void}} args.tap
+ * @param {string} args.file - see {@link createUnknownActs}
+ * @param {(line: string) => void} [args.log]
+ * @returns {{stop: () => void, names: ReturnType<typeof createUnknownActs>["names"]}}
+ */
+export function attachUnknownActs({ tap, file, log }) {
+    const acts = createUnknownActs({ file, log });
+    const offs = [CMD_PUSH_ACTIONS, CMD_PUSH_CONTROLS].map((cmd) =>
+        tap.on(cmd, (frame) => acts.observe(cmd, frame.data)),
+    );
+    // Every other command, by number (a tap without `onAny` simply does not offer this).
+    if (typeof tap.onAny === "function") offs.push(tap.onAny((view) => acts.observeCommand(view)));
+    return {
+        stop() {
+            for (const off of offs.splice(0)) off();
+        },
+        names: acts.names,
+    };
+}