@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/mcp/message-buffer.js

@@ -7,9 +7,14 @@
  * cursor. It used to delete the messages, so one bot's zalo_mark_read emptied
  * every other bot's inbox (triage M7). Messages now leave only by eviction
  * (maxSize per thread, maxAge), which bounds memory as before.
+ *
+ * Cursors live only as long as the process, but a long-poller keeps its cursor across a daemon restart
+ * (bug-reports #10). So the daemon's buffer starts counting at the clock (`forSession`), above anything
+ * an earlier run handed out, and a cursor beyond the newest message is read as stale (from the start of
+ * this buffer) rather than as "nothing yet": skipping is silent, a repeat is not.
  */
 
-import { batchParams } from "./wait-result.js";
+import { batchParams } from "./wait-batch.js";
 
 /** Sleep `ms`, or less if `signal` aborts. */
 function sleep(ms, signal) {
@@ -48,6 +53,12 @@ async function settleUntilFull(read, limit, settleMs, signal) {
     return r;
 }
 
+/**
+ * The key system events are buffered under (not a conversation's messages: a `storage_quota` event). No thread id is
+ * this word (they are digits), so no conversation's read returns them, and the conversation lists leave the key out.
+ */
+export const SYSTEM_EVENTS = "system";
+
 /** The consumer a caller that names none reads as. */
 export const DEFAULT_CONSUMER = "default";
 
@@ -58,19 +69,41 @@ export class MessageBuffer {
     /**
      * @param {number} maxSize - Max messages per thread before eviction
      * @param {number} maxAge - Max message age in ms before eviction (default 2h)
+     * @param {{ startCursor?: number }} [opts] - The cursor the first message follows
      */
-    constructor(maxSize = 500, maxAge = 2 * 60 * 60 * 1000) {
+    constructor(maxSize = 500, maxAge = 2 * 60 * 60 * 1000, { startCursor = 0 } = {}) {
         /** @type {Map<string, { messages: Array, lastActivity: number }>} */
         this._threads = new Map();
         this._maxSize = maxSize;
         this._maxAge = maxAge;
-        this._globalCursor = 0;
+        this._globalCursor = startCursor;
         /** @type {Map<string, { cursor: number, at: number }>} */
         this._readCursors = new Map();
         /** @type {Set<{ threadId: string|null, resolve: Function, timer: NodeJS.Timeout }>} */
         this._waiters = new Set();
     }
 
+    /**
+     * The buffer a daemon serves from: cursors start at the clock (epoch ms), so a cursor saved before a
+     * restart is below every cursor this run hands out, as long as the earlier run buffered fewer messages
+     * than it lived milliseconds.
+     * @param {number} [maxSize]
+     * @param {number} [maxAge]
+     * @returns {MessageBuffer}
+     */
+    static forSession(maxSize, maxAge) {
+        return new MessageBuffer(maxSize, maxAge, { startCursor: Date.now() });
+    }
+
+    /**
+     * A caller's cursor, with one from beyond the newest message (an earlier run's) read as 0.
+     * @param {number} since
+     * @returns {number}
+     */
+    _fresh(since) {
+        return since > this._globalCursor ? 0 : since;
+    }
+
     /**
      * The read cursor of one consumer: messages after it are unread for them.
      * @param {string} [consumer="default"]
@@ -106,6 +139,15 @@ export class MessageBuffer {
         }
     }
 
+    /**
+     * Add one system event: every read and wait that names no conversation gets it, in order with the messages
+     * (it moves the same cursor), marked `system: true` with `threadId` and `msgId` null.
+     * @param {object} event - `{type, ...}`
+     */
+    pushSystem(event) {
+        this.push(SYSTEM_EVENTS, { threadId: null, msgId: null, timestamp: Date.now(), ...event, system: true });
+    }
+
     /**
      * Wait for the next buffered message (or return immediately if `since` is
      * provided and a newer message is already in the buffer).
@@ -134,7 +176,7 @@ export class MessageBuffer {
      * @param {number} [opts.since] - Optional cursor (exclusive)
      * @param {number} [opts.timeoutMs=60000] - Max wait for the FIRST message
      * @param {AbortSignal} [opts.signal]
-     * @param {number} [opts.limit=1] - Most messages to return (1-100)
+     * @param {number|null} [opts.limit] - Most messages to return; omitted = every one already waiting
      * @param {number} [opts.settleMs=0] - After the first message, wait this long for more (0-5000)
      * @returns {Promise<{ messages: object[], hasMore: boolean }>} `messages` is empty on timeout or abort
      */
@@ -143,11 +185,12 @@ export class MessageBuffer {
         since = undefined,
         timeoutMs = 60000,
         signal = undefined,
-        limit = 1,
+        limit = null,
         settleMs = 0,
     } = {}) {
-        const { limit: max, settleMs: settle } = batchParams({ limit, settleMs });
-        const from = (cursor) => this.read(threadId || undefined, cursor, max);
+        const { limit: asked, settleMs: settle } = batchParams({ limit, settleMs });
+        const max = asked ?? Infinity;
+        const from = (cursor) => this.read(threadId || undefined, this._fresh(cursor), max);
 
         if (since !== undefined && since !== null && Number.isFinite(Number(since))) {
             let r = from(Number(since));
@@ -211,10 +254,12 @@ export class MessageBuffer {
      * Read messages from a thread, optionally since a cursor.
      * @param {string} [threadId] - If omitted, reads from all threads
      * @param {number} [since=0] - Cursor to read from (exclusive)
-     * @param {number} [maxCount=20] - Max messages to return
+     * @param {number|null} [maxCount] - Max messages to return; omitted, null or <= 0 = every one buffered
      * @returns {{ messages: Array, cursor: number, hasMore: boolean }}
      */
-    read(threadId, since = 0, maxCount = 20) {
+    read(threadId, since = 0, maxCount = null) {
+        since = this._fresh(since);
+        if (!(Number(maxCount) > 0)) maxCount = Infinity;
         const sources = threadId ? [this._threads.get(threadId)].filter(Boolean) : Array.from(this._threads.values());
 
         // Collect all messages after cursor, sorted by cursor
@@ -235,14 +280,15 @@ export class MessageBuffer {
 
     /**
      * Advance one consumer's read cursor to `cursor`. Nothing is deleted, and no
-     * other consumer's cursor moves; a cursor never moves backwards.
+     * other consumer's cursor moves; a cursor never moves backwards, and a stale one (beyond the newest
+     * message) does not move it at all.
      * @param {number} cursor
      * @param {string} [consumer="default"]
      * @returns {number} how many buffered messages this newly marked read for that consumer
      */
     markRead(cursor, consumer = DEFAULT_CONSUMER) {
         const from = this.readCursor(consumer);
-        const to = Math.max(from, Number(cursor) || 0);
+        const to = Math.max(from, this._fresh(Number(cursor) || 0));
         let marked = 0;
         for (const [, thread] of this._threads) {
             for (const m of thread.messages) if (m._cursor > from && m._cursor <= to) marked++;
@@ -263,7 +309,7 @@ export class MessageBuffer {
     getStats(readCursor = 0) {
         const stats = [];
         for (const [threadId, thread] of this._threads) {
-            if (thread.messages.length === 0) continue;
+            if (thread.messages.length === 0 || threadId === SYSTEM_EVENTS) continue;
             const unread = thread.messages.filter((m) => m._cursor > readCursor).length;
             stats.push({
                 threadId,

package/src/mcp/notifier.js

@@ -47,7 +47,7 @@ const TYPE_LABEL = {
 
 export class ZaloNotifier {
     /**
-     * @param {object} api - zca-js API instance
+     * @param {object} api - session object
      * @param {object} config - Full MCP config (uses config.notify section)
      * @param {boolean} config.notify.enabled
      * @param {string|null} config.notify.thread - Group ID to send notifications to

package/src/mcp/official-tool.js

@@ -0,0 +1,298 @@
+/**
+ * `zalo_official`: the official-API commands (`oa …`, `zbs …`, `social …`) as one MCP tool.
+ *
+ * Each call runs the CLI command itself, `zalo-agent --json <command> …`, in a child process: the tool and the command
+ * cannot drift apart, and the official APIs never touch the personal account's session (they have their own OAuth
+ * logins under ~/.zalo-agent/). The command tree is read from the same `register*` functions src/index.js calls, so the
+ * tool's command list, arguments and options are the CLI's. A guarded command (src/core/confirm-guard.js) is settled
+ * here first, through the server's confirm mode, and then run with `--yes`.
+ *
+ * The commands left out (OFFICIAL_CLI_ONLY) are the ones that take a secret as input, open a browser login, or run a
+ * long-lived server; tests/unit/mcp-cli-parity.test.js holds every other one to an entry in the tool's list.
+ */
+
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { z } from "zod";
+import { registerOACommands } from "../commands/oa.js";
+import { registerZbsCommands } from "../commands/zbs.js";
+import { registerSocialCommands } from "../commands/social.js";
+import { confirmInput, dryRunInput, ticketInput } from "./action-tool.js";
+
+/** Official commands with no MCP counterpart, and why. Mirrored in skill/references/mcp-guide.md. */
+export const OFFICIAL_CLI_ONLY = Object.freeze({
+    "oa login": "an OAuth login in the owner's browser on a local callback port: an operator's step",
+    "oa setup": "takes the OA access token as an argument: credentials never pass through an agent",
+    "oa init": "the setup wizard: takes the app secret and logs in through the browser",
+    "oa listen": "a long-running webhook server: run it as a service, not from a tool call",
+    "social setup": "takes the app secret: credentials never pass through an agent",
+    "social login": "an OAuth login in the user's browser on a local callback port",
+});
+
+/** Options a caller never sets through `options`: the tool's own inputs answer for them. */
+const RESERVED = new Set(["yes", "dry-run", "json", "help"]);
+
+/** The CLI entry point the commands run through. */
+const CLI_ENTRY = fileURLToPath(new URL("../index.js", import.meta.url));
+
+/** How long one command may run: `oa article create` and `video-upload` wait for Zalo's processing. */
+const RUN_TIMEOUT_MS = 10 * 60 * 1000;
+
+let tree = null;
+
+/**
+ * The official commands by their CLI path ("oa msg text"), from the same registrations src/index.js makes.
+ *
+ * @returns {Map<string, import("commander").Command>}
+ */
+export function officialCommands() {
+    if (tree) return tree;
+    const program = new Command();
+    registerOACommands(program);
+    registerZbsCommands(program);
+    registerSocialCommands(program);
+    const map = new Map();
+    const walk = (cmd, path) => {
+        for (const c of cmd.commands) {
+            const p = [...path, c.name()];
+            if (c.commands.length) walk(c, p);
+            else if (!OFFICIAL_CLI_ONLY[p.join(" ")]) map.set(p.join(" "), c);
+        }
+    };
+    walk(program, []);
+    tree = map;
+    return map;
+}
+
+/** An option's flag name without the dashes ("oa-id", "no-wait"). */
+const flagName = (o) => (o.long ?? o.short).replace(/^-+/, "");
+
+/** What an option takes: nothing (a switch), one value, an optional value, or a list. */
+function takes(o) {
+    if (o.variadic) return "values";
+    if (o.required) return "value";
+    if (o.optional) return "optional value";
+    return "none";
+}
+
+/**
+ * One command's usage, as the tool lists it: its positional arguments and its options by flag name.
+ *
+ * @param {string} path
+ * @param {import("commander").Command} cmd
+ * @returns {object}
+ */
+export function describeOfficial(path, cmd) {
+    return {
+        command: path,
+        description: cmd.description(),
+        args: cmd.registeredArguments.map((a) => ({
+            name: a.name(),
+            required: a.required,
+            ...(a.variadic && { list: true }),
+            ...(a.description && { description: a.description }),
+        })),
+        options: cmd.options
+            .filter((o) => !RESERVED.has(flagName(o)))
+            .map((o) => ({
+                name: flagName(o),
+                takes: takes(o),
+                description: o.description,
+                ...(o.defaultValue !== undefined && typeof o.defaultValue !== "boolean" && { default: o.defaultValue }),
+            })),
+        ...(cmd.zaloGuard && { guarded: true }),
+    };
+}
+
+/** The option an `options` key names: its flag name ("oa-id"), with or without dashes, or its camelCase name. */
+function findOption(cmd, key) {
+    const k = String(key).replace(/^-+/, "");
+    return cmd.options.find((o) => flagName(o) === k || o.attributeName() === k) ?? null;
+}
+
+/**
+ * The argv for one command, after checking its arguments and options against the command, plus the parsed values
+ * the guard reads. Options go first as `--flag=value`, then `--`, then the arguments: an argument that starts with a
+ * dash is never read as a flag.
+ *
+ * @param {string} path - e.g. "oa msg text"
+ * @param {import("commander").Command} cmd
+ * @param {string[]} [args]
+ * @param {Record<string, unknown>} [options]
+ * @returns {{argv: string[], positional: unknown[], opts: object} | {error: string}}
+ */
+export function officialArgv(path, cmd, args = [], options = {}) {
+    const usage = () => ` Usage: ${JSON.stringify(describeOfficial(path, cmd))}`;
+    const regs = cmd.registeredArguments;
+    const variadic = regs.at(-1)?.variadic === true;
+    const required = regs.filter((a) => a.required).length;
+    if (args.length < required)
+        return { error: `'${path}' needs ${required} argument(s), got ${args.length}.${usage()}` };
+    if (!variadic && args.length > regs.length) {
+        return { error: `'${path}' takes at most ${regs.length} argument(s), got ${args.length}.${usage()}` };
+    }
+    const positional = regs.map((a, i) => (a.variadic ? args.slice(i) : args[i]));
+
+    const flags = [];
+    const opts = {};
+    for (const o of cmd.options) if (o.defaultValue !== undefined) opts[o.attributeName()] = o.defaultValue;
+    for (const [key, value] of Object.entries(options ?? {})) {
+        const o = findOption(cmd, key);
+        if (!o || RESERVED.has(flagName(o))) {
+            return { error: `'${path}' has no option '${key}'.${usage()}` };
+        }
+        const flag = o.long ?? o.short;
+        const kind = takes(o);
+        if (kind === "none") {
+            if (typeof value !== "boolean") return { error: `Option '${key}' is a switch: give true or false.` };
+            if (value) {
+                flags.push(flag);
+                opts[o.attributeName()] = !o.negate;
+            }
+            continue;
+        }
+        if (value === false || value === null) continue;
+        if (kind === "optional value" && value === true) {
+            flags.push(flag);
+            opts[o.attributeName()] = true;
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        if (values.length > 1 && kind !== "values") return { error: `Option '${key}' takes one value.` };
+        if (values.some((v) => typeof v === "boolean" || typeof v === "object")) {
+            return { error: `Option '${key}' takes a value (a string or a number).` };
+        }
+        for (const v of values) flags.push(`${flag}=${String(v)}`);
+        opts[o.attributeName()] = kind === "values" ? values.map(String) : String(values[0]);
+    }
+    return { argv: [...path.split(" "), ...flags, "--", ...args.map(String)], positional, opts };
+}
+
+/**
+ * Run the CLI with `argv` and settle when it exits.
+ *
+ * @param {string[]} argv
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function runOfficialCli(argv) {
+    return new Promise((done) => {
+        execFile(
+            process.execPath,
+            [CLI_ENTRY, "--json", ...argv],
+            {
+                env: { ...process.env, ZALO_JSON_MODE: "1" },
+                maxBuffer: 64 * 1024 * 1024,
+                timeout: RUN_TIMEOUT_MS,
+                windowsHide: true,
+            },
+            (e, stdout, stderr) => {
+                const code = e ? (typeof e.code === "number" ? e.code : 1) : 0;
+                done({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), killed: e?.killed === true });
+            },
+        );
+    });
+}
+
+/** The command's JSON reply: the whole of stdout, or else its last JSON value; null when there is none. */
+function parseReply(stdout) {
+    const text = stdout.trim();
+    if (!text) return null;
+    try {
+        return JSON.parse(text);
+    } catch {
+        const start = Math.max(text.lastIndexOf("\n{"), text.lastIndexOf("\n["));
+        if (start < 0) return null;
+        try {
+            return JSON.parse(text.slice(start + 1));
+        } catch {
+            return null;
+        }
+    }
+}
+
+/** The tool's metadata. */
+export function officialMeta() {
+    const names = [...officialCommands().keys()];
+    return {
+        title: "Zalo Official APIs (OA, ZBS, Social)",
+        description:
+            "Run one of Zalo's official-API commands, the same as the CLI `zalo-agent <command>`: Official Account " +
+            "(`oa …`: consultation messages, followers, tags, articles, OA group chats, calls), ZBS Template Message " +
+            "(`zbs …`: paid template messages by phone number or user id) and the Social API (`social …`: the profile " +
+            "of a user who logged in to the owner's app). These use the owner's official OAuth logins, never the " +
+            "personal account. Omit `command` to list every command with its arguments and options. `args` are the " +
+            "positional arguments in order; `options` are named by the CLI flag without dashes, e.g. " +
+            '{"oa-id": "shop", "quote": "<message id>"}; a switch takes true. The logins themselves (`oa login`, ' +
+            "`oa setup`, `oa init`, `social setup`, `social login`) and `oa listen` are run by the owner on the CLI. " +
+            "Guarded commands (deletions, `oa purchase confirm-order`, `oa call consent-request`) take `confirm` " +
+            "and `dryRun` like every guarded action.",
+        inputSchema: z
+            .object({
+                command: z
+                    .enum(names)
+                    .optional()
+                    .describe("The command, as on the CLI (e.g. 'oa msg text'); omit to list them all"),
+                args: z
+                    .array(z.union([z.string(), z.number()]))
+                    .max(100)
+                    .optional()
+                    .describe("Positional arguments, in the command's order (ids as strings)"),
+                options: z
+                    .record(
+                        z.string(),
+                        z.union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number()]))]),
+                    )
+                    .optional()
+                    .describe('Options by CLI flag name without dashes, e.g. {"oa-id": "shop", "all": true}'),
+                confirm: confirmInput("a guarded command (deletions, paying an order, a call consent request)"),
+                dryRun: dryRunInput("a guarded command"),
+                ticket: ticketInput(),
+            })
+            .strict(),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    };
+}
+
+/**
+ * zalo_official's handler.
+ *
+ * @param {{ok: Function, err: Function, gate: Function}} ctx - the reply wrappers and the guard (mcp-tools.js)
+ * @param {{run?: typeof runOfficialCli}} [deps] - the runner (tests pass a fake)
+ * @returns {(args: object, extra?: object) => Promise<object>}
+ */
+export function officialTool(ctx, { run = runOfficialCli } = {}) {
+    return async ({ command, args = [], options = {}, confirm, dryRun, ticket } = {}, extra) => {
+        const commands = officialCommands();
+        if (!command) return ctx.ok({ commands: [...commands].map(([p, c]) => describeOfficial(p, c)) });
+        const cmd = commands.get(command);
+        if (!cmd) return ctx.err(`Unknown official command '${command}'. Omit command to list them.`);
+        const built = officialArgv(command, cmd, args.map(String), options);
+        if (built.error) return ctx.err(built.error);
+
+        const guard = cmd.zaloGuard;
+        if (guard) {
+            const target = guard.target(...built.positional, built.opts);
+            const applies = guard.when ? guard.when(target, built.opts) : true;
+            const held = await ctx.gate(guard.key, target, { confirm, dryRun, ticket }, extra, { applies });
+            if (held) return held;
+            built.argv.splice(built.argv.indexOf("--"), 0, "--yes");
+        } else if (dryRun === true) {
+            return ctx.err(
+                `dryRun previews only the guarded commands, and '${command}' is not one: nothing was done. Call it ` +
+                    "again without dryRun to do it.",
+            );
+        }
+
+        const r = await run(built.argv);
+        const reply = parseReply(r.stdout);
+        if (r.code === 0) return ctx.ok({ command, result: reply ?? (r.stdout.trim() || null) });
+        if (r.killed) return ctx.err(`'${command}' did not finish within ${RUN_TIMEOUT_MS / 60000} minutes.`);
+        const why =
+            (reply && typeof reply === "object" && reply.error) ||
+            r.stderr.trim().split("\n").filter(Boolean).at(-1) ||
+            `'${command}' exited with code ${r.code}`;
+        console.error(`[mcp-tools] zalo_official ${command} error:`, why);
+        return ctx.err(String(why));
+    };
+}

package/src/mcp/sync-jobs.js

@@ -6,6 +6,12 @@
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 
+/**
+ * The stages zalo_sync can start. Only `messages` taps the owner's phone; the rest run on this server's session
+ * (`reactions` on its socket, `cloud`, `media` and `boards` over HTTP).
+ */
+export const SYNC_STAGES = Object.freeze(["messages", "reactions", "cloud", "media", "boards"]);
+
 /**
  * Create a bounded, account-local job tracker using the daemon's stage lock.
  * Completed jobs are retained until displaced by ten newer jobs or restart.
@@ -26,7 +32,7 @@ export function createSyncJobs({ runners, lock }) {
                 }
                 return snapshot(existing);
             }
-            if (!["messages", "reactions"].includes(stage) || typeof runners[stage] !== "function") {
+            if (!SYNC_STAGES.includes(stage) || typeof runners[stage] !== "function") {
                 throw new Error("Unsupported sync stage.");
             }
             const release = lock.tryAcquire(`mcp-sync:${stage}`);

package/src/mcp/sync-stages.js

@@ -0,0 +1,72 @@
+/**
+ * The zalo_sync stages the MCP server runs itself, beside the daemon's own runners (src/core/daemon-sync.js:
+ * `messages`, `reactions`, `cloud`): `media` downloads the attachments a restore recorded, as `sync-media` does, and
+ * `boards` stores notes, pins, polls and reminders, as `sync-boards` does. Neither taps the phone. Both write the
+ * cache, and this server is the account's one writer, so they run here, under the same stage lock as the others.
+ */
+
+import { getSyncState, getThreadNames } from "../core/db.js";
+import { downloadSyncedMedia } from "../core/sync-v2/media.js";
+import { runBoardPass } from "../core/board-pass.js";
+
+const DAY_MS = 86_400_000;
+
+/**
+ * @param {object} deps
+ * @param {() => object} deps.getApi - the daemon's CURRENT session
+ * @param {string} deps.accountDir - the account's folder; media goes under its `media/`
+ * @param {string} [deps.mediaRoot] - the configured media root, when it is not `<accountDir>/media`
+ * @returns {{media: Function, boards: Function}} stage runners, as createSyncJobs takes them
+ */
+export function createMcpStageRunners({ getApi, accountDir, mediaRoot }) {
+    return {
+        /**
+         * @param {{threadId?: string, kinds?: string[], days?: number, limit?: number}} params
+         * @param {(e: object) => void} onEvent
+         */
+        async media(params = {}, onEvent = () => {}) {
+            // The window the last restore covered, unless days says otherwise: media outside it has the oldest
+            // links, the likeliest to be dead (as `sync-media` without --all-history).
+            let since = params.days ? Date.now() - params.days * DAY_MS : undefined;
+            if (since === undefined) {
+                const covered = Number(getSyncState("lastSyncOkFrom"));
+                if (Number.isFinite(covered) && covered > 0) since = covered;
+            }
+            return downloadSyncedMedia({
+                api: getApi(),
+                accountDir,
+                threadId: params.threadId,
+                kinds: params.kinds,
+                since,
+                concurrency: 2,
+                maxFiles: params.limit,
+                timeoutMs: 60_000,
+                threadNames: getThreadNames(),
+                mediaRoot,
+                onProgress: (p) => {
+                    if (p.phase === "saved" && (p.done === p.total || p.done % 25 === 0)) {
+                        onEvent({ phase: "media", detail: `${p.done}/${p.total} downloaded` });
+                    }
+                },
+            });
+        },
+
+        /**
+         * @param {{threadId?: string, limit?: number}} params
+         * @param {(e: object) => void} onEvent
+         */
+        async boards(params = {}, onEvent = () => {}) {
+            const api = getApi();
+            if (!api) throw new Error("this server has no session to read the boards with");
+            return runBoardPass(api, {
+                thread: params.threadId,
+                limit: params.limit,
+                onProgress: (p) => {
+                    if (p.done === p.total || p.done % 25 === 0) {
+                        onEvent({ phase: "boards", detail: `${p.done}/${p.total} threads` });
+                    }
+                },
+            });
+        },
+    };
+}

package/src/mcp/thread-name-cache.js

@@ -1,4 +1,6 @@
 import { readUserAliases, resolveCurrentUserNames } from "../core/current-user-names.js";
+import { rememberFriends } from "../core/typing.js";
+import { goneGroupMap, noteGroupInfo } from "../core/group-exit.js";
 
 /**
  * In-memory cache mapping threadId → {name, type, memberCount}.
@@ -31,9 +33,10 @@ export class ThreadNameCache {
     /**
      * Initialize cache by fetching all groups and friends from Zalo API.
      * Batches group info requests (50 per batch) to avoid rate limits.
-     * @param {object} api - zca-js API instance
+     * @param {object} api - session object
+     * @param {{ownId?: string}} [opts] - the account: a group its info lists as removed is disbanded (group_gone)
      */
-    async init(api) {
+    async init(api, { ownId } = {}) {
         const start = Date.now();
         let groupCount = 0;
         let friendCount = 0;
@@ -49,12 +52,19 @@ export class ThreadNameCache {
                 const batch = groupIds.slice(i, i + batchSize);
                 try {
                     const info = await api.getGroupInfo(batch);
+                    // Disbanded: the group fetch lists it in removedsGroup (Zalo's version-map rule).
+                    if (ownId && info?.removedsGroup?.length) {
+                        for (const e of await noteGroupInfo({ ownId, result: info, groupIds: batch }))
+                            this._cache.delete(e.threadId);
+                    }
                     const map = info?.gridInfoMap || {};
                     for (const [gid, g] of Object.entries(map)) {
                         this._cache.set(gid, {
                             name: g.name || "?",
                             type: "group",
                             memberCount: g.totalMember || 0,
+                            // A group recall sends it, as Zalo's does (src/zalo/custom/group-visibility.js).
+                            ...(g.visibility !== undefined && g.visibility !== null && { visibility: g.visibility }),
                         });
                         groupCount++;
                     }
@@ -70,6 +80,8 @@ export class ThreadNameCache {
         try {
             const friends = await api.getAllFriends();
             const list = Array.isArray(friends) ? friends : [];
+            // The friend list zalo_conversation `typing` checks a DM against (src/core/typing.js).
+            if (Array.isArray(friends)) rememberFriends(list);
             for (const f of list) {
                 if (f.userId) {
                     friendProfiles.set(String(f.userId), f);
@@ -85,11 +97,37 @@ export class ThreadNameCache {
         }
 
         await this.refreshUsers(api, friendProfiles);
+        this.applyGone();
         this._ready = true;
         const elapsed = Date.now() - start;
         console.error(`[thread-name-cache] Ready: ${groupCount} groups, ${friendCount} friends (${elapsed}ms)`);
     }
 
+    /**
+     * Bring the cache in line with the groups the local cache records as gone (src/core/group-exit.js): one whose
+     * history is kept is listed flagged (`gone`, `leftAt`, `goneReason`), one whose history was purged is left out.
+     *
+     * @param {Map<string, object>} [gone] - pin the gone groups (tests)
+     */
+    applyGone(gone = goneGroupMap()) {
+        for (const [id, g] of gone) {
+            if (g.messages > 0) {
+                this.set(id, { name: g.name || this._cache.get(id)?.name || "?", type: "group" });
+                this.set(id, { gone: true, leftAt: g.leftAt, goneReason: g.goneReason });
+            } else this._cache.delete(id);
+        }
+    }
+
+    /**
+     * Forget one thread (a gone group whose history was purged).
+     *
+     * @param {string} threadId
+     * @returns {boolean}
+     */
+    drop(threadId) {
+        return this._cache.delete(String(threadId));
+    }
+
     /**
      * Get thread info by ID. Returns null if not cached.
      * @param {string} threadId
@@ -120,10 +158,10 @@ export class ThreadNameCache {
      * Search threads by name with Vietnamese-aware fuzzy matching.
      * @param {string} query - Search keyword
      * @param {"group"|"dm"|"all"} [type="all"] - Filter by thread type
-     * @param {number} [limit=10] - Max results
+     * @param {number|null} [limit] - Max results; omitted, null or <= 0 = every match
      * @returns {Array<{ threadId: string, name: string, type: "group"|"dm", memberCount?: number }>}
      */
-    search(query, type = "all", limit = 10) {
+    search(query, type = "all", limit = null) {
         const normalizedQuery = normalizeVietnamese(query);
         const results = [];
 
@@ -146,7 +184,7 @@ export class ThreadNameCache {
             return aNorm.localeCompare(bNorm);
         });
 
-        return results.slice(0, limit);
+        return Number(limit) > 0 ? results.slice(0, limit) : results;
     }
 
     /**